Ljung-Box
Install and import#
npm install fintech-algorithmsimport { ljungBox } from "fintech-algorithms/statistical-time-series/diagnostics/ljung-box";Signature#
ljungBox(values, lags, modelDf, alpha)Tests whether a group of autocorrelations is jointly zero. Applied to model residuals it answers the question that matters after fitting: is there structure left that the model failed to capture?
Parameters#
| Name | Type | Notes |
|---|---|---|
values | number[] | Observation series in chronological order, oldest first. |
lags | number | Number of lags tested jointly. min: 1 · integer: true |
modelDf | number | Parameters estimated by the model whose residuals these are. Omitting it inflates the degrees of freedom and makes a bad model look adequate. min: 0 · integer: true |
alpha | number | Significance level. min: 0 |
Returns#
{ method, lags, model_df, degrees_of_freedom, terms, statistic, p_value, decision, … }
The statistic and p-value with the degrees-of-freedom adjustment shown.
Errors#
- When modelDf is not less than lags — throws
Complexity: time O(n × lags),
space O(lags).
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.1869847, -1.93610944, 1.06953965, 0.16494849, -0.7467157]Showing 6 of 96 elements.
1200.05Call#
ljungBox(values, lags, modelDf, alpha)Returns#
object with 13 fields: method, variant, nobs, lags, model_df, degrees_of_freedom, terms, statistic, …
{
"method": "ljung_box",
"variant": "demeaned-residual-portmanteau",
"nobs": 96,
"lags": 12,
"model_df": 0,
"degrees_of_freedom": 12,
"terms": [
{
"lag": 1,
"acf": -0.0475050120854155,
"term": 0.00002375501234984708
},
{
"lag": 2,
"acf": -0.01074438668394694,
"term": 0.0000012281047363210248
},
{
"lag": 3,
"acf": 0.10423989737175164,
"term": 0.00011683823875347651
}
],
"statistic": 11.395763774723312,
"p_value": 0.49534027421087556,
"alpha": 0.05,
"reject_null": false,
"state": "fail-to-reject-residual-whiteness",
"reason": "p-value-not-below-alpha"
}Other exports#
This module also exports
acf, pacf, adf, kpss, 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#
Ljung-Box decision flow
flowchart TD
A["Ordered finite series"] --> B{"Contract valid?"}
B -- "No" --> X["Stop: explicit invalid state"]
B -- "Yes" --> C["Compute residual ACF through h"]
C --> D["Scale and sum squared lag terms"]
D --> E["Set df = h - model_df"]
E --> F["Compare chi-square tail with alpha"]
F --> G{"Declared strict decision rule"}
G --> H["Report machine state, null, and limitation"]
H --> I["Compare with Zivot-Andrews Break Test"]
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.
References#
- statsmodels.tsa.stattools.acf
- On a measure of lack of fit in time series models
- statsmodels.stats.diagnostic.acorr_ljungbox
- Evidence decisions