Data Science Toolkit: el lenguaje Bonsai

El lenguaje Bonsai está diseñado para escribir lógica de árbol de decisión para modelos predictivos personalizados. En esta página se explica la sintaxis y la semántica principal del lenguaje Bonsai. Para obtener referencia adicional, también hemos proporcionado la gramática completa en Backus-Naur notación formulario.

Expresiones

Un árbol de decisión escrito en Bonsai se estructura como una branch o una serie de ramas escritas como if/elif/else expresiones o switch .  El resultado de se branch conoce como o leafleaf value. La variable que recibe leaf value depende del modelo personalizado que se use. Por ejemplo, si usó un modelo personalizado con un model_output que tiene un tipo de se aplicaría al precio de bidleaf la oferta de CPM del uso del modelo personalizado.

Nota:

Las pujas que son negativas o cero (0) no se admiten a menos que se especifiquen explícitamente en la descripción de la característica. No use estas expresiones ni se pueden producir resultados inesperados. Es mejor especificar no_bid explícitamente mediante hojas inteligentes de Bonsai.

If/Elif/Else

Cada if debe tener una coincidencia else. Puede haber 0 o más elif expresiones entre if y .else

Ejemplo

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

En este ejemplo se muestra una if/elif/else expresión con una expresión anidada if/else . La ruta de acceso de decisión de este ejemplo es la siguiente:

1. ¿El usuario reside en Estados Unidos?
   • Si es así, puja 1.
   • Si no es así, vaya al paso 2.
2. ¿Está entre las 8 a. m. y las 12 p. m. en la zona horaria del usuario?
   • Si es así, vaya al paso 3.
   • Si no es así, puja 0.1.
3. ¿El dominio es "news.com"?
   • Si es así, puja 0,85.
   • Si no es así, puja 0.2.

Modificador

Una switch expresión se puede usar como alternativa a muchas instrucciones encadenados if/elif . Esto puede ser útil si tiene muchos valores que desea probar para una sola característica.

Algunas cosas a tener en cuenta sobre switch las expresiones:

• Cada caso debe comenzar con la palabra clave case.
• Un caso puede ser un valor único, una lista de valores o un intervalo. Los rangos solo se pueden usar para valores numéricos.  
• El valor, la lista de valores o el intervalo de valores de cada caso se deben encapsular entre paréntesis.
• Un intervalo se indica mediante dos períodos (..). Puede usar un intervalo con uno o dos límites. Los límites son inclusivos. Por ejemplo, ( .. 3) se aplica a todos los casos numerados hasta e incluido 3.
• Un caso puede conducir a una hoja o a otra expresión.
• Una switch expresión debe concluir con un default caso. Esto garantiza que cada hoja del árbol tiene un valor.

Ejemplo

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

La ruta de acceso de decisión de este ejemplo es la siguiente:

1. ¿La zona horaria del usuario está entre la 1 a. m. y las 3 a. m.?
   • Si es así, puja 0.4.
   • Si no es así, vaya al paso 2.
2. ¿Son las 4, las 6 u las 8 de la mañana en la zona horaria del usuario?
   • Si es así, vaya al paso 3.
   • Si no es así, puja 0.1.
3. ¿Está presente el país?
   • Si es así, puja 0,8.
   • Si no es así, puja 0,4.

Condiciones

En if las instrucciones y elif , puede usar las any condiciones y every para aplicar lógica booleana a una serie de características.

Nota:

No es posible combinar any y every condiciones en una sola if instrucción o elif .

Cualquiera

Cuando se usa la any condición en una if instrucción o elif , los separadores de comas entre los valores de característica son efectivamente "ors". Esto significa que si alguna de las características de la instrucción coincide con la impresión, se evaluará la hoja.

En este ejemplo, si la hora está presente O el país está presente O y es domingo, lunes o martes, la 1 hoja se evaluará:

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

Cada

Cuando se usa la every condición en una if instrucción o elif , los separadores de comas entre los valores de característica son efectivamente "y". Esto significa que si todas las características de la instrucción coinciden con la impresión, se evaluará la hoja.

En este ejemplo, si la hora está presente Y el país está presente Y y es domingo, lunes o martes, la 1 hoja se evaluará:

Características

Un elemento sintáctico central de Bonsai es la característica. Una característica se compone de:

1. Una palabra clave
2. Conjunto de valores válidos

En el ejemplo siguiente, la palabra clave feature es user_dayy sus valores válidos son enteros entre 06-, donde 0 es sunday y 6 es saturday.

if user_day < 6:
        1
else:
        2 

Cuando se usa un valor no válido para una palabra clave de característica, la API devolverá un error que le informará de la ubicación exacta y la naturaleza del problema en el árbol de decisión:

if user_day < 100:
        1
else:
        2

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

Para obtener más información sobre la validación de Bonsai, consulte Validación del árbol de decisión y Mensajes de error.

Para obtener una lista completa de las características disponibles y sus valores válidos, consulte Características de Bonsai. Tenga en cuenta que algunas características son numéricas (como user_hour) mientras que otras no (como country). Algunos operadores numéricos solo son válidos para los tipos numéricos.

Nota:

La segment característica se controla de forma diferente a todas las demás. Solo se puede probar en función de lo siguiente:

• Presencia de segmentos
• Número de minutos transcurridos desde que el usuario se agregó al segmento
• Valor definido por el usuario pasado con el segmento

Para obtener más detalles, vea Segment Presence, Segment Age y Segment Value in Bonsai Features.

Operadores

Presencia/ausencia

Los present operadores y absent se usan para probar la presencia o ausencia de características:

if country present:
        2
else:
        1

Comparison

Se admiten los siguientes operadores de comparación.

Operador	Significado
=	Igual a
!=	Distinto de
/=	Distinto de
<	Menor que (solo se puede usar con enteros)
>	Mayor que (solo se puede usar con enteros)
<=	Menor o igual que (solo se puede usar con enteros)
>=	Mayor o igual que (solo se puede usar con enteros)

if country = "US":
        2
else:
        1

En

El in operador se usa para probar si un valor de característica coincide con cualquier valor de una lista de valores posibles. Tenga en cuenta que la lista debe encapsularse entre paréntesis.

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

Rango

El range operador se usa para probar un valor de característica para la pertenencia a un intervalo inclusivo de valores.

• Este operador solo se puede usar con valores enteros. 

• El intervalo entero debe ajustarse entre paréntesis.

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

El ejemplo anterior probaría si la hora está en cualquier lugar entre la 1 a. m. y las 12 p. m. en la zona horaria del usuario.

Nota:

Al usar un intervalo para especificar los casos de una expresión de modificador, use dos puntos (..) dentro del intervalo, en lugar de una coma. Para obtener más información, vea Switch.

No

La not palabra clave se usa para negar una condición.

if not country present:
        1
else:
        0.2

Hoja

Cada rama de árbol conduce a un valor hoja.

• Cada hoja puede ser un entero o float.  
• Para modelos personalizados con :"bid"model_output
  • Cada hoja es un precio de oferta cpm en la moneda del uso del modelo personalizado.
• Para modelos personalizados con :"bid_modifier"model_output
  • Cada hoja es un multiplicador que se va a aplicar a una puja de CPM derivada de la optimización de Xandr.

En el "bid"model_output ejemplo siguiente, cuando se usa en un en USD, las hojas dan como resultado valores de puja de 1,00 USD cpm y 0,25 USD.

if not country present:
        1
else:
        0.25

Hoja inteligente

Las hojas inteligentes modifican dinámicamente las pujas en función de una serie de métricas estimadas de rendimiento y entrega de anuncios.

• Las hojas inteligentes admiten tanto el y "bid""bid_modifier" model_outputcomo .
• Las hojas inteligentes permiten especificar un "no_bid" valor.
• Las hojas inteligentes permiten asignar un nombre a las hojas con el leaf_name campo .
• Los valores de puja se pueden derivar de:
  • Tasa de obtención de acceso de IAB estimada
  • Precio medio estimado
  • Precio claro estimado
  • Números aleatorios uniformes

En el ejemplo siguiente, el precio de la oferta es el precio medio estimado multiplicado por 1,5 y compensado por 0,03 USD, con un valor mínimo de 1 USD y un valor máximo de 5 USD:

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

Para obtener más información, vea Hojas inteligentes de Bonsai.

Sangría

El carácter de tabulación (\t) se usa para indicar la sangría de una línea, que a su vez se usa para determinar la agrupación de expresiones (similar a Python). Por el momento, solo se admiten pestañas (se omiten los espacios). El carácter de nueva línea (\n) se usa para marcar el final de una línea.

Comentarios

El # carácter es para los comentarios. Un comentario es una línea de texto que Bonsai no intentará ejecutar como código. Es sólo para que los humanos lean.

Los comentarios facilitan la comprensión del código. Al examinar el código u otros usuarios que quieran colaborar con usted, pueden leer los comentarios y averiguar fácilmente lo que hace el código.

• Cada comentario debe estar en su propia línea y debe comenzar con el # carácter .

• Si escribe un comentario de varias líneas, cada línea debe comenzar con el # carácter .

• En este momento, no es posible insertar comentarios en la misma línea que otro código bonsai.

  Comentario válido

  # 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
  

  Comentario válido

  # 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
  

  Comentario no válido

  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
  

Gramática completa

Esta gramática completa está en Backus-Naur notación form.

Expandir origen

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
    ; 

Temas relacionados

• Servicio de analizador de modelos personalizados
• Servicio de modelo personalizado
• Características del lenguaje Bonsai
• Hojas inteligentes de Bonsai
• Creación de un modelo personalizado de árbol de decisión de Bonsai
• Flujo de trabajo del modelo personalizado de Bonsai
• Modelos personalizados