Skip to content

Quickstart

Time: about 10 minutes · You need: mli installed (Installation) and a labelled table for a binary classification problem. You'll end with: a fitted classifier profiled by mli: its archetypes, rules, explanations, evaluation, trust summary and model card, saved to disk.

mli explains a model that is already fitted. It reads tree ensembles (LightGBM, XGBoost, CatBoost, scikit-learn forests and gradient boosting, a single tree) and glass-box models (linear or logistic regression, EBM, RuleFit). It does not train the model for you.

1. Train a model

Any supported model works. This one is a LightGBM fraud classifier:

import pandas as pd
from lightgbm import LGBMClassifier
from sklearn.model_selection import train_test_split

df = pd.read_parquet("transactions.parquet")
y = df.pop("is_fraud")
X_train, X_test, y_train, y_test = train_test_split(
    df, y, test_size=0.2, stratify=y, random_state=42,
)
clf = LGBMClassifier(n_estimators=400).fit(X_train, y_train)

2. Choose what to compute

Each optional analysis is a section of ProfilingConfig. Leave a section out and it is not computed.

from parleml_mli import (
    EDAConfig, ExplanationsConfig, PdpConfig, PermutationImportanceConfig,
    ProfilingConfig, ReportConfig, RulesConfig,
)

config = ProfilingConfig(
    rules=RulesConfig(),                         # → result.rules_
    explanations=ExplanationsConfig(             # → result.explanations_
        pdp=PdpConfig(),
        permutation_importance=PermutationImportanceConfig(),
    ),
    eda=EDAConfig(),                             # → result.eda_
    report=ReportConfig(output_dir="out", persist_inference_data=True),  # also save the data
)

3. Profile the model

from parleml_mli import fit_profiler

result = fit_profiler(
    model=clf,
    X=X_train,
    y=y_train,
    target_mask=(y_train == 1),            # the rows to profile: the frauds
    X_test=X_test, y_test=y_test,          # → result.model_evaluation_
    X_holdout=X_test, y_holdout=y_test,    # held-out rows for the rules' Test numbers
    config=config,
)

target_mask is the key choice. It selects the rows the archetypes describe. Here it is the positive class. For regression, use a quantile or a business cut-off (see the Profiling guide).

X_test and y_test feed the model evaluation. X_holdout and y_holdout test the mined rules. Pass the same held-out rows to both, as here, to measure both on one set.

4. Look at the result

result.summary_df          # one row per archetype: size, lift, key signatures
result.labels_             # the archetype of each target row
result.rules_              # the mined rules, per engine
result.explanations_       # PDP, importance and the other explanations you asked for
result.eda_                # correlations, alerts, leakage findings
result.model_evaluation_   # metrics and calibration on the test rows

result.plot_umap()         # the archetypes as an interactive scatter (a Plotly figure)

5. Derive the trust summary and the model card

from parleml_mli import compute_trust_summary
from parleml_mli.autodoc import build_model_card

trust = compute_trust_summary(result)   # nine traffic-light tiles
card = build_model_card(result)         # a structured ModelCard

6. Save it

result.save("out/profiling_result.joblib")

The file holds the model and every computed analysis. Reload it later with ProfilingResult.load("out/profiling_result.joblib") to read them without running anything again. Because persist_inference_data=True, the source frames are saved separately in out/model_training_data/.

Details: compute the analyses later instead

You don't have to compute everything up front. Profile with the archetypes only, then add each analysis when you need it:

from parleml_mli import ExplanationsConfig, PdpConfig, ProfilingConfig, PsiConfig, fit_profiler
from parleml_mli.result import build_eda_result, build_explanations_result, build_rules_result

result = fit_profiler(
    model=clf, X=X_train, y=y_train, target_mask=(y_train == 1),
    config=ProfilingConfig(),   # archetypes only
)
result.rules_ = build_rules_result(result, X=X_train)
result.explanations_ = build_explanations_result(
    result, X=X_train,
    config=ExplanationsConfig(pdp=PdpConfig(), psi=PsiConfig()),
)
result.eda_ = build_eda_result(result, X=X_train)

Bootstrap stability of the archetypes is off by default. Turn it on with ArchetypeConfig(n_bootstrap=...).

Next