Repository navigation
v1.0.2 - 2026-10-20
Fixed
-
Thresholded-regression Venn–Abers score precision (#251): split-CPS scores
are now rounded to 10 decimal places at both calibration and inference. This
removes spurious interval changes when identical scalar scores straddle the
former four-decimal calibration grid, and merges floating-point variants of
equal tuple-event scores. Probability estimates and interval endpoints can
change substantially (up to 0.50 for an endpoint in a small synthetic
comparison). Classification and percentile-based regression are unchanged. -
No false invariant warnings for one-sided or off-centre percentile
intervals (#247): in regression without a threshold,
predict(..., uq_interval=True),explain_factualandexplore_alternatives
warnedPrediction invariant violated: predict not in [low, high]for valid
queries. This happened in two cases. Withlow_high_percentiles=(-inf, q)or
(q, inf), the open end is reported as the minimum or maximum calibration
target, so a median outside that range was flagged. Intervals such as
(-inf, 40)or(60, inf)do not contain the median at all. The check now
only applies to the sides the requested percentiles imply. It no longer uses
the placeholder end, and it is still enforced for(5, 95),(40, 60),
(-inf, 90)and(10, inf). Plugin batch validation follows the same rule.
Classification and probabilistic regression are unchanged. All returned
numbers are unchanged, including themin(y_cal)/max(y_cal)placeholder
ends, and alow > highwarning is still raised when the placeholder
crosses the finite bound. Representing the open end as unbounded is planned
for v1.1.0 (#237). ADR-021 §4/§4b is amended accordingly. -
One authoritative interval-calibration update path; inconsistent
reinitializeinputs fail fast (#208): the unreachable duplicate
IntervalRegistry.updateis removed (it had no callers, and its
classification branch ignoredxs/ys), leaving
calibration.interval_learner.update_interval_learneras the only update
path.reinitializeused to dropxssilently whenyswas missing (and
vice versa), ignorebinsgiven without data, and fail with an internal
indexing error when appending to a Mondrian explainer withoutbins. These
now raiseValidationErrorup front. Appending in fast mode raises a
ConfigurationErrorthat names the alternatives. The calibration state is
unchanged in every case. -
reinitializenow refreshes calibration (silent wrong output, #239):
CalibratedExplainer.reinitialize(learner, xs, ys)appended the rows to
x_cal/y_cal, but classification kept using the Venn-Abers calibrator
fitted on the original calibration set. Probabilities and intervals were
unchanged, bit for bit, and no warning was raised.reinitialize(learner)
with a new or refitted learner had the same problem in both modes; this
includesWrapCalibratedExplainer.fit()aftercalibrate(). The cached
calibrator, the cached predict function and (whenCE_CACHEis enabled)
cached predictions are now discarded. After an append, classification
matches a fresh calibration on the combined data. After a learner change,
both modes match a fresh calibration. Regression appends still extend the
existing conformal split in place.reinitializeis now atomic: if it fails
(including on mismatchedbins), the calibration set, bins, learner and
calibrator are restored. ADR-013 now states that an interval plugin must not
return a cached calibrator for anoperation="update"context. -
set_modenow rebuilds the calibrator for the new mode (#241):
CalibratedExplainer.set_mode()re-ran calibrator initialization but reused
the cached calibrator, task and predict function of the previous mode, so
switching between classification and regression kept aVennAbersor
IntervalRegressorof the wrong kind. The calibrator is now rebuilt for the
new mode and the default predict function is rebound (predict_probaor
predict; a user-supplied one is kept). If the rebuild fails, the previous
mode and calibration state are restored. -
Calibrator primitive checksums are reproducible and verified (#240): the
checksums.sha256ofVennAbers/IntervalRegressorprimitives was a digest
of a pickle of the in-memory calibrator. It changed between processes for
identical content, and nothing checked it on load. It is now a SHA-256 over
the canonical JSON of the persisted content, tagged
"algorithm": "sha256-canonical-json-v1".from_primitive()verifies it
and raisesIncompatibleStateErrorwhen the content was modified or the
algorithm is unknown. Primitives saved by 1.0.1 and earlier have no tag. They
still load, but with aUserWarningplus an INFO log, because they cannot be
verified. A future schema version will reject them, so re-save them with
save_state(). -
Regression
Pipelines are no longer treated as classifiers (#245): the
task was inferred from"predict_proba" in dir(learner). Before
scikit-learn 1.8,dir()of aPipelinelistspredict_probaeven when the
final step is a regressor, socalibrate()withoutmode=treated a
regression pipeline as a classifier and failed. scikit-learn estimators are
now classified byis_classifier/is_regressor, other learners by whether
predict_probais accessible. The plotting paths use the same check. -
Thresholded regression is now instance-wise (batch-invariant):
predict_proba(x, threshold=...),predict(..., threshold=...)and
thresholded explanations could give the same object a different calibrated
probability and Venn-Abers interval depending on which other rows shared the
batch, their order and the batch size (differences up to 0.18 observed).
crepes' smoothed conformal p-values draw their random term per row index
after reseeding, so an object's Venn-Abers input score depended on its batch
position. Scalar thresholds were affected; tuple thresholds were affected only
under exact ties, because the random term cancels in the difference. Test
scores also came from a CPS fitted on all calibration data, while the
Venn-Abers calibration scores came from the split CPS. The score is now the
deterministic (unsmoothed) CPD value of the split CPS, on both the calibration
and the test side: the standard inductive Venn-Abers construction, with one
score function. Numerical outputs of thresholded regression change:
across the evaluated datasets, Brier score and ECE show no significant
degradation (unconditional and normalized calibration improve slightly).
Venn-Abers intervals are slightly wider, most visibly under Mondrian
calibration. Individual probabilities can shift noticeably when the
calibration set is small. New requirementCE-REQ-PRED-PROB-INSTANCE-001(TIF
CE-TIF-PRED-PROB-002) pins the contract. The split CPS needs one
difficulty value per instance. Without a difficulty estimator, every input
type, including a pandasDataFrame, now gets one value per row, so
DataFrameand array inputs give identical results (#249). -
Unknown
CE_*environment-variable warning no longer repeats: the
UserWarningfromConfigManager.from_sources()fired on every explainer
construction, so a single strayCE_*variable could flood experiment
logs. It now fires once per process for each distinct set of unknown keys.
The release-tooling variableCE_CONDA_FEEDSTOCK_DIRwas renamed to
CALIBRATED_EXPLANATIONS_FEEDSTOCK_DIRso that it stays out of the
library's reservedCE_namespace. -
Enabled parallel with the
autostrategy now fails fast (#218):
perf_parallel(True)withoutbackend=, orCE_PARALLEL=1/on/enable
without a strategy token, left the removedautostrategy selected, and the
executor silently picked a backend when entered (jobliblocally,
sequentialin CI), contradicting ADR-004.build_config(),
WrapCalibratedExplainer.from_config()andcalibrate()now raise
ConfigurationError, and entering an enabledParallelExecutorwith
strategy="auto"raises instead of auto-selecting. The executor the explain
runtime creates for itself, and the pool from
CalibratedExplainer.initialize_pool()/with explainer:, now use
sequentialwhenCE_PARALLELnames no strategy, so defaultexplain_*
calls are unaffected and no longer start a worker pool. -
Unrecognised
CE_PARALLEL/CE_CACHEtokens are surfaced (#219): a
token neither parser understands (for example the typo in
CE_PARALLEL=enable,thread, an unknowngranularity=value or a
non-booleanforce_serial=value) used to be dropped silently. It is still
ignored, but now emits aUserWarningplus an INFO log naming the variable
and the token; from v1.1.0 it raisesConfigurationError(#225). Both
parsers now accept the same case-insensitive enable labels
(1/true/on/yes/enable) and disable labels
(0/false/off/no/disable) in any position, so
CE_PARALLEL=1,threadsnow enables parallel execution instead of ignoring
the1. -
CE_CACHEis honoured by a plainWrapCalibratedExplainer(#220):
CE_CACHEused to be read only byExplainerBuilder/ExplainerConfig, so
CE_CACHE=onhad no effect onWrapCalibratedExplainer(model)or
CalibratedExplainer(...)and nothing reported it. Both now provision a
calibrator cache fromCE_CACHE, likeCE_PARALLELalready did; a
perf_cache=argument (including a builder-provided cache) still takes
precedence, and nothing changes whenCE_CACHEis unset. -
An enabled calibrator cache no longer breaks
predict(#220): cache keys
kept arrays nested inside tuples unhashed, and cache hits compared stored
prediction tuples with==, so any enabled cache raisedTypeErroror
ValueErroron the first prediction. Nested arrays are now hashed and cached
results are returned unchanged. -
Narrative HTML output escapes user-supplied content (#222):
to_narrative(output_format="html")inserted feature names, class labels
and categorical values into the table without escaping, so any markup they
contained was rendered as live HTML (for example in a notebook). Header and
cell content is now passed throughhtml.escapebefore the newline-to-<br>
conversion. Thetext,markdown,dictanddataframeformats are
unchanged. -
Narrative capability claim names the real template dependency (#223):
CE-CAP-NARR-001said template narration depended on Jinja2 and fell back
or raisedImportErrorwithout it. Narration uses PyYAML (thenarrative
extra); the claim now records that without PyYAML a YAML template, including
the packaged default, raisesSerializationErrorwith no fallback, and only
a caller-supplied.jsontemplate_pathworks. No code change.
Added
- Optional conda-forge feedstock auto-update:
make release-postcommitnow
ends with a best-effortscripts/update_conda_feedstock.pystep that, when
CALIBRATED_EXPLANATIONS_FEEDSTOCK_DIRpoints at a local clone of the
calibrated-explanations-feedstockfork, bumpsrecipe/meta.yamlto the
just-published PyPI version and opens a PR against
conda-forge/calibrated-explanations-feedstock. No-op when the env var is
unset; failures warn rather than fail the release. Standalone retry via
make conda-feedstock-update.
Documentation / Governance
- ADR-042 canonical ranking semantics (#224), accepted: defines one ranking
contract per explanation type for rule retrieval, plots, narratives and
conjunction selection. Factual rules rank strongest first by|weight|,
with the narrower uncertainty interval winning ties. Alternative rules use
theensuredscore that alternative plots already use by default, now also
for__repr__, narratives and conjunction candidates. Narratives follow
plot logic, andadd_conjunctions()andto_narrative()gain the plot's
rnk_metric/rnk_weightarguments. Ties then fall back
to native rule index,NaNranks last,top_kedge cases are defined,
PlotSpecsort_bystays presentation-only, and no statistical
ranking-stability guarantee is claimed. Current (v1.0.x) behaviour,
including the inconsistencies it replaces, is pinned by characterisation
tests. No ranking behaviour changes in this release; the ordering changes
land in v1.1.0 (#204).
What's Changed
- chore(deps): bump actions/upload-artifact from 7.0.1 to 7.0.2 by @dependabot[bot] in #236
- Feat/ce project hub and enterprise links 20261014 by @tuvelofstrom in #238
- fix: land thresholded-regression batch invariance (makes main green) by @tuvelofstrom in #242
- fix: refresh calibration on reinitialize and verify calibrator checksums (#239, #240) by @tuvelofstrom in #243
- fix: rebuild the interval calibrator on set_mode (#241) by @tuvelofstrom in #244
- docs: accept ADR-042 canonical ranking semantics (#224, T6) by @tuvelofstrom in #246
- fix: percentile-aware prediction invariant checks for CPS regression (#247) by @tuvelofstrom in #248
- fix: one constant difficulty value per instance for DataFrame input (#249) by @tuvelofstrom in #250
Full Changelog: v1.0.1...v1.0.2