prior_predictive_check#

cultivars.bayes.checks.prior_predictive_check(model, *, statistics=None, n_replications=200, seed=None, **hyperparameters)[source]#

Replicate the sample from the prior and locate the data in what it generates.

For each of n_replications draws \(\theta^{(r)} \sim p(\theta)\) from the model’s prior, a data set \(y^{\text{rep},(r)} \sim p(y \mid \theta^{(r)})\) of the shape of the effective sample is simulated, and the observed panel is located in the replicated distribution of each discrepancy statistic by replication_check(). No fitting happens: the check is what Gabry et al. (2019) call the prior predictive step of a Bayesian workflow, and its reading is the replicated quantile band of each statistic on the data’s own scale – whether the prior deems the data’s scale, persistence, and tail weight plausible, or whether it puts most of its mass on data that look nothing like these. The tail probability is reported but is not a test; the data are one draw the prior may or may not cover.

A Minnesota-type prior centred on the unit root generates explosive systems at some rate by construction. The check measures that rate – the share of replications reaching beyond a thousand times the largest observation – and records it as a note when it is non-zero, so the reader can decide whether that mass is intended.

Parameters:

  • model (ReplicatingModel) – An unfitted model that can draw from its prior, that is, one satisfying ReplicatingModel by exposing observed and prior_replications(): BVAR, StudentBVAR, GibbsBVAR under a static prior without dummy observations, and SV. The stochastic-volatility BVAR is excluded: its random-walk volatility prior has no stationary distribution to replicate from.

  • statistics (Sequence[str] | None) – Discrepancy statistics, as for replication_check(); None selects mean, sd, acf1, kurtosis, arch1.

  • n_replications (int) – Prior draws, and so replicated data sets. At least 20.

  • seed (int | Generator | None) – Seed or generator for the prior draws and the innovations.

  • **hyperparameters (object) – Prior settings the model’s prior_replications accepts by name, passed through unchanged: df for StudentBVAR; prior_mu, prior_phi, prior_sigma2 for SV, exactly as its sample() takes them. A name the model does not accept is refused before anything is simulated.

Return type:

PredictiveCheckTest

Returns:

The PredictiveCheckTest with kind="prior", the model’s variable names, source naming the model and its prior label when the model carries one, and the explosive-share remark in notes when it applies.

Raises:

  • SpecificationError – If the model cannot draw from its prior, if a statistic name is unknown, or if a keyword in hyperparameters is not one the model’s prior_replications takes; the message lists the names it does take.

  • DimensionError – If fewer than 20 replications are asked for.

Note

Prior replications of an autoregressive model are simulated from the observed presample, so a prior check on a series in levels starts every replication where the data start; the mean statistic then reads the drift the prior admits over the sample length, not a prior on the level itself.

See also

References

Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., & Gelman, A. (2019). Visualization in Bayesian workflow. Journal of the Royal Statistical Society A, 182(2), 389-402.

Gelman, A., Vehtari, A., Simpson, D., Margossian, C. C., Carpenter, B., Yao, Y., Kennedy, L., Gabry, J., Bürkner, P.-C., & Modrák, M. (2020). Bayesian workflow. arXiv:2011.01808.

Example

What the default Minnesota prior says a random-walk panel could look like, on the two features that prior is about:

>>> import numpy as np
>>> from cultivars.multivariate.large_dim.bayesian import BVAR
>>> rng = np.random.default_rng(0)
>>> y = np.cumsum(rng.standard_normal((120, 2)), axis=0)
>>> check = prior_predictive_check(BVAR(y, order=2), statistics=["sd", "acf1"], seed=0)
>>> check.kind, check.replicated.shape
('prior', (200, 2, 2))
>>> check.source
'BVAR under niw(l1=0.2, l3=1, l4=100)'

A hyperparameter the model does not take is refused by name:

>>> prior_predictive_check(BVAR(y, order=2), df=5)
Traceback (most recent call last):
    ...
cultivars.exceptions.SpecificationError: BVAR.prior_replications does not take ['df']; ...