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)

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 currently min((nobs // 2 - 2), 40). After 0.12 this will change to 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.

return_dfbool, default None

Flag indicating whether to return the result as a single DataFrame with columns lb_stat, lb_pvalue, and optionally bp_stat and bp_pvalue. After 0.12, this will become the only return method. Set to True to return the DataFrame or False to continue returning the 2 - 4 output. If None (the default), a warning is raised.

auto_lagbool, default False

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

Returns

lbvaluefloat or array

The Ljung-Box test statistic.

pvaluefloat or array

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

bpvalue(optional), float or array

The test statistic for Box-Pierce test.

bppvalue(optional), float or array

The p-value based for Box-Pierce test on chi-square distribution. The p-value is computed as 1.0 - chi2.cdf(bpvalue, 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.

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

*

Green, W. “Econometric Analysis,” 5th ed., Pearson, 2003.

†

J. Carlos Escanciano, Ignacio N. Lobato “An automatic Portmanteau test for serial correlation”., Volume 151, 2009.

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