HierarchicalBVARResult

class cultivars.multivariate.large_dim.hierarchical.HierarchicalBVARResult(*, endog, names, order, trend, prior_label, coefficients, deterministic, beta_mean, sigma_u, beta_draws, sigma_draws, log_marginal_likelihood, posterior_df, resid, fittedvalues, nobs, n_dummy, hyper_names, hyper_mode, hyper_draws, acceptance_rate, method)

A fitted hierarchical BVAR: the tightness carries a posterior too.

Everything the conjugate result reports, with one change of meaning and one addition. The change: under the full method the retained (B, Sigma) draws marginalize over the hyperparameters \(\theta = (\lambda, \mu, \delta)\),

\[p(B, \Sigma \mid y) = \int p(B, \Sigma \mid y, \theta)\, p(\theta \mid y)\, d\theta, \qquad p(\theta \mid y) \propto p(y \mid \theta)\, p(\theta),\]

with \(p(y \mid \theta)\) the conjugate model’s closed-form marginal likelihood, so every band downstream – coefficients, impulse responses, the predictive – includes hyperparameter uncertainty; log_marginal_likelihood is the value at the hyperparameter mode, conditional on it. The addition is the hyperparameter layer itself: the posterior mode, the kept draws, and the chain’s acceptance rate.

Note

Under method="empirical" the (B, Sigma) draws condition on hyper_mode, hyper_draws is empty and acceptance_rate is nan; hyperparameter_interval refuses. A hyperparameter whose dummies carry no information – mu when the presample mean is zero, since the sum-of-coefficients rows are that mean divided by mu – has a posterior equal to its hyperprior and a mode at the search’s start; the marginal likelihood is flat in it, which is correct and worth noticing. The summary’s acceptance-rate guidance is for the kept span; a short run after a long adaptive burn-in can sit above it without harm.

Variables:

• hyper_names – One label per hyperparameter, in draw-column order – "lambda", then "mu" and "delta" when active, parameterized as in Giannone-Lenza-Primiceri.

• hyper_mode – Posterior-mode hyperparameter vector.

• hyper_draws – (S, d) kept hyperparameter draws; empty under empirical Bayes.

• acceptance_rate – Metropolis acceptance over the kept span; nan under empirical Bayes.

• method – "full" or "empirical".

See also

• HierarchicalBVAR – the model that produces this record.

• BVARResult – the conjugate record this one extends, with the tightness fixed.

References

Giannone, D., Lenza, M., & Primiceri, G. E. (2015). Prior selection for vector autoregressions. Review of Economics and Statistics, 97(2), 436-451.

Example

The full hierarchy on a bivariate VAR(1): the tightness has a posterior, the mode agrees with the empirical-Bayes fit, and the coefficient bands marginalize over it:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = np.zeros((150, 2))
>>> for t in range(1, 150):
...     y[t] = 0.6 * y[t - 1] + rng.standard_normal(2)
>>> y += 5.0
>>> model = HierarchicalBVAR(y, order=1)
>>> full = model.fit(method="full", n_draws=300, n_burn=300, seed=0)
>>> full.method, full.hyper_names, full.hyper_draws.shape, full.n_kept
('full', ('lambda', 'mu', 'delta'), (300, 3), 300)
>>> low, mean, high = full.hyperparameter_interval("lambda")
>>> bool(0.0 < low < mean < high < 1.0), bool(0.1 < full.acceptance_rate < 0.9)
(True, True)
>>> empirical = model.fit(method="empirical", n_draws=100, seed=0)
>>> bool(np.allclose(empirical.hyper_mode, full.hyper_mode))
True
>>> bool(empirical.log_marginal_likelihood == full.log_marginal_likelihood)
True

Attributes

hyper_names	lambda, then mu, delta.
hyper_mode	(d,) posterior-mode hyperparameter vector.
hyper_draws	(S, d) kept hyperparameter draws; empty under empirical Bayes.
acceptance_rate	Metropolis acceptance over the kept span; nan under empirical Bayes.
method	"full" (marginalized) or "empirical" (conditioned on the mode).
beta_draws	(S, w, k) independent posterior draws of the coefficient matrix.
beta_mean	(w, k) posterior mean coefficient matrix \(\bar B\).
coefficients	(p, k, k) lag stack at the posterior mean.
deterministic	(n_det, k) deterministic block at the posterior mean.
endog	The observed panel, (T, k), including the presample.
fittedvalues	(nobs, k) one-step-ahead conditional means at the posterior mean.
k_endog	Number of endogenous variables, k.
log_marginal_likelihood	Log marginal likelihood of the sample given the prior, in closed form.
n_dummy	Artificial rows the prior contributed to the update.
n_kept	Posterior draws retained, S.
names	Variable labels, one per column of endog, in column order.
nobs	the rows the posterior was updated on, dummy rows excluded.
observed	The effective sample the replications are shaped like, (nobs, k).
order	the number of lag blocks in coefficients.
posterior_df	Inverse-Wishart posterior degrees of freedom \(\bar\nu\).
prior_label	Short description of the prior the posterior was updated under.
resid	(nobs, k) residuals at the posterior mean.
sigma_draws	(S, k, k) independent posterior draws of the innovation covariance.
sigma_u	(k, k) exact posterior mean of the innovation covariance.
stable_share	Posterior probability that the system is stable.
trend	"n" (none), "c" (constant), or "ct".

Methods

convergence(*chains[, include, exclude, ...])	Assess the sampler's convergence over the retained draws.
credible_interval(equation, regressor)	Posterior summary of one coefficient: 16th percentile, mean, 84th percentile.
forecast([steps, seed])	The posterior predictive: parameter and shock uncertainty.
forecast_paths([steps, seed])	The posterior predictive's raw simulated paths, one per retained draw.
hyperparameter_interval(name)	One hyperparameter's posterior summary: 16th percentile, mean, 84th.
irf([horizon, orthogonalized, cumulative])	Posterior mean impulse responses.
irf_bands([horizon, orthogonalized, cumulative])	Posterior bands of the impulse responses.
marginal_likelihood()	The closed-form log marginal likelihood as a comparable record.
posterior_replications([n_replications, seed])	Replicated effective samples, one per posterior draw used.
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.