smooth

Python implementation of the smooth package for forecasting and time series analysis using Single Source of Error (SSOE) state-space models.

Every wheel published to PyPI is signed via Sigstore on the exact GitHub Actions runner that built it and ships with PEP 740 attestations (SLSA Build Level 3 provenance). Verify a downloaded wheel client-side with pypi-attestations:

pip install pypi-attestations
pypi-attestations verify pypi --repository https://github.com/openforecast-org/smooth smooth-*.whl

The package includes the following models:

• ADAM - Augmented Dynamic Adaptive Model, uniting exponential smoothing, ARIMA and regression, implemented in the ADAM class.
• ETS - Exponential Smoothing in the SSOE state space form, implemented in the ES class.
• CES - Complex Exponential Smoothing with complex-valued smoothing parameters, implemented in the CES class (fixed seasonality type) and AutoCES class (automatic seasonality selection).
• MSARIMA - Multiple seasonal ARIMA in state space form, implemented in the MSARIMA class (fixed orders) and AutoMSARIMA class (automatic order selection).
• OM - Occurrence Model for intermittent demand, implemented in the OM class (plus OMG for the general two-component model and AutoOM for automatic type selection).
• SMA - Simple Moving Average in state-space form (an AR(m) model with fixed coefficients), implemented in the SMA class with automatic order selection.
• TBATS - De Livera et al.'s TBATS in ADAM's framework, for multiple and non-integer seasonal periods, implemented in the TBATS class.
• SM - Scale Model, a second ADAM fitted to the scale of the error term so the variance evolves over time, available as the .sm() method on a fitted model.

The package also provides standalone data generators that mirror R's sim.* family — sim_es, sim_ssarima, sim_ces, sim_gum, sim_sma, and sim_oes — plus a .simulate() method on fitted ADAM, OM, and OMG objects. See Simulation Functions.

All of these are implemented with the support of the following features:

• Automatic components selection in ETS and forecasts combination
• Explanatory variables
• Multiple seasonal models (e.g. for high frequency data)
• Advanced loss functions
• Fine tuning of any elements of ADAM/ETS/ARIMA/Regression
• A variety of prediction interval construction methods

Like the R version, the Python smooth depends on the greybox package for distributions, information criteria, regressor selection, and the LOWESS smoother. It is installed automatically as a dependency.

Installation

From PyPI (recommended):

pip install smooth

From source (development):

pip install "git+https://github.com/openforecast-org/smooth.git@master#subdirectory=python"

See the Installation Guide for platform-specific instructions.

System Requirements

If installing from source, this package requires compilation of C++ extensions. Before installing, ensure you have:

• C++ compiler (g++, clang++, or MSVC)
• CMake >= 3.25
• Armadillo linear algebra library

Quick Example

import numpy as np
from smooth import ADAM

# Sample data
y = np.array([10, 12, 15, 13, 16, 18, 20, 19, 22, 25, 28, 30,
              11, 13, 16, 14, 17, 19, 21, 20, 23, 26, 29, 31])

# Fit ADAM model with additive error, no trend, no seasonality
model = ADAM(model="ANN")
model.fit(y)

# Generate forecasts
forecasts = model.predict(h=12)

# With seasonal component (monthly data, annual seasonality)
model = ADAM(model="ANA", lags=[1, 12])
model.fit(y)
forecasts = model.predict(h=12)

ADAMX — ADAM with Explanatory Variables

This also works with the exponential smoothing (ETSX) via the ES() class.

import numpy as np
from smooth import ADAM

# Simulate data where y depends on two external regressors
rng = np.random.default_rng(42)
n = 120
X = rng.standard_normal((n, 2))
y = 10 + 2 * X[:, 0] - 1.5 * X[:, 1] + rng.standard_normal(n)

# Fit ETSX(AAN) — use all regressors with fixed coefficients
model = ADAM(model="AAN", regressors="use")
model.fit(y, X)
print(model)           # shows fitted coefficients including xreg

# Forecast 12 steps ahead with future regressor values
X_future = rng.standard_normal((12, 2))
fc = model.predict(h=12, X=X_future)
print(fc.mean)

# Automatic variable selection (drops insignificant regressors)
model_sel = ADAM(model="AAN", regressors="select")
model_sel.fit(y, X)

# Adaptive (time-varying) regressor coefficients
model_adp = ADAM(model="AAN", regressors="adapt")
model_adp.fit(y, X)

X accepts a NumPy array or a pandas DataFrame (column names are preserved as regressor names). regressors controls treatment: "use" (fixed coefficients), "select" (stepwise selection via greybox), or "adapt" (ETS-style time-varying coefficients).

AutoMSARIMA — Automatic ARIMA Order Selection

AutoMSARIMA selects the best ARIMA orders automatically using information criteria, mirroring R's auto.msarima(). It fixes distribution="dnorm" and uses pure ARIMA (no ETS components).

import numpy as np
from smooth import AutoMSARIMA

# Monthly time series (e.g. AirPassengers, 144 observations)
y = np.array([
    112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
    # ... remaining observations
], dtype=float)

# Automatic seasonal ARIMA — searches up to ARIMA(3,2,3)(3,1,3)[12]
model = AutoMSARIMA(lags=[1, 12])
model.fit(y)
print(model)   # AutoMSARIMA: ARIMA([p,P],[d,D],[q,Q])

# Reduce search space for speed
model = AutoMSARIMA(
    lags=[1, 12],
    ar_order=[2, 1],   # max AR: p≤2 at lag 1, P≤1 at lag 12
    i_order=[2, 1],    # max I:  d≤2 at lag 1, D≤1 at lag 12
    ma_order=[2, 1],   # max MA: q≤2 at lag 1, Q≤1 at lag 12
)
model.fit(y)
fc = model.predict(h=24)

CES — Complex Exponential Smoothing

CES and AutoCES mirror R's ces() / auto.ces(). CES uses complex-valued smoothing parameters to capture both the level and the "potential" of a series, covering four seasonality modes: "none", "simple", "partial", "full".

import numpy as np
from smooth import CES, AutoCES

y = np.array([
    112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
    115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140,
], dtype=float)

# CES with a fixed seasonality type
model = CES(seasonality="partial", lags=[1, 12], h=6, holdout=True)
model.fit(y)
print(model.model_name)         # e.g. "CES(partial)"
print(model.a_, model.b_)       # complex smoothing parameters
fc = model.predict(h=6)
print(fc.mean)

# AutoCES — select the best seasonality type by information criterion; fit()
# returns the selected CES, with the criteria of all the candidates in ICs
best = AutoCES(lags=[1, 12], h=6, holdout=True, ic="AICc").fit(y)
print(best.model_name, best.ICs)

Note: strict R-parity in the two-stage NLopt path requires nlopt>=2.10.0; older versions still fit, but the BOBYQA stage-1 trajectory may differ slightly from R.

SM — Scale Model

A scale model is a second ADAM fitted to a transform of the location model's residuals, so the error's scale varies over time instead of being one number — the state-space counterpart of a GARCH or GAMLSS scale equation. It mirrors R's sm(), and is scored by the location model's likelihood, so the information criteria of the two are directly comparable.

import numpy as np
from smooth import ADAM

# Monthly series whose noise grows with the level
rng = np.random.default_rng(42)
t = np.arange(120)
level = 100 + 0.8 * t + 10 * np.sin(2 * np.pi * t / 12)
y = level * (1 + rng.normal(0, 0.02 + 0.0004 * t))

# Location model: the mean. Requires loss="likelihood" (the default).
model = ADAM(model="AAA", lags=[1, 12], distribution="dnorm")
model.fit(y)
print(model.aicc)                     # 801.9385 — one constant scale

# Scale model: the variance. "YYY" (the default) selects among multiplicative ETS.
scale = model.sm(model="MNN")
model.scale_model = scale             # this assignment is R's implant()
print(model.aicc)                     # 775.9587 — now a time-varying scale

print(scale.model_name)               # ETS(MNN)
print(model.extract_scale()[:3])      # [2.930 2.853 2.766] — scale per observation

# Prediction intervals now widen and narrow with the fitted scale
fc = model.predict(h=12, interval="prediction", level=0.95)
print(fc.upper[:3])

sm is also importable directly — from smooth import sm, then sm(model, ...), which mirrors R's call form; it is the same function the method wraps.

sm() supports seven distributions — dnorm, dlaplace, ds, dgnorm, dlnorm, dgamma, dinvgauss — and takes the usual ADAM arguments (lags, orders, regressors, X, initial, ic, bounds), so the scale can carry its own ETS structure, ARIMA orders or explanatory variables. Set model.scale_model = None to detach it. There is no implant() function: Python can modify a fitted object in place, so assignment does the job.

TBATS — Multiple and Non-Integer Seasonality

TBATS mirrors R's tbats(): De Livera, Hyndman and Snyder's (2011) model in ADAM's single source of error framework — an ETS level and trend, a trigonometric seasonality for each period and ARMA errors, after a Box-Cox transform. The periods can be several and need not be integers; the number of harmonics, the trend, the ARMA orders and the distribution are selected automatically.

import numpy as np
from smooth import TBATS

# Ten years of weekly data with a yearly cycle of 52.18 weeks
t = np.arange(1, 521)
y = 100 + 0.05 * t + 10 * np.sin(2 * np.pi * t / 52.18) + np.random.normal(0, 2, 520)

model = TBATS(lags=[1, 52.18], h=52, holdout=True).fit(y)
print(model.model_name)        # TBATS(lambda, {p,q}, phi, <52.18,k>)
fc = model.predict(h=52, interval="prediction")
print(fc.mean[:3])

See the TBATS wiki page for the details.

Documentation

• GitHub Wiki - Full documentation
• ADAM - Main unified ETS/ARIMA framework
• Installation Guide - Dependencies and troubleshooting

The pages below document the models and their Python classes:

• ADAM — Augmented Dynamic Adaptive Model — unified ETS/ARIMA/regression framework
• AutoADAM — Automatic ADAM with distribution and ARIMA order selection
• ES — Exponential Smoothing (ETS) wrapper for ADAM
• CES — Complex Exponential Smoothing (CES, AutoCES)
• MSARIMA — Multiple Seasonal ARIMA (fixed orders) and automatic selection (AutoMSARIMA)
• OM — Occurrence Model for intermittent demand (OM, OMG, AutoOM)
• SMA — Simple Moving Average in state-space form with automatic order selection
• TBATS — Trigonometric seasonality, Box-Cox and ARMA for multiple and non-integer seasonal periods
• Scale Model — model.sm(), a dynamic model for the scale of the error term
• Simulation Functions — sim_es, sim_ssarima, sim_ces, sim_gum, sim_sma, sim_oes, and the .simulate() method on fitted models

Book: Svetunkov, I. (2023). Forecasting and Analytics with the Augmented Dynamic Adaptive Model (ADAM). Chapman and Hall/CRC. Online: https://openforecast.org/adam/

See Also

• R package on CRAN - Production-ready R implementation

About

smooth is developed and maintained by OpenForecast, a demand forecasting and inventory management consultancy. The package implements the methods we use in our consulting and teach in our training courses.