srvar.spec

class srvar.spec.BLassoSpec(mode='global', a0_global=1.0, b0_global=1.0, a0_c=1.0, b0_c=1.0, a0_L=1.0, b0_L=1.0, tau_init=10000.0, lambda_init=2.0)[source]

Bases: object

a0_L: float
a0_c: float
a0_global: float
b0_L: float
b0_c: float
b0_global: float
lambda_init: float
mode: Literal['global', 'adaptive']
tau_init: float
class srvar.spec.DLSpec(abeta=0.5, dl_scaler=0.1)[source]

Bases: object

Hyperparameters for the Dirichlet–Laplace (DL) shrinkage prior.

This is a global–local shrinkage prior implemented to match the MATLAB reference code in functions/parfor_vintages.m (model mnemonic “DirLap”).

Parameters:

  • abeta (float) – Dirichlet concentration parameter (named abeta in the MATLAB code).

  • dl_scaler (float) – Small positive initialization scale used for the latent DL variables (named DL_scaler in the MATLAB code).

abeta: float
dl_scaler: float
class srvar.spec.MinnesotaCanonicalSpec(sigma2, inv_v0_vec, mode='canonical', tempered_alpha=None)[source]

Bases: object

Equation-wise canonical Minnesota prior metadata.

Parameters:

  • sigma2 (ndarray) – Scale variances used in the Minnesota construction (length N).

  • inv_v0_vec (ndarray) – Equation-wise prior precision vector over vec(beta) in Fortran / column-major order. The block of K coefficients for equation j occupies inv_v0_vec[j*K:(j+1)*K].

  • mode (Literal['canonical', 'tempered']) – Equation-wise Minnesota variant label. "canonical" is the exact canonical construction; "tempered" is the experimental geometric bridge between the legacy and canonical variance maps.

  • tempered_alpha (float | None) – Blend weight for mode="tempered". 0.0 reproduces the legacy coefficient variances and 1.0 reproduces the canonical coefficient variances.

inv_v0_vec: ndarray
mode: Literal['canonical', 'tempered']
sigma2: ndarray
tempered_alpha: float | None
class srvar.spec.ModelSpec(p, include_intercept=True, steady_state=None, elb=None, volatility=None, shocks=None)[source]

Bases: object

Model configuration for VAR/SRVAR estimation.

Parameters:

  • p (int) – VAR lag order.

  • include_intercept (bool) – Whether to include an intercept term in the VAR design matrix.

  • steady_state (SteadyStateSpec | None) – Optional steady-state configuration.

  • elb (ElbSpec | None) – Optional effective-lower-bound (ELB) configuration. When enabled, specified variables are treated as censored at the bound and latent shadow values are sampled during estimation.

  • volatility (VolatilitySpec | None) – Optional stochastic volatility configuration. When enabled, the model uses a stochastic volatility specification for time-varying variances (random-walk or AR(1) dynamics). Residual covariance can be diagonal (independent shocks) or a triangular factorization with time-invariant correlations.

Notes

ModelSpec is intentionally small and immutable. The heavy lifting is done in srvar.api.fit().

elb: ElbSpec | None
include_intercept: bool
p: int
shocks: ShockSpec | None
steady_state: SteadyStateSpec | None
volatility: VolatilitySpec | None
class srvar.spec.MuSSVSSpec(spike_var=0.0001, slab_var=100.0, inclusion_prob=0.5)[source]

Bases: object

inclusion_prob: float
slab_var: float
spike_var: float
class srvar.spec.NIWPrior(m0, v0, s0, nu0)[source]

Bases: object

Normal-Inverse-Wishart (NIW) prior parameters.

This prior is used for conjugate Bayesian VAR estimation.

Notes

Shapes follow the conventions used throughout the toolkit:

  • m0 has shape (K, N) where K = (1 if include_intercept else 0) + N * p

  • v0 has shape (K, K)

  • s0 has shape (N, N)

m0: ndarray
nu0: float
s0: ndarray
v0: ndarray
class srvar.spec.PriorSpec(family, niw, ssvs=None, blasso=None, dl=None, minnesota_canonical=None)[source]

Bases: object

Prior specification wrapper.

This object selects the prior family via family and carries the required parameter blocks.

Parameters:

  • family (str) – Prior family identifier. Supported values include "niw", "ssvs", "blasso", and "dl".

  • niw (NIWPrior) – NIW parameter block. This is required for both families because SSVS uses a NIW-like structure with a modified coefficient covariance V0.

  • ssvs (SSVSSpec | None) – Optional SSVS hyperparameters (required when family='ssvs').

  • blasso (BLassoSpec | None) – Optional Bayesian Lasso hyperparameters (required when family='blasso').

  • dl (DLSpec | None) – Optional Dirichlet–Laplace hyperparameters (required when family='dl').

  • minnesota_canonical (MinnesotaCanonicalSpec | None) – Optional equation-wise Minnesota metadata. When present, the prior is fit via the explicit equation-wise Minnesota path rather than the legacy NIW matrix-normal path. mode="canonical" is the exact canonical construction; mode="tempered" is the experimental bridge between the legacy and canonical variance maps.

blasso: BLassoSpec | None
dl: DLSpec | None
family: str
static from_blasso(*, k, n, mode='global', include_intercept=True, m0=None, s0=None, nu0=None, a0_global=1.0, b0_global=1.0, a0_c=1.0, b0_c=1.0, a0_L=1.0, b0_L=1.0, tau_init=10000.0, lambda_init=2.0)[source]
Return type:

PriorSpec

static from_dl(*, k, n, include_intercept=True, m0=None, s0=None, nu0=None, abeta=0.5, dl_scaler=0.1)[source]
Return type:

PriorSpec

static from_ssvs(*, k, n, include_intercept=True, m0=None, s0=None, nu0=None, spike_var=0.0001, slab_var=100.0, inclusion_prob=0.5, intercept_slab_var=None, fix_intercept=True)[source]

Construct a prior specification for SSVS estimation.

Parameters:

  • k (int) – Number of regressors K.

  • n (int) – Number of endogenous variables N.

  • include_intercept (bool) – Whether the corresponding model includes an intercept.

  • m0 (ndarray | None) – Optional NIW blocks. If omitted, sensible defaults are used.

  • s0 (ndarray | None) – Optional NIW blocks. If omitted, sensible defaults are used.

  • nu0 (float | None) – Optional NIW blocks. If omitted, sensible defaults are used.

  • spike_var (float) – SSVS hyperparameters.

  • slab_var (float) – SSVS hyperparameters.

  • inclusion_prob (float) – SSVS hyperparameters.

  • intercept_slab_var (float | None) – Optional slab variance override for the intercept term.

  • fix_intercept (bool) – Whether to force inclusion of the intercept row.

Return type:

PriorSpec

minnesota_canonical: MinnesotaCanonicalSpec | None
niw: NIWPrior
static niw_default(*, k, n)[source]

Construct a simple default NIW prior.

This uses a zero prior mean for coefficients and relatively weak regularization.

Parameters:

  • k (int) – Number of regressors K.

  • n (int) – Number of endogenous variables N.

Return type:

PriorSpec

static niw_minnesota(*, p, y, n=None, include_intercept=True, lambda1=0.1, lambda2=0.5, lambda3=1.0, lambda4=100.0, own_lag_means=None, own_lag_mean=0.0, min_sigma2=1e-12)[source]

Backward-compatible alias for the legacy Minnesota-style NIW prior.

This method preserves the historical srvar-toolkit behaviour. For an explicit reproducibility path, prefer PriorSpec.niw_minnesota_legacy().

Return type:

PriorSpec

Notes

The current implementation is a legacy Minnesota-style NIW construction, not a full canonical Minnesota prior. In particular, it uses one scalar cross-variable shrinkage weight derived from lambda2 rather than equation-specific own-vs-cross shrinkage.

static niw_minnesota_canonical(*, p, y, n=None, include_intercept=True, lambda1=0.1, lambda2=0.5, lambda3=1.0, lambda4=100.0, own_lag_means=None, own_lag_mean=0.0, min_sigma2=1e-12)[source]

Construct an explicit canonical Minnesota prior on the equation-wise path.

This constructor preserves the standard own-vs-cross variance distinction by storing per-equation prior precisions rather than collapsing everything into a shared NIW row covariance. The resulting fit path is currently supported for homoskedastic models and diagonal stochastic-volatility models.

Return type:

PriorSpec

Notes

The exact equation-wise coefficient prior is carried in prior.minnesota_canonical.inv_v0_vec. The companion prior.niw.v0 block is a row-averaged diagonal summary kept for shape compatibility with the rest of the toolkit.

static niw_minnesota_legacy(*, p, y, n=None, include_intercept=True, lambda1=0.1, lambda2=0.5, lambda3=1.0, lambda4=100.0, own_lag_means=None, own_lag_mean=0.0, min_sigma2=1e-12)[source]

Construct the legacy Minnesota-style NIW prior used by this toolkit.

This preserves the historical srvar-toolkit prior semantics. It is a Minnesota-style NIW construction with lag decay and a scalar cross-variable shrinkage weight, but it is not a full canonical Minnesota prior.

Parameters:

  • p (int) – VAR lag order.

  • y (ndarray) – Data array used to estimate scaling variances (T, N).

  • include_intercept (bool) – Whether the resulting prior is compatible with a VAR that includes an intercept.

  • lambda1 (float) – Legacy Minnesota-style hyperparameters. lambda2 is collapsed into a scalar cross-variable weight shared across equations.

  • lambda2 (float) – Legacy Minnesota-style hyperparameters. lambda2 is collapsed into a scalar cross-variable weight shared across equations.

  • lambda3 (float) – Legacy Minnesota-style hyperparameters. lambda2 is collapsed into a scalar cross-variable weight shared across equations.

  • lambda4 (float) – Legacy Minnesota-style hyperparameters. lambda2 is collapsed into a scalar cross-variable weight shared across equations.

  • own_lag_mean (own_lag_means /) – Optional prior mean(s) for own first lag.

  • min_sigma2 (float) – Floor for estimated variances used in scaling.

Returns:

A PriorSpec instance with family='niw'.

Return type:

PriorSpec

static niw_minnesota_tempered(*, p, y, n=None, include_intercept=True, lambda1=0.1, lambda2=0.5, lambda3=1.0, lambda4=100.0, alpha=0.25, own_lag_means=None, own_lag_mean=0.0, min_sigma2=1e-12)[source]

Construct an experimental tempered bridge between legacy and canonical Minnesota.

This keeps the equation-wise sampling path used by PriorSpec.niw_minnesota_canonical(), but geometrically blends the legacy and canonical coefficient variances:

  • alpha=0.0 reproduces the legacy variance map

  • alpha=1.0 reproduces the canonical variance map

Notes

This is an explicit experimental mitigation path. It does not redefine the semantics of PriorSpec.niw_minnesota_canonical().

Return type:

PriorSpec

ssvs: SSVSSpec | None
class srvar.spec.SSVSSpec(spike_var=0.0001, slab_var=100.0, inclusion_prob=0.5, intercept_slab_var=None, fix_intercept=True)[source]

Bases: object

Hyperparameters for stochastic search variable selection (SSVS).

The SSVS implementation uses a spike-and-slab Gaussian prior over coefficient rows (predictor-specific inclusion indicators).

Parameters:

  • spike_var (float) – Prior variance for excluded predictors (spike component).

  • slab_var (float) – Prior variance for included predictors (slab component).

  • inclusion_prob (float) – Prior inclusion probability for each predictor.

  • intercept_slab_var (float | None) – Optional slab variance override for the intercept term.

  • fix_intercept (bool) – If True and an intercept is included in the model, the intercept is always included.

fix_intercept: bool
inclusion_prob: float
intercept_slab_var: float | None
slab_var: float
spike_var: float
class srvar.spec.SamplerConfig(draws=2000, burn_in=500, thin=1)[source]

Bases: object

MCMC configuration for Gibbs samplers.

Parameters:

  • draws (int) – Total number of iterations to run.

  • burn_in (int) – Number of initial iterations to discard.

  • thin (int) – Keep every thin-th draw after burn-in.

Notes

For conjugate NIW estimation (no ELB/SV), draws are sampled directly and then burn-in/thinning is applied post hoc. For iterative samplers (ELB, SSVS, SV), burn-in/thinning is applied online.

burn_in: int
draws: int
thin: int
class srvar.spec.ShockSpec(family='gaussian', df=7.0, outlier_prob=0.05, outlier_variance=10.0)[source]

Bases: object

Innovation (shock) distribution configuration.

Parameters:

  • family (Literal['gaussian', 'student_t', 'mixture_outlier']) –

    Shock family identifier.

    • "gaussian": standard Gaussian innovations.

    • "student_t": multivariate Student-t innovations via a scale-mixture of normals.

    • "mixture_outlier": two-component Gaussian mixture with an outlier variance inflation.

  • df (float) – Degrees of freedom for family="student_t". Must be finite and > 2.

  • outlier_prob (float) – Outlier probability for family="mixture_outlier". Must be in (0, 1).

  • outlier_variance (float) – Variance inflation factor for outliers in family="mixture_outlier". Must be finite and > 1.0. When an outlier occurs, innovations have covariance outlier_variance * Sigma.

df: float
family: Literal['gaussian', 'student_t', 'mixture_outlier']
outlier_prob: float
outlier_variance: float
class srvar.spec.SteadyStateSpec(mu0, v0_mu, ssvs=None)[source]

Bases: object

mu0: ndarray
ssvs: MuSSVSSpec | None
v0_mu: float | ndarray