LinearityTest#

class cultivars.diagnostics.nonlinearity.LinearityTest(*, statistic, pvalue, name, df, null, alternative, order, delay, nobs, threshold=None, critical_values=None, suggestion=None, companions=())[source]#

Verdict of a test of a linear autoregression against a nonlinear alternative.

The four members share a null, that the AR(\(p\)) is correctly specified, and differ in the alternative they aim at, which the record names. Three are \(F\) tests on an auxiliary regression of the linear model’s residuals \(\hat u_t\) on its regressors and a set of added terms,

\[F = \frac{(SSR_0 - SSR_1) / q}{SSR_1 / (n - k - q)} \;\sim\; F(q,\; n - k - q),\]

with \(q\) added terms: cubic products of the lags and the transition variable for Teräsvirta, powers of the fitted values for RESET, and, for Tsay, the arranged autoregression’s predictive residuals regressed on the lags. Hansen’s test alone is a sup statistic, the largest \(F\) over candidate thresholds, whose law has no table because the threshold is unidentified under the null; its p-value and critical values are simulated, it locates the threshold it found, and its df is None. A rejection by Tsay or Hansen says “threshold”; a rejection by Teräsvirta says “smooth transition” and, through the escalation sequence carried as companions, which kind; a rejection by RESET says only that something smooth was left in the residual.

Variables:

  • name – The test.

  • statistic – The test statistic, F for the regression tests and sup-F for Hansen.

  • pvalue – Its p-value.

  • df – (numerator, denominator) degrees of freedom of an F reference; None for a simulated law.

  • null – The hypothesis under test.

  • alternative – What a rejection points to.

  • order – Autoregressive order of the linear null.

  • delay – Delay of the transition variable, or None where the test has none.

  • nobs – Observations in the auxiliary regression.

  • threshold – Hansen’s estimated threshold; None otherwise.

  • critical_values – Simulated {"1%", "5%", "10%"} critical values for Hansen; None otherwise.

  • suggestion – Teräsvirta’s model-selection reading, "LSTAR" or "ESTAR"; None otherwise.

  • companions – The steps of Teräsvirta’s escalation sequence.

Note

The Teräsvirta record always carries a suggestion, whether or not linearity is rejected: the rule compares the three escalation p-values and one of them is always smallest. Read it only after reject() says there is a transition to choose between. The tests are for the conditional mean; neglected conditional heteroskedasticity inflates all four, so run an ARCH test on the linear residuals first and read a rejection here in its light.

See also

References

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

Tsay, R. S. (1989). Testing and modeling threshold autoregressive processes. Journal of the American Statistical Association, 84(405), 231-240.

Hansen, B. E. (1996). Inference when a nuisance parameter is not identified under the null hypothesis. Econometrica, 64(2), 413-430.

Example

A two-regime threshold autoregression is caught by all four, each naming its own alternative:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> y = np.zeros(400)
>>> for t in range(1, 400):
...     slope = 0.8 if y[t - 1] < 0.0 else -0.5
...     y[t] = slope * y[t - 1] + rng.standard_normal()
>>> for test in (terasvirta(y, order=1), tsay(y, order=1), ramsey_reset(y, order=1)):
...     print(f"{test.name:<11} {test.alternative:<24} {test.df}  {test.reject()}")
Teräsvirta  smooth transition        (3, 394)  True
Tsay        threshold                (2, 336)  True
RESET       smooth misspecification  (2, 395)  True
>>> test = hansen_threshold(y, order=1, replications=500, seed=0)
>>> test.df, test.reject(), bool(abs(test.threshold) < 0.5)
(None, True, True)

Attributes#

name

"Teräsvirta", "Tsay", "RESET", "Hansen sup-F", or a step name.

df

(numerator, denominator) degrees of freedom of the F reference, or None.

null

The hypothesis under test, "linear AR(p) is correctly specified" with p filled in.

alternative

What a rejection points to.

order

Autoregressive order \(p\) of the linear null.

delay

Delay \(d\) of the transition variable \(y_{t-d}\), or None for RESET.

nobs

Observations in the auxiliary regression, T - max(order, delay).

threshold

Hansen's least-squares threshold estimate; None otherwise.

critical_values

Simulated {"1%", "5%", "10%"} critical values of Hansen's sup-F.

suggestion

Teräsvirta's reading of the escalation sequence; None off that record.

companions

The escalation steps H04, H03, H02 of a Teräsvirta record, each a full record.

pvalue

from the F reference, or simulated for Hansen.

statistic

Methods#

reject(*[, alpha])

Whether the null is rejected at level alpha.

summary()

The test as a table, renderable as text, HTML, or a dataframe.