CallableAdapter
Bases: ForecasterAdapter
Wrap a user-supplied function into a :class:ForecasterAdapter.
The callable must accept a history array and return a point forecast.
No capability mixins are provided — the callable has no concept of
refit, quantiles, or bootstrap.
Parameters
predict_fn : callablefn(history) -> forecast where history has shape
(n_series, T) and the return value has shape
(n_series, horizon). May optionally accept an X keyword to
receive exogenous features; see :meth:predict.
horizon : int
Number of steps to forecast.
n_series : int
Number of series in the panel.
Notes
predict_fn is hidden from model_json_schema(): pydantic cannot
render a JsonSchema for a callable, and no schema-filled call could supply
a Python function anyway — it has to be passed programmatically. For the
same reason this adapter does not round-trip through
model_validate(model_dump()).
CallableAdapter.horizon
CallableAdapter.n_series
CallableAdapter.predict
X keyword, the exogenous array
is forwarded to it; otherwise X is ignored.
Parameters
history : Series, shape (n_series, T) X : NDArray or None, shape (n_series, 1, horizon, n_features)Returns
Forecast, shape (n_series, 1, horizon)Raises
ValueError Ifhistory is not 2-D, has the wrong leading axis, contains
NaN, or if the callable returns an unexpected shape.
CallableAdapter.predict_batch
Parameters
histories : list of Series, each shape (n_series, T) X : Exog or None, shape (n_series, len(histories), horizon, n_features) Per-window future exogenous features; windoww receives
X[:, w:w+1, :, :].
Returns
Forecast, shape (n_series, len(histories), horizon) Default implementation callspredict in a loop and stacks results.
Adapters where the underlying library supports batch inference should
override this for performance.
CallableAdapter.predict_fn
CallableAdapter.supports
capability (a mixin type).
The default is an isinstance check. Adapters whose capability is
runtime-conditional (e.g. a NeuralForecast adapter whose quantile
support depends on the fitted loss) override this. Keeping the check
here means the runtime capability gate lives where the forecaster is
bound — the first thing calibrate and calibrate_cv do — never
inside predict.
Parameters
capability : type A capability mixin class (e.g.SupportsCrossValidation).
Returns
boolStatsForecastAdapter
Bases: ForecasterAdapter, SupportsRefit, SupportsCrossValidation, SupportsQuantiles, SupportsCrossValidationQuantiles
Adapter for a fitted :class:statsforecast.StatsForecast instance.
n_series is derived from train_df rather than accepted; passing it
is refused at construction.
Parameters
sf : StatsForecast An already-fitted StatsForecast instance. train_df : pandas.DataFrame or polars.DataFrame The long-format DataFrame used to fitsf. Kept in its own backend:
a polars frame means every frame handed to StatsForecast is polars.
horizon : int
Forecast horizon in time steps.
freq : str or int
The freq you passed to StatsForecast: a pandas alias ('D', 'MS')
for pandas frames, a polars interval ('1d', '1mo') for polars
frames, or an int for an integer time column.
model_name : str
Which model column to read from StatsForecast output. Must match one
of the fitted model aliases.
id_col : str
Column identifying individual series (default 'unique_id').
time_col : str
Timestamp column (default 'ds').
target_col : str
Target value column (default 'y').
exog_features : list of str or None, default None
Names of the model’s future exogenous regressor columns, in the
order they appear on the exogenous feature axis of X. When
None (the default), passing a non-None X to predict
raises ValueError.
Notes
Not serialisable, deliberately:sf is a live library object and
train_df a DataFrame, so model_validate(model_dump()) cannot
rebuild one — and it would be refused anyway, since a dump carries the
derived n_series. Those two fields are hidden from
model_json_schema() along with the derived ones, so a schema-filled
call still has to supply sf and train_df programmatically; the
schema describes the scalar arguments only.
StatsForecastAdapter.cross_validate
Parameters
n_windows : int Number of evaluation windows (>= 1). step_size : int Steps between successive windows (>= 1). refit : bool or int Whether (or how often) to refit between windows. aligned : bool, default FalseFalse returns dense per-series arrays (window axis = k steps
before each series’ own end). True returns calendar-aligned
cutoffs with NaN cells for late-starting series.
Returns
predictions : Forecast, shape (n_series, n_windows, horizon) truths : Forecast, shape (n_series, n_windows, horizon)StatsForecastAdapter.cross_validate_quantiles
Parameters
n_windows : int Number of evaluation windows (>= 1). step_size : int Steps between successive windows (>= 1). quantiles : NDArray, shape (n_quantiles,) Values in(0, 1). Symmetric-pair / range rules of
:func:_nixtla_common.quantiles_to_levels apply.
refit : bool or int
Whether (or how often) to refit between windows.
Returns
quantile_predictions : Forecast, shape (n_series, n_windows, horizon, n_quantiles) Quantiles are on the last axis, in the order requested. truths : Forecast, shape (n_series, n_windows, horizon)Raises
ValueError Ifn_windows / step_size are invalid, the quantile
validation fails, or the model did not return a requested
quantile column.
RuntimeError
If the cross-validation output contains NaN.
StatsForecastAdapter.exog_features
StatsForecastAdapter.freq
StatsForecastAdapter.horizon
StatsForecastAdapter.id_col
StatsForecastAdapter.model_name
StatsForecastAdapter.n_series
StatsForecastAdapter.predict
history.
The anchor follows the panel’s width: a history of T columns against
a training panel of train_t_len ends train_t_len - T steps before
the training end. A rolling predict_batch loop therefore stamps each
window with its own dates, which is what makes seasonal and calendar
components line up for older windows.
Parameters
history : Series, shape (n_series, T) X : Forecast or None, shape (n_series, 1, horizon, n_features) Future exogenous features, aligned to thehorizon steps that
follow history. Requires the adapter to have been constructed
with exog_features=[...].
Returns
Forecast, shape (n_series, 1, horizon)Raises
ValueError IfX is not None but the adapter was constructed without
exog_features.
StatsForecastAdapter.predict_batch
Parameters
histories : list of Series, each shape (n_series, T) X : Exog or None, shape (n_series, len(histories), horizon, n_features) Per-window future exogenous features; windoww receives
X[:, w:w+1, :, :].
Returns
Forecast, shape (n_series, len(histories), horizon) Default implementation callspredict in a loop and stacks results.
Adapters where the underlying library supports batch inference should
override this for performance.
StatsForecastAdapter.predict_quantiles
Parameters
history : Series, shape (n_series, T) quantiles : NDArray, shape (n_quantiles,) Values in(0, 1). Must come in symmetric pairs around 0.5;
q == 0.5 is rejected.
Returns
Forecast, shape (n_series, n_quantiles, horizon) Quantiles are on the middle axis, in the order the user requested.Raises
ValueError If quantiles fail the symmetric-pair / range checks, or if the underlying model did not return a requested quantile column. UnsupportedCapability If the adapter was constructed withexog_features. The
SupportsQuantiles contract has no X parameter, so there is
no way to supply the future regressors — and forecasting a model
fit with regressors without them yields intervals that look
plausible and are not the model’s.
StatsForecastAdapter.refit
exog_features:
a Series panel carries target values only, so there is nowhere for
the regressors’ new values to come from.
Parameters
history : Series, shape (n_series, T)Raises
ValueError Ifexog_features was set, or if the series IDs change.
StatsForecastAdapter.sf
StatsForecastAdapter.supports
SupportsQuantiles contract has no X
parameter, so an adapter built with exog_features cannot honour it —
there would be no way to supply the future regressors. Reporting that
through supports puts the failure where the forecaster is bound
— the first thing calibrate / calibrate_cv do — which is where
CLAUDE.md requires capability checks to happen; without it, an exogenous
adapter calibrates a CQR method happily and only fails at predict —
after the user has paid for a full CV calibration.
Mirrors :meth:NeuralForecastAdapter.supports, which gates on the
fitted loss for the same reason.
Parameters
capability : type A capability mixin class.Returns
boolStatsForecastAdapter.target_col
StatsForecastAdapter.time_col
StatsForecastAdapter.train_df
MLForecastAdapter
Bases: ForecasterAdapter, SupportsRefit, SupportsCrossValidation
Adapter for a fitted :class:mlforecast.MLForecast instance.
The adapter wraps point forecasters only. Any MLForecast configuration
that produces intervals natively (prediction_intervals) is rejected at
construction; conformalforecast produces its own intervals from point forecasts.
n_series is derived from train_df rather than accepted; passing it
is refused at construction.
Parameters
mlf : MLForecast An already-fitted MLForecast instance with point models only. train_df : pandas.DataFrame or polars.DataFrame The long-format DataFrame used to fitmlf. Kept in its own backend:
a polars frame means every frame handed to MLForecast is polars.
horizon : int
Forecast horizon in time steps.
freq : str or int
The freq you passed to MLForecast: a pandas alias ('D', 'MS')
for pandas frames, a polars interval ('1d', '1mo') for polars
frames, or an int for an integer time column.
model_name : str
Which model column to read from MLForecast output. Must be an alias
present in mlf.models_.
id_col : str
Column identifying individual series (default 'unique_id').
time_col : str
Timestamp column (default 'ds').
target_col : str
Target value column (default 'y').
exog_features : list of str or None
Names of the future exogenous columns mlf was fitted with. Required
to pass X to :meth:predict, and train_df must carry them:
MLForecast.predict rebuilds its feature matrix from the history
frame, so the regressors’ past values have to travel with it.
Notes
Not serialisable, deliberately: mlf is a live library object and
train_df a DataFrame, so model_validate(model_dump()) cannot
rebuild one — and it would be refused anyway, since a dump carries the
derived n_series. Those two fields are hidden from
model_json_schema() along with the derived ones, so a schema-filled
call still has to supply mlf and train_df programmatically; the
schema describes the scalar arguments only.
MLForecastAdapter.cross_validate
Parameters
n_windows : int Number of evaluation windows (>= 1). step_size : int Steps between successive windows (>= 1). refit : bool or int Whether (or how often) to refit between windows. aligned : bool, default FalseFalse returns dense per-series arrays (window axis = k steps
before each series’ own end). True returns calendar-aligned
cutoffs with NaN cells for late-starting series.
Returns
predictions : Forecast, shape (n_series, n_windows, horizon) truths : Forecast, shape (n_series, n_windows, horizon)MLForecastAdapter.exog_features
MLForecastAdapter.freq
MLForecastAdapter.horizon
MLForecastAdapter.id_col
MLForecastAdapter.mlf
MLForecastAdapter.model_name
MLForecastAdapter.n_series
MLForecastAdapter.predict
history sits in the training data.
Parameters
history : Series, shape (n_series, T) X : Forecast or None, shape (n_series, 1, horizon, n_features) Future exogenous features, aligned to thehorizon steps that
follow history. Requires the adapter to have been constructed
with exog_features=[...].
Returns
Forecast, shape (n_series, 1, horizon)Raises
ValueError IfX is not None but the adapter was constructed without
exog_features.
MLForecastAdapter.predict_batch
Parameters
histories : list of Series, each shape (n_series, T) X : Exog or None, shape (n_series, len(histories), horizon, n_features) Per-window future exogenous features; windoww receives
X[:, w:w+1, :, :].
Returns
Forecast, shape (n_series, len(histories), horizon) Default implementation callspredict in a loop and stacks results.
Adapters where the underlying library supports batch inference should
override this for performance.
MLForecastAdapter.refit
exog_features:
a Series panel carries target values only, so there is nowhere for
the regressors’ new values to come from.
Parameters
history : Series, shape (n_series, T)Raises
ValueError Ifexog_features was set, or if the series IDs change.
MLForecastAdapter.supports
SupportsRefit depends on how the adapter was configured rather than
on its class: a history panel carries target values only, so refitting
an exogenous model would retrain it without its regressors. Gating here
means the failure surfaces where the forecaster is bound, at the top of
calibrate / calibrate_cv, not mid-calibration.
MLForecastAdapter.target_col
MLForecastAdapter.time_col
MLForecastAdapter.train_df
NeuralForecastAdapter
Bases: ForecasterAdapter, SupportsRefit, SupportsCrossValidation, SupportsQuantiles, SupportsCrossValidationQuantiles
Adapter for a fitted :class:neuralforecast.NeuralForecast instance.
The adapter wraps point forecasters only. Any NeuralForecast
configuration that produces intervals natively (prediction_intervals)
is rejected at construction; conformalforecast produces its own intervals
from point forecasts.
The horizon is read from the underlying models’ h attribute. All
models in nf.models must share the same horizon.
horizon, n_series and exog_features are all derived — from the
models’ h, from train_df, and from the selected model’s
futr_exog_list respectively — rather than accepted; passing any of them
is refused at construction.
Parameters
nf : NeuralForecast An already-fitted NeuralForecast instance with point models only. train_df : pandas.DataFrame or polars.DataFrame The long-format DataFrame used to fitnf. Kept in its own backend:
a polars frame means every frame handed to NeuralForecast is polars.
freq : str or int
The freq you passed to NeuralForecast: a pandas alias ('D', 'MS')
for pandas frames, a polars interval ('1d', '1mo') for polars
frames, or an int for an integer time column.
model_name : str
Which model column to read from NeuralForecast output. Must be the
alias of a model in nf.models (or its class name if no alias was
set explicitly).
id_col : str
Column identifying individual series (default 'unique_id').
time_col : str
Timestamp column (default 'ds').
target_col : str
Target value column (default 'y').
Notes
Not serialisable, deliberately:nf is a live library object and
train_df a DataFrame, so model_validate(model_dump()) cannot
rebuild one — and it would be refused anyway, since a dump carries the
derived horizon, n_series and exog_features. Those two fields are hidden from
model_json_schema() along with the derived ones, so a schema-filled
call still has to supply nf and train_df programmatically; the
schema describes the scalar arguments only.
NeuralForecastAdapter.cross_validate
Parameters
n_windows : int Number of evaluation windows (>= 1). step_size : int Steps between successive windows (>= 1). refit : bool or int Whether (or how often) to refit between windows. aligned : bool, default FalseFalse returns dense per-series arrays (window axis = k steps
before each series’ own end). True returns calendar-aligned
cutoffs with NaN cells for late-starting series.
Returns
predictions : Forecast, shape (n_series, n_windows, horizon) truths : Forecast, shape (n_series, n_windows, horizon)NeuralForecastAdapter.cross_validate_quantiles
Parameters
n_windows : int Number of evaluation windows (>= 1). step_size : int Steps between successive windows (>= 1). quantiles : NDArray, shape (n_quantiles,) Values in(0, 1). Symmetric-pair / range rules of
:func:_nixtla_common.quantiles_to_levels apply.
refit : bool or int
Whether (or how often) to refit between windows.
Returns
quantile_predictions : Forecast, shape (n_series, n_windows, horizon, n_quantiles) Quantiles are on the last axis, in the order requested. truths : Forecast, shape (n_series, n_windows, horizon)Raises
UnsupportedCapability If the underlying model was fit with a non-probabilistic loss. ValueError Ifn_windows / step_size are invalid, the quantile
validation fails, or the model did not return a requested
quantile column.
RuntimeError
If the cross-validation output contains NaN.
NeuralForecastAdapter.exog_features
NeuralForecastAdapter.freq
NeuralForecastAdapter.horizon
NeuralForecastAdapter.id_col
NeuralForecastAdapter.model_name
NeuralForecastAdapter.n_series
NeuralForecastAdapter.nf
NeuralForecastAdapter.predict
history sits in the training data.
Parameters
history : Series, shape (n_series, T) X : Forecast or None, shape (n_series, 1, horizon, n_features) Future exogenous features. Not supported by this adapter.Returns
Forecast, shape (n_series, 1, horizon)Raises
ValueError IfX is not None but the model declares no future exogenous
features, or if it declares them and X is None.
NeuralForecastAdapter.predict_batch
Parameters
histories : list of Series, each shape (n_series, T) X : Exog or None, shape (n_series, len(histories), horizon, n_features) Per-window future exogenous features; windoww receives
X[:, w:w+1, :, :].
Returns
Forecast, shape (n_series, len(histories), horizon) Default implementation callspredict in a loop and stacks results.
Adapters where the underlying library supports batch inference should
override this for performance.
NeuralForecastAdapter.predict_quantiles
Parameters
history : Series, shape (n_series, T) quantiles : NDArray, shape (n_quantiles,) Values in(0, 1). Must come in symmetric pairs around 0.5;
q == 0.5 is rejected. NeuralForecast’s runtime behaviour for
MQLoss ignores arbitrary quantile requests in favour of the
quantiles the loss was trained with — this adapter therefore
uses level= (the underlying API both losses honour) and
requires symmetric inputs.
Returns
Forecast, shape (n_series, n_quantiles, horizon) Quantiles are on the middle axis, in the order requested.Raises
UnsupportedCapability If the underlying model was fit with a non-probabilistic loss. ValueError If the symmetric-pair / range checks fail, or if the model did not return a requested quantile column. ForMQLoss, the
requested quantiles must match a symmetric pair the loss was
trained with.
NeuralForecastAdapter.refit
fit retrains the neural networks from
scratch and may take significantly longer than the StatsForecast or
MLForecast equivalents. For online-style usage, batch the refits.
Not available when the model declares future exogenous features: a
Series panel carries target values only, so there is nowhere for the
regressors’ new values to come from.
Parameters
history : Series, shape (n_series, T)Raises
ValueError If the model declares future exogenous features.NeuralForecastAdapter.supports
_supports_quantiles_runtime for
:class:SupportsQuantiles / :class:SupportsCrossValidationQuantiles
and defers to the default isinstance check otherwise. This puts the
runtime quantile gate at the top of calibrate / calibrate_cv,
where the forecaster is bound, rather than surfacing it only at
predict time.

