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 multiclass or multilabel models, set target_index to choose which class to explain.

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": "25-01-2020, 00: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.

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),
    )