AutoForecaster¶

class omnicast.AutoForecaster(models=None, seasonal_period=None, metric='rmse', validation_horizon=1, keep_all=False)[source]

Bases: BaseForecaster

Choose the model with the best rolling-origin validation score.

With keep_all=True every candidate is also fitted on the full series and kept in fitted_ (name -> fitted model).

Examples

>>> import pandas as pd
>>> from omnicast import AutoForecaster
>>> y = pd.Series([10.0, 12.0, 11.0, 13.0, 15.0, 14.0])
>>> model = AutoForecaster().fit(y)
>>> model.leaderboard_["model"].iloc[0]
'ThetaForecaster'
>>> model.predict(horizon=2).mean.round(2).tolist()
[14.05, 14.49]

Notes

When to use this model¶
Best for	The default entry point – backtests a panel of candidates and refits the winner, so you don’t have to pick a model by hand
Avoid when	You already know which model fits, need exogenous regressors (not yet supported here), or want a single deterministic model without a backtest step
Handles trend	Depends on which candidate wins the backtest
Handles seasonality	Yes, via `seasonal_period` (adds seasonal-aware candidates)
Extra dependencies	None by default; include `LSTMForecaster` explicitly via `models=[...]` to pull in `torch`
Min. observations	Whatever the strictest candidate in `models` requires; a failing candidate is skipped rather than aborting selection

Parameters:

models (list[BaseForecaster] | None)
seasonal_period (int | None)
metric (str)
validation_horizon (int)
keep_all (bool)

fit(y, X=None)[source]

predict(horizon, X=None, level=(80, 95))[source]

plot_all(horizon=None, level=(80, 95), observed=None, intervals=False, **kwargs)[source]

Overlay every successful candidate’s forecast on one axes.

Refits each candidate on the full training series, unless the estimator was built with keep_all=True (then the stored fits are reused).

Parameters:

horizon (int, optional) – Steps to forecast. Defaults to validation_horizon.
level (float or sequence of float, default (80, 95)) – Prediction-interval coverage levels to compute.
observed (pd.Series, optional) – History to draw. Defaults to the full training series.
intervals (bool, default False) – Shade each candidate’s prediction bands. Off by default – with several candidates the overlapping bands get muddy.
**kwargs – Forwarded to the trajectory plot (title, ax, save_path, …).

fit_predict(y, horizon, **kwargs)

Return type:

ForecastResult

Parameters:

y (Iterable[float] | Series)
horizon (int)
kwargs (object)

get_params()

Return type:: dict[str, object]

Fits a panel of candidate models, scores each with rolling-origin backtesting (backtest()), and refits the winner on the full series. This is the model to reach for by default – everything else in this guide is either a candidate it already tries or a tool for building your own candidate list.

from omnicast import AutoForecaster

model = AutoForecaster(
    seasonal_period=12,
    metric="rmse",
    validation_horizon=1,
).fit(y)

print(model.leaderboard_)

                     model   score status
    AutoARIMAForecaster   1.141     ok
          ETSForecaster   4.341     ok
        ThetaForecaster   4.665     ok
        DriftForecaster   4.687     ok
        NaiveForecaster   4.850     ok
SeasonalNaiveForecaster  27.483     ok
         MeanForecaster  46.988     ok

The ranking here lines up with what the individual model pages show: AutoARIMAForecaster and ETSForecaster both model the trend and yearly seasonality directly and backtest far better than the flat MeanForecaster or SeasonalNaiveForecaster baselines. predict delegates to whichever model won:

forecast = model.predict(horizon=6, level=[80, 95])
print(forecast.to_frame())     # identical to AutoARIMAForecaster's own output
print(model.best_model_)       # the winning fitted estimator

           mean  lower_80  upper_80  lower_95  upper_95
2026-01  207.64    206.13    209.15    205.33    209.95
2026-02  215.19    213.46    216.92    212.54    217.84
2026-03  219.77    218.00    221.55    217.05    222.50
2026-04  224.87    223.04    226.71    222.07    227.68
2026-05  225.02    223.14    226.91    222.15    227.90
2026-06  223.05    221.12    224.98    220.10    226.00

Default candidates¶

With no models= argument, AutoForecaster builds: NaiveForecaster, MeanForecaster, DriftForecaster, ThetaForecaster, ETSForecaster, AutoARIMAForecaster(seasonal_period=...) – plus SeasonalNaiveForecaster inserted whenever seasonal_period is set and the series has more than one full cycle. LSTMForecaster is never a default candidate (see LSTMForecaster); include it explicitly:

from omnicast import LSTMForecaster, ThetaForecaster, AutoForecaster

model = AutoForecaster(
    models=[LSTMForecaster(seed=0), ThetaForecaster(seasonal_period=12)],
).fit(y)

Passing models=[...] replaces the default panel entirely rather than extending it – list every candidate you want considered.

Resilience to candidate failure¶

A candidate that raises during backtesting (numerical failure, non- convergence, insufficient data for its minimum sample size) does not abort selection: it’s recorded in leaderboard_ with score = inf and the exception message in status, and selection proceeds among the rest. AutoForecaster.fit only raises if every candidate fails.

validation_horizon controls the backtest’s forecast horizon per fold (not the horizon you’ll eventually call predict with – those are independent). initial for the internal backtest is chosen automatically as max(5, len(y) - max(3 * validation_horizon, len(y) // 4)).