Science des données Toolkit - La langue Bonsai

Le langage Bonsai est conçu pour écrire une logique d’arbre de décision pour les modèles prédictifs personnalisés. Cette page explique la syntaxe et la sémantique de base du langage Bonsai. Pour plus de référence, nous avons également fourni la grammaire complète dans Backus-Naur notation de formulaire.

Expressions

Un arbre de décision écrit en Bonsai est structuré sous la forme d’une branch ou d’une série de branches écrites en tant qu’expressions if/elif/else et/ou switch .  Le résultat d’un branch est appelé leaf ou leaf value. La variable qui reçoit dépend leaf value du modèle personnalisé utilisé. Par exemple, si vous avez utilisé un modèle personnalisé avec un model_output qui a un type de serait appliqué au prix de bidleaf l’offre CPM du à l’aide du modèle personnalisé.

If/Elif/Else

Chaque if doit avoir un correspondant else. Il peut y avoir 0 ou plusieurs elif expressions entre et if le correspondant else.

Exemple

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

Cet exemple montre une if/elif/else expression avec une expression imbriquée if/else . Le chemin de décision de cet exemple est le suivant :

1. L’utilisateur réside-t-il dans le États-Unis ?
   • Si oui, enchérir 1.
   • Si non, passez à l’étape 2.
2. Est-ce entre 8 h et 12 h dans le fuseau horaire de l’utilisateur ?
   • Si oui, passez à l’étape 3.
   • Si non, enchérir 0,1.
3. Le domaine est-il « news.com » ?
   • Si oui, enchérir 0,85.
   • Si non, enchérir 0,2.

Commutateur

Une switch expression peut être utilisée comme alternative à de nombreuses instructions chaînées if/elif . Cela peut être utile si vous avez de nombreuses valeurs que vous souhaitez tester pour une seule fonctionnalité.

Voici quelques points à noter sur les switch expressions :

• Chaque cas doit commencer par le mot clé case.
• Un cas peut être une valeur unique, une liste de valeurs ou une plage. Les plages ne peuvent être utilisées que pour les valeurs numériques.  
• La valeur, la liste de valeurs ou la plage de valeurs pour chaque cas doivent être placées entre parenthèses.
• Une plage est désignée par deux points (..). Vous pouvez utiliser une plage avec une ou deux limites. Les limites sont inclusives. Par exemple, ( .. 3) s’applique à tous les cas numérotés jusqu’à et dont 3.
• Un cas peut conduire à une feuille ou à une autre expression.
• Une switch expression doit se terminer par un default cas. Cela garantit que chaque feuille de l’arbre a une valeur.

Exemple

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

Le chemin de décision de cet exemple est le suivant :

1. Le fuseau horaire de l’utilisateur est-il compris entre 1h et 3h du matin ?
   • Si oui, enchérir 0,4.
   • Si non, passez à l’étape 2.
2. Est-il 4, 6 ou 8 heures dans le fuseau horaire de l’utilisateur ?
   • Si oui, passez à l’étape 3.
   • Si non, enchérir 0,1.
3. Le pays est-il présent ?
   • Si oui, enchérir 0,8.
   • Si non, enchérir 0,4.

Conditions

Dans if les instructions et elif , vous pouvez utiliser les conditions et every pour appliquer une any logique booléenne à une série de fonctionnalités.

N’importe lequel

Lorsque vous utilisez la any condition dans une if instruction ou elif , les séparateurs de virgules entre les valeurs de caractéristique sont en fait « ors ». Cela signifie que si l’une des caractéristiques de l’instruction correspond à l’impression, la feuille est évaluée.

Dans cet exemple, si l’heure est présente OU que le pays est présent OU que c’est le dimanche, le lundi ou le mardi, la 1 feuille est évaluée :

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

Chaque

Lorsque vous utilisez la every condition dans une if instruction ou elif , les séparateurs de virgules entre les valeurs de fonctionnalité sont en fait « ands ». Cela signifie que si toutes les caractéristiques de l’instruction correspondent à l’impression, la feuille est évaluée.

Dans cet exemple, si l’heure est présente ET que le pays est présent ET que c’est le dimanche, le lundi ou le mardi, la 1 feuille est évaluée :

Fonctionnalités

Un élément syntaxique central de Bonsai est la caractéristique. Une fonctionnalité est composée des fonctionnalités suivantes :

1. Un mot clé
2. Ensemble de valeurs valides

Dans l’exemple ci-dessous, la fonctionnalité mot clé est user_day, et ses valeurs valides sont des entiers compris entre 06-, où 0 est dimanche et 6 samedi.

if user_day < 6:
        1
else:
        2 

Lorsque vous utilisez une valeur non valide pour un mot clé de fonctionnalité, l’API retourne une erreur vous informant de l’emplacement exact et de la nature du problème dans votre arbre de décision :

if user_day < 100:
        1
else:
        2

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

Pour plus d’informations sur la validation Bonsai, consultez Validation de l’arbre de décision et messages d’erreur.

Pour obtenir la liste complète des fonctionnalités disponibles et leurs valeurs valides, consultez Fonctionnalités Bonsai. Notez que certaines fonctionnalités sont numériques (telles que user_hour) tandis que d’autres ne le sont pas (comme country). Certains opérateurs numériques ne sont valides que pour les types numériques.

Opérateurs

Présence/absence

Les present opérateurs et absent sont utilisés pour tester la présence/l’absence de fonctionnalité :

if country present:
        2
else:
        1

Comparaison

Les opérateurs de comparaison suivants sont pris en charge.

if country = "US":
        2
else:
        1

Dans le paramètre

L’opérateur in est utilisé pour tester si une valeur de fonctionnalité correspond à une valeur dans une liste de valeurs possibles. Notez que la liste doit être encapsulée entre parenthèses.

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

Plage

L’opérateur range est utilisé pour tester l’appartenance à une valeur de fonctionnalité dans une plage de valeurs inclusive.

• Cet opérateur ne peut être utilisé qu’avec des valeurs entières. 

• La plage d’entiers doit être encapsulée entre parenthèses.

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

L’exemple ci-dessus teste si l’heure est comprise entre 1 h et 12 h dans le fuseau horaire de l’utilisateur.

Not

Le not mot clé est utilisé pour nier une condition.

if not country present:
        1
else:
        0.2

Feuille

Chaque branche d’arbre conduit à une valeur feuille.

• Chaque feuille peut être un entier ou un float.  
• Pour les modèles personnalisés avec :"bid"model_output
  • Chaque feuille est un prix d’enchère cpm dans la devise du à l’aide du modèle personnalisé.
• Pour les modèles personnalisés avec :"bid_modifier"model_output
  • Chaque feuille est un multiplicateur à appliquer à une offre CPM dérivée de l’optimisation Xandr.

Dans l’exemple "bid"model_output ci-dessous, lorsqu’ils sont utilisés dans un en USD, les feuilles aboutissent à des valeurs d’enchères de 1,00 $ CPM et de 0,25 $ CPM.

if not country present:
        1
else:
        0.25

Feuille intelligente

Smart laisse modifier dynamiquement les enchères en fonction d’un certain nombre de métriques estimées de performances publicitaires et de livraison.

• Les feuilles intelligentes prennent en charge les "bid" et "bid_modifier" model_output.
• Les feuilles intelligentes vous permettent de spécifier une "no_bid" valeur.
• Les feuilles intelligentes vous permettent de nommer les feuilles avec le leaf_name champ .
• Les valeurs d’enchère peuvent être dérivées de :
  • Taux d’affichage de l’IAB estimé
  • Prix moyen estimé
  • Prix clair estimé
  • Nombres aléatoires uniformes

Dans l’exemple ci-dessous, le prix de l’offre est le prix moyen estimé multiplié par 1,5 et décalé par 0,03 $, avec une valeur minimale de 1 $ et une valeur maximale de 5 $ :

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

Pour plus d’informations, consultez Bonsai Smart Leaves.

Indentation

Le caractère de tabulation (\t) est utilisé pour indiquer la mise en retrait d’une ligne, qui à son tour est utilisée pour déterminer le regroupement des expressions (similaire à Python). Pour le moment, seuls les onglets sont pris en charge (les espaces sont ignorés). Le caractère newline (\n) est utilisé pour marquer la fin d’une ligne.

Commentaires

Le # caractère est destiné aux commentaires. Un commentaire est une ligne de texte que Bonsai n’essaie pas d’exécuter en tant que code. C’est juste pour les humains de lire.

Les commentaires facilitent la compréhension de votre code. Lorsque vous examinez votre code ou que d’autres personnes souhaitent collaborer avec vous, ils peuvent lire vos commentaires et déterminer facilement ce que fait votre code.

• Chaque commentaire doit être sur sa propre ligne et doit commencer par le # caractère .

• Si vous écrivez une commentaire de ligne, chaque ligne doit commencer par le # caractère .

• Pour l’instant, il n’est pas possible d’insérer des commentaires sur la même ligne que d’autres codes Bonsai.

  Commentaire valide

  # 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
  

  Commentaire valide

  # 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
  

  Commentaire non valide

  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
  

Grammaire complète

Cette grammaire complète se trouve dans Backus-Naur notation de forme.

Développer la source

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
    ; 

Voir aussi

• Service d’analyseur de modèle personnalisé
• Service de modèle personnalisé
• Fonctionnalités du langage Bonsai
• Feuilles intelligentes Bonsai
• Create un modèle personnalisé d’arbre de décision Bonsai
• Flux de travail du modèle personnalisé Bonsai
• Modèles personnalisés