Interpretation

BaseModel can explain why a scenario model makes specific predictions. It computes attribution scores — numeric measures of how much each input contributes to a prediction — using gradient-based attribution methods: Integrated Gradients (deterministic, default) or GradientSHAP (stochastic, typically faster). Both operate on the input-space Cleora/EMDE sketches the model consumes. Attributions are produced at three levels — data sources, features, and feature values — so you can trace a prediction from the broadest signal (which data source matters most) down to individual values (which brand or price range pushed the score).

In This Section

Prediction Drivers

Generating Attributions

Point interpret() at a predictions file and the checkpoint that produced it. The function computes attributions and writes plots and JSON summaries to the output directory.

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

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

You need to provide the paths to your predictions file, output directory, and model checkpoint. For multiclass or multilabel models, set target_index to choose which class to explain.

For the full parameter list, see Reference: Interpretability.

Choosing an Attribution Method

interpret() defaults to Integrated Gradients (method="integrated_gradients") — deterministic, reproducible run-to-run, and the right choice for regulated reporting. For production-scale attribution or downstream SHAP-style plots, switch to GradientSHAP, which averages gradients across stochastic baselines and is typically ~2× faster with denser attributions:

interpret(
    predictions_path=Path("./predictions.tsv"),
    output_path=Path("./interpretations"),
    checkpoint_path=Path("./my_model"),
    device="cuda",
    method="gradient_shap",
)

Both methods write the same source_importance.json / per-feature / per-value structure described below — only the numeric attribution values differ. See Attribution Methods for the tradeoff table.

Understanding the Output

The output directory mirrors the data-source / feature / value hierarchy:

output_path/
├── source_importance.json          # Attribution scores per data source
├── source_importance.png           # Bar chart of data source importance
└── {data_source}/                  # One directory per data source
    ├── feature_importance.json     # Attribution scores per feature
    ├── feature_importance.png      # Bar chart of feature importance
    └── {feature}/                  # One directory per feature
        ├── values_importance.json
        ├── values_highest_importance.png
        └── values_lowest_importance.png

Each level contains a JSON file with numeric scores and a PNG bar chart. You can consume the JSON programmatically or explore the results interactively with Treemaps.