Quick Reference · ML explainability & interpretability

shapash cheat sheet

Shapash is an overlay on top of SHAP / LIME by MAIF. One SmartExplainer binds your model, data and encoders together, then a single vocabulary of xpl.plot.* calls turns raw contributions into labelled, human-readable plots — plus a web app, an audit-ready HTML report, and a light deployment object. Learn the pipeline once and the methods stop being a list to memorise.

build (model & data) explain (compile) plot / visualise report & deploy explainability quality ★ most common

Distilled & cross-checked across: shapash.readthedocs.io · github.com/MAIF/shapash · maif.github.io/shapash · pypi.org/project/shapash · towardsdatascience.com · verified 2026-08-28 against Shapash 2.9.0 (Python 3.11–3.14; overlays current SHAP/LIME + Plotly) · SmartExplainer / SmartPredictor API

The pipeline & the methods that move you along it

01Install & Importonce per env

pip install shapash★
Core library (Python 3.11–3.14).
pip install shapash[report]
Extra deps to enable generate_report.
pip install shapash[xgboost,lightgbm,catboost]
Optional model backends.
from shapash import SmartExplainer★
The one class you start from.

02Bring a Modelwhat Shapash wraps

# any fitted, compatible model
Regression · binary · multiclass.
regressor.fit(Xtrain, ytrain)
Catboost · Xgboost · LightGBM · Sklearn · linear · SVM.
y_pred = regressor.predict(Xtest)
Optional — Shapash defaults to model.predict.
encoder = OrdinalEncoder(...).fit(X)
category-encoders / ColumnTransformer for clean labels.

03Declare Explainerstep 1 · bind it

xpl = SmartExplainer(model=regressor)★
model is the one required arg.
…, features_dict=house_dictopt
Map raw names → human labels.
…, preprocessing=encoderopt
Lets plots inverse-transform to raw values.
…, backend='shap'opt
'shap' (default) or 'lime'.
…, label_dict={0:'Death',1:'Survival'}opt
Readable class names (classification).

04Compilestep 2 · the workhorse

xpl.compile(x=Xtest)★
x is the only required arg — computes contributions.
…, y_pred=y_predopt
Your own predictions to explain.
…, y_target=ytestopt
Enables True-vs-Predicted plots.
…, additional_data=X_extraopt
Extra columns for filtering in the web app.

05Global Plotsstep 3 · the big picture

xpl.plot.features_importance()★
Sum of |contributions| per feature — start here.
…features_importance(selection=subset)
Compare a subset vs the whole population.
xpl.plot.contribution_plot('Age')★
How one feature's value drives the output (auto violin/scatter).
xpl.plot.top_interactions_plot()
Strongest pairwise feature interactions.

06Local Plotsexplain one prediction

xpl.plot.local_plot(index=42)★
Why row 42 got its prediction — bars ± per feature.
…local_plot(row_num=0)
Select by position instead of index label.
…local_plot(query="Age > 60")
Select the single row matching a condition.
xpl.plot.compare_plot(row_num=[0,1,2])★
Side-by-side: why these individuals differ.
xpl.plot.local_neighbors_plot(index=42)
Are near-identical rows explained the same way?

07Summarise & Exporttune the local story

xpl.filter(max_contrib=8)★
Cap how many features the summary shows.
…filter(threshold=0.01)
Hide contributions below a magnitude.
…filter(positive=True)
Keep only positive (or negative) drivers.
xpl.to_pandas(max_contrib=5)★
Export the local summary as a DataFrame.
xpl.add(y_pred=new_pred)
Attach / update preds or labels after compile.

08Explainability Qualitycan you trust it?

xpl.plot.stability_plot()★
Stability — similar rows get similar contributions.
…stability_plot(distribution='boxplot')
Show spread of variability per feature.
xpl.plot.compacity_plot()
Compacity — how few features explain ~90% of output.
xpl.plot.consistency_plot()
Consistency — do shap & lime agree?

09Web Appnavigate interactively

app = xpl.run_app()★
Launch the interactive explorer (global ⇄ local).
xpl.run_app(title_story="My model")
Title shown in the app header.
xpl.run_app(port=8050)
Pin host / port if needed.
app.kill()
Stop the running app thread.

10Audit Reportstep 4 · standalone HTML

xpl.generate_report(★
One self-contained HTML file for auditors / DPO / risk.
output_file='report.html',
Where to write it.
project_info_file='info.yml',
Project title, purpose, authors, data prep.
x_train=Xtrain, y_train=ytrain,
Splits used to enrich the document.
metrics=[{'name':'MSE','path':...}])
Metrics to freeze into the snapshot.

11Deploy · SmartPredictorstep 5 · production

predictor = xpl.to_smartpredictor()★
Light object for API / batch — with consistency checks.
predictor.add_input(x=new_df)
Feed raw (un-preprocessed) rows to score.
predictor.detail_contributions()
Predictions + their local contributions.
predictor.summarize()
Wordy, human-readable local explanation.
predictor.save('pred.pkl')
Pickle it for the serving layer.

12Save & Reloadpersist the explainer

xpl.save('xpl.pkl')
Persist the compiled explainer.
xpl2 = SmartExplainer.load('xpl.pkl')
Reload without recomputing contributions.
from shapash.utils.load_smartpredictor import load_smartpredictor
Loader for a saved SmartPredictor pickle.

★Select a Rowanywhere you pick an instance

index=1023
by the DataFrame's index label
row_num=0
by 0-based position
query="Pclass==1 & Age>60"
by a condition matching one row
selection=[3,7,12]
a subset for global plots
label='Survival'
which class to explain (classification)
max_contrib=10
how many features to show

The five plots you'll actually use

Every plot is one xpl.plot.* call on a compiled explainer. Sketches below show the shape of each output — the real ones are interactive Plotly figures with your feature labels.

features_importance()

Global ranking — the sum of absolute contributions per feature. Your first look at what the model leans on.

contribution_plot('Age')

How one feature's value maps to its contribution. Auto-picks violin (categorical) or scatter (continuous).

local_plot(index=42)

One prediction, decomposed. Green pushes the output up, red pulls it down — the ± drivers for that single row.

compare_plot(row_num=[0,1,2])

Several individuals overlaid on the same feature axis — see at a glance why their predictions diverge.

stability_plot()

Quality check: for similar instances, are contributions similar? Points near the axis = stable, trustworthy explanations.

compacity_plot()

Quality check: how many features are enough to reproduce ~90% of the output? A curve that plateaus early = a simple story.

Worth memorising

overlay, not methodShapash wraps shap / lime — it doesn't compute values itself

global vs localfeatures_importance = whole model · local_plot = one row

only 2 required argsmodel at init · x at compile — rest is optional polish

features_dictthe single biggest readability win — map codes to labels

filter ➜ to_pandasfilter() sets the summary; to_pandas() exports that same view

3 quality metricsStability · Consistency · Compacity — trust before you ship

Explainer ≠ PredictorSmartExplainer = analysis · SmartPredictor = light deploy

report needs extraspip install shapash[report] before generate_report()

Shapash cheat sheet · synthesised from the official references of Shapash (readthedocs.io & MAIF GitHub), PyPI, the MAIF project site, and Towards Data Science.
API shown for Shapash 2.9.0 (current, re-verified 2026-08-28; Python 3.11–3.14) · v2.0+ moves model/backend/preprocessing into SmartExplainer(...) init (previously passed to compile). Plots are interactive Plotly figures; sketches are illustrative.