API Reference / algorithms / timeseries /

var.py

Vector Autoregression (VAR) for multivariate time series forecasting.

Classes

VAR

class algorithms.timeseries.var.VAR(Regressor)

Vector Autoregression for multivariate time series forecasting.

A VAR treats every series in a panel as a linear function of the past values of all the series, so cross-series feedback is modelled explicitly rather than assumed away. It is the multivariate generalisation of the univariate AR model and the standard workhorse for macroeconomic and sensor-panel forecasting.
Constructor 
__init__(
    self,
    lags: Union[int, str] = 1,
    maxlags: int | None = None,
    ic: str = 'aic',
    trend: str = 'c',
)

Overview

  1. Stack the p lagged observations of every series into a single
design matrix Z, one row per usable time point.
  1. Estimate the coefficient matrices by ordinary least squares.
  2. Optionally choose the lag order over 1..maxlags by AIC or BIC,
comparing all candidates on an identical sample.
  1. Forecast recursively by feeding each prediction back in as the most
recent lag (iterating the companion form).

Theory

A VAR of order p on k series is

y_t = c + A_1 y_{t-1} + A_2 y_{t-2} + \dots + A_p y_{t-p} + \varepsilon_t , \qquad \varepsilon_t \sim (0, \Sigma),

with y_t \in \mathbb{R}^k, A_i \in \mathbb{R}^{k \times k} and c \in \mathbb{R}^k. Writing z_t = (1, y_{t-1}^\top, \dots, y_{t-p}^\top)^\top and stacking the rows gives Y = Z B + E, whose least-squares solution is

\hat{B} = (Z^\top Z)^{-1} Z^\top Y .

Because every equation shares exactly the same regressors, the seemingly-unrelated-regressions correction collapses and equation-by-equation OLS is the exact conditional maximum-likelihood estimator for a Gaussian VAR with an identical lag structure across equations -- there is nothing to gain from a joint GLS step.

Lag order is chosen by minimising an information criterion built from the ML residual covariance \hat{\Sigma}_p = E^\top E / T:

\mathrm{AIC}(p) = \ln|\hat{\Sigma}_p| + \frac{2 p k^2}{T}, \qquad \mathrm{BIC}(p) = \ln|\hat{\Sigma}_p| + \frac{\ln(T) p k^2}{T}.

Multi-step forecasts iterate the companion form: the h-step forecast uses previous forecasts in place of the unobserved future values, which is the conditional mean E[y_{n+h} \mid y_{1:n}].

Parameters

lags
int or "auto" = 1
Number of lags :math:`p`. "auto" selects the order over 1..maxlags by the criterion given in ic.
maxlags
int = None
Upper bound for automatic order selection. When None it is min(10, (n_timepoints - 1) // (n_series + 1)), floored at 1.
ic
{"aic", "bic"} = "aic"
Information criterion used when lags="auto".
trend
{"c", "n"} = "c"
"c" includes an intercept, "n" omits it.

Attributes

coefs_
np.ndarray of shape (lags, n_series, n_series)
Coefficient matrices, coefs_[i - 1] is :math:`A_i`.
intercept_
np.ndarray of shape (n_series,)
Estimated intercept :math:`c`; zeros when trend="n".
lags_
int
Lag order actually used.
n_series_
int
Number of series in the panel.
n_obs_
int
Number of time points in the training data.
sigma_
np.ndarray of shape (n_series, n_series)
Maximum-likelihood residual covariance :math:`E^\top E / T`.
ic_values_
dict or None
Criterion value per candidate lag when lags="auto".
endog_
np.ndarray of shape (n_obs, n_series)
The training panel, retained to seed recursive forecasts.
input_was_1d_
bool
Whether fit received a 1-D series, in which case predict returns a 1-D forecast.
fitted_values_
np.ndarray of shape (n_obs - lags, n_series)
In-sample one-step-ahead forecasts.
resid_
np.ndarray of shape (n_obs - lags, n_series)
In-sample residuals.

Notes

Complexity:

  • Training: O(T d^2 + d^3) with d = pk + 1 regressors
and T usable time points; order selection multiplies this by the number of candidate lags.
  • Prediction: O(h p k^2).
When to use VAR:
  • Several series that plausibly drive one another (demand and price,
several sensors on one machine, macroeconomic aggregates).
  • When you want forecasts for the whole panel jointly rather than one
model per series.
  • Requires roughly stationary series -- difference or detrend first if
the panel trends; a unit root makes the OLS estimates unreliable.
  • Parameters grow as p k^2, so keep p small on wide
panels or the fit overfits.

References

Sims1980
Sims, C. A. (1980). Macroeconomics and reality. Econometrica, 48(1), 1-48. :doi:`10.2307/1912017`
Lutkepohl2005
Lutkepohl, H. (2005). New Introduction to Multiple Time Series Analysis. Springer. :doi:`10.1007/978-3-540-27752-1`
Hamilton1994
Hamilton, J. D. (1994). Time Series Analysis. Princeton University Press.

See Also

ARIMA

Univariate Box-Jenkins forecasting.
AR

Univariate autoregression.
ThetaForecaster

Univariate Theta method.
python 
>>> import numpy as np
>>> from tuiml.algorithms.timeseries.var import VAR
>>> rng = np.random.default_rng(0)
>>> n, y = 300, np.zeros((300, 2))
>>> A = np.array([[0.5, 0.1], [-0.2, 0.3]])
>>> for t in range(1, n):
...     y[t] = A @ y[t - 1] + rng.normal(size=2)
>>> model = VAR(lags=1).fit(y)
>>> model.coefs_.shape
(1, 2, 2)
>>> model.predict(steps=4).shape
(4, 2)

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, y: np.ndarray, X: Optional[np.ndarray]=None) -> 'VAR'

Fit the VAR by equation-by-equation OLS on stacked lags.

Parameters
y
np.ndarray of shape (n_timepoints, n_series) or (n_timepoints,)
The panel of series. A 1-D array is treated as a single-series panel and predict then returns a 1-D forecast.
X
np.ndarray = None
Ignored. Present for API consistency with regressors.
Returns
self
VAR
Fitted estimator.
predict (self, steps: int=1, X: Optional[np.ndarray]=None) -> np.ndarray

Forecast the panel forward by iterating the companion form.

Parameters
steps
int = 1
Number of future time steps to forecast.
X
np.ndarray = None
Ignored. Present for API consistency with regressors.
Returns
forecast
np.ndarray of shape (steps, n_series), or (steps,)
Forecasted values. The 1-D shape is returned when fit received a 1-D series.
fit_predict (self, y: np.ndarray, steps: int=1) -> np.ndarray

Fit the model and forecast in one call.

Parameters
y
np.ndarray of shape (n_timepoints, n_series) or (n_timepoints,)
The panel of series.
steps
int = 1
Number of future time steps to forecast.
Returns
forecast
np.ndarray of shape (steps, n_series), or (steps,)
Forecasted values.