kpss#

cultivars.diagnostics.unit_roots.kpss(endog, *, trend='c', kernel='bartlett', bandwidth=None)[source]#

KPSS test with stationarity under the null.

The series is regressed on the deterministic terms, and the residuals’ partial sums \(S_t = \sum_{i \le t} \hat e_i\) are scaled by a kernel estimate of their long-run variance,

\[\eta = \frac{T^{-2} \sum_{t = 1}^{T} S_t^2}{\hat\lambda^2},\]

which under stationarity converges to the integral of a squared Brownian bridge (a second-level bridge for "ct") and under a unit root diverges, so rejection lies in the upper tail. This is the Lagrange multiplier test of a zero variance for a random-walk component, and it is the complement of the Dickey-Fuller family: the two nulls are the two sides of the question, and a series that keeps both is one the sample cannot decide. The p-value is interpolated in the authors’ table and clipped to [0.01, 0.10] outside it, so 0.01 reads as “at most 1%” and 0.10 as “at least 10%”.

Parameters:

  • endog (ArrayLike) – The series, (T,).

  • trend (str) – "c" for level stationarity or "ct" for trend stationarity.

  • kernel (str) – "bartlett" or "quadratic-spectral".

  • bandwidth (float | None) – Kernel bandwidth; None for the automatic rule.

Return type:

UnitRootTest

Returns:

The UnitRootTest named "KPSS" with null="stationarity" and lower_tail=False; lags reports the bandwidth.

Raises:

Note

The long-run variance is estimated under the null, so a bandwidth too short for the residual autocorrelation over-rejects and one too long loses power; the test is known to over-reject on a highly persistent stationary series at any bandwidth, which is the mirror of the ADF’s low power there. The p-value’s clipping means two strong rejections cannot be ranked by it; rank by the statistic against its critical values.

See also

  • adf() – the complementary test with the unit root under the null.

  • canova_hansen() – the same construction at the seasonal frequencies.

  • long_run_variance() – the kernel estimator on its own.

References

Kwiatkowski, D., Phillips, P. C. B., Schmidt, P., & Shin, Y. (1992). Testing the null hypothesis of stationarity against the alternative of a unit root. Journal of Econometrics, 54(1-3), 159-178.

Nyblom, J. (1989). Testing for the constancy of parameters over time. Journal of the American Statistical Association, 84(405), 223-230.

Example

A random walk rejects level stationarity at the table’s floor; white noise keeps it at its ceiling:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> walk = np.cumsum(rng.standard_normal(300))
>>> test = kpss(walk)
>>> test.reject(), test.pvalue, test.critical_values["5%"]
(True, 0.01, 0.463)
>>> kpss(rng.standard_normal(300)).pvalue
0.1
On this page