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)[source]

Bases: _SummaryMixin, _SeriesMixin, _ComparisonMixin

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

Private attributes#

_params

The parameter record, rebuilt for the emitters.

Private methods#

_comparison_label()

Specification label used when this result appears in a ranking.

_from_fit(fit, model)

Assemble the public result from a raw fit and its specification.

_series()

Aligned per-observation output.

_summary_table()

Structured summary rendered by every display path.