SVResult

class cultivars.univariate.stochastic_volatility.SVResult(*, endog, mean_spec, mean, mu, phi, sigma2, nu, rho, llf, method, nobs, n_params, log_variance, log_variance_std)

A point-estimated stochastic-volatility model.

The model

\[y_t = c + \exp(h_t / 2)\,\varepsilon_t, \qquad h_{t+1} = \mu + \phi\,(h_t - \mu) + \sigma\,\eta_t,\]

with \(\varepsilon_t\) standard normal or Student-t with \(\nu\) degrees of freedom, \(\eta_t\) standard normal, and \(\operatorname{corr}(\varepsilon_t, \eta_t) = \rho\) when leverage is specified. The log variance is latent, so what the record carries beside the parameters is its smoothed path and standard deviation, and everything volatility-related is read off those: volatility is \(\exp(\hat h_t / 2)\), the bands exponentiate normal bands on \(\hat h_t\), and the variance forecast propagates the last smoothed moment through the AR(1) with the log-normal correction \(E[\exp(h)] = \exp(E[h] + \tfrac12 \operatorname{Var}[h])\). Two estimators produce it: the Harvey-Ruiz-Shephard quasi-maximum likelihood on the linearized model \(\log (y_t - c)^2 = h_t + \log \varepsilon_t^2\), where the Kalman filter treats \(\log \varepsilon_t^2\) as Gaussian with mean \(-1.2704\) and variance \(\pi^2 / 2\), and simulated maximum likelihood on a particle estimate of the exact likelihood.

Variables:

• endog – The observed series.

• mean_spec – "constant" or "zero".

• mean – The observation mean c.

• mu – Unconditional mean of the log variance.

• phi – Persistence of the log variance.

• sigma2 – Innovation variance of the log variance.

• nu – Degrees of freedom of the observation noise, or None under Gaussian tails.

• rho – Correlation between the observation and log-variance innovations; 0.0 without leverage.

• llf – The criterion at the optimum. Under method="qml" this is the exact Gaussian likelihood of the linearized model, a quasi-likelihood for the true one; under method="particle" it is a particle estimate of the exact likelihood, carrying Monte Carlo error. Information criteria are comparable only within one method.

• method – "qml" or "particle".

• nobs – Observations.

• n_params – Free parameters.

• log_variance – Smoothed log-variance path, (n,).

• log_variance_std – Smoothed log-variance standard deviations.

Note

QML reads the data only through \(\log (y_t - c)^2\), which discards the sign of \(y_t - c\); a leverage correlation is therefore not identified by it and comes back as rho = 0.0 with the parameter count unchanged, and \(\nu\) is weakly identified because the degrees of freedom enter only through the two moments of \(\log \varepsilon_t^2\). The samplers on SV are the estimators for either. The linearized sample is \(\log\bigl((y_t - c)^2 + 10^{-6}\bigr)\), the offset guarding an exact zero. Standard errors are not yet reported by this estimator.

See also

• SV – the specification that produces this, and whose sample returns the posterior record instead.

• GARCHResult – observation-driven volatility, where the variance is a function of past data rather than a latent state.

• NonlinearSSM – what state_space returns.

References

Taylor, S. J. (1986). Modelling Financial Time Series. Wiley.

Harvey, A. C., Ruiz, E., & Shephard, N. (1994). Multivariate stochastic variance models. Review of Economic Studies, 61(2), 247-264.

Kim, S., Shephard, N., & Chib, S. (1998). Stochastic volatility: Likelihood inference and comparison with ARCH models. Review of Economic Studies, 65(3), 361-393.

Example

A persistent log variance recovered by QML, with the smoothed path tracking the true one:

>>> import numpy as np
>>> from cultivars.engine._internals._simulators import _simulate_stochastic_volatility
>>> rng = np.random.default_rng(0)
>>> y, h = _simulate_stochastic_volatility(
...     500, mu=-1.0, phi=0.95, sigma2=0.05, mean=0.0, rng=rng
... )
>>> res = SV(y, mean="zero").fit()
>>> res.method, res.nobs, res.n_params, res.nu, res.rho
('qml', 500, 3.0, None, 0.0)
>>> bool(abs(res.phi - 0.95) < 0.05), bool(np.corrcoef(res.log_variance, h)[0, 1] > 0.5)
(True, True)
>>> bool(abs(res.unconditional_variance - y.var()) < 0.05)
True

Attributes

endog	(n,) observed series.
mean_spec	"constant" when c was estimated, "zero" when fixed.
mean	The observation mean c; 0.0 under mean_spec="zero".
mu	Unconditional mean of the log variance.
phi	AR(1) coefficient of the log variance.
sigma2	Innovation variance of the log variance.
nu	Student-t degrees of freedom, or None under Gaussian tails.
rho	Leverage correlation; 0.0 without leverage or under QML.
llf	Quasi-likelihood (QML) or particle likelihood estimate at the optimum.
method	"qml" or "particle".
nobs	Observations the criterion was evaluated on.
n_params	three for the log variance plus the mean if estimated.
log_variance	(n,) smoothed log-variance path.
log_variance_std	(n,) smoothed log-variance standard deviations.
half_life	Periods for a log-variance shock to halve, log 0.5 / log phi.
information_criteria	AIC, BIC, and HQIC derived from the likelihood and parameter count.
quasi_state_space	The Harvey-Ruiz-Shephard linearization on the linear substrate.
state_space	The fitted model on the nonlinear substrate.
unconditional_variance	E[exp(h_t)] under the stationary log-normal law.
volatility	Smoothed volatility exp(h_t / 2), (n,).
fittedvalues
resid

Methods

compare(*others[, criterion])	Rank this result against others by an information criterion.
forecast_variance(steps)	Expected variance E[exp(h_{T+k}) | y] for k = 1..steps.
likelihood_ratio_test(unrestricted)	Test this result as the restricted model against a nesting one.
simulate([n, seed, burn])	A fresh sample path at the fitted parameters.
summary()	The estimation summary, renderable as text, HTML, or a dataframe.
to_dict()	The aligned per-observation outputs as plain numpy arrays.
to_pandas(*[, index])	The aligned per-observation outputs as a pandas.DataFrame.
to_polars()	The aligned per-observation outputs as a polars.DataFrame.
volatility_bands(*[, alpha])	Pointwise 1 - alpha bands on the volatility from the smoothed log variance.