statsmodels.stats.diagnostic.acorr_ljungbox#

statsmodels.stats.diagnostic.acorr_ljungbox(x, lags=None, boxpierce=False, model_df=0, period=None, return_df=None, 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.

lagsint or array_like of int, optional

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.

All lags must be integers >= 1 and the largest lag must be smaller than nobs, the number of observations. An empty sequence is not allowed.

Changed in version 0.15.1: A ValueError is raised if lags is empty or contains a value below 1. Previously lag 0 and negative lags silently reported the statistic of another lag or failed with an unrelated error.

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.

return_dfbool, optional

Unused. A DataFrame is always returned.

Deprecated since version 0.15.1: return_df has no effect and will be removed in statsmodels 0.17.0. Passing any value issues a FutureWarning.

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 chi2.sf(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 chi2.sf(bp_stat, dof) where dof is lag - model_df. If lag - model_df <= 0, then NaN is returned for the pvalue.

Raises:
ValueError

If lags is empty or contains a value below 1, if the largest lag is not smaller than nobs, or if the default number of lags (used when lags is None) is below 1 because the series is too short.

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 has better finite-sample properties.

References

Examples

>>> import statsmodels.api as sm
>>> data = sm.datasets.sunspots.load_pandas().data
>>> res = sm.tsa.ARIMA(data["SUNACTIVITY"], order=(1, 0, 1)).fit()
>>> sm.stats.acorr_ljungbox(res.resid, lags=[10])
       lb_stat     lb_pvalue
10  214.108691  1.825879e-40