Machine Learning

The Machine Learning (ML) API provides a framework for building custom ML models directly in Lytics. Lytics ML models are self-training, continuously-updating, and real-time. To learn about building models using the Lytics UI, see the Lookalike Model documentation.

ML models are built by identifying:

A segment of users, called the Target Segment who exhibit behavior for prediction,
A segment of users, called the Source Segment to be candidates for model evaluation, or scoring.

Models are built with a variety of pre-selected candidate features, which include behavioral scores and content affinities, and can additionally support any custom field available in Lytics user profiles.

ML model object attributes:

Field	Datatype	Description
id	string	Unique ID, Lytics assigned
name	string	Name of the ML model
label	string	User assigned label
state	string	State of the model (either 'completed', 'invalid', or 'building')
source	string	ID of the source audience
target	string	ID of the target audience
type	string	Model-type (either 'rf' or 'gbm')
is_healthy	boolean	Indicates whether a model is healthy
is_active	boolean	Indicates whether a model is active
created	Date	Created date
updated	Date	Last Updated date
config	Config	ML model configuration

Model config object attributes:

Field	Datatype	Description
use_scores	boolean	Include Lytics Behavioral Scores as features in the model
use_content	boolean	Include Lytics Content Affinities as features in the model
collect	integer	The number of samples to collect when creating the model (Default: 5000)
build_only	boolean	Build the model without scoring each user. This is useful during model building exercises when comparing efficiency and accuracy between models
auto_tune	boolean	Enable auto-tune feature selection
tune_model	booealn	Enable model parameter optimization
re_run	boolean	Re-train the model on a weekly basis
additional	[]string	List of additional user fields to include in the model

ML List

/api/ml

Get a list of all ML models for an account. For more information about ML models, consult the api/ml/:id/summary API below.

GET

ML List

/api/ml

Response 200

Headers

Content-Type: application/json

Body

{
    "data": [
        {
            "aid": 1234,
            "id": "2120ae0818414cba840b68308710b98a",
            "name": "ML: Grow Customer Base",
            "label": "Predictive Model to grow customer base",
            "state": "complete",
            "source": "cf21ba3ceb194961b964358ee92ec4a9",
            "target": "e34563f98bc848b7abb17c4a0499968c",
            "type": "rf",
            "is_healthy": true,
            "is_active": true,
            "created": "2020-08-10T16:00:00.123456789-07:00",
            "updated": "2020-08-10T16:00:00.123456789-07:00",
            "config": {
                "collect": 5000,
                "use_scores": true,
                "use_content": true,
                "build_only": false,
                "auto_tune": false,
                "model_type": "rf",
                "re_run": true,
                "tune_model": true
            }
        }
    ]
}

ML

/api/ml/{id}

Get a ML model by ID

Parameters
id	string (required) Ex: abcdefg123456	id of a ML model

GET

ML Fetch

/api/ml/{id}

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}

PUT

ML Update

/api/ml/{id}

Update a ML Model. Currently only the is_active and label attributes can be updated.

# update label 
curl -s -XPOST "https://api.lytics.io/api/ml/abcdefg123456" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d '{ "label": "my new label" }' 

http PUT "https://api.lytics.io/api/ml/abcdefg123456" key==$LIOKEY label=="my new label"

# update is_active
curl -s -XPOST "https://api.lytics.io/api/ml/abcdefg123456" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d '{ "is_active": true }' 

http PUT "https://api.lytics.io/api/ml/abcdefg123456" key==$LIOKEY is_active==false

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}

DELETE

ML Delete

/api/ml/{id}

Delete a ML Model

Response 204

POST

ML Create

/api/ml/{id}

Create a new ML model.

# Create a simple model 
http POST "https://api.lytics.io/api/ml" key==$LIOKY \
    source==<source_segment_id> \ 
    target==<target_segment_id> \
    label=="my new model"

# Create a custom model 
echo '{
    "source": "<source_segment_id>",
    "target": "<target_segmente_id>",
    "name": "Grow Customer Base",
    "label": "Model to increase customer base",
    "config": {
        "use_scores": true,
        "use_content": true,
        "additional": [ "city", "visit_ct", "utm_mediums" ]
    }
}' | http POST "https://api.lytics.io/api/ml" key==$key

Response 201

Headers

Content-Type: application/json

Body

{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}

ML Summary

/api/ml/{id}/summary

Get a summary of a ML model

GET

ML Model Summary Fetch

/api/ml/{id}/summary

Get a ML model summary

Additional atttributes from a ML model

field	DataType	Description
features: kind	string	The field is either a Lytics Segment feature (segment), a lql/user-field feature (lql), a Lytics Behavioral Score feature (score), or a Lytics Content Affinity feature (content)
features: fieldtype	string	Field type is either numeric or categorical
features: name	string	The name of a field
features: importance	number	The relative importance of a field in the model
features: correlation	number	Correlation between specific field and target
features: impact	object	The impact object details the Lift and shows the marginal effect of a feature on the predicted outcome of the model
mse	number	Mean-squared error value
rsq	number	R-squared value or coefficient of determination
false_negative	number	The number of users in the source segment who are predicted to be in the target segment.
false_positive	number	The number of users in the target segment who are not predicted to be in the target segment.
true_negative	number	The number of users in the source segment who are not predicted to be in the target segment.
true_positive	number	The number of users in the target segment who are predicted to be in the target segment.
success	[]number	Number of successful predictions for a given prediction value
failure	[]number	Number of failed predictions for a given prediction value
auc	number	Area under the ROC curve
threshold	number	Optimal decision threshold to minimize false-positives and false-negatives
accuracy	number	A value that represents the accuracy of the model; scale ranges from 0 (least accurate) to 10 (most accurate).
reach	number	A value that represents the number of source users that look like target users; scale ranges from 0 (low reach) to 10 (high reach).
model_health	number	The overall health of the model (i.e. "healthy", "unhealthy")
msgs	number	Messages for the user about the model with levels of severity (i.e. "debug", "info", "warn", "error")

To learn more about the metrics false negative, false positive etc., check out binary classification.

# Curl example of getting a SegmentML model
curl -s -J -XGET "https://api.lytics.io/api/ml/abcdef123/summary" -H "Authorization: $LIOKEY"

Parameters
id	string (required) Ex: abcdef123	ID of the ML model to retrieve

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "abcdefg123456",
        "name": "My Custom ML Model",
        "summary": {
            "mse": 0.09,
            "rsq": 0.91,
            "auc": 0.90,
            "threshold": 0.55,
            "accuracy": 8,
            "reach": 4,
            "audience_similarity": 0.33,
            "health":  "healthy"
        },
        "features": [
            {
                "kind": "score",
                "type": "numeric",
                "name": "score_intensity",
                "importance": 47.123,
                "correlation": 0.11,
                "prevalance": {
                    "source": 0.84,
                    "target": 0.91
                },
                "impact": {
                    "lift": 0.22,
                    "threshold": 0.1,
                    "value": 40
                }
            },
            {
                "kind": "content",
                "type": "numeric",
                "name": "lytics_content::Baking",
                "importance": 12.123,
                "correlation": 0.29,
                "prevalance": {
                    "source": 0.14,
                    "target": 0.41
                },
                "impact": {
                    "lift": 0.02,
                    "threshold": 0.11,
                    "value": 0.71
                }
            }
        ]
    }
}

Machine Learning

ML model object attributes:

Model config object attributes:

ML List

ML List

Response 200

Headers

Body

ML

ML Fetch

Response 200

Headers

Body

ML Update

Response 200

Headers

Body

ML Delete

Response 204

ML Create

Response 201

Headers

Body

ML Summary

ML Model Summary Fetch

Response 200

Headers

Body

Account Setting

User