# 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.

```python
# 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()`:

```python
# 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)](https://github.com/Moffran/calibrated_explanations/blob/main/docs/improvement/adrs/ADR-021-calibrated-interval-semantics.md) for details

### If You Maintain Tests

Update test docstrings and comments:

```python
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

- [Concept Guide: Probabilistic Regression](probabilistic_regression.md)
- [ADR-021: Calibrated Interval Semantics (GitHub)](https://github.com/Moffran/calibrated_explanations/blob/main/docs/improvement/adrs/ADR-021-calibrated-interval-semantics.md)

---

## Questions?

See the [concept guide](probabilistic_regression.md) or file an issue on GitHub.