Configure Conditional Calibration¶

Conditional, or Mondrian, calibration partitions calibration data by category label and fits separate calibrators per category. Use it when uncertainty must be reported by subgroup or segment.

Channel A: Inline Labels¶

Use bins= when labels are already available for every calibration and inference instance.

from calibrated_explanations import WrapCalibratedExplainer

explainer = WrapCalibratedExplainer(model)
explainer.fit(x_train, y_train)

group_cal = x_cal[:, group_idx].astype(int)
group_test = x_test[:, group_idx].astype(int)

explainer.calibrate(x_cal, y_cal, bins=group_cal)
explanations = explainer.explain_factual(x_test, bins=group_test)
probabilities, interval = explainer.predict_proba(
    x_test,
    uq_interval=True,
    bins=group_test,
)

Channel B: Stored Categorizer¶

Use mc= when category labels are derived from the input matrix. A MondrianCategorizer is created without constructor arguments in the pinned crepes API.

from crepes.extras import MondrianCategorizer

from calibrated_explanations import WrapCalibratedExplainer

explainer = WrapCalibratedExplainer(model)
explainer.fit(x_train, y_train)

mc = MondrianCategorizer()
mc.fit(x_cal, f=lambda X: model.predict_proba(X)[:, 1], no_bins=5)

explainer.calibrate(x_cal, y_cal, mc=mc)
explanations = explainer.explain_factual(x_test)
probabilities, interval = explainer.predict_proba(x_test, uq_interval=True)

Resolution Rules¶

Calibration state	Inference `bins`	Result
Stored `mc`	omitted	Categories are derived automatically
Stored `mc`	provided	`ConfigurationError`
Inline `bins`	omitted	`ValidationError`
Inline `bins`	provided	Labels are validated and used
Global	omitted	Global calibrated output
Global	provided	`ConfigurationError`

Labels passed at inference must have one value per instance and must belong to the label vocabulary seen during calibration.

Recalibration¶

Conditional state belongs to each calibration call. Calling calibrate(x_cal, y_cal) without bins= or mc= resets the wrapper to global calibration. To intentionally reuse a stored categorizer, call:

explainer.calibrate(x_new_cal, y_new_cal, reuse_conditional=True)

reuse_conditional=True requires a stored mc. Inline labels cannot be reused because they are aligned with the previous calibration set.

Persistence¶

Calibrator bins are persisted, but arbitrary categorizer objects are dropped by pickle and save_state(). CE emits a UserWarning and INFO log when this happens. After loading an mc-calibrated wrapper, pass explicit bins= at inference time.

Minimum Category Size¶

Aim for at least 30-50 calibration samples per category. Smaller categories can produce unstable or very wide intervals and should be documented as an assumption boundary in audits.