statsmodels.tsa.stattools.acf#

statsmodels.tsa.stattools.acf(x, adjusted=False, nlags=None, qstat=False, fft=True, alpha=None, bartlett_confint=True, missing='none', *, result_object=None)[source]#

Calculate the autocorrelation function

Parameters:

xarray_like: The time series data.
adjustedbool, optional: If True, then denominators for autocovariance are n-k, otherwise n.
nlagsint, optional: Number of lags to return autocorrelation for. If not provided, uses min(10 * np.log10(nobs), nobs - 1). The returned value includes lag 0 (ie., 1) so size of the acf vector is (nlags + 1,).
qstatbool, optional: If True, returns the Ljung-Box q statistic for each autocorrelation coefficient. See q_stat for more information.
fftbool, optional: If True, computes the ACF via FFT.
alphafloat, optional: If a number is given, the confidence intervals for the given level are returned. For instance if alpha=.05, 95 % confidence intervals are returned where the standard deviation is computed according to Bartlett’s formula.
bartlett_confintbool, optional: Confidence intervals for ACF values are generally placed at 2 standard errors around r_k. The formula used for standard error depends upon the situation. If the autocorrelations are being used to test for randomness of residuals as part of the ARIMA routine, the standard errors are determined assuming the residuals are white noise. The approximate formula for any lag is that standard error of each r_k = 1/sqrt(N). See section 9.4 of [2] for more details on the 1/sqrt(N) result. For more elementary discussion, see section 5.3.2 in [3]. For the ACF of raw data, the standard error at a lag k is found as if the right model was an MA(k-1). This allows the possible interpretation that if all autocorrelations past a certain lag are within the limits, the model might be an MA of order defined by the last significant autocorrelation. In this case, a moving average model is assumed for the data and the standard errors for the confidence intervals should be generated using Bartlett’s formula. For more details on Bartlett formula result, see section 7.2 in [2].
missing{“none”, “raise”, “conservative”, “drop”}, optional: Specifies how the NaNs are to be treated. “none” performs no checks. “raise” raises an exception if NaN values are found. “drop” removes the missing observations and then estimates the autocovariances treating the non-missing as contiguous. “conservative” computes the autocovariance using nan-ops so that nans are removed when computing the mean and cross-products that are used to estimate the autocovariance. When using “conservative”, n is set to the number of non-missing observations.
result_objectbool, optional: Flag indicating whether to return the results as an AcfResult instead of a plain tuple. AcfResult always carries all four fields, matching the legacy tuple’s contents only when both qstat is True and alpha is not None; that combination is always returned, with no warning. Requesting only one of qstat or alpha still returns the shorter legacy tuple by default and issues a FutureWarning, because AcfResult would change how many values are returned. Ignored when qstat is False and alpha is None, since acf returns a single array in that case.

Deprecated since version 0.15.0: In release 0.16.0 or after July 2027, whichever is later, the default will change to always return an AcfResult. Set result_object=True to opt in now, or result_object=False to silence the warning and keep the current return type.

Returns:

acfndarray

The autocorrelation function for lags 0, 1, …, nlags. Shape (nlags+1,). Returned directly (not part of a tuple) unless qstat is True or alpha is not None.

AcfResult

A result object with fields acf, confint, qstat and pvalues (each of the latter three is None when it was not computed). See AcfResult.

This is returned whenever result_object=True. It is also returned by default when both qstat is True and alpha is not None, because AcfResult then has exactly the same four values as the legacy tuple; that case is adopted silently. Requesting only one of qstat or alpha still returns the shorter legacy tuple below and warns, since AcfResult would change how many values are returned.

confintndarray, optional

Confidence intervals for the ACF at lags 0, 1, …, nlags. Shape (nlags + 1, 2). Returned (as part of a plain tuple, the deprecated default) if alpha is not None. The confidence intervals are centered on the estimated ACF values. This behavior differs from plot_acf which centers the confidence intervals on 0.

qstatndarray, optional

The Ljung-Box Q-Statistic for lags 1, 2, …, nlags (excludes lag zero). Returned (as part of a plain tuple, the deprecated default) if qstat is True.

pvaluesndarray, optional

The p-values associated with the Q-statistics for lags 1, 2, …, nlags (excludes lag zero). Returned (as part of a plain tuple, the deprecated default) if qstat is True.