Conformal

polars_ts.probabilistic.conformal

Conformal prediction intervals for time series forecasts.

Provides distribution-free prediction intervals with finite-sample coverage guarantees. Implements split conformal and EnbPI (Ensemble Batch Prediction Intervals) from Ch 16 of "Modern Time Series Forecasting with Python" (2nd Ed.).

EnbPI

Ensemble Batch Prediction Intervals for time series.

A conformal method that produces adaptive prediction intervals using bootstrap aggregation of out-of-bag residuals. Intervals adapt over time via the update method.

.. note::

Interval width is currently constant across all forecast steps. In practice, prediction uncertainty grows with the horizon due to error accumulation in recursive prediction.

Parameters

estimator_factory Callable returning a fresh scikit-learn-compatible estimator. n_bootstraps Number of bootstrap models to train. lags Lag offsets used as features. coverage Desired coverage level (e.g. 0.9 for 90%). target_col Column with the target values. id_col Column identifying each time series. time_col Column with timestamps for ordering.

fit(df)

Fit bootstrap ensemble and compute out-of-bag residuals.

Parameters

df Training DataFrame.

Returns

EnbPI Fitted instance (self).

predict(df, h)

Generate h-step-ahead forecasts with prediction intervals.

Parameters

df DataFrame containing the history to predict from. h Forecast horizon.

Returns

pl.DataFrame DataFrame with columns [id_col, time_col, "y_hat", "y_hat_lower", "y_hat_upper"].

update(new_obs)

Update residuals with newly observed data for adaptive intervals.

Parameters

new_obs DataFrame with actual observations to incorporate. Must contain id_col, time_col, and target_col, plus a y_hat column with the corresponding predictions.

Returns

EnbPI Updated instance (self).

conformal_interval(cal_residuals, predictions, coverage=0.9, residual_col='residual', predicted_col='y_hat', id_col=None, symmetric=True)

Add conformal prediction intervals to point forecasts.

Uses calibration residuals to compute a coverage-adjusted quantile, then adds lower/upper bounds to the prediction DataFrame.

Parameters

cal_residuals DataFrame containing calibration residuals. For symmetric mode, this should contain absolute residuals |y - y_hat|. For asymmetric mode, this should contain signed residuals y - y_hat (positive means model under-predicted). predictions DataFrame with point forecasts in predicted_col. coverage Desired coverage level (e.g. 0.9 for 90% intervals). residual_col Column name for residuals in cal_residuals. predicted_col Column name for point forecasts in predictions. id_col If provided, compute per-group quantiles for adaptive intervals. symmetric If True, use |residual| for symmetric intervals. If False, compute separate upper/lower bounds from signed residuals y - y_hat.

Returns

pl.DataFrame Copy of predictions with y_hat_lower and y_hat_upper columns appended.

_conformal_quantile(residuals, coverage)

Compute the conformal quantile with finite-sample correction.

q_hat = ceil((n+1) * coverage) / n -th empirical quantile.

_conformal_quantile_lower(residuals, alpha_half)

Compute finite-sample-corrected lower conformal quantile.

_conformal_quantile_upper(residuals, alpha_half)

Compute finite-sample-corrected upper conformal quantile.

_symmetric_interval(cal_residuals, predictions, coverage, residual_col, predicted_col, id_col)

Compute symmetric conformal intervals using |residual| quantiles.

_asymmetric_interval(cal_residuals, predictions, coverage, residual_col, predicted_col, id_col)

Compute asymmetric conformal intervals using signed residual quantiles.