Skip to content

v1.0.2

Latest

Choose a tag to compare

@tuvelofstrom tuvelofstrom released this 20 Oct 21:35
· 13 commits to main since this release

v1.0.2 - 2026-10-20

Full changelog

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_factual and explore_alternatives
    warned Prediction invariant violated: predict not in [low, high] for valid
    queries. This happened in two cases. With low_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 the min(y_cal)/max(y_cal) placeholder
    ends, and a low > high warning 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
    reinitialize inputs fail fast (#208):
    the unreachable duplicate
    IntervalRegistry.update is removed (it had no callers, and its
    classification branch ignored xs/ys), leaving
    calibration.interval_learner.update_interval_learner as the only update
    path. reinitialize used to drop xs silently when ys was missing (and
    vice versa), ignore bins given without data, and fail with an internal
    indexing error when appending to a Mondrian explainer without bins. These
    now raise ValidationError up front. Appending in fast mode raises a
    ConfigurationError that names the alternatives. The calibration state is
    unchanged in every case.

  • reinitialize now 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
    includes WrapCalibratedExplainer.fit() after calibrate(). The cached
    calibrator, the cached predict function and (when CE_CACHE is 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. reinitialize is now atomic: if it fails
    (including on mismatched bins), the calibration set, bins, learner and
    calibrator are restored. ADR-013 now states that an interval plugin must not
    return a cached calibrator for an operation="update" context.

  • set_mode now 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 a VennAbers or
    IntervalRegressor of the wrong kind. The calibrator is now rebuilt for the
    new mode and the default predict function is rebound (predict_proba or
    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.sha256 of VennAbers/IntervalRegressor primitives 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 raises IncompatibleStateError when 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 a UserWarning plus 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 a Pipeline lists predict_proba even when the
    final step is a regressor, so calibrate() without mode= treated a
    regression pipeline as a classifier and failed. scikit-learn estimators are
    now classified by is_classifier/is_regressor, other learners by whether
    predict_proba is 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 requirement CE-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 pandas DataFrame, now gets one value per row, so
    DataFrame and array inputs give identical results (#249).

  • Unknown CE_* environment-variable warning no longer repeats: the
    UserWarning from ConfigManager.from_sources() fired on every explainer
    construction, so a single stray CE_* variable could flood experiment
    logs. It now fires once per process for each distinct set of unknown keys.
    The release-tooling variable CE_CONDA_FEEDSTOCK_DIR was renamed to
    CALIBRATED_EXPLANATIONS_FEEDSTOCK_DIR so that it stays out of the
    library's reserved CE_ namespace.

  • Enabled parallel with the auto strategy now fails fast (#218):
    perf_parallel(True) without backend=, or CE_PARALLEL=1/on/enable
    without a strategy token, left the removed auto strategy selected, and the
    executor silently picked a backend when entered (joblib locally,
    sequential in CI), contradicting ADR-004. build_config(),
    WrapCalibratedExplainer.from_config() and calibrate() now raise
    ConfigurationError, and entering an enabled ParallelExecutor with
    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
    sequential when CE_PARALLEL names no strategy, so default explain_*
    calls are unaffected and no longer start a worker pool.

  • Unrecognised CE_PARALLEL / CE_CACHE tokens are surfaced (#219): a
    token neither parser understands (for example the typo in
    CE_PARALLEL=enable,thread, an unknown granularity= value or a
    non-boolean force_serial= value) used to be dropped silently. It is still
    ignored, but now emits a UserWarning plus an INFO log naming the variable
    and the token; from v1.1.0 it raises ConfigurationError (#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,threads now enables parallel execution instead of ignoring
    the 1.

  • CE_CACHE is honoured by a plain WrapCalibratedExplainer (#220):
    CE_CACHE used to be read only by ExplainerBuilder/ExplainerConfig, so
    CE_CACHE=on had no effect on WrapCalibratedExplainer(model) or
    CalibratedExplainer(...) and nothing reported it. Both now provision a
    calibrator cache from CE_CACHE, like CE_PARALLEL already did; a
    perf_cache= argument (including a builder-provided cache) still takes
    precedence, and nothing changes when CE_CACHE is 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 raised TypeError or
    ValueError on 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 through html.escape before the newline-to-<br>
    conversion. The text, markdown, dict and dataframe formats are
    unchanged.

  • Narrative capability claim names the real template dependency (#223):
    CE-CAP-NARR-001 said template narration depended on Jinja2 and fell back
    or raised ImportError without it. Narration uses PyYAML (the narrative
    extra); the claim now records that without PyYAML a YAML template, including
    the packaged default, raises SerializationError with no fallback, and only
    a caller-supplied .json template_path works. No code change.

Added

  • Optional conda-forge feedstock auto-update: make release-postcommit now
    ends with a best-effort scripts/update_conda_feedstock.py step that, when
    CALIBRATED_EXPLANATIONS_FEEDSTOCK_DIR points at a local clone of the
    calibrated-explanations-feedstock fork, bumps recipe/meta.yaml to 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
    the ensured score that alternative plots already use by default, now also
    for __repr__, narratives and conjunction candidates. Narratives follow
    plot logic, and add_conjunctions() and to_narrative() gain the plot's
    rnk_metric/rnk_weight arguments. Ties then fall back
    to native rule index, NaN ranks last, top_k edge cases are defined,
    PlotSpec sort_by stays 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

Full Changelog: v1.0.1...v1.0.2