Single Entity Interpretation

Aggregate attributions (covered on the Interpretation overview) show which features matter across many entities. Single-entity interpretation drills into one entity, showing how individual events in that entity's history contribute to the prediction.

Generating Entity-Level Attributions

from pathlib import Path
from datetime import datetime
from monad.interpretability import interpret_entity

interpret_entity(
    output_path=Path("./interpretations/customer_123.json"),
    checkpoint_path=Path("./my_model"),
    predictions_path=Path("./predictions.tsv"),
    main_entity_id="customer_123",
    device="cuda",
    prediction_date=datetime(2024, 6, 1),
)

You need to provide the paths to your predictions file, output JSON, and model checkpoint, plus the main_entity_id to explain — it must match a value in the main_entity_id column of your predictions file. For classification models, set target_index to choose which output to explain (0 for binary classification).

The entity is compared with a reference drawn from the whole predict population, not with itself. On a large dataset, set limit_batches to cap how many batches that reference is drawn from and keep the run fast.

For the full parameter list, see Reference: Interpretability.

Output Format

The JSON contains time-ordered events grouped by data source. Each event lists per-feature attributions:

{
    "transactions": [
        {
            "timestamp": "2020-01-25T00:00:00",
            "modality_attributions": [
                {
                    "data_source_name": "transactions",
                    "name": "article_id",
                    "value": "0854796002",
                    "attribution": -0.124
                },
                {
                    "data_source_name": "transactions",
                    "name": "price",
                    "value": "0.017",
                    "attribution": -0.009
                }
            ]
        }
    ]
}

Positive attributions push the prediction higher; negative attributions push it lower.

Events with the same value, or with values that share a sketch position, split that position's attribution between them instead of each receiving all of it. The split follows each event's weight in the sketch; for recency sketches, the newest event gets it all. In 1.13 and earlier, each event received the full attribution of every position it reached, so per-event values differ from runs made with those releases.

Next to the JSON file, interpret_entity() writes a run manifest, <output file stem>_<main_entity_id>_run.json, that records the method, reference, and base_value of the run. See Output Files.

Processing Multiple Entities

Loop over a list of entity IDs to generate one JSON per entity:

from pathlib import Path
from datetime import datetime
from monad.interpretability import interpret_entity

entities_to_explain = ["cust_001", "cust_002", "cust_003"]

for entity_id in entities_to_explain:
    interpret_entity(
        output_path=Path(f"./interpretations/{entity_id}.json"),
        checkpoint_path=Path("./my_model"),
        predictions_path=Path("./predictions.tsv"),
        main_entity_id=entity_id,
        device="cuda",
        prediction_date=datetime(2024, 6, 1),
    )