Developing with Lytics / Lytics API Documentation

SegmentML

SegmentML provides a framework for building custom machine learning models directly in Lytics. Lytics SegmentML models are self-training, continuously-updating and real-time.

SegmentML models are built by identifying:

  1. A segment of users, called the Target Segment who exhibit behavior for prediction,

  2. 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.

Attributes concerning the SegmentML model's setup configuration are detailed in SegmentML Create. Attributes concerning the model's results are defined in SegmentML Model Fetch.

Generic attributes from SegmentML model GET and POST:

fieldDataTypeDescription
namestringThe model's name
statestringThe state of the model: Either building, invalid, or complete
reasonstringIf the state is invalid the reason will denote the error
createdstringDate and time the model was created

SegmentML

/api/segmentml/{id}
GET

SegmentML Model Fetch

/api/segmentml/{id}

Get a SegmentML model.

Additional atttributes from a completed SegmentML model GET response:

fieldDataTypeDescription
features: kindstringThe 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)
feautres: fieldtypestringField type is either numeric or categorical
features: namestringThe name of a field
features: importancenumberThe relative importance of a field in the model
features: correlationnumberCorrelation between specific field and target
msenumberMean-squared error value
rsqnumberR-squared value or coefficient of determination
false_negativenumberThe number of users in the source segment who are predicted to be in the target segment.
false_positivenumberThe number of users in the target segment who are not predicted to be in the target segment.
true_negativenumberThe number of users in the source segment who are not predicted to be in the target segment.
true_positivenumberThe number of users in the target segment who are predicted to be in the target segment.
successnumber:numberNumber of successful predictions for a given prediction value
failurenumber:numberNumber of failed predictions for a given prediction value
aucnumberROC Area under curve
thresholdnumberCorrelation threshold at which to discard features in the model

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/segmentml/all::smt_power" -H "Authorization: $LIOKEY"
Parameters
idstring (required)
Ex: source::target
ID of the SegmentML model to retrieve, of the form `SOURCE_SLUG::TARGET_SLUG`.

Response 200

Body
    {
        "name": "test_rf",
        "state": "complete",
        "reason": "",
        "created": "2018-07-11T13:29:05.541395646-07:00",
        "conf": {
            "source": {
                "aid": 123,
                "account_id": "lol",
                "id": "",
                "name": "all",
                "is_public": false,
                "slug_name": "",
                "description": "",
                "author_id": "",
                "updated": "0001-01-01T00:00:00Z",
                "created": "2018-07-11T13:29:05.529857044-07:00",
                "invalid": false,
                "invalid_reason": "",
                "deleted": false,
                "datemath_calc": false,
                "forward_datemath": false,
                "save_hist": false,
                "schedule_exit": false,
                "tags": null
            },
            "target": {
                "aid": 123,
                "account_id": "lol",
                "id": "",
                "name": "goal",
                "is_public": false,
                "slug_name": "",
                "description": "",
                "author_id": "",
                "updated": "0001-01-01T00:00:00Z",
                "created": "2018-07-11T13:29:05.529857281-07:00",
                "invalid": false,
                "invalid_reason": "",
                "deleted": false,
                "datemath_calc": false,
                "forward_datemath": false,
                "save_hist": false,
                "schedule_exit": false,
                "tags": null
            },
            "target_field": null,
            "additional": null,
            "collections": null,
            "collect": 0,
            "use_scores": true,
            "use_content": false,
            "write_to_gcs": false,
            "build_only": false
        },
        "features": [
            {
                "kind": "segment",
                "type": "numeric",
                "name": "all",
                "importance": 4.7989306961749,
                "correlation": 0.96589217433474
            },
            {
                "kind": "segment",
                "type": "numeric",
                "name": "aspect_aspect_known_email",
                "importance": 0.99674901777453,
                "correlation": -0.99651332091371
            },
            {
                "kind": "segment",
                "type": "numeric",
                "name": "lytics_score_momentum",
                "importance": 15.98742606104,
                "correlation": 0.99805972372001
            },
            {
                "kind": "segment",
                "type": "numeric",
                "name": "goal",
                "importance": 0,
                "correlation": 1
            }
        ],
        "summary": {
            "conf": {
                "false_positive": 12,
                "true_positive": 27,
                "false_negative": 11,
                "true_negative": 23
            },
            "mse": 0.043853370740741,
            "rsq": 0.93170981829093,
            "success": {
                "0.00": 2,
                "0.03": 1,
                "0.04": 2,
                "0.09": 2,
                "0.14": 4,
                "0.20": 2,
                "0.33": 5,
                "0.40": 2,
                "0.45": 2,
                "0.50": 2,
                "0.53": 1,
                "0.54": 2,
                "0.56": 4,
                "0.61": 2,
                "0.67": 2,
                "0.68": 1,
                "0.71": 2,
                "0.74": 1,
                "0.82": 2,
                "0.84": 2,
                "0.86": 2,
                "0.90": 3,
            },
            "fail": {
                "0.10": 1,
                "0.30": 2,
                "0.44": 2,
                "0.53": 3,
                "0.66": 3,
                "0.78": 4,
                "1.00": 2,
            },
            "auc": 0.76,
            "threshold": 0.9
        }
    }
POST

SegmentML Create

/api/segmentml{?source,target,target_field,use_scores,use_content,aspect_collections,additional_fields,model_only,eval_only,tune_model,write_to_gcs,tags,re_run,save_segments,as_is,num_to_train,cor_threshold}

Create a new SegmentML model.

In order to create models with this endpoint, the account must have the use_segmentml account setting. This can be enabled by contacting Lytics Customer Success.

Model configuration can be specified either through sending the options as a flat JSON object POST body or through URL parameters on the request.

# Curl example of creating a SegmentML model
curl -s -J -XPOST "https://api.lytics.io/api/segmentml" -H "Authorization: $LIOKEY" -d '
{
    "source": "all",
    "target": "smt_power",
    "use_scores": true
}
'
Parameters
sourcestring (required)
Ex: all
ID or slug of the source segment.
targetstring (optional)
Ex: smt_power
ID or slug of the target segment. **Required** if target field is not supplied.
use_scoresboolean (optional)
Ex: true
Include raw behavioral scores as features in the model (usually very useful).
target_fieldstring (optional)
Ex: LTV
Slug of the target field. Cannot provide both a target and a target field, hence required if target segment is not indicated (see above).
use_contentboolean (optional)
Ex: false
If true, include content affinities as features in the model.
aspect_collections[]string (optional)
Ex: ["web", "mobile"]
List of Segment Collections to include in the model. Possible values are "email", "web", "support", "mobile", "commerce", "behaviors", "content".
additional_fields[]string (optional)
Ex: ["age", "country"]
List of additional user fields to include in the model.
model_onlyboolean (optional)
Ex: true
Build the model without scoring each user. This is useful during model building exercises when comparing efficiency and accuracy between models. Set true by default unless **evalonly** is selected.
eval_onlyboolean (optional)
Ex: false
If true, a previously built model is used to rescore users. Only the source and target parameters are needed in the API call to to identify which model to use.
tune_modelboolean (optional)
Ex: false
If true, model tuning parameters are optimized before any models are built. Experimental.
write_to_gcsboolean (optional)
Ex: false
If true, model will be saved to GCS.
tags[]string (optional)
Ex: ["increase momentum", "mobile users"]
Includes tags to be associated with the model.
re_runboolean (optional)
Ex: false
If true, re-run the model every week.
save_segmentsboolean (optional)
Ex: false
If true, this saves three different segments: 1) Users from source and target segments who "look like" users from the target segment. 2) Users not in the target segment. 3) Users from the source segment who look like users from the target segment.
as_isboolean (optional)
Ex: false
If true, do not remove any of the model features when creating the model.
num_to_trainnumber (optional)
Ex: 5000
The number of samples to collect from both the source and target segment for feature matrices. Defaults to 5,000.
cor_thresholdnumber (optional)
Ex: 0.9
Threshold (0.0-1.0) at which to remove correlated features.

Response 201

Headers
Content-Type: application/json
Body
{
    "name": "test_rf",
    "state": "building",
    "reason": "",
    "created": "2018-07-10T16:10:54.456003352-07:00",
    "conf": {
        "source": {
            "aid": 123,
            "account_id": "lol",
            "id": "",
            "name": "all",
            "is_public": false,
            "slug_name": "",
            "description": "",
            "author_id": "",
            "updated": "0001-01-01T00:00:00Z",
            "created": "2018-07-10T16:10:54.442558895-07:00",
            "invalid": false,
            "invalid_reason": "",
            "deleted": false,
            "datemath_calc": false,
            "forward_datemath": false,
            "save_hist": false,
            "schedule_exit": false,
            "tags": null
        },
        "target": {
            "aid": 123,
            "account_id": "lol",
            "id": "",
            "name": "goal",
            "is_public": false,
            "slug_name": "",
            "description": "",
            "author_id": "",
            "updated": "0001-01-01T00:00:00Z",
            "created": "2018-07-10T16:10:54.442559277-07:00",
            "invalid": false,
            "invalid_reason": "",
            "deleted": false,
            "datemath_calc": false,
            "forward_datemath": false,
            "save_hist": false,
            "schedule_exit": false,
            "tags": null
            },
        "target_field": null,
        "additional": null,
        "collections": null,
        "collect": 0,
        "use_scores": true,
        "use_content": false,
        "write_to_gcs": false,
        "build_only": false
    }
}
DELETE

SegmentML Delete

/api/segmentml/{id}

Delete a SegmentML model.

# Curl example of deleting a SegmentML model
curl -s -J -XDELETE "https://api.lytics.io/api/segmentml/all::smt_power" -H "Authorization: $LIOKEY"
Parameters
idstring (required)
Ex: source::target
ID of the SegmentML model to delete, of the form `SOURCE_SLUG::TARGET_SLUG`.

Response 204