Data Science Toolkit - ALI workflow with custom models

Working with Custom Models such as Bonsai trees or Logistic Regression models and Augmented Line Items (ALI) is fairly similar to the process of working with traditional campaigns. This guide provides instructions for creating and associating custom models to an ALI. In the example below, we will create a Bonsai expected value decision tree object and use it as a bidding strategy for an ALI.

Tree creation and validation

The syntax for Bonsai trees and the features currently available for campaigns is the same for trees that work with ALI. Use the Custom Model Service for creating your custom model. The Custom Model Parser Service can be utilized to validate the Bonsai decision tree. Documentation for these services can be found here:

• Custom Model Service
• Custom Model Parser Service

Example

For the purposes of this example, we will create a simple tree (a literal '0' character) under a test advertiser:

Custom model

custom_model.json

{
  "custom_model": {
    "name": "Test Custom Model",
    "code": "mcg-test-custom-model",
    "advertiser_id": 354236,
    "custom_model_structure": "decision_tree",
    "model_output": "bid",
    "model_text": "MAo="
  }
}

POST/Creation of tree model

POST model (response abbreviated)

$ curl -b dcc -c dcc -X POST -s -d '@json/custom-model.json' "https://api-test.appnexus.com/custom-model?advertiser_id=354236"  | jq '.'
{
  "response": {
    "status": "OK",
    "count": 1,
    "id": "379792",
    "start_element": 0,
    "num_elements": 100,
    "custom_model": {
      "id": 379792,
      "name": "Test Custom Model",
      "code": "mcg-test-custom-model",
      "member_id": 958,
      "advertiser_id": 354236,
      "custom_model_structure": "decision_tree",
      "model_output": "bid",
      "compiled_text": null,
      "model_text": "MAo=",
      "original_text": "0
",
      "active": true,
      "last_modified": "2016-08-30 20:55:38"
    },
    "dbg_info": {...}
  }
}

Creating an ALI through the API

Custom models are designed to enable Xandr API users to add decision-making logic to the valuation models, non-valuation models, and creative delivery of their Augmented Line Items or campaigns. For instructions on creating an ALI, review the documentation.

Associating a custom model with an ALI

On augmented line items, there is an array field titled, 'custom_models' which lists custom models associated with a Line Item. Instructions for associating a custom model with an ALI can be found in the Line Item Model Service documentation.

Targeting IP addresses

Customers in countries that conform to GDPR regulations should be aware that when targeting IP addresses or IP ranges, either in your line item, Bonsai tree, or logistic regression model, there is a possibility the address may be truncated. For details on this process, see our Service Policies.

Multiple custom models

You will be able to associate multiple custom models of different types to the augmented line item. These include a number of custom model types that can be used to override portions of the impression's expected value calculation. An example below demonstrates how the process of associating multiple custom models to a Line Item may work:

Custom model example

update_models.json

// Update / Set a single model
{
  "line_item_model": {
      "custom_model_id": 123,
      "type": "click_imp"
    }
}
 
// Set / Update multiple models
{
  "line_item_models": [
    {
      "custom_model_id": 123,
      "type": "click_imp"
    },
    {
      "custom_model_id": 456,
      "type": "ev_click"
    }
  ]
}

Custom model types

The following model types can be associated as custom models to your Line Item: