VECMResult

class cultivars.multivariate.reduced_form.error_correction.VECMResult(*, endog, names, order, trend, sigma_u, sigma_ml, resid, fittedvalues, design, llf, nobs, n_params, posterior=None, prior_label='none', rank, cointegration_trend, alpha, beta, gamma, short_run_deterministic, eigenvalues, coefficients, deterministic)

A fitted vector error-correction model.

A VAR of order \(p\) in \(k\) integrated variables, rewritten around its unit roots,

\[\Delta y_t = \Pi\, y_{t-1} + \sum_{i=1}^{p-1} \Gamma_i\, \Delta y_{t-i} + \mu_t + u_t, \qquad \Pi = \alpha \beta',\]

with \(\Pi\) of rank \(r < k\): the columns of \(\beta\) are the cointegrating vectors, \(\beta' y_{t-1}\) the stationary disequilibria, \(\alpha\) the speeds at which each variable corrects them, and \(k - r\) common stochastic trends drive the rest. Estimation is Johansen’s reduced-rank maximum likelihood: concentrate out the short-run terms, take \(\beta\) from the eigenvalue problem, then regress the differences on [deterministic | lagged differences | error-correction terms] for everything else.

The result carries two representations of one estimate, and each half of the inherited surface reads the one it needs.

The short-run representation is what was actually regressed: differences on deterministic terms, lagged differences, and the error-correction terms. design, resid, fittedvalues, and everything built on the coefficient covariance – params, bse, pvalues, conf_int – describe that regression, so a standard error here belongs to an alpha, a Gamma, or a deterministic term, conditional on beta. The conditioning is what makes them exact rather than approximate: beta converges at rate T against the usual root-T, fast enough that everything estimated alongside it behaves as though the cointegrating space were known.

The levels representation is the vector autoregression this model reparameterizes, recovered by to_var() and exposed as coefficients. Impulse responses, the variance decomposition, and the historical decomposition read it, which is why they are inherited rather than rewritten: an error-correction model has no separate impulse-response theory, only different coordinates.

Three members depart from the reduced-form surface deliberately. stability_check() permits unit roots, because k - r of them are the specification rather than a failure. forecast() folds any restricted deterministic term back out of the cointegrating space, since a constant that lives inside beta still shifts the level of a forecast. granger_causality() restricts both transmission channels at once.

Note

Two things this record does not do. It does not test its own rank: the Johansen trace and maximum-eigenvalue tests have non-standard null distributions and live on the model as rank_test(), to be read before a rank is chosen, and a likelihood-ratio comparison of this result against a levels VAR or a VECM of another rank through the inherited likelihood_ratio_test is a chi-squared test of a restriction that is not chi-squared and should not be read. And it reports no standard errors for beta: its asymptotics are mixed-Gaussian and conditional on the normalization, so the summary prints the cointegrating vectors without inference columns.

Variables:

• endog – The sample in levels.

• names – Variable labels, in Cholesky order.

• order – Lags of the levels system; order - 1 lagged differences.

• rank – Cointegrating rank.

• cointegration_trend – The Johansen case the model was estimated under.

• trend – Deterministic terms of the levels representation, with any restricted term folded back out.

• alpha – (k, r) adjustment loadings.

• beta – (k or k + 1, r) cointegrating vectors.

• gamma – (p - 1, k, k) coefficients on lagged differences.

• coefficients – (p, k, k) implied levels autoregressive matrices.

• deterministic – (d, k) deterministic coefficients of the levels representation, restricted terms folded in.

• short_run_deterministic – (d_s, k) unrestricted deterministic terms, as they entered the short-run regression.

• eigenvalues – Squared canonical correlations, descending.

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

• sigma_ml – Residual covariance divided by the effective sample.

• resid – Residuals of the short-run equation.

• fittedvalues – Fitted differences.

• design – The short-run regressor matrix.

• llf – Gaussian log-likelihood.

• nobs – Effective sample size.

• n_params – Free parameters, covariance included.

See also

• VECM – the model whose fit() returns this record and whose rank_test() chooses the rank.

• VECMXResult – the conditional extension with weakly exogenous integrated regressors.

• VARResult – the levels system this result reparameterizes and whose propagation surface it inherits.

• GVAR – the assembler that links conditional error-correction units into one closed system.

References

Johansen, S. (1991). Estimation and hypothesis testing of cointegration vectors in Gaussian vector autoregressive models. Econometrica, 59(6), 1551-1580.

Johansen, S. (1995). Likelihood-Based Inference in Cointegrated Vector Autoregressive Models. Oxford University Press.

Lütkepohl, H. (2005). New Introduction to Multiple Time Series Analysis. Springer. Chapters 6-7.

Example

Two series sharing one stochastic trend, the second twice the first plus noise. At rank one the fit recovers the relation \(y_1 - y_2 / 2\) with the second variable doing all the adjusting, the levels companion carries exactly one unit root, and the inherited propagation surface reads the levels representation:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> common = np.cumsum(rng.standard_normal(300))
>>> y = np.column_stack([common, 2 * common + rng.standard_normal(300)])
>>> res = VECM(y, order=2, rank=1).fit()
>>> res.n_common_trends, res.trend
(1, 'c')
>>> res.normalized_beta().ravel().round(2)
array([ 1.  , -0.49])
>>> bool(res.pvalues["y1: ec1"] > 0.1), bool(res.pvalues["y2: ec1"] < 0.001)
(True, True)
>>> check = res.stability_check()
>>> check.n_unit_roots, bool(abs(check.max_modulus - 1.0) < 1e-6)
(1, True)
>>> res.irf(4).shape, res.forecast(3).shape
((5, 2, 2), (3, 2))

Attributes

coefficients	The (p, k, k) levels autoregressive matrices \(A_i\) the fit implies.
deterministic	The (d, k) deterministic coefficients of the levels representation.
alpha
beta
bse	Standard errors, keyed identically to params.
coefficient_covariance	Covariance of the coefficient matrix, sampling or posterior.
cointegrating_matrix	The long-run impact matrix \(\Pi = \alpha \beta'\), over the variables only.
cointegration_trend
companion	The (kp, kp) companion matrix of the autoregressive block.
design
eigenvalues
endog
fittedvalues
gamma
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.
llf
n_common_trends	Unit roots the specification carries, k - r.
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.
rank
resid
short_run_deterministic
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.
error_correction_terms()	The fitted disequilibria, one column per cointegrating relation.
fevd([horizon])	Forecast-error variance decomposition.
forecast([steps])	Point forecasts in levels.
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)	Test that one variable drives another through neither channel.
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.
normalized_alpha(*[, on])	Adjustment loadings rescaled to pair with normalized_beta().
normalized_beta(*[, on])	Cointegrating vectors scaled so one variable's loading is one in each.
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()	Assess the levels companion, permitting the unit roots by design.
structural_shocks()	Orthogonalized innovations P^{-1} u_t, shape (nobs, k).
summary()	The estimation summary, renderable as text, HTML, or a dataframe.
to_var()	The levels autoregressive matrices this specification implies.
weak_exogeneity(variable)	Test that a variable does not adjust to any disequilibrium.