TAR#

class cultivars.univariate.threshold.TAR(endog, *, order, threshold_variable, delay=1, trim=0.15, n_grid=300)[source]

Bases: _ThresholdModel[SETARResult]

Threshold autoregression driven by an external transition variable.

Identical machinery to SETAR, but the regime is decided by a variable you supply rather than by the series’ own past,

\[\begin{split}y_t = \begin{cases} \phi_L' x_t + \varepsilon_t & z_{t-d} \le r \\ \phi_U' x_t + \varepsilon_t & z_{t-d} > r \end{cases},\end{split}\]

so the threshold is in the units of \(z\) and the grid is built on its quantiles. The delay is fixed rather than searched: with an exogenous driver the lag is usually a modelling choice with economic content, not a nuisance parameter. Because the driver’s future is not part of the model, the result refuses simulate and nonlinear_state_space; everything else on SETARResult applies.

Variables:

  • _endog – The observed series as a float array, shape (n,).

  • _order – The autoregressive order within each regime.

  • _delays – The single fixed delay.

  • _trim – The fraction trimmed from each tail of the grid.

  • _n_grid – The number of candidate thresholds.

  • _threshold_variable – The transition variable, shape (n,).

Parameters:

  • endog (ArrayLike) – The series.

  • order (int) – Autoregressive order within each regime, at least 1.

  • threshold_variable (ArrayLike) – The transition variable, one-dimensional and aligned with endog.

  • delay (int) – Delay applied to the transition variable, at least 1.

  • trim (float) – Fraction trimmed from each tail of the quantile grid, in (0, 0.5).

  • n_grid (int) – Candidate thresholds, at least 1.

Raises:

  • SpecificationError – If order, delay or n_grid is below 1 or trim is outside (0, 0.5).

  • DimensionError – If either series is not one-dimensional, the transition variable is not the length of endog, or the sample is shorter than 2 (order + 2) + delay.

See also

  • SETARResult – the record fit returns.

  • SETAR – the self-exciting form, which can simulate and emit a state space.

References

Tong, H. (1990). Non-linear Time Series: A Dynamical System Approach. Oxford University Press, ch. 3.

Example

An autoregression whose persistence flips with the sign of an external driver:

>>> import numpy as np
>>> rng = np.random.default_rng(1)
>>> z = rng.standard_normal(400)
>>> y = np.zeros(400)
>>> for t in range(1, 400):
...     phi = 0.5 if z[t - 1] <= 0.0 else -0.5
...     y[t] = phi * y[t - 1] + rng.standard_normal()
>>> res = TAR(y, order=1, threshold_variable=z).fit()
>>> res.self_exciting, res.searched_delay, res._comparison_label()
(False, False, 'TAR(1, d=1)')
>>> bool(abs(res.threshold) < 0.3), bool(np.allclose(res.threshold_values, z[:-1]))
(True, True)
>>> bool(abs(res.lower_params[1] - 0.5) < 0.1), bool(abs(res.upper_params[1] + 0.5) < 0.1)
(True, True)
>>> TAR(y, order=1, threshold_variable=z[:300])
Traceback (most recent call last):
cultivars.exceptions.DimensionError: threshold_variable must be one-dimensional with ...