KPSS

Install and import#

npm install fintech-algorithms

import { kpss } from "fintech-algorithms/statistical-time-series/diagnostics/kpss";

Signature#

kpss(values, lags, criticalValue)

Tests stationarity with the null *reversed* relative to ADF: here the null is that the series is stationary. Running both is standard practice, because agreement is informative and disagreement tells you the sample cannot settle the question.

Parameters#

Returns#

{ method, variant, residual_mean, partial_sum_numerator, long_run_variance, statistic, decision, … }

The statistic with the long-run variance behind it, which is where the bandwidth choice shows up.

Errors#

• When the sample is shorter than the bandwidth requires — throws

Complexity: time O(n × lags), space O(n).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

[0.49366418, 1.54242291, -0.82556495, 0.47513288, 0.50704417, -0.3816439]

Showing 6 of 96 elements.

5

0.463

Call#

kpss(values, lags, criticalValue)

Returns#

object with 13 fields: method, variant, nobs, lags, residual_mean, partial_sum_numerator, long_run_variance, covariance_terms, …

{
  "method": "kpss",
  "variant": "level-stationary-fixed-bartlett-bandwidth",
  "nobs": 96,
  "lags": 5,
  "residual_mean": -2.0816681711721685e-17,
  "partial_sum_numerator": 0.2446756917455388,
  "long_run_variance": 4.82902222159472,
  "covariance_terms": [
    {
      "lag": 1,
      "weight": 0.8333333333333334,
      "cross_product": 102.29629606088473
    },
    {
      "lag": 2,
      "weight": 0.6666666666666667,
      "cross_product": 67.86612357881646
    },
    {
      "lag": 3,
      "weight": 0.5,
      "cross_product": 43.864068660314665
    }
  ],
  "statistic": 0.05066775022309546,
  "critical_value": 0.463,
  "reject_null": false,
  "state": "fail-to-reject-level-stationarity",
  "reason": "statistic-not-above-boundary"
}

Other exports#

This module also exports acf, pacf, adf, ljungBox, zivotAndrews, runDiagnostic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Calculation flow#

flowchart TD
  A["Ordered finite series"] --> B{"Contract valid?"}
  B -- "No" --> X["Stop: explicit invalid state"]
  B -- "Yes" --> C["Demean for level null"]
  C --> D["Accumulate residual partial sums"]
  D --> E["Estimate Bartlett long-run variance"]
  E --> F["Compare KPSS statistic with boundary"]
  F --> G{"Declared strict decision rule"}
  G --> H["Report machine state, null, and limitation"]
  H --> I["Compare with Ljung-Box"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Testing the null hypothesis of stationarity against the alternative of a unit root
• statsmodels.tsa.stattools.kpss
• Evidence decisions

The rest of the Diagnostics family#

• ACFAutocorrelation at each lag.
• PACFPartial autocorrelation: correlation at each lag with the intervening lags removed.
• Augmented Dickey-FullerTests for a unit root.
• Ljung-BoxTests whether a group of autocorrelations is jointly zero.
• Zivot-Andrews Break TestA unit-root test that allows one structural break at an unknown date, found by searching.