VARXResult

class cultivars.multivariate.reduced_form.vector_autoregression.VARXResult(*, endog, names, order, trend, sigma_u, sigma_ml, resid, fittedvalues, design, llf, nobs, n_params, posterior=None, prior_label='none', coefficients, deterministic, exog, exog_names, exog_order, exog_coefficients)

A fitted vector autoregression with exogenous regressors.

The estimated system is

\[y_t = D d_t + \sum_{i=1}^{p} A_i y_{t-i} + \sum_{j=0}^{s} B_j x_{t-j} + u_t, \qquad u_t \sim (0, \Sigma_u),\]

with the distributed lag of \(x\) appended to the design after the endogenous lags. Everything the reduced-form surface offers is inherited unchanged, because the exogenous block does not enter the moving-average representation: irf, fevd, historical_decomposition, granger_causality, stability_check and residual_diagnostics read the endogenous dynamics and are therefore the same objects they are for a plain VAR on \((A_1, \dots, A_p, \Sigma_u)\).

forecast() is the exception, and it is the only new behaviour in the model. A VARX forecast is conditional on a path for \(x\), and this class has no model of \(x\) to supply one, so it asks for the path and refuses without it.

Note

Granger causality is a test between endogenous variables. An exogenous regressor cannot be named as a cause, because its block is conditioned on rather than modelled; the coefficient on it and its lags, with standard errors, is in params, bse and equation().

Variables:

• endog – The (n, k) endogenous sample.

• exog – The (n, m) exogenous sample, aligned on the same index.

• names – Endogenous labels, in Cholesky order.

• exog_names – Exogenous labels.

• order – Endogenous autoregressive order p.

• exog_order – Exogenous lags s beyond the contemporaneous term.

• trend – "n", "c" or "ct".

• coefficients – (p, k, k) stack of A_1, ..., A_p.

• exog_coefficients – (s + 1, k, m) stack of B_0, ..., B_s.

• deterministic – (d, k) deterministic coefficients.

• sigma_u – Residual covariance with the degrees-of-freedom correction.

• sigma_ml – Residual covariance divided by the effective sample.

• resid – (nobs, k) residuals over the effective sample.

• fittedvalues – (nobs, k) one-step conditional means.

• design – (nobs, d + kp + m(s + 1)) regressor matrix as estimated.

• llf – Gaussian log-likelihood.

• nobs – Effective sample size n - max(p, s).

• n_params – Free parameters, covariance included.

See also

• VARX – the model whose fit() returns this record.

• VARResult – the surface this record inherits.

• GVAR – consumes to_varx() to close conditional units into one system.

References

Lütkepohl, H. (2005). New Introduction to Multiple Time Series Analysis. Springer. Chapter 10.

Example

A bivariate system driven by one exogenous series that hits the first equation on impact and the second with a lag. The fit recovers both impact matrices, the fitted values are the design applied row by row, and the forecast needs the future path:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> A = np.array([[0.5, 0.2], [0.0, 0.4]])
>>> B0, B1 = np.array([[1.0], [0.0]]), np.array([[0.0], [0.5]])
>>> x = rng.standard_normal((200, 1))
>>> y = np.zeros((200, 2))
>>> for t in range(1, 200):
...     y[t] = A @ y[t - 1] + B0 @ x[t] + B1 @ x[t - 1] + 0.3 * rng.standard_normal(2)
>>> res = VARX(y, x, order=1, exog_order=1, names=("a", "b"), exog_names=("z",)).fit()
>>> res.exog_coefficients.shape, res.k_exog, res.nobs, res.n_params
((2, 2, 1), 1, 199, 13)
>>> bool(np.abs(res.exog_coefficients[0] - B0).max() < 0.1)
True
>>> bool(np.abs(res.exog_coefficients[1] - B1).max() < 0.1)
True
>>> fitted = (
...     res.deterministic[0]
...     + y[:-1] @ res.coefficients[0].T
...     + x[1:] @ res.exog_coefficients[0].T
...     + x[:-1] @ res.exog_coefficients[1].T
... )
>>> bool(np.allclose(fitted, res.fittedvalues))
True
>>> res.forecast(2, exog_future=np.zeros((2, 1))).shape
(2, 2)
>>> res.forecast(2)
Traceback (most recent call last):
cultivars.exceptions.SpecificationError: a VARX forecast is conditional on the ...

Attributes

coefficients	The (p, k, k) autoregressive stack A_1, ..., A_p on the endogenous lags.
deterministic	The (d, k) deterministic coefficients, one row per term in the order constant, trend.
exog	The (n, m) exogenous sample as supplied, aligned with endog row for row.
exog_names	The exogenous labels, in the column order of exog.
exog_order	Exogenous lags s beyond the contemporaneous term.
exog_coefficients	The (s + 1, k, m) distributed-lag stack B_0, ..., B_s; B_0 is the impact.
bse	Standard errors, keyed identically to params.
coefficient_covariance	Covariance of the coefficient matrix, sampling or posterior.
companion	The (kp, kp) companion matrix of the autoregressive block.
design
endog
fittedvalues
information_criteria	AIC, BIC, and HQIC derived from the likelihood and parameter count.
is_stable	Whether every companion eigenvalue lies inside the unit circle.
k_endog	Number of endogenous variables.
k_exog	Number of exogenous variables.
llf
n_params
names
nobs
order
params	Every coefficient, keyed "{equation}: {regressor}".
posterior
prior_label
pvalues	Two-sided p-values against zero, keyed identically to params.
resid
sigma_ml
sigma_u
trend
tvalues	Normal test statistics against zero, keyed identically to params.

Methods

arch_test(variable[, lags])	Engle's LM test for conditional heteroskedasticity in one equation.
compare(*others[, criterion])	Rank this result against others by an information criterion.
conf_int(*[, alpha])	Confidence bounds for every coefficient.
equation(name)	The coefficients of one equation, keyed by regressor.
fevd([horizon])	Forecast-error variance decomposition.
forecast([steps, exog_future])	Point forecasts conditional on a future path for the exogenous block.
generalized_fevd([horizon])	Variance shares from the generalized responses, normalized to sum to one.
generalized_irf([horizon, cumulative])	Pesaran-Shin impulse responses, which do not depend on variable order.
granger_causality(cause, effect)	Wald test that one variable's lags are jointly zero in another equation.
historical_decomposition()	Attribute each observation to the shocks that produced it.
identify(strategy)	Declare an identification scheme and return the structural view.
irf([horizon, orthogonalized, cumulative])	Impulse responses to a one-standard-deviation shock.
likelihood_ratio_test(unrestricted)	Test this result as the restricted model against a nesting one.
ma_representation([horizon])	Moving-average matrices Psi_0, ..., Psi_horizon.
normality_test(variable)	Jarque-Bera test on one equation's residuals.
portmanteau_test([lags])	Multivariate Ljung-Box test for residual autocorrelation.
residual_diagnostics(*[, portmanteau_lags, ...])	Run every residual test and collect them into one table.
simulate([n, seed, burn])	A fresh sample path from the fitted system.
stability_check()	Eigenvalue verdict for the companion matrix.
structural_shocks()	Orthogonalized innovations P^{-1} u_t, shape (nobs, k).
summary()	The estimation summary, renderable as text, HTML, or a dataframe.
to_varx()	This unit's equations in levels, as a global system consumes them.