tessl/pypi-mapie

A scikit-learn-compatible module for estimating prediction intervals using conformal prediction methods.

Overview

Eval results

Files

Regression Methods

Name: tessl/pypi-mapie
Author: tessl

Conformal prediction methods for regression that provide prediction intervals with finite-sample coverage guarantees. MAPIE implements several regression approaches including split conformal, cross conformal, jackknife-after-bootstrap, time series, and conformalized quantile regression methods.

Capabilities

Split Conformal Regression

Implements the split conformal prediction method for regression, dividing data into training and conformalization sets. Provides efficient prediction intervals with exact finite-sample coverage guarantees.

class SplitConformalRegressor:
    """
    Split conformal regression predictor.

    Parameters:
    - estimator: RegressorMixin, base regression estimator (default: LinearRegression())
    - confidence_level: Union[float, List[float]], target coverage level (default: 0.9)
    - conformity_score: Union[str, BaseRegressionScore], conformity score method (default: "absolute")
    - prefit: bool, whether estimator is already fitted (default: True)
    - n_jobs: Optional[int], number of parallel jobs
    - verbose: int, verbosity level (default: 0)
    """
    def __init__(self, estimator=None, confidence_level=0.9, conformity_score="absolute", prefit=True, n_jobs=None, verbose=0): ...

    def fit(self, X_train, y_train, fit_params=None):
        """
        Fit the base estimator.

        Parameters:
        - X_train: ArrayLike, training features
        - y_train: ArrayLike, training targets
        - fit_params: Optional[Dict], parameters passed to estimator.fit()

        Returns:
        Self
        """

    def conformalize(self, X_conformalize, y_conformalize, predict_params=None):
        """
        Estimate prediction intervals using conformalization set.

        Parameters:
        - X_conformalize: ArrayLike, conformalization features
        - y_conformalize: ArrayLike, conformalization targets
        - predict_params: Optional[Dict], parameters passed to estimator.predict()

        Returns:
        Self
        """

    def predict_interval(self, X, minimize_interval_width=False, allow_infinite_bounds=False):
        """
        Predict intervals for new data.

        Parameters:
        - X: ArrayLike, test features
        - minimize_interval_width: bool, whether to minimize interval width (default: False)
        - allow_infinite_bounds: bool, whether to allow infinite bounds (default: False)

        Returns:
        Tuple[NDArray, NDArray]: (predictions, intervals)
        """

    def predict(self, X):
        """
        Predict point estimates for new data.

        Parameters:
        - X: ArrayLike, test features

        Returns:
        NDArray: predictions
        """

Cross Conformal Regression

Implements cross conformal prediction using cross-validation for better data utilization. Provides multiple aggregation methods and robust prediction intervals.

class CrossConformalRegressor:
    """
    Cross conformal regression predictor.

    Parameters:
    - estimator: RegressorMixin, base regression estimator (default: LinearRegression())
    - confidence_level: Union[float, List[float]], target coverage level (default: 0.9)
    - conformity_score: Union[str, BaseRegressionScore], conformity score method (default: "absolute")
    - method: str, aggregation method ("plus", "base", "minmax") (default: "plus")
    - cv: Union[int, BaseCrossValidator], cross-validation strategy (default: 5)
    - n_jobs: Optional[int], number of parallel jobs
    - verbose: int, verbosity level (default: 0)
    - random_state: Optional[int], random seed
    """
    def __init__(self, estimator=None, confidence_level=0.9, conformity_score="absolute", method="plus", cv=5, n_jobs=None, verbose=0, random_state=None): ...

    def fit_conformalize(self, X, y, groups=None, fit_params=None, predict_params=None):
        """
        Fit estimators and compute conformity scores using cross-validation.

        Parameters:
        - X: ArrayLike, input features
        - y: ArrayLike, target values
        - groups: Optional[ArrayLike], group labels for cross-validation
        - fit_params: Optional[Dict], parameters passed to estimator.fit()
        - predict_params: Optional[Dict], parameters passed to estimator.predict()

        Returns:
        Self
        """

    def predict_interval(self, X, aggregate_predictions="mean", minimize_interval_width=False, allow_infinite_bounds=False):
        """
        Predict intervals using cross conformal method.

        Parameters:
        - X: ArrayLike, test features
        - aggregate_predictions: str, prediction aggregation method ("mean", "median") (default: "mean")
        - minimize_interval_width: bool, whether to minimize interval width (default: False)
        - allow_infinite_bounds: bool, whether to allow infinite bounds (default: False)

        Returns:
        Tuple[NDArray, NDArray]: (predictions, intervals)
        """

    def predict(self, X, aggregate_predictions="mean"):
        """
        Predict point estimates using ensemble aggregation.

        Parameters:
        - X: ArrayLike, test features
        - aggregate_predictions: str, aggregation method ("mean", "median") (default: "mean")

        Returns:
        NDArray: aggregated predictions
        """

Jackknife-After-Bootstrap Regression

Implements the jackknife-after-bootstrap method for prediction intervals, combining bootstrap aggregation with conformal prediction for enhanced uncertainty quantification.

class JackknifeAfterBootstrapRegressor:
    """
    Jackknife-after-bootstrap regression predictor.

    Parameters:
    - estimator: RegressorMixin, base regression estimator (default: LinearRegression())
    - confidence_level: Union[float, List[float]], target coverage level (default: 0.9)
    - conformity_score: Union[str, BaseRegressionScore], conformity score method (default: "absolute")
    - method: str, interval construction method ("plus", "base", "minmax") (default: "plus")
    - resampling: Union[int, Subsample], number of bootstrap samples or Subsample object (default: 30)
    - aggregation_method: str, prediction aggregation ("mean", "median") (default: "mean")
    - n_jobs: Optional[int], number of parallel jobs
    - verbose: int, verbosity level (default: 0)
    - random_state: Optional[int], random seed
    """
    def __init__(self, estimator=None, confidence_level=0.9, conformity_score="absolute", method="plus", resampling=30, aggregation_method="mean", n_jobs=None, verbose=0, random_state=None): ...

    def fit_conformalize(self, X, y, fit_params=None, predict_params=None):
        """
        Fit bootstrap ensemble and compute conformity scores.

        Parameters:
        - X: ArrayLike, input features
        - y: ArrayLike, target values
        - fit_params: Optional[Dict], parameters passed to estimator.fit()
        - predict_params: Optional[Dict], parameters passed to estimator.predict()

        Returns:
        Self
        """

    def predict_interval(self, X, ensemble=True, minimize_interval_width=False, allow_infinite_bounds=False):
        """
        Predict intervals using jackknife-after-bootstrap method.

        Parameters:
        - X: ArrayLike, test features
        - ensemble: bool, whether to use ensemble predictions (default: True)
        - minimize_interval_width: bool, whether to minimize interval width (default: False)
        - allow_infinite_bounds: bool, whether to allow infinite bounds (default: False)

        Returns:
        Tuple[NDArray, NDArray]: (predictions, intervals)
        """

    def predict(self, X, ensemble=True):
        """
        Predict point estimates using bootstrap ensemble.

        Parameters:
        - X: ArrayLike, test features
        - ensemble: bool, whether to use ensemble predictions (default: True)

        Returns:
        NDArray: predictions
        """

Time Series Regression

Specialized conformal prediction for time series data, implementing EnbPI (Ensemble batch Prediction Intervals) and ACI (Adaptive Conformal Inference) methods with support for temporal dependencies.

class TimeSeriesRegressor:
    """
    Time series conformal regression predictor.

    Parameters:
    - estimator: Optional[RegressorMixin], base time series estimator
    - method: str, time series method ("enbpi", "aci") (default: "enbpi")
    - cv: Optional[Union[int, str, BaseCrossValidator]], cross-validation strategy
    - n_jobs: Optional[int], number of parallel jobs
    - agg_function: Optional[str], aggregation function ("mean") (default: "mean")
    - verbose: int, verbosity level (default: 0)
    - conformity_score: Optional[BaseRegressionScore], conformity score method
    - random_state: Optional[Union[int, np.random.RandomState]], random seed
    """
    def __init__(self, estimator=None, method="enbpi", cv=None, n_jobs=None, agg_function="mean", verbose=0, conformity_score=None, random_state=None): ...

    def fit(self, X, y, sample_weight=None, **fit_params):
        """
        Fit the time series model.

        Parameters:
        - X: ArrayLike, time series features
        - y: ArrayLike, time series targets
        - sample_weight: Optional[ArrayLike], sample weights
        - **fit_params: additional parameters passed to estimator.fit()

        Returns:
        Self
        """

    def partial_fit(self, X, y, sample_weight=None, **fit_params):
        """
        Update the time series model with new data (for EnbPI method).

        Parameters:
        - X: ArrayLike, new time series features
        - y: ArrayLike, new time series targets
        - sample_weight: Optional[ArrayLike], sample weights
        - **fit_params: additional parameters

        Returns:
        Self
        """

    def predict(self, X, ensemble=False, alpha=None):
        """
        Predict point estimates and intervals for time series.

        Parameters:
        - X: ArrayLike, time series features
        - ensemble: bool, whether to use ensemble predictions (default: False)
        - alpha: Optional[Union[float, Iterable[float]]], significance levels

        Returns:
        Union[NDArray, Tuple[NDArray, NDArray]]: predictions or (predictions, intervals)
        """

Conformalized Quantile Regression

Implements conformalized quantile regression, combining quantile regression with conformal prediction for distribution-free prediction intervals.

class ConformalizedQuantileRegressor:
    """
    Conformalized quantile regression predictor.

    Parameters:
    - estimator: Optional[Union[RegressorMixin, Pipeline, List[Union[RegressorMixin, Pipeline]]]], quantile regressor(s)
    - confidence_level: float, target coverage level (default: 0.9)
    - prefit: bool, whether estimator(s) are already fitted (default: False)
    """
    def __init__(self, estimator=None, confidence_level=0.9, prefit=False): ...

    def fit(self, X_train, y_train, fit_params=None):
        """
        Fit quantile regressors for target, lower, and upper quantiles.

        Parameters:
        - X_train: ArrayLike, training features
        - y_train: ArrayLike, training targets
        - fit_params: Optional[Dict], parameters passed to estimator.fit()

        Returns:
        Self
        """

    def conformalize(self, X_conformalize, y_conformalize, sample_weight=None):
        """
        Conformalize the quantile predictions using conformalization set.

        Parameters:
        - X_conformalize: ArrayLike, conformalization features
        - y_conformalize: ArrayLike, conformalization targets
        - sample_weight: Optional[ArrayLike], sample weights

        Returns:
        Self
        """

    def predict_interval(self, X):
        """
        Predict conformalized quantile intervals.

        Parameters:
        - X: ArrayLike, test features

        Returns:
        Tuple[NDArray, NDArray]: (predictions, intervals)
        """

    def predict(self, X):
        """
        Predict point estimates using median quantile regressor.

        Parameters:
        - X: ArrayLike, test features

        Returns:
        NDArray: predictions
        """

Usage Examples

Basic Split Conformal Regression

from sklearn.ensemble import RandomForestRegressor
from mapie.regression import SplitConformalRegressor
import numpy as np

# Prepare data
X_train, X_calib, y_train, y_calib = train_test_split(X, y, test_size=0.3)

# Fit base model
rf = RandomForestRegressor(n_estimators=100, random_state=42)
rf.fit(X_train, y_train)

# Create conformal predictor
mapie_reg = SplitConformalRegressor(
    estimator=rf,
    prefit=True,
    confidence_level=[0.8, 0.9, 0.95]
)

# Conformalize
mapie_reg.conformalize(X_calib, y_calib)

# Predict with intervals
y_pred, y_intervals = mapie_reg.predict_interval(X_test)

Cross Conformal with Custom Conformity Score

from mapie.regression import CrossConformalRegressor
from mapie.conformity_scores import GammaConformityScore

# Use gamma conformity score for heteroscedastic data
gamma_score = GammaConformityScore()

mapie_reg = CrossConformalRegressor(
    estimator=RandomForestRegressor(n_estimators=50),
    conformity_score=gamma_score,
    method="plus",
    cv=10,
    random_state=42
)

# Fit and predict
mapie_reg.fit_conformalize(X, y)
y_pred, y_intervals = mapie_reg.predict_interval(X_test)