Data Science Toolkit - Bonsai 言語

[アーティクル]
07/05/2024

Bonsai 言語は、カスタム予測モデルのデシジョンツリーロジックを記述するように設計されています。このページでは、Bonsai 言語の構文とコアセマンティクスについて説明します。追加のリファレンスとして、Backus-Naur フォーム表記法の完全な文法も提供しました。

式

Bonsai で記述されたデシジョンツリーは、 branch または if/elif/else や switch 式として書かれた一連の分岐として構成されます。 branchの結果は、leafまたはleaf valueと呼ばれます。 leaf valueを受け取る変数は、使用されているカスタムモデルによって異なります。たとえば、カスタムモデルの種類が bidのmodel_outputでカスタムモデルを使用した場合、leafはカスタムモデルを使用しての CPM 入札価格に適用されます。

注:

負またはゼロ (0) の入札は、機能の説明で明示的に指定しない限りサポートされません。これらの式を使用しないか、予期しない結果が発生する可能性があります。 Bonsai Smart Leaves を使用してno_bidを明示的に指定することをお勧めします。

If/Elif/Else

すべての if には、一致する elseが必要です。 ifと一致するelseの間には、0 個以上のelif式を指定できます。

例

if country = "US":
        1
elif user_hour range (8, 12):
        if domain = "news.com":
                0.85
        else:
                0.2
else:
        0.1

この例では、入れ子になったif/else式を持つif/elif/else式を示します。この例の決定パスは次のとおりです。

ユーザーは米国に存在しますか?
- はいの場合は、1 を入札します。
- いいえの場合は、手順 2 に進みます。
ユーザーのタイムゾーンの午前 8 時から午後 12 時の間ですか?
- はいの場合は、手順 3 に進みます。
- いいえの場合は、0.1 に入札します。
ドメインは "news.com" ですか?
- はいの場合は、0.85 に入札します。
- いいえの場合は、0.2 に入札します。

スイッチ

switch式は、多数のチェーンされたif/elif ステートメントの代替として使用できます。これは、1 つの機能についてテストする値が多数ある場合に便利です。

switch式に関する注意事項:

各ケースは、キーワード caseで始まる必要があります。
ケースには、1 つの値、値の一覧、または範囲を指定できます。範囲は数値にのみ使用できます。
各ケースの値、値の一覧、または値の範囲は、かっこで囲む必要があります。
範囲は、2 つのピリオド (..) で示されます。範囲は、1 つまたは 2 つの境界で使用できます。境界は包括的です。たとえば、 ( .. 3) は、3 まで番号付けされたすべてのケースに適用されます。
大文字と小文字を区別すると、リーフまたは別の式が発生する可能性があります。
switch式は、defaultケースで終了する必要があります。これにより、ツリーのすべてのリーフに値が設定されます。

例

switch user_hour: 
    case (1 .. 3): 
        0.4 
    case (4, 6, 8): 
        if country present: 
            0.8 
        else: 
            0.4 
    default: 0.1

この例の決定パスは次のとおりです。

ユーザーのタイムゾーンは午前 1 時から午前 3 時の間ですか?
- はいの場合は、0.4 に入札します。
- いいえの場合は、手順 2 に進みます。
ユーザーのタイムゾーンの午前 4 時、6 時、または午前 8 時ですか?
- はいの場合は、手順 3 に進みます。
- いいえの場合は、0.1 に入札します。
国は存在しますか?
- はいの場合は、0.8 に入札します。
- いいえの場合は、0.4 に入札します。

条件

ifステートメントと elif ステートメントでは、any条件とevery条件を使用して、ブール値ロジックを一連の機能に適用できます。

注:

単一のifステートメントまたはelif ステートメントでany条件とevery条件を組み合わせうことはできません。

任意

if または elif ステートメントでany条件を使用する場合、特徴値間のコンマ区切り記号は実質的に "ors" になります。つまり、ステートメント内 のいずれかの 機能が印象と一致する場合、リーフが評価されます。

この例では、時間が存在する OR 国が OR で、日曜日、月曜日、または火曜日の場合、 1 リーフが評価されます。

if any user_hour present, country present, user_day < 4:
        1
else:
        0.2

毎

if または elif ステートメントでevery条件を使用すると、特徴値間のコンマ区切り記号は実質的に "ands" になります。つまり、ステートメント 内のすべての 機能が印象と一致すると、リーフが評価されます。

この例では、時間が存在し、国が AND で、日曜日、月曜日、または火曜日である場合、 1 リーフが評価されます。

機能

Bonsai の中心的な構文要素が特徴です。機能は、次で構成されます。

キーワード
有効な値のセット

次の例では、feature キーワードは user_dayで、有効な値は 0-6間の整数です。ここで、 0 は日曜日、 6 は土曜日です。

if user_day < 6:
        1
else:
        2

feature キーワードに無効な値を使用すると、API は、デシジョンツリーの問題の正確な場所と性質を示すエラーを返します。

if user_day < 100:
        1
else:
        2

ERROR: Invalid value on line 1 at position 13; user_day must be between 0 and 6

Bonsai 検証の詳細については、「デシジョンツリーの検証とエラーメッセージ」を参照してください。

使用可能な機能とその有効な値の完全な一覧については、「 Bonsai 機能」を参照してください。一部の特徴は数値 ( user_hourなど) ですが、他の特徴は ( countryなど) ではないことに注意してください。特定の数値演算子は、数値型に対してのみ有効です。

注:

segment機能は、他のすべての機能とは異なる方法で処理されます。これは、次に基づいてのみテストできます。

セグメントプレゼンス
ユーザーがセグメントに追加されてからの分数
セグメントと共に渡されるユーザー定義値

詳細については、「 Bonsai 特徴のセグメントプレゼンス、セグメント年齢、セグメント値」を参照してください。

演算子

プレゼンス/不在

present演算子とabsent演算子は、機能の有無をテストするために使用されます。

if country present:
        2
else:
        1

比較

次の比較演算子がサポートされています。

オペレーター	意味
`=`	等しい
`!=`	等しくない
`/=`	等しくない
`<`	より小さい (整数でのみ使用できます)
`>`	より大きい (整数でのみ使用できます)
`<=`	以下 (整数でのみ使用できます)
`>=`	以上 (整数でのみ使用できます)

if country = "US":
        2
else:
        1

In

in演算子は、特徴値が使用可能な値の一覧内の任意の値と一致するかどうかをテストするために使用されます。リストはかっこで囲む必要があることに注意してください。

if country in ("US", "MX", "CA"):
        2
else:
        1

範囲

range演算子は、包括的な値範囲のメンバーシップの特徴値をテストするために使用されます。

この演算子は整数値でのみ使用できます。

整数範囲はかっこで囲む必要があります。

if user_hour range (1, 12):
        1
else:
        0.2

上記の例では、時間がユーザーのタイムゾーンの午前 1 時から午後 12 時の間にあるかどうかをテストします。

注:

範囲を使用してスイッチ式のケースを指定する場合は、コンマではなく、範囲内の 2 つのピリオド (..) を使用します。詳細については、「スイッチ」を参照してください。

未サポート

not キーワードは、条件を否定するために使用されます。

if not country present:
        1
else:
        0.2

葉

すべてのツリーブランチはリーフ値につながります。

各リーフには、整数または浮動小数点数を指定できます。
"bid" model_outputを使用したカスタムモデルの場合:
- 各リーフは、カスタムモデルを使用するの通貨での cpm 入札価格です。
"bid_modifier" model_outputを使用したカスタムモデルの場合:
- 各リーフは、Xandr 最適化派生 CPM 入札に適用される乗数です。

次の "bid"model_output 例では、でを USD で使用すると、葉の入札値は $1.00 CPM と $0.25 CPM になります。

if not country present:
        1
else:
        0.25

スマートリーフ

スマートリーフでは、広告のパフォーマンスと配信に関する推定指標に基づいて、入札単価が動的に変更されます。

スマートリーフは、 "bid" と "bid_modifier" model_outputの両方をサポートします。
スマートリーフを使用すると、 "no_bid" 値を指定できます。
スマートリーフを使用すると、 leaf_name フィールドでリーフに名前を付けできます。
入札値は、次の情報から取得できます。
- 推定 IAB ビュースルー率
- 推定平均価格
- 見積もりクリア価格
- 一様乱数

次の例では、入札価格は推定平均価格に 1.5 を掛け、オフセットは $0.03 で、最小値は $1、最大値は $5 です。

if country = "US":
        leaf_name: "10000"
        value: compute(estimated_average_price, 1.50, 0.03, 1.00, 5.00)

詳細については、「 Bonsai Smart Leaves」を参照してください。

圧入

タブ文字 (\t) は、行のインデントを示すために使用されます。これは、式のグループ化 (Python と同様) を決定するために使用されます。現時点では、タブのみがサポートされています (スペースは無視されます)。改行文字 (\n) は、行の末尾をマークするために使用されます。

注釈

#文字はコメント用です。コメントは、Bonsai がコードとして実行しようとしないテキスト行です。人間が読むだけです。

コメントを使用すると、コードの理解が容易になります。コードを振り返ったり、他のユーザーが共同作業を行いたい場合は、コメントを読んで、コードの動作を簡単に把握できます。

各コメントは、独自の行にあり、 # 文字で始まる必要があります。
複数行のコメントを記述する場合、各行は # 文字で始まる必要があります。

現時点では、他の Bonsai コードと同じ行にコメントを挿入することはできません。

有効なコメント

# Evaluate if hour is between 1am and 12pm in the user's time zone. If so, bid $1.00. If not, bid $0.20.
if user_hour range (1, 12):
        1
else:
        0.2

有効なコメント

# Evaluate if hour is between 1am and 12pm in the user's time zone. 
# If so, bid $1.00. If not, bid $0.20.
if user_hour range (1, 12):
        1
else:
        0.2

無効なコメント

if user_hour range (1, 12): # Evaluate if hour is between 1am and 12pm in the user's time zone. if so, bid $1.00. If not, bid $0.20.
        1
else:
        0.2

完全な文法

この完全な文法は、Backus-Naur フォーム表記です。

ソースの展開

expression : ifExpression
        | switchExpression
        | leaf
        ;
ifExpression : 'if' condition consequent alternative
        ;
condition : anyCondition
        | everyCondition
        | notCondition
        | segmentCondition
        | scalarCondition
        ;
conditionList : simpleCondition
        | simpleCondition ',' conditionList
        ;
simpleCondition : simpleNotCondition
        | segmentCondition
        | scalarCondition
        ;
simpleNotCondition : 'not' simpleCondition
        ;
anyCondition : 'any' conditionList
        ;
everyCondition : 'every' conditionList
        ;
notCondition : 'not' condition
        ;
segmentCondition : 'segment' INT segmentSubconditionList
        | 'segment' INT
        ;
segmentSubconditionList : segmentSubcondition segmentSubconditionList
        | segmentSubcondition
        ;
segmentSubcondition : age < INT
        | age > INT
        | value < INT
        | value > INT
        ;
scalarCondition : feature_keyword 'present'
        | feature_keyword 'absent'
        | feature_keyword 'in' valueList
        | feature_keyword '=' value 
        | feature_keyword '>' value
        | feature_keyword '<' value
        | feature_keyword '/=' value
        | feature_keyword 'range' '(' value ',' value ')'
        ;
valueList : value
        | '(' value ',' valueList ')'
        ;
value | determind by feature;
feature_keyword : 'country'
        |'region'
        |'city'
        |'value'
        |'cookie_age' 
        |'user_hour'
        |'size'
        |'user_day'
        |'os_family'
        |'os_extended'
        |'browser'
        |'language'
        |'domain'
        |'position'
        |'placement'
        |'placement_group'
        |'publisher'
        |'seller_member_id'
        |'mobile_app'
        |'advertiser_day_freq'
        |'advertiser_life_freq'
        |'advertiser_recency'
        |'supply_type'
        |'carrier'
        |'device_type'
        |'device_model'
        |'zip'
        |'user_gender'
        |'dma'
        ;
consequent : ':' INDENT expression DEINDENT
        ;
alternative : 'elif' condition consequent alternative
        | 'else' ':' INDENT expression DEINDENT
switchExpression : 'switch' feature_keyword ':' INDENT caseList DEINDENT
        ;
caseList : case caseList 
        | default
        ;
case : 'case' valueList ':' INDENT expression DEINDENT
default : 'default' ':' INDENT expression DEINDENT
leaf : INT
    | FLOAT
    | smartLeaf
    ;
smartLeaf : keyVal smartLeaf
    | keyVal
    ;
kevVal : value
    | learn
    | name
    ; 
value : 'value' ':' valueVals
    ;
learn : 'is_learn' ':' BOOL
    ;
name : 'leaf_name' ':' ID
    ; 
valueVals : computeLeaf
    | 'no_bid'
    | numeric
    ; 
computeLeaf : 'compute' '(' inputField ',' computeVal ',' computeVal ',' computeVal ',' computeVal ')'' 
inputField : 'estimated_iab_viewthrough_rate'
    | 'estimated_video_completion_rate'
    | 'estimated_average_price'
    | 'estimated_clearing_price'
    | 'estimated_click_rate'
    | 'uniform'
    ;
computeVal : numeric
    | '_'
    ;
numeric : INT
    | FLOAT
    ;

次の方法で共有

Data Science Toolkit - Bonsai 言語

式

If/Elif/Else

例

スイッチ

例

条件

任意

毎

機能

演算子

プレゼンス/不在

比較

In

範囲

未サポート

葉

スマートリーフ

圧入

注釈

完全な文法

ソースの展開

その他のリソース

次の方法で共有

Data Science Toolkit - Bonsai 言語

式

If/Elif/Else

例

スイッチ

例

条件

任意

毎

機能

演算子

プレゼンス/不在

比較

In

範囲

未サポート

葉

スマート リーフ

圧入

注釈

完全な文法

ソースの展開

関連項目

その他のリソース

スマートリーフ