mapie.regression.TimeSeriesRegressor

class mapie.regression.TimeSeriesRegressor(estimator: RegressorMixin | None = None, method: str = 'enbpi', cv: int | str | BaseCrossValidator | None = None, n_jobs: int | None = None, agg_function: str | None = 'mean', verbose: int = 0, conformity_score: BaseRegressionScore | None = None, random_state: int | RandomState | None = None)[source]

Prediction intervals with out-of-fold residuals for time series. This class only has two valid method : "enbpi" or "aci"

The prediction intervals are calibrated on a split of the trained data. Both strategies are estimating prediction intervals on single-output time series.

EnbPI allows you to update conformal scores using the update function. It will replace the oldest one with the newest scores. It will keep the same amount of total scores

Actually, EnbPI only corresponds to TimeSeriesRegressor if the cv argument is of type BlockBootstrap.

The ACI strategy allows you to adapt the conformal inference (i.e the quantile). If the real values are not in the coverage, the size of the intervals will grow. Conversely, if the real values are in the coverage, the size of the intervals will decrease. You can use a gamma coefficient to adjust the strength of the correction. If the quantile is equal to zero, the method will produce an infinite set size.

References

Chen Xu, and Yao Xie. “Conformal prediction for dynamic time-series.” https://arxiv.org/abs/2010.09107

Isaac Gibbs, Emmanuel Candes “Adaptive conformal inference under distribution shift” https://proceedings.neurips.cc/paper/2021/file/0d441de75945e5acbc865406fc9a2559-Paper.pdf

Margaux Zaffran et al. “Adaptive Conformal Predictions for Time Series” https://arxiv.org/pdf/2202.07282.pdf

__init__(estimator: RegressorMixin | None = None, method: str = 'enbpi', cv: int | str | BaseCrossValidator | None = None, n_jobs: int | None = None, agg_function: str | None = 'mean', verbose: int = 0, conformity_score: BaseRegressionScore | None = None, random_state: int | RandomState | None = None) → None[source]
adapt_conformal_inference(X: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], y: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], gamma: float, confidence_level: float | Iterable[float] | None = None, ensemble: bool = False, optimize_beta: bool = False) → TimeSeriesRegressor[source]

Adapt the alpha_t attribute when new data with known labels are available.

Parameters:
X: ArrayLike of shape (n_samples, n_features)

Input data.

y: ArrayLike of shape (n_samples_test,)

Input labels.

ensemble: bool

Boolean determining whether the predictions are ensembled or not. If False, predictions are those of the model trained on the whole training set. If True, predictions from perturbed models are aggregated by the aggregation function specified in the agg_function attribute. If cv is "prefit" or "split", ensemble is ignored.

By default False.

gamma: float

Coefficient that decides the correction of the conformal inference. If it equals 0, there are no corrections.

confidence_level: Optional[Union[float, Iterable[float]]]

Between 0 and 1, represents the confidence level of the interval.

By default None.

optimize_beta: bool

Whether to optimize the PIs’ width or not.

By default False.

Returns:
TimeSeriesRegressor

The model itself.

Raises:
ValueError

If the length of y is greater than the length of the training set.

predict(X: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], ensemble: bool = False, confidence_level: float | Iterable[float] | None = None, optimize_beta: bool = False, allow_infinite_bounds: bool = False, **predict_params) → ndarray[tuple[Any, ...], dtype[_ScalarT]] | Tuple[ndarray[tuple[Any, ...], dtype[_ScalarT]], ndarray[tuple[Any, ...], dtype[_ScalarT]]][source]

Predict target on new samples with confidence intervals.

Parameters:
X: ArrayLike of shape (n_samples, n_features)

Test data.

ensemble: bool

Boolean determining whether the predictions are ensembled or not. If False, predictions are those of the model trained on the whole training set. If True, predictions from perturbed models are aggregated by the aggregation function specified in the agg_function attribute. If cv is "prefit" or "split", ensemble is ignored.

By default False.

confidence_level: Optional[Union[float, Iterable[float]]]

Between 0 and 1, represents the confidence level of the interval.

By default None.

optimize_beta: bool

Whether to optimize the PIs’ width or not.

By default False.

allow_infinite_bounds: bool

Allow infinite prediction intervals to be produced.

predict_paramsdict

Additional predict parameters.

Returns:
Union[NDArray, Tuple[NDArray, NDArray]]

  • NDArray of shape (n_samples,) if alpha is None.

  • Tuple[NDArray, NDArray] of shapes (n_samples,) and (n_samples, 2, n_alpha) if alpha is not None. - [:, 0, :]: Lower bound of the prediction interval. - [:, 1, :]: Upper bound of the prediction interval.

set_fit_request(*, groups: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → TimeSeriesRegressor

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
groupsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for groups parameter in fit.

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_weight parameter in fit.

Returns:
selfobject

The updated object.

set_predict_request(*, allow_infinite_bounds: bool | None | str = '$UNCHANGED$', confidence_level: bool | None | str = '$UNCHANGED$', ensemble: bool | None | str = '$UNCHANGED$', optimize_beta: bool | None | str = '$UNCHANGED$') → TimeSeriesRegressor

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
allow_infinite_boundsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for allow_infinite_bounds parameter in predict.

confidence_levelstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for confidence_level parameter in predict.

ensemblestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for ensemble parameter in predict.

optimize_betastr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for optimize_beta parameter in predict.

Returns:
selfobject

The updated object.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → TimeSeriesRegressor

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to score.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_weight parameter in score.

Returns:
selfobject

The updated object.

update(X: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], y: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], ensemble: bool = False, confidence_level: float | Iterable[float] | None = None, gamma: float = 0.0, optimize_beta: bool = False) → TimeSeriesRegressor[source]

Update with respect to the used method. method="enbpi" updates conformity scores via EnbPI, method="aci" calls adapt_conformal_inference.

Parameters:
X: ArrayLike of shape (n_samples, n_features)

Input data.

y: ArrayLike of shape (n_samples_test,)

Input labels.

ensemble: bool

Boolean determining whether the predictions are ensembled or not. If False, predictions are those of the model trained on the whole training set. If True, predictions from perturbed models are aggregated by the aggregation function specified in the agg_function attribute. If cv is "prefit" or "split", ensemble is ignored.

By default False.

confidence_level: Optional[Union[float, Iterable[float]]]

Between 0 and 1, represents the confidence level of the interval.

By default None.

gamma: float

Coefficient that decides the correction of the conformal inference. If it equals 0, there are no corrections.

By default 0..

optimize_beta: bool

Whether to optimize the PIs’ width or not.

By default False.

Returns:
TimeSeriesRegressor

The model itself.

Raises:
ValueError

If the length of y is greater than the length of the training set.

Examples using mapie.regression.TimeSeriesRegressor

Tutorial for time series

Tutorial for time series

Time series: example of the EnbPI technique

Time series: example of the EnbPI technique

Adaptive conformal predictions for time series, Zaffran et al. (2022)

Adaptive conformal predictions for time series, Zaffran et al. (2022)