SARIMA/SARIMAX
Install and import#
npm install fintech-algorithmsimport { forecastSARIMAX } from "fintech-algorithms/statistical-time-series/forecast-models/sarima-sarimax";Signature#
forecastSARIMAX(values, exog, futureExog, beta, ar, ma, seasonalAr, seasonalMa, intercept, differenceOrder, seasonalDifferenceOrder, period, horizon)Seasonal ARIMA with optional exogenous regressors. Future exogenous values must be supplied for the whole horizon — if you do not know them, the forecast is conditional on a guess, and that dependency is worth being explicit about.
Parameters#
| Name | Type | Notes |
|---|---|---|
values | number[] | Observation series in chronological order, oldest first. |
exog | number[][] | In-sample exogenous regressors, one row per observation. |
futureExog | number[][] | Exogenous values over the forecast horizon. These are assumptions, not data. |
beta | number[] | Coefficients on the exogenous regressors. |
ar | number[] | Non-seasonal AR coefficients. |
ma | number[] | Non-seasonal MA coefficients. |
seasonalAr | number[] | Seasonal AR coefficients. |
seasonalMa | number[] | Seasonal MA coefficients. |
intercept | number | Constant term. |
differenceOrder | number | Non-seasonal differencing order. min: 0 · integer: true |
seasonalDifferenceOrder | number | Seasonal differencing order. min: 0 · integer: true |
period | number | Seasonal period — 12 for monthly, 4 for quarterly, 5 for trading days in a week. min: 1 · integer: true |
horizon | number | Steps ahead. min: 1 · integer: true |
Returns#
{ forecast, fitted, residuals, state, transformed_forecast, residualized_forecast }
The final forecast plus the transformed and residualised intermediates.
Errors#
- When futureExog is shorter than the horizon — throws
Complexity: time O(n × (p + q + P + Q)),
space O(n).
Worked example#
verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.
Input#
[12, 15, 18, 21, 24, 27]Showing 6 of 8 elements.
[
[1],
[2],
[3]
]Showing 3 of 8 elements.
[
[9],
[10]
][2][0.5][][0.25][]01022Call#
forecastSARIMAX(values, exog, futureExog, beta, ar, ma, seasonalAr, seasonalMa, intercept, differenceOrder, seasonalDifferenceOrder, period, horizon)Returns#
object with 1 field: forecast
{
"forecast": [35.625, 38.0625]
}Diagrams#
Calculation flow#
SARIMA/SARIMAX Calculation Flow
flowchart LR
A["Finalized equally spaced training series"] --> B["Validate cutoff and frozen parameters"]
B --> C["Build selected state or transformed series"]
C --> D["Calculate horizon h conditional mean"]
D --> E{"More horizons?"}
E -- "yes" --> F["Append forecast and zero future innovation"]
F --> D
E -- "no" --> G["Publish path and state trace"]
G --> H["Reveal holdout only for evaluation"]
How it works#
This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.
References#
- statsmodels.tsa.statespace.sarimax.SARIMAX — statsmodels developers
- Forecasting: Principles and Practice — Seasonal ARIMA — Rob J. Hyndman and George Athanasopoulos
- statsmodels.tsa.arima.model.ARIMA — statsmodels developers
- Forecasting: Principles and Practice — Evaluating point forecast accuracy — Rob J. Hyndman and George Athanasopoulos
- Forecasting: Principles and Practice — Time series cross-validation — Rob J. Hyndman and George Athanasopoulos
- Forecasting: Principles and Practice — Evaluating regression and residual behavior — Rob J. Hyndman and George Athanasopoulos