smooth 1.0.4

Forecasting and time series analysis with single-source-of-error state-space models (ADAM, ETS, ARIMA, occurrence, SMA)

smooth

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

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.
• 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.

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/config-i1/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)

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
• 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

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