Calibration Methods¶

This module contains all calibration algorithms implemented in Calibre.

Base Classes¶

class calibre.BaseCalibrator(enable_diagnostics=False)[source]¶

Bases: BaseEstimator, TransformerMixin

Base class for all calibrators.

All calibrator classes should inherit from this base class to ensure consistent API and functionality. This follows the scikit-learn transformer interface with fit/transform/fit_transform methods.

Parameters:: enable_diagnostics (bool, default=False) – Whether to run plateau diagnostics after fitting.

fit(X, y)[source]¶

Fit the calibrator to training data.

Parameters:

X (ndarray)
y (ndarray | None)

Return type:

BaseCalibrator

transform(X)[source]¶

Apply calibration to new data.

Parameters:: X (ndarray)
Return type:: ndarray

fit_transform(X, y)[source]¶

Fit and then transform in one step.

Parameters:

X (ndarray)
y (ndarray | None)

Return type:

ndarray

get_diagnostics()[source]¶

Get diagnostic results if available.

Return type:: dict | None

Notes

Subclasses must implement the fit() and transform() methods. The fit_transform() method is provided by default.

Examples

>>> import numpy as np
>>> from calibre import BaseCalibrator
>>>
>>> class SimpleCalibrator(BaseCalibrator):
...     def __init__(self, enable_diagnostics=False):
...         super().__init__(enable_diagnostics=enable_diagnostics)
...     def fit(self, X, y):
...         self.mean_ = np.mean(y)
...         return self
...
...     def transform(self, X):
...         return np.full_like(X, self.mean_)
>>>
>>> X = np.array([0.1, 0.3, 0.5])
>>> y = np.array([0, 1, 1])
>>>
>>> cal = SimpleCalibrator()
>>> cal.fit(X, y)
>>> cal.transform(X)
array([0.667, 0.667, 0.667])

__init__(enable_diagnostics=False)[source]¶

diagnostic_summary()[source]¶

Get a human-readable summary of diagnostic analysis.

Returns:: summary – Human-readable plateau summary.
Return type:: str

Examples

>>> from calibre import IsotonicCalibrator
>>> import numpy as np
>>>
>>> X = np.array([0.1, 0.3, 0.5, 0.7, 0.9])
>>> y = np.array([0, 0, 1, 1, 1])
>>>
>>> cal = IsotonicCalibrator(enable_diagnostics=True)
>>> cal.fit(X, y)
>>> print(cal.diagnostic_summary())

fit(X, y=None)[source]¶

Fit the calibrator.

Parameters:

X (array-like of shape (n_samples,)) – The values to be calibrated (e.g., predicted probabilities).
y (array-like of shape (n_samples,), default=None) – The target values (e.g., true labels).

Returns:

self – Returns self for method chaining.

Return type:

BaseCalibrator

Raises:

NotImplementedError – This method must be implemented by subclasses.

fit_transform(X, y=None)[source]¶

Fit the calibrator and then transform the data.

This is a convenience method that combines fit() and transform() in a single call. The default implementation simply calls fit() followed by transform().

Parameters:

X (array-like of shape (n_samples,)) – The values to be calibrated.
y (array-like of shape (n_samples,), default=None) – The target values.

Returns:

X_calibrated – Calibrated values.

Return type:

array-like of shape (n_samples,)

Examples

>>> import numpy as np
>>> from calibre import IsotonicCalibrator
>>> X = np.array([0.1, 0.3, 0.5, 0.7, 0.9])
>>> y = np.array([0, 0, 1, 1, 1])
>>> cal = IsotonicCalibrator()
>>> X_calibrated = cal.fit_transform(X, y)

get_diagnostics()[source]¶

Get diagnostic results.

Returns:: diagnostics – Diagnostic results from plateau analysis, or None if diagnostics were not computed or are not available.
Return type:: dict or None

Examples

>>> from calibre import IsotonicCalibrator
>>> import numpy as np
>>>
>>> X = np.array([0.1, 0.3, 0.5])
>>> y = np.array([0, 1, 1])
>>>
>>> cal = IsotonicCalibrator(enable_diagnostics=True)
>>> cal.fit(X, y)
>>> diagnostics = cal.get_diagnostics()
>>> if diagnostics:
...     print(f"Found {diagnostics['n_plateaus']} plateaus")

get_metadata_routing()¶

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:: routing – A MetadataRequest encapsulating routing information.
Return type:: MetadataRequest

get_params(deep=True)¶

Get parameters for this estimator.

Parameters:: deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:: params – Parameter names mapped to their values.
Return type:: dict

has_diagnostics()[source]¶

Check if diagnostic information is available.

Returns:: has_diag – True if diagnostics have been computed and are available.
Return type:: bool

Examples

>>> from calibre import IsotonicCalibrator
>>> import numpy as np
>>>
>>> X = np.array([0.1, 0.3, 0.5])
>>> y = np.array([0, 1, 1])
>>>
>>> cal = IsotonicCalibrator(enable_diagnostics=True)
>>> cal.fit(X, y)
>>> if cal.has_diagnostics():
...     print("Diagnostics available!")

set_output(*, transform=None)¶

Set output container.

See Introducing the set_output API for an example on how to use the API.

Parameters:

transform ({"default", "pandas", "polars"}, default=None) –

Configure output of transform and fit_transform.

”default”: Default output format of a transformer
”pandas”: DataFrame output
”polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

self – Estimator instance.

Return type:

estimator instance

set_params(**params)¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:: **params (dict) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance

transform(X)[source]¶

Apply calibration to new data.

Parameters:: X (array-like of shape (n_samples,)) – The values to be calibrated.
Returns:: X_calibrated – Calibrated values.
Return type:: array-like of shape (n_samples,)
Raises:: NotImplementedError – This method must be implemented by subclasses.

Calibration Algorithms¶

Nearly Isotonic Regression¶

I-Spline Calibrator¶

Relaxed PAVA¶

Regularized Isotonic Regression¶

Smoothed Isotonic Regression¶

Usage Examples¶

Basic Example¶

from calibre import NearlyIsotonicRegression
import numpy as np

# Generate example data
np.random.seed(42)
X = np.random.uniform(0, 1, 1000)
y = np.random.binomial(1, X, 1000)

# Fit calibrator
calibrator = NearlyIsotonicRegression(lam=1.0)
calibrator.fit(X, y)

# Transform predictions
X_new = np.random.uniform(0, 1, 100)
y_calibrated = calibrator.transform(X_new)

Comparing Methods¶

from calibre import (
    NearlyIsotonicRegression,
    ISplineCalibrator,
    RelaxedPAVA,
    RegularizedIsotonicRegression
)

# Initialize different calibrators
calibrators = {
    'Nearly Isotonic': NearlyIsotonicRegression(lam=1.0),
    'I-Spline': ISplineCalibrator(n_splines=10),
    'Relaxed PAVA': RelaxedPAVA(percentile=10),
    'Regularized': RegularizedIsotonicRegression(alpha=0.1)
}

# Fit and compare
results = {}
for name, cal in calibrators.items():
    cal.fit(X, y)
    y_cal = cal.transform(X_new)
    results[name] = y_cal