STVAR#

class cultivars.multivariate.nonlinear.smooth_transition.STVAR(endog, *, order, transition_variable, transition='logistic', delay=1, trend='c', names=None)[source]

Bases: _SmoothTransitionVectorAutoRegressionModel[STVARResult]

Smooth-transition vector autoregression, in the Auerbach-Gorodnichenko mould.

At every date the system is a convex blend of two regimes, weighted by a logistic or exponential function of an observable – a named column’s own lag, or an external series such as a smoothed growth measure. The weight \(G(z_t)\) lies in \([0, 1]\), so a date can be, say, seventy percent recession, which no hard split can represent. Estimation concentrates the regime coefficients out of the likelihood and searches only the transition’s speed and location, derivative-free and multi-start, from a seed near the best hard split.

Variables:

  • _endog – The observed panel, from the base model.

  • _order – The autoregressive order p, from the base model.

  • _trend – The deterministic specification, from the base model.

  • _names – The variable labels, from the base model.

  • _delays – The single delay, as a one-element tuple, from the observed-regime base.

  • _threshold_name – The transition variable’s label, from the observed-regime base.

  • _transition_series – The aligned transition series, from the observed-regime base.

  • _transition (str) – The transition family, "logistic" or "exponential".

Parameters:

  • endog (ArrayLike) – The observed panel, shape (nobs, k).

  • order (int) – Autoregressive order within each regime.

  • transition_variable (str | ArrayLike) – A variable name from names (self-exciting) or an aligned external series.

  • transition (Transition) – "logistic" for directional regimes, "exponential" for distance-from-threshold regimes.

  • delay (int) – Delay of the transition variable.

  • trend (Literal['n', 'c', 'ct']) – Deterministic terms per regime.

  • names (Sequence[str] | None) – One label per variable. Defaults to y1 ... yk.

Raises:

  • SpecificationError – If the specification is malformed or transition is not one of the two families.

  • DimensionError – If the sample cannot support two regimes.

See also

  • STVARResult – the record fit returns.

  • TVAR – the abrupt two-regime model this one smooths.

  • FunctionalCoefficientVAR – the nonparametric specification check on the transition’s shape.

  • LSTAR – the univariate logistic model.

References

Auerbach, A. J., & Gorodnichenko, Y. (2012). Measuring the output responses to fiscal policy. American Economic Journal: Economic Policy, 4(2), 1-27.

Terasvirta, T., & Yang, Y. (2014). Specification, estimation and evaluation of vector smooth transition autoregressive models with applications. CREATES Research Paper 2014-08.

Granger, C. W. J., & Terasvirta, T. (1993). Modelling Nonlinear Economic Relationships. Oxford University Press.

Example

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = np.zeros((300, 2))
>>> for t in range(1, 300):
...     g = 1.0 / (1.0 + np.exp(-5.0 * y[t - 1, 0]))
...     a = (1.0 - g) * 0.6 + g * -0.3
...     y[t] = a * y[t - 1] + rng.standard_normal(2)
>>> res = STVAR(y, order=1, transition_variable="y1", delay=1).fit()
>>> 0.0 < res.upper_fraction < 1.0
True
>>> res.forecast(3).shape
(3, 2)
>>> res.irf(4, regime="upper").shape, res.is_regimewise_stationary
((5, 2, 2), True)
>>> STVAR(y, order=1, transition_variable="y1", transition="exponential").fit().transition
'exponential'
>>> STVAR(y, order=1, transition_variable="y1", transition="tanh")
Traceback (most recent call last):
cultivars.exceptions.SpecificationError: transition must be one of ('logistic', ...