statsmodels.stats.diagnostic.acorr_ljungbox

statsmodels.stats.diagnostic.acorr_ljungbox(x, lags=None, boxpierce=False, model_df=0, period=None, return_df=True, auto_lag=False)[source]

Ljung-Box test of autocorrelation in residuals.

Parameters:
xarray_like

The data series. The data is demeaned before the test statistic is computed.

lags{int, array_like}, default None

If lags is an integer then this is taken to be the largest lag that is included, the test result is reported for all smaller lag length. If lags is a list or array, then all lags are included up to the largest lag in the list, however only the tests for the lags in the list are reported. If lags is None, then the default maxlag is min(10, nobs // 5). The default number of lags changes if period is set.

boxpiercebool, default False

If true, then additional to the results of the Ljung-Box test also the Box-Pierce test results are returned.

model_dfint, default 0

Number of degrees of freedom consumed by the model. In an ARMA model, this value is usually p+q where p is the AR order and q is the MA order. This value is subtracted from the degrees-of-freedom used in the test so that the adjusted dof for the statistics are lags - model_df. If lags - model_df <= 0, then NaN is returned.

periodint, default None

The period of a Seasonal time series. Used to compute the max lag for seasonal data which uses min(2*period, nobs // 5) if set. If None, then the default rule is used to set the number of lags. When set, must be >= 2.

auto_lagbool, default False

Flag indicating whether to automatically determine the optimal lag length based on threshold of maximum correlation value.

Returns:
DataFrame

Frame with columns:

  • lb_stat - The Ljung-Box test statistic.

  • lb_pvalue - The p-value based on chi-square distribution. The p-value is computed as 1 - chi2.cdf(lb_stat, dof) where dof is lag - model_df. If lag - model_df <= 0, then NaN is returned for the pvalue.

  • bp_stat - The Box-Pierce test statistic.

  • bp_pvalue - The p-value based for Box-Pierce test on chi-square distribution. The p-value is computed as 1 - chi2.cdf(bp_stat, dof) where dof is lag - model_df. If lag - model_df <= 0, then NaN is returned for the pvalue.

See also

statsmodels.regression.linear_model.OLS.fit

Regression model fitting.

statsmodels.regression.linear_model.RegressionResults

Results from linear regression models.

statsmodels.stats.stattools.q_stat

Ljung-Box test statistic computed from estimated autocorrelations.

Notes

Ljung-Box and Box-Pierce statistic differ in their scaling of the autocorrelation function. Ljung-Box test is has better finite-sample properties.

References

Examples

>>> import statsmodels.api as sm
>>> data = sm.datasets.sunspots.load_pandas().data
>>> res = sm.tsa.ARMA(data["SUNACTIVITY"], (1,1)).fit(disp=-1)
>>> sm.stats.acorr_ljungbox(res.resid, lags=[10], return_df=True)
       lb_stat     lb_pvalue
10  214.106992  1.827374e-40
Last update: Dec 16, 2024