STARResult#

class cultivars.univariate.smooth_transition.STARResult(*, endog, fittedvalues, resid, llf, nobs, n_params, order, delay, threshold, threshold_values, lower_params, upper_params, sigma2, ssr, transition, gamma, transition_scale)[source]#

A fitted smooth-transition autoregression.

The model blends two linear autoregressions by a weight that moves smoothly with a lagged value of the series,

\[y_t = \bigl(1 - G(z_t)\bigr)\,\phi_L' x_t + G(z_t)\,\phi_U' x_t + \varepsilon_t, \qquad x_t = (1, y_{t-1}, \ldots, y_{t-p})', \qquad z_t = y_{t-d},\]

with the logistic transition \(G(z) = \bigl(1 + \exp(-\gamma (z - c) / s)\bigr)^{-1}\) and the exponential transition \(G(z) = 1 - \exp(-\gamma (z - c)^2 / s^2)\), where \(s\) is the sample standard deviation of \(z\). The logistic weight is monotone in \(z\), so the regimes are “low” and “high”; the exponential weight is symmetric about \(c\), so both tails share a regime and the middle is the other. Conditional on \((\gamma, c)\) the model is linear, so the regime blocks are concentrated out by least squares and only the two transition parameters are searched; gamma is reported per standard deviation of the transition variable so it is comparable across series, with the scale retained so the weight path can be reproduced.

Variables:

  • transition – "logistic" or "exponential".

  • gamma – Transition speed, in units of standard deviations of the transition variable.

  • transition_scale – The standard deviation gamma is expressed against, retained so the weight path can be reproduced and so gamma can be read on the original scale.

Note

The inherited fields are endog, fittedvalues, resid, llf, nobs, n_params, order, delay, threshold, threshold_values, lower_params, upper_params, sigma2 and ssr; the inherited properties upper_fraction, lower_stability, upper_stability and is_regimewise_stationary read the regime blocks as linear autoregressions, and likelihood_ratio_test refuses because the threshold and delay are unidentified under linearity. The effective sample drops max(order, delay) leading observations. n_params counts the two regime blocks, the threshold, gamma and the variance. Standard errors are not yet reported by this estimator.

See also

References

Terasvirta, T. (1994). Specification, estimation, and evaluation of smooth transition autoregressive models. Journal of the American Statistical Association, 89(425), 208-218.

van Dijk, D., Terasvirta, T., & Franses, P. H. (2002). Smooth transition autoregressive models: A survey of recent developments. Econometric Reviews, 21(1), 1-47.

Example

A logistic transition between a rising and a falling regime, recovered with its threshold:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = np.zeros(600)
>>> for t in range(1, 600):
...     w = 1.0 / (1.0 + np.exp(-10.0 * y[t - 1]))
...     y[t] = (1 - w) * (0.5 + 0.6 * y[t - 1]) + w * (-0.5 - 0.6 * y[t - 1])
...     y[t] += 0.3 * rng.standard_normal()
>>> res = LSTAR(y, order=1).fit()
>>> res.transition, res.nobs
('logistic', 599)
>>> list(res.params)
['lower.const', 'lower.ar.L1', 'upper.const', 'upper.ar.L1', 'threshold', 'gamma', 'sigma2']
>>> bool(abs(res.threshold) < 0.1), bool(abs(res.gamma / res.transition_scale - 10.0) < 4.0)
(True, True)
>>> bool(res.lower_params[1] > 0.4), bool(res.upper_params[1] < -0.4)
(True, True)

Attributes#

transition

"logistic" or "exponential".

gamma

Transition speed per standard deviation of the transition variable.

transition_scale

Sample standard deviation of the transition variable.

delay

endog

fittedvalues

information_criteria

AIC, BIC, and HQIC derived from the likelihood and parameter count.

is_effectively_abrupt

Whether the fitted transition is so fast it is a hard threshold.

is_regimewise_stationary

Whether both regimes are stationary read as linear autoregressions.

llf

lower_params

lower_stability

Companion-eigenvalue verdict for the lower-regime AR block.

n_params

nobs

order

params

Estimated parameters keyed by display name, in table order.

regime_weight

The transition function evaluated over the sample.

resid

sigma2

ssr

threshold

threshold_values

upper_fraction

Share of the effective sample assigned to the upper regime.

upper_params

upper_stability

Companion-eigenvalue verdict for the upper-regime AR block.

Methods#

compare(*others[, criterion])

Rank this result against others by an information criterion.

likelihood_ratio_test(unrestricted)

Refuse the test: the threshold is unidentified under the null.

nonlinear_state_space(measurement_variance)

The fitted smooth-transition mean as a noisily observed state space.

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.