LSTMForecaster¶

class omnicast.LSTMForecaster(lookback=12, hidden_size=32, num_layers=1, epochs=200, learning_rate=0.01, dropout=0.0, seed=0)[source]

Bases: BaseForecaster

Autoregressive LSTM forecaster wrapping torch.nn.LSTM.

Not an R port – this wraps a major Python deep-learning module the same way ETSForecaster/ARIMAForecaster wrap statsmodels. Requires the optional torch extra (pip install omnicast[torch]); raises a clear ImportError naming the missing package if torch is absent, and the module still imports cleanly without it.

The series is standardized (zero mean, unit variance, computed from training data only) and reframed as a sliding-window supervised regression: lookback consecutive points predict the next one. A single-layer (by default) LSTM is trained with Adam/MSE, full-batch, for epochs iterations – appropriate for the short series typical of this package, not for large-scale training. Multi-step forecasts are produced autoregressively: each predicted point is fed back in as the most recent observation of the next window.

Prediction intervals use the same residual-variance random-walk scaling (sqrt(sigma2 * h)) as NaiveForecaster and ThetaForecaster – an approximation, since the network has no closed-form predictive variance.

Not included in AutoForecaster’s default candidate list: it is optional-dependency and materially slower to backtest than the built-in statistical models. Pass it explicitly via AutoForecaster(models=[…]) to include it.

Minimum sample size: lookback + 2 observations. Training is not deterministic across torch versions/hardware even with a fixed seed; do not rely on exact reproducibility across environments.

Examples

>>> import pandas as pd
>>> from omnicast import LSTMForecaster
>>> y = pd.Series([10.0, 12.0, 11.0, 13.0, 15.0, 14.0, 16.0, 15.0])
>>> model = LSTMForecaster(lookback=2, hidden_size=4, epochs=30, seed=0).fit(y)
>>> forecast = model.predict(horizon=2)  # values vary slightly by platform

Notes

When to use this model¶
Best for	Exploring a nonlinear, learned alternative once the built-in statistical models have been tried; short series only
Avoid when	You need a fast default, exact reproducibility across machines, or don’t want the optional `torch` dependency – never included in `AutoForecaster`’s default candidates for these reasons
Handles trend	Implicitly, via the sliding-window autoregression
Handles seasonality	Only if `lookback` spans a full cycle; no explicit seasonal component
Extra dependencies	`torch` (`pip install omnicast[torch]`)
Min. observations	`lookback + 2`

Parameters:

lookback (int)
hidden_size (int)
num_layers (int)
epochs (int)
learning_rate (float)
dropout (float)
seed (int)

fit(y, X=None)

Return type:

BaseForecaster

Parameters:

y (Iterable[float] | Series)
X (object)

fit_predict(y, horizon, **kwargs)

Return type:

ForecastResult

Parameters:

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

get_params()

Return type:: dict[str, object]

predict(horizon, X=None, level=(80, 95))

Return type:

ForecastResult

Parameters:

horizon (int)
X (object)
level (float | Iterable[float])

The package’s first neural model: wraps torch.nn.LSTM, following the same BaseForecaster interface as the statsmodels-backed estimators. Requires the optional torch extra:

pip install omnicast[torch]

If torch isn’t installed, the module still imports cleanly, and only fit() raises a clear ImportError naming the missing package.

from omnicast import LSTMForecaster

model = LSTMForecaster(
    lookback=12,      # window of past points used to predict the next one
    hidden_size=16,
    num_layers=1,
    epochs=150,
    learning_rate=1e-2,
    seed=0,
).fit(y)
forecast = model.predict(horizon=6, level=[80, 95])
print(forecast.to_frame())

           mean  lower_80  upper_80  lower_95  upper_95
2026-01  204.24    201.46    207.03    199.98    208.50
2026-02  209.65    205.70    213.59    203.62    215.67
2026-03  212.22    207.40    217.05    204.84    219.61
2026-04  212.16    206.58    217.73    203.63    220.68
2026-05  210.43    204.20    216.66    200.90    219.96
2026-06  207.81    200.99    214.64    197.37    218.25

The series is standardized (zero mean, unit variance, from training data only) and reframed as sliding windows of length lookback predicting the next point; training is full-batch Adam/MSE for epochs iterations. Multi-step forecasts are autoregressive – each predicted point is fed back in as the newest observation of the next window, so errors can compound over a long horizon the way they do for any autoregressive model.

Not in AutoForecaster’s default candidates

LSTMForecaster is optional-dependency and materially slower to backtest than the built-in statistical models, so AutoForecaster never selects it automatically. Include it explicitly:

AutoForecaster(models=[LSTMForecaster(), ThetaForecaster(seasonal_period=12)])

Reproducibility

seed fixes torch.manual_seed, but training is not guaranteed deterministic across torch versions or hardware (CPU/GPU, BLAS backend). Don’t rely on bit-exact reproduction across environments.

Minimum sample size is lookback + 2 observations; fit raises ValueError below that.