TARNN#

class cultivars.univariate.mean_function.TARNN(endog, *, order, engine=None, threshold_variable=None, delay=1, threshold=None, trim=0.15)[source]#

Neural threshold autoregression: one learned function per regime.

The sample is split at a fixed threshold on a lagged variable – the series itself or an external one – and a separate network is trained on each side, with one pooled innovation variance. The threshold defaults to the median of the lagged threshold variable so the two training sets are balanced; trim refuses a split that would leave either network with less than that share of the effective sample. The threshold is not searched: with a nonlinear learner per regime, a grid search would retrain both networks at every candidate, and the resulting split would carry a sampling uncertainty the record could not report.

Variables:

  • _endog – The validated series.

  • _order – Number of lagged levels.

  • _engine – The training backend.

  • _threshold_variable – The external variable, or None.

  • _delay – Delay of the threshold variable.

  • _threshold – The fixed split, or None for the median.

  • _trim – Minimum regime share.

Parameters:

  • endog (ArrayLike) – The series.

  • order (int) – Lagged levels fed to each regime’s learner.

  • engine (MeanFunctionEngine | None) – Training backend, invoked once per regime.

  • threshold_variable (ArrayLike | None) – External threshold variable aligned with endog; None makes the model self-exciting on y_{t-delay}.

  • delay (int) – Delay applied to the threshold variable.

  • threshold (float | None) – Fixed split point; None uses the median of the threshold variable.

  • trim (float) – Minimum share of the effective sample each regime must hold, so a lopsided split cannot leave one network trained on a handful of points.

Raises:

  • SpecificationError – If order or delay is not a positive integer.

  • DimensionError – If endog is not one-dimensional, is too short, or threshold_variable is not aligned with it.

  • NumericalError – If a series contains non-finite values, or the threshold leaves a regime with fewer than trim of the effective sample (raised by fit()).

See also

  • TARNNResult – what fit() returns.

  • ARNN – one function over the whole sample.

  • SETAR – linear regimes with a searched threshold.

References

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

Terasvirta, T., Lin, C.-F., & Granger, C. W. J. (1993). Power of the neural network linearity test. Journal of Time Series Analysis, 14(2), 209-220.

Example

>>> import numpy as np
>>> rng = np.random.default_rng(1)
>>> z = np.zeros(600)
>>> for t in range(1, 600):
...     slope = 0.6 if z[t - 1] <= 0 else -0.4
...     z[t] = slope * z[t - 1] + 0.3 * rng.standard_normal()
>>> res = TARNN(z, order=1, threshold=0.0).fit()
>>> res.threshold, res.n_lower > res.n_upper
(0.0, True)
>>> TARNN(z, order=1, threshold=5.0).fit()
Traceback (most recent call last):
    ...
cultivars.exceptions.NumericalError: threshold 5.0 leaves a regime with too few ...

Attributes#

delay

The threshold delay.

endog

The validated endogenous series.

engine

The training backend.

order

The autoregressive order.

self_exciting

Whether the threshold variable is a lag of the series itself.

Methods#

fit()

Split on the threshold, train one function per regime.
On this page