Data Science Toolkit - Bonsai smart leaves

You use the Bonsai Language to write decision tree logic for custom predictive models. Each branch leads to a node, or "leaf", that evaluates to a simple numeric value representing the bid. Instead of evaluating a single static value, smart leaves evaluate a bid value that's dynamically modified based on a specified ad performance or delivery metric. Smart leaves also allow you to name individual leaves with an arbitrary string value. This is available in the standard feed to aid debugging and performance analysis.

compute() syntax

You can use smart leaves to specify a static value or a bid calculated from an advertising metric or to specify that no bid be made at all. If the value is calculated, it is determined by the compute expression, which uses the following format:

value: compute(input_field, multiplier, offset, min_value, max_value)

This is evaluated as the following equation:

max(min_value, min(max_value, input_field * multiplier + offset))

That is, the calculated value is the input field times the multiplier, plus an offset. If the result is less than the minimum value, the minimum value is returned instead. If the result is greater than the maximum value, the maximum value is returned. To omit a calculation (multiplier, offset, minimum value, or maximum value), use an underscore (_) for the omitted value. If you omit to specify the multiplier value, the default value is 1.

Smart leaf fields

Input fields for compute()

The values for the input fields are determined by Xandr optimization. For more information, see the Optimization Guide for the Augmented Line Item in the documentation (login required).

Use segments as input for compute()

You can perform calculations using the value or age of the user in a first-party or third-party segment to determine a bid value. If the user is not present in the segment, no bid is made. Use the Segment Service to retrieve segment IDs.

Use frequency or recency as inputs for compute()

You can perform calculations using frequency or recency to determine a bid value.

Examples

Bid price with estimated average price

One leaf has a minimum allowable bid price but no limit on the maximum.

    # This tree determines a bid price as follows: 
    # 1. If the user is in California, bid the estimated average price * 1.05, plus $0.03.
    # 2. Otherwise, bid the estimated average price * .75, but don't bid less than $1.00. There is no maximum bound for bids.
     
    if region = "US:CA":
            leaf_name: "eap001"
            value: compute(estimated_average_price, 1.05, 0.03, _, _)       
    else:
            leaf_name: "eap002"
           value: compute(estimated_average_price, 0.75, 0.00, 1.00, _)

Bid price tree with estimated clearing price, no bid, and static value smart leaves

# This tree determines a bid price as follows: 
# 1. If the user is in California, bid the estimated clearing price * 1.05, plus $0.03.
# 2. If the user is in New York, bid the estimated clearing price * .75, but don't bid less than $0.10 or more than $1.00. 
# 3. If the user is in Delaware, do not bid.
# 4. Otherwise, bid $0.50.
if region = "US:CA":
        leaf_name: "ecp_ca"
        value: compute(estimated_clearing_price, 1.05, 0.03, _, _)      
elif region = "US:NY":
        leaf_name: "ecp_ny"
        value: compute(estimated_clearing_price, 0.75, _, 0.10, 1.00)
elif region = "US:DE":
        leaf_name: "no_de"
        value: no_bid
else:
        leaf_name: "default"
        value: 0.50

Bid price tree with estimated IAB viewthrough rate smart leaves

# This tree determines a bid modifier as follows: 
# 1. If the user is in California, bid the value determined by Xandr optimization multipled by the estimated IAB viewthrough rate and 0.50, plus $0.03.
# 2. If the user is in New York, bid the value determined by Xandr optimization multiplied by the estimated IAB viewthrough rate and 0.75. 
# 3. If the user is in Delaware, bid the estimated clearing price, but don't bid less than $0.10 or more than $1.00.
# 4. Otherwise, bid $0.50.
if every region = "US:CA":
        leaf_name: "t00001"
        value: compute(estimated_iab_viewthrough_rate, 0.50, 0.03, _, _)        
elif region = "US:NY":
        leaf_name: "t00002"
        value: compute(estimated_iab_viewthrough_rate, 0.70, 0.00, _, _)
elif region = "US:DE":
        leaf_name: "t00003"
        value: compute(estimated_clearing_price, 1.00, _, 0.10, 1.00)
else:
        leaf_name: "default"
        value: 0.50

Bid based on segment value

#1. If the user is in California, bid the value of segment 111 times 2.0, plus 1.0.
#2. Otherwise, do not bid.
if region = "US:CA":
        leaf_name: "a00001"
        value: compute(segment[111].value, 2.0, 1.0, _, _)
else:
        value: no_bid

Bid based on segment age

#1. If the user is in California, bid the segment age times -.2, plus 8.0, as long as the bid is under 8.0.
#2. Otherwise, do not bid.
 
if region = "US:CA":
        leaf_name: "b00001"
        value: compute(segment[111].age, -0.2, 8.0, 0.0, 8.0)
else:
        value: no_bid

Bid based on daily frequency

#1. If the user is in California and in segment 111, bid the user's daily frequency for line item 222 times -.2, plus 5, with an upper bound of 4.
#2. Otherwise, do not bid.
 
if every region="US:CA", segment[111]:
        leaf_name: "d0001"
        value: compute(line_item[222].day_frequency, -0.2, 5.0, 0.0, 4.0)
else:
        leaf_name: "d0000"
        value: no_bid

Bid based on lifetime frequency

#1. If the user is in California and in segment 111, bid the lifetime frequency for creative 333 times -.2, plus 8, with an upper bound of 6.
#2. Otherwise, do not bid.
 
if every region="US:CA", segment[111]:
        leaf_name: "e0001"
        value: compute(creative[333].lifetime_frequency, -0.2, 8.0, 0.0, 6.0)
else:
        leaf_name: "e0000"
        value: no_bid

Bid based on recency

#1. If the user is in California, bid the recency for creative 333 times -.2, plus 8, with an upper bound of 6.
#2. Otherwise, do not bid.
 
if region="US:CA":
        leaf_name: "f0001"
        value: compute(creative[333].recency, -0.2, 8.0, 0.0, 6.0)
else:
        leaf_name: "f0000"
        value: no_bid

Related topics

• Custom Models
• The Bonsai Language
• Bonsai Features
• Custom Model Parser Service
• Custom Model Service