Terminology Standardization

Release: v0.9.1+ Date: November 2025 Impact: Documentation and code naming (no breaking changes) Audience: All users, contributors, and plugin developers

Summary

Terminology was standardized to clarify the relationship between “probabilistic regression” and “thresholded regression.” This guide explains what changed and how it affects you.

Key Change

“Probabilistic regression” is now the canonical term across all user-facing documentation and code. “Thresholded regression” remains in technical architecture documents (ADRs, design notes) to describe the implementation mechanism.

Both terms refer to the same feature: regression with calibrated probability predictions.

Backward Compatibility Guarantee

✅ Zero breaking changes to public API

  • is_thresholded() method remains unchanged

  • threshold and y_threshold parameters unchanged

  • All existing code continues to work without modification

  • Internal method _is_thresholded() removed in v0.10.0 (use _is_probabilistic_regression())

What Changed

For End Users

No changes. The threshold parameter, predict_proba(threshold=...) API, and all user-facing functionality remain identical.

However:

  • Documentation now consistently uses “probabilistic regression” instead of mixing both terms

  • Concept guides and quickstarts are aligned on terminology

  • Papers and citations use the preferred term

For Contributors & Plugin Developers

Code Changes

  1. Method Rename:

    • Old: _is_thresholded()

    • New: _is_probabilistic_regression()

    • Location: calibrated_explanations.explanations.CalibratedExplanations class

    • Impact: Private method; only relevant if you access this in tests or extensions

  2. Public API (unchanged):

    • is_thresholded() method on Explanation objects remains unchanged (for backward compatibility)

    • Parameters threshold and y_threshold remain unchanged (describe the value, not the mode)

Docstring Updates

  • IntervalRegressor.predict_probability() now documents “probabilistic regression” with technical notes

  • CalibratedExplainer.predict() docstring clarified to use “probabilistic regression”

  • Comments and docstrings throughout the codebase updated for consistency

For Maintainers

  • ADR-021 now includes a “Terminology” section explaining the equivalence

  • ADR-013 references this section for consistency

  • Architecture discussions should use “thresholded regression” when discussing CPS + Venn-Abers mechanics

  • User-facing APIs and docs should use “probabilistic regression”

Migration Path

If You Use the Public API

No action required. The threshold parameter and all methods work identically.

# This continues to work exactly as before:
ce.predict(x_test, threshold=150, uq_interval=True)
explanations = ce.explain_factual(x_test, threshold=150)

If You Access Internal Methods (Tests, Extensions)

Update references to _is_thresholded():

# Old:
if collection._is_thresholded():
    ...

# New:
if collection._is_probabilistic_regression():
    ...

If You Build Custom Plugins

Follow ADR-021 terminology guidance:

  • Use “probabilistic regression” in public-facing docstrings and error messages

  • Use “thresholded regression” in implementation comments where you discuss the threshold mechanism or CPS/Venn-Abers details

  • See the ADR-021 Terminology section (GitHub) for details

If You Maintain Tests

Update test docstrings and comments:

def test_probabilistic_regression():
    """Test probabilistic regression behavior.

    Probabilistic regression (also called thresholded regression in the architecture
    layer) applies a threshold to convert regression predictions into calibrated
    probabilities P(y <= threshold).
    """

Why This Change?

  1. User clarity: Practitioners immediately understand they’re getting probability predictions

  2. Consistency: Mirrors “probabilistic classification” terminology

  3. Marketing: Emphasizes the novel capability (probabilities from regression)

  4. Research alignment: Published papers use “probabilistic regression”

  5. Technical precision: “Thresholded regression” in architecture docs clarifies the mechanism

Further Reading

Questions?

See the concept guide or file an issue on GitHub.