srvar.api

srvar.api.fit(dataset, model, prior, sampler, *, rng=None)[source]

Fit an SRVAR/BVAR model and return posterior draws.

This is the primary user-facing entry point for estimating models in this package.

Supported configurations

  • Conjugate BVAR with Normal-Inverse-Wishart prior (prior.family='niw')

  • Spike-and-slab variable selection (prior.family='ssvs')

  • Effective lower bound (ELB) data-augmentation Gibbs sampler (model.elb.enabled)

  • Stochastic volatility random-walk (SVRW) (model.volatility.enabled; requires NIW)

type dataset:

Dataset

param dataset:

Observed data (T, N). When ELB is enabled, some variables are interpreted as censored at the ELB.

type model:

ModelSpec

param model:

Model configuration, including lag order p and optional ELB/SV specs.

type prior:

PriorSpec

param prior:

Prior configuration. The prior family is determined by prior.family.

type sampler:

SamplerConfig

param sampler:

MCMC configuration (draws, burn-in, thinning).

type rng:

Generator | None

param rng:

Optional NumPy RNG.

returns:

Fit result with posterior parameters and/or stored posterior draws depending on the model configuration.

rtype:

FitResult

Notes

For conjugate NIW without ELB/SV, FitResult.posterior is populated and beta_draws/sigma_draws are produced by direct sampling.

For Gibbs samplers (ELB, SSVS, SV), burn-in and thinning are applied online and the returned *_draws arrays contain only kept draws.

When ELB is enabled, the latent series is initialized by setting observations at or below the bound to a small amount below the bound (bound - elb.init_offset). This is a numerical initialization choice intended to avoid starting exactly at the truncation boundary.

srvar.api.forecast(fit, horizons, *, draws=1000, quantile_levels=None, stationarity='allow', stationarity_tol=1e-10, stationarity_max_draws=None, rng=None)[source]

Generate predictive simulations from a fitted model.

Forecasts are produced by Monte Carlo simulation using posterior parameter draws.

Parameters:

  • fit (FitResult) – Result from srvar.api.fit().

  • horizons (list[int]) – List of forecast horizons (in steps) requested by the caller. Internally, simulations are generated out to H = max(horizons).

  • draws (int) – Number of predictive simulation paths.

  • quantile_levels (list[float] | None) – Quantiles to compute from the simulated draws. Defaults to [0.1, 0.5, 0.9].

  • rng (Generator | None) – Optional NumPy RNG.

  • stationarity (str) –

    Stationarity policy for VAR coefficient draws used in forecasting:

    • "allow" (default): do not enforce stability.

    • "reject": require stable VAR dynamics (companion eigenvalues strictly inside the unit circle), rejecting non-stationary coefficient draws.

  • stationarity_tol (float) – Numerical tolerance for the stability check. A draw is considered stationary if max(abs(eigvals)) < 1 - stationarity_tol.

  • stationarity_max_draws (int | None) – When fit does not contain stored posterior draws (i.e., forecasting samples from a conjugate NIW posterior), this caps the total number of candidate posterior draws attempted to collect draws stationary draws under stationarity="reject". If not provided, defaults to 50 * draws.

Returns:

Forecast result containing:

  • draws: simulated observations with shape (D, H, N)

  • mean: mean across draws with shape (H, N)

  • quantiles: dict mapping each requested quantile to an array (H, N)

Return type:

ForecastResult

Notes

If ELB is enabled in the fitted model, returned draws are the observed (floored) draws, and latent_draws contains the unconstrained latent draws.

If you call forecast(fit, horizons=[1, 3], ...) then result.mean[0] corresponds to horizon 1 and result.mean[2] corresponds to horizon 3.