Single entity interpretations

⚠️

Check This First!

This article refers to BaseModel accessed via Docker container. Please refer to Snowflake Native App section if you are using BaseModel as SF GUI application.

BaseModel provides interpretability of prediction for a single main entity, such as a customer. This article shows how to generate attributions of particular events in main entity's history.

Function interpret_entity will use saved model and main entity id to put attributions to a JSON file.

• output_path: Path
  No default
  Path to output JSON file.
• checkpoint_path: Path
  No default
  Path to the model checkpoint - the model that was used to run predictions.
• predictions_path: Path
  No default
  Path to your saved predictions.
• main_entity_id: str
  No default
  Single main entity id to generate interpretations for. For some databases, such as snowflake value needs to be escaped. This should be one of the values that appear in the tsv file with predictions in the main_entity_id column.
• device: str
  No default
  Device to compute the attributions on. Most commonly "cpu" or "cuda"/"cuda:X" where X is the device number.
• target_index: int, optional
  Default: None
  Output indices for which interpretations are computed. For multiclass and multi-label classification should be the id number of a class. No target index is needed for binary classification, one-output regression, and recommendation.
• recommended_value: str, optional
  Default: None
  Value of recommended entity for which the interpretation should be generated. Required for recommendation models.
• kwargs: Any
  Additonally, as kwargs, you should use the same data_params that were passed during inference (see Instantiating the testing module). Generally, it is necessary to define test_start_date and test_end_date.

The code snippet below demonstrates how to use interpret_entity function to generate interpretability for a main entity.

from datetime import datetime
from pathlib import Path

from monad.ui.interpretability import interpret_entity


interpret_entity(
        output_path=Path("<path/to/josn/file/where/results/should/be/saved.json>"),
        checkpoint_path=Path("<path/to/downstream/model/checkpoints>"),
        predictions_path=Path("<path/to/predictions/my_predictions.tsv>"),
        main_entity_id="<main_entity_id_to_be_explained>",
        device="cpu", # cpu or cuda
        target_index=0,
        test_start_date = datetime(2023, 8, 1), # first day of prediction period used during inference
    		test_end_date = datetime(2023, 8, 29), # last day of prediction period used during inference
)

Below is the content of the example JSON file with the entity explanations. Attributions are structured in the following way, at the first level is a dictionary, which keys are data sources (here only "transactions") and values are lists of events of a particular entity. Each element of the events list is a dictionary with a "timestamp" and "modality_attributions" list that contain dictionaries with data source, name, value, and attribution of a feature.
Attributions express how much a given feature value increase or decrease prediction score.

{
    "transactions": [
        {
            "timestamp": 1579910400.0,
            "modality_attributions": [
                {
                    "data_source_name": "transactions",
                    "name": "article_id",
                    "value": "0854796002",
                    "attribution": -0.12365846803964302
                },
                {
                    "data_source_name": "transactions",
                    "name": "price",
                    "value": 0.0169322033898305,
                    "attribution": -0.009004642532037296
                },
                {
                    "data_source_name": "transactions",
                    "name": "department_name",
                    "value": "Jersey",
                    "attribution": 0.0032127736097015713
                },
                {
                    "data_source_name": "transactions",
                    "name": "sales_channel_id",
                    "value": "1",
                    "attribution": -0.007205603966012458
                },
                {
                    "data_source_name": "transactions",
                    "name": "product_code",
                    "value": "854796",
                    "attribution": -0.12518642687574574
                }
            ]
        },
        {
            "timestamp": 1592265600.0,
            "modality_attributions": [
                {
                    "data_source_name": "transactions",
                    "name": "article_id",
                    "value": "0630777018",
                    "attribution": -0.13195706266438356
                },
                {
                    "data_source_name": "transactions",
                    "name": "price",
                    "value": 0.0220169491525423,
                    "attribution": 0.0004090762672481559
                },
                {
                    "data_source_name": "transactions",
                    "name": "department_name",
                    "value": "Jersey Fancy",
                    "attribution": 0.0013805675135995274
                },
                {
                    "data_source_name": "transactions",
                    "name": "sales_channel_id",
                    "value": "2",
                    "attribution": -0.0026675029044388823
                },
                {
                    "data_source_name": "transactions",
                    "name": "product_code",
                    "value": "630777",
                    "attribution": -0.13603511418558373
                }
            ]
        }
    ]
}