Omnicast

Automatic statistical forecasting for Python with one consistent, interval-aware API -- fit, backtest, and plot every model the same way.

Status: v0.1 alpha (renamed from auto-time-series). The API is usable, but model coverage and R parity fixtures are still growing.

Install

pip install omnicast

For local development:

uv sync --extra dev

Full docs with a worked example for every model, a real-data walkthrough, and the complete API reference are hosted at afraz496.github.io/omnicast (source under docs/). Build them locally with:

uv sync --extra docs
uv run sphinx-build -b html docs docs/_build/html

LSTMForecaster requires PyTorch, kept out of the base install:

pip install omnicast[torch]
# or, for development:
uv sync --extra dev --extra torch

Quick start

import pandas as pd
from omnicast import AutoForecaster

y = pd.Series(
    [112, 118, 121, 130, 128, 137, 143, 149, 154, 162, 169, 175],
    index=pd.period_range("2025-01", periods=12, freq="M"),
)

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

forecast = model.predict(horizon=6, level=[80, 95])
print(model.leaderboard_)
print(forecast.to_frame())

Every fitted estimator exposes fitted_values_, residuals_, sigma2_, and prediction_intervals_. Statistical estimators also expose params_, parameter_confidence_intervals_ (95%), aic_, and bic_. Prediction intervals are returned on each prediction because they depend on horizon and requested coverage.

Models

Estimator	Purpose	Intervals
NaiveForecaster	Random walk	Horizon-scaled Gaussian innovation
SeasonalNaiveForecaster	Seasonal random walk	Cycle-scaled Gaussian innovation
MeanForecaster	Historical mean	Mean forecast uncertainty
DriftForecaster	Random walk with drift	Drift forecast uncertainty
ThetaForecaster	Theta method (port of R forecast::thetaf)	Random-walk innovation scaling
ETSForecaster	Error/trend/seasonal state space	State-space forecast uncertainty
ARIMAForecaster	ARIMA/SARIMA, optional regressors	State-space forecast uncertainty
AutoARIMAForecaster	AICc grid-selected ARIMA	State-space forecast uncertainty
LSTMForecaster	Autoregressive LSTM (torch, optional)	Random-walk innovation scaling
AutoForecaster	Rolling-origin model selection	Selected model's intervals

Evaluation

from omnicast import NaiveForecaster, backtest

folds = backtest(NaiveForecaster(), y, horizon=3, initial=6, metric="rmse")
print(folds)

Available metrics are MAE, RMSE, MAPE, and sMAPE. Backtesting uses expanding windows and never trains on future observations.

Design and scope

The package follows pandas index semantics and the familiar fit/predict estimator pattern. Learned state uses trailing underscores. Models validate input rather than silently imputing data or guessing an irregular date frequency.

This codebase is a Python implementation foundation, not a blanket claim of parity with R forecasting packages. Each future port must record its algorithm source, licensing, deviations, and numerical parity tests. See CONTRIBUTING.md.

ThetaForecaster is the first R port: a compatible pure-Python reimplementation of forecast::thetaf's classical Theta method, described in its own docstring along with the exact deviations from R's output (approximate intervals, no numerical parity fixtures yet).

LSTMForecaster is the first wrapper around a Python deep-learning module (torch, optional dependency), following the same BaseForecaster interface as the statsmodels-backed models. It is not part of AutoForecaster's default candidate list -- pass it explicitly via AutoForecaster(models=[...]) -- since it is optional-dependency and materially slower to backtest.

Contributors

• Afraz Arif Khan (@Afraz496) -- core estimator API, statistical models, evaluation, and the Sphinx docs site.
• Javier Martínez-Rodríguez (@JavierMtzRdz) -- the plotting and backtesting system: ForecastResult/BacktestResult and their .plot() methods, the Backtester class, every function in omnicast.plotting, AutoForecaster.plot_all(), and the real-data forecasting walkthrough notebook.

Licensed under Apache-2.0.