srvar.sv

class srvar.sv.VolatilitySpec(enabled=True, dynamics='rw', covariance='diagonal', q_prior_var=1.0, k_factors=1, loading_prior_var=1.0, store_factor_draws=False, epsilon=0.0001, h0_prior_mean=1e-06, h0_prior_var=10.0, sigma_eta_prior_nu0=1.0, sigma_eta_prior_s0=0.01, phi_prior_mean=0.95, phi_prior_var=0.1, gamma0_prior_mean=0.0, gamma0_prior_var=10.0)

Bases: object

Stochastic volatility configuration.

When enabled in srvar.spec.ModelSpec, estimation uses a diagonal stochastic volatility random-walk (SVRW) model for time-varying variances.

By default, residual covariance is diagonal (independent shocks). Setting covariance='triangular' enables a triangular factorization:

Sigma_t = Q^{-1} diag(exp(h_t)) (Q^{-1})'

where Q is upper-triangular with ones on the diagonal. This yields a full residual covariance matrix with time-varying variances and a time-invariant correlation structure.

Setting covariance='factor' enables factor stochastic volatility (FSV):

eps_t = Lambda f_t + eta_t

f_t ~ N(0, diag(exp(h_f,t)))

eta_t ~ N(0, diag(exp(h_eta,t)))

Sigma_t = Lambda diag(exp(h_f,t)) Lambda' + diag(exp(h_eta,t))

This yields a full, time-varying covariance matrix with scalable low-rank structure.

Parameters:

• enabled (bool) – Whether stochastic volatility is enabled.

• dynamics (Literal['rw', 'ar1']) –

  Volatility state dynamics. "rw" uses a random-walk prior:

  h_t = h_{t-1} + eta_t

  "ar1" uses an AR(1) prior:

  h_t = gamma0 + phi * h_{t-1} + eta_t

  with phi and gamma0 sampled in the Gibbs routine.

• covariance (Literal['diagonal', 'triangular', 'factor']) – Covariance structure. "diagonal" is independent shocks. "triangular" uses an upper-triangular factor Q with ones on the diagonal (a CCCM-style multivariate SV factorization). "factor" enables factor SV (FSV).

• q_prior_var (float) – Prior variance for the off-diagonal elements of Q when covariance='triangular'.

• k_factors (int) – Number of latent factors for covariance='factor'.

• loading_prior_var (float) – Prior variance for free elements of the factor loading matrix Lambda when covariance='factor'.

• store_factor_draws (bool) – If True, store latent factor draws f_t in the fit result. This can be memory intensive (scales with draws × T × k_factors), so the default is False.

• epsilon (float) – Small positive constant used in the transform log(e_t^2 + epsilon) to avoid log(0).

• h0_prior_mean (float) – Prior mean for the initial log-variance state h0.

• h0_prior_var (float) – Prior variance for the initial log-variance state h0.

• sigma_eta_prior_nu0 (float) – Prior hyperparameters for the innovation variance of the log-volatility random walk.

• sigma_eta_prior_s0 (float) – Prior hyperparameters for the innovation variance of the log-volatility random walk.

• phi_prior_mean (float) – Prior mean/variance for the AR(1) coefficient phi when dynamics='ar1'. A normal prior is used with truncation to (-1, 1).

• phi_prior_var (float) – Prior mean/variance for the AR(1) coefficient phi when dynamics='ar1'. A normal prior is used with truncation to (-1, 1).

• gamma0_prior_mean (float) – Prior mean/variance for the AR(1) intercept gamma0 when dynamics='ar1'.

• gamma0_prior_var (float) – Prior mean/variance for the AR(1) intercept gamma0 when dynamics='ar1'.

covariance: Literal['diagonal', 'triangular', 'factor']

dynamics: Literal['rw', 'ar1']

enabled: bool

epsilon: float

gamma0_prior_mean: float

gamma0_prior_var: float

h0_prior_mean: float

h0_prior_var: float

k_factors: int

loading_prior_var: float

phi_prior_mean: float

phi_prior_var: float

q_prior_var: float

sigma_eta_prior_nu0: float

sigma_eta_prior_s0: float

store_factor_draws: bool

srvar.sv.log_e2_star(e, *, epsilon)

Compute the log-squared residual transform used for SV mixture sampling.

Given residuals e_t, this returns log(e_t^2 + epsilon). The small epsilon avoids log(0) and stabilizes sampling when residuals are extremely small.

Return type:

ndarray

srvar.sv.sample_ar1_params(*, h, h0, sigma_eta2, phi_prior_mean, phi_prior_var, gamma0_prior_mean, gamma0_prior_var, rng, phi_bounds=(-0.999, 0.999))

Sample (gamma0, phi) for the AR(1) volatility state equation.

Return type:

tuple[float, float]

srvar.sv.sample_beta_svrw(*, x, y, m0, v0, h, rng, jitter=1e-06)

Return type:

ndarray

srvar.sv.sample_h0(*, h1, sigma_eta2, prior_mean, prior_var, rng)

Return type:

float

srvar.sv.sample_h0_ar1(*, h1, sigma_eta2, gamma0, phi, prior_mean, prior_var, rng)

Return type:

float

srvar.sv.sample_h_ar1(*, y_star, h, sigma_eta2, h0, gamma0, phi, rng)

Sample log-volatilities under an AR(1) state equation.

Return type:

ndarray

State equation:

h_t = gamma0 + phi * h_{t-1} + eta_t, eta_t ~ N(0, sigma_eta2)

Observation equation uses the KSC mixture approximation as in sample_h_svrw().

srvar.sv.sample_h_svrw(*, y_star, h, sigma_eta2, h0, rng)

Sample a full path of log-volatilities under an SV random-walk prior.

This updates h = (h_1, ..., h_T) in the SVRW model

y*_t = log(e_t^2) pprox h_t + m_{s_t} + u_t h_t = h_{t-1} + eta_t, eta_t ~ N(0, sigma_eta2)

using the KSC mixture approximation and a precision-based Gaussian sampler for the resulting banded linear system.

Args:

y_star: Transformed residuals (T,). h: Current log-volatility values (T,). sigma_eta2: Innovation variance for the random walk. h0: Initial state value used in the prior for h_1. rng: NumPy RNG.

Returns:

Updated log-volatility path with shape (T,).

Return type:

ndarray

srvar.sv.sample_mixture_indicators(*, y_star, h, rng)

Sample KSC mixture indicators for the log-chi-square approximation.

This implements the standard Kim-Shephard-Chib (KSC) 7-component Gaussian mixture approximation for the observation equation arising from:

y*_t = log(e_t^2) with e_t ~ N(0, exp(h_t))

Conditional on a discrete indicator s_t taking values in {0, …, 6}, the model is:

y*_t = h_t + m_{s_t} + u_t, u_t ~ N(0, v_{s_t})

where (pi, m, v) are fixed mixture weights/means/variances.

Notes:

The constant 1.2704 used in the mixture mean vector definition corresponds to E[log(chi^2_1)] and is used to match the centered form commonly reported for the KSC approximation.

References:

Kim, S., Shephard, N., & Chib, S. (1998). Stochastic volatility: Likelihood inference and comparison with ARCH models.

Returns:

Integer array of shape (T,) with entries in {0, …, 6}.

Return type:

ndarray

srvar.sv.sample_sigma_eta2(*, h, h0, nu0, s0, rng)

Return type:

float

srvar.sv.sample_sigma_eta2_ar1(*, h, h0, gamma0, phi, nu0, s0, rng)

Return type:

float