GibbsBVARResult

class cultivars.multivariate.large_dim.gibbs.GibbsBVARResult(*, endog, names, order, trend, prior_label, coefficients, deterministic, beta_mean, sigma_u, beta_draws, sigma_draws, shrinkage, shrinkage_label, resid, fittedvalues, nobs, n_dummy, n_draws, n_burn, thin, _engine)

A fitted Gibbs BVAR: a sampled posterior, and the prior’s own diagnostics.

The posterior of

\[y_t = c + \sum_{i=1}^{p} A_i y_{t-i} + u_t, \qquad u_t \sim N(0, \Sigma),\]

under a prior on the stacked coefficients \(\beta\) stated independently of \(\Sigma\), reached by Gibbs sampling: a joint generalized-least-squares draw of \(\beta \mid \Sigma, y\), an inverse-Wishart draw of \(\Sigma \mid \beta, y\), and, under an adaptive prior, one sweep of the scale hierarchy’s conditionals. The propagation surface – credible intervals, impulse responses with posterior bands, the posterior predictive, the stability share, the chain diagnostics – is the family’s shared one from _VectorPosteriorDrawsResult. What this result adds is the adaptive prior’s averaged latent diagnostic – inclusion probabilities under a selection prior, local shrinkage scales under a global-local one – and Chib’s marginal likelihood where the two-block sampler makes it exact.

Note

marginal_likelihood is available under a static moment prior and refused under an adaptive prior (whose scale block would need reduced runs) or a dummy-observation prior (whose artificial rows the sampler treats as data). shrinkage is the posterior mean of the latent diagnostic, Rao-Blackwellized over kept sweeps: a conditional inclusion probability, not a binary indicator, under a selection prior; a conditional prior standard deviation on the standardized scale under a global-local prior. The draws are a Markov chain – burn-in and thinning are real choices and convergence says whether they were enough. The point summaries (coefficients, sigma_u, resid) are at the posterior mean and inherit its caveats.

Variables:

• prior_label – Short description of the prior estimated under.

• shrinkage – (w, k) posterior mean per-coefficient diagnostic from an adaptive prior, in design-row order; empty under a static prior. Read it through inclusion_probabilities() or shrinkage_scales().

• shrinkage_label – What shrinkage is; empty under a static prior.

• n_dummy – Artificial rows the prior contributed.

• n_draws – Total sampler iterations.

• n_burn – Burn-in discarded.

• thin – Post-burn thinning.

See also

• GibbsBVAR – the model that produces this record.

• BVARResult – the conjugate posterior, exact and with a closed-form marginal likelihood.

• SpikeAndSlabPrior – the selection prior whose inclusion map this result reports.

References

Koop, G., & Korobilis, D. (2010). Bayesian multivariate time series methods for empirical macroeconomics. Foundations and Trends in Econometrics, 3(4), 267-358.

George, E. I., Sun, D., & Ni, S. (2008). Bayesian stochastic search for VAR model restrictions. Journal of Econometrics, 142(1), 553-580.

Chib, S. (1995). Marginal likelihood from the Gibbs output. Journal of the American Statistical Association, 90(432), 1313-1321.

Example

A diagonal VAR(1) under a selection prior: the own lags are included with probability near one and the cross lags are not:

>>> import numpy as np
>>> from cultivars.bayes.priors import SpikeAndSlabPrior
>>> rng = np.random.default_rng(0)
>>> y = np.zeros((200, 3))
>>> for t in range(1, 200):
...     y[t] = 0.6 * y[t - 1] + rng.standard_normal(3)
>>> res = GibbsBVAR(y, order=1, prior=SpikeAndSlabPrior()).fit(
...     n_draws=300, n_burn=100, seed=0
... )
>>> res.prior_label, res.shrinkage_label, res.n_kept, res.n_dummy
('ssvs(spike=0.1, slab=10, p=0.5)', 'posterior inclusion probability', 200, 0)
>>> res.shrinkage.shape, res.beta_draws.shape, res.sigma_draws.shape
((4, 3), (200, 4, 3), (200, 3, 3))
>>> included = res.inclusion_probabilities()[0]
>>> off_diagonal = included[~np.eye(3, dtype=bool)]
>>> bool(np.all(np.diag(included) > 0.9)), bool(off_diagonal.max() < 0.5)
(True, True)
>>> low, mid, high = res.credible_interval("y1", "y1.L1")
>>> bool(0.3 < low < mid < high < 0.8)
True

Attributes

endog	The observed panel, shape (nobs_total, k).
names	Variable labels, in column order.
order	The autoregressive order p.
trend	"n", "c" or "ct".
prior_label	Short description of the prior estimated under.
coefficients	(p, k, k) lag stack at the posterior mean.
deterministic	(n_det, k) deterministic block at the posterior mean.
beta_mean	(w, k) full posterior mean coefficient matrix.
sigma_u	(k, k) posterior mean innovation covariance.
beta_draws	(S, w, k) coefficient draws.
sigma_draws	(S, k, k) covariance draws.
shrinkage	(w, k) averaged latent diagnostic of an adaptive prior; empty otherwise.
shrinkage_label	What shrinkage measures; empty under a static prior.
resid	(nobs, k) residuals at the posterior mean.
fittedvalues	(nobs, k) one-step means at the posterior mean.
nobs	Effective sample size after the p presample rows.
n_dummy	Artificial rows a dummy-observation prior contributed.
n_draws	Total sampler iterations, burn-in included.
n_burn	Iterations discarded from the start.
thin	Every thin-th post-burn iteration is kept.
k_endog	Number of endogenous variables.
n_kept	Posterior draws retained.
observed	The effective sample the replications are shaped like, (nobs, k).
stable_share	Posterior probability that the system is stable.

Methods

convergence(*chains[, include, exclude, ...])	Assess the sampler's convergence over the retained draws.
credible_interval(equation, regressor)	One coefficient's posterior summary: 16th percentile, mean, 84th.
forecast([steps, seed])	The posterior predictive: parameter and shock uncertainty.
forecast_paths([steps, seed])	The posterior predictive's raw simulated paths, one per kept draw.
inclusion_probabilities()	Posterior inclusion probability of each lag coefficient.
irf([horizon, orthogonalized, cumulative, ...])	Posterior mean impulse responses.
irf_bands([horizon, orthogonalized, ...])	Posterior bands of the impulse responses.
marginal_likelihood()	Chib's (1995) log marginal likelihood of the sample.
posterior_replications([n_replications, seed])	Replicated effective samples, one per posterior draw used.
shrinkage_scales()	Posterior mean local-global scale of each standardized lag coefficient.
simulate([n, seed, burn, draw])	A fresh sample path from the fitted system at the posterior mean or at one draw.
summary()	The estimation summary, renderable as text, HTML, or a dataframe.