ACF

This function estimates the autocorrelation function (ACF) of a univariate time series for lag values from 0 up to a selected maximum lag.

The lag-k autocorrelation is the normalized covariance between observations separated by k periods:

\rho_k = \frac{\operatorname{Cov}(x_t, x_{t-k})}{\operatorname{Var}(x_t)}

Optional confidence intervals and Ljung-Box diagnostics can be included to help assess whether observed autocorrelations are statistically significant.

Excel Usage

=ACF(x, adjusted, nlags, qstat, fft, alpha, bartlett_confint, missing)

x (list[list], required): Time-series observations as a 2D range.
adjusted (bool, optional, default: false): Use denominator n-k instead of n in covariance normalization.
nlags (int, optional, default: null): Maximum lag to compute; null uses statsmodels default.
qstat (bool, optional, default: false): Return Ljung-Box Q statistics and p-values for lags above zero.
fft (bool, optional, default: true): Use FFT-based computation for improved speed on long series.
alpha (float, optional, default: null): Significance level for confidence intervals; null disables intervals.
bartlett_confint (bool, optional, default: true): Use Bartlett formula for confidence interval standard errors.
missing (str, optional, default: “none”): Missing-data handling mode.

Returns (list[list]): 2D table with columns lag, acf, conf_low, conf_high, q_stat, and p_value.

Example 1: ACF for a short increasing series

Inputs:

x						adjusted	nlags	qstat	fft	alpha	bartlett_confint	missing
1	2	3	4	5	6	false	3	false	true		true	none

Excel formula:

=ACF({1,2,3,4,5,6}, FALSE, 3, FALSE, TRUE, , TRUE, "none")

Expected output:

Result
0	1
1	0.5
2	0.0571429
3	-0.271429

Example 2: ACF with confidence intervals

Inputs:

x								adjusted	nlags	qstat	fft	alpha	bartlett_confint	missing
2	1	2	1	2	1	2	1	false	4	false	true	0.05	true	none

Excel formula:

=ACF({2,1,2,1,2,1,2,1}, FALSE, 4, FALSE, TRUE, 0.05, TRUE, "none")

Expected output:

Result
0	1	1	1
1	-0.875	-1.56795	-0.182048
2	0.75	-0.35248	1.85248
3	-0.625	-1.95002	0.700016
4	0.5	-0.959729	1.95973

Example 3: ACF with Ljung-Box statistics

Inputs:

x									adjusted	nlags	qstat	fft	alpha	bartlett_confint	missing
1	0	1	0	1	0	1	0	1	false	4	true	true		true	none

Excel formula:

=ACF({1,0,1,0,1,0,1,0,1}, FALSE, 4, TRUE, TRUE, , TRUE, "none")

Expected output:

Result
0	1
1	-0.888889	9.77778	0.00176634
2	0.772222	18.2115	0.000111023
3	-0.666667	25.5449	0.0000118766
4	0.544444	31.414	0.00000252021

Example 4: ACF using adjusted denominator

Inputs:

x								adjusted	nlags	qstat	fft	alpha	bartlett_confint	missing
3	4	6	8	7	5	4	6	true	3	false	false		true	none

Excel formula:

=ACF({3,4,6,8,7,5,4,6}, TRUE, 3, FALSE, FALSE, , TRUE, "none")

Expected output:

Result
0	1
1	0.423181
2	-0.505241
3	-0.909434

Python Code

import numpy as np
from statsmodels.tsa.stattools import acf as sm_acf

def acf(x, adjusted=False, nlags=None, qstat=False, fft=True, alpha=None, bartlett_confint=True, missing='none'):
    """
    Compute autocorrelation values across lags with optional confidence intervals and Ljung-Box statistics.

    See: https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.acf.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        x (list[list]): Time-series observations as a 2D range.
        adjusted (bool, optional): Use denominator n-k instead of n in covariance normalization. Default is False.
        nlags (int, optional): Maximum lag to compute; null uses statsmodels default. Default is None.
        qstat (bool, optional): Return Ljung-Box Q statistics and p-values for lags above zero. Default is False.
        fft (bool, optional): Use FFT-based computation for improved speed on long series. Default is True.
        alpha (float, optional): Significance level for confidence intervals; null disables intervals. Default is None.
        bartlett_confint (bool, optional): Use Bartlett formula for confidence interval standard errors. Default is True.
        missing (str, optional): Missing-data handling mode. Valid options: None, Raise, Conservative, Drop. Default is 'none'.

    Returns:
        list[list]: 2D table with columns lag, acf, conf_low, conf_high, q_stat, and p_value.
    """
    try:
        def to1d(values):
            if isinstance(values, list):
                if all(isinstance(row, list) for row in values):
                    raw = [item for row in values for item in row]
                else:
                    raw = values
            else:
                raw = [values]

            out = []
            for item in raw:
                try:
                    out.append(float(item))
                except (TypeError, ValueError):
                    continue
            return out

        if missing not in ("none", "raise", "conservative", "drop"):
            return "Error: missing must be one of 'none', 'raise', 'conservative', or 'drop'"

        series = to1d(x)
        if len(series) < 2:
            return "Error: x must contain at least two numeric values"

        result = sm_acf(
            np.asarray(series, dtype=float),
            adjusted=adjusted,
            nlags=nlags,
            qstat=qstat,
            fft=fft,
            alpha=alpha,
            bartlett_confint=bartlett_confint,
            missing=missing,
        )

        acf_vals = None
        confint = None
        q_vals = None
        p_vals = None

        if isinstance(result, tuple):
            if len(result) == 4:
                acf_vals, confint, q_vals, p_vals = result
            elif len(result) == 3:
                acf_vals, q_vals, p_vals = result
            elif len(result) == 2:
                acf_vals, confint = result
            else:
                return "Error: Unexpected output format from statsmodels acf"
        else:
            acf_vals = result

        acf_arr = np.asarray(acf_vals, dtype=float)
        conf_arr = np.asarray(confint, dtype=float) if confint is not None else None
        q_arr = np.asarray(q_vals, dtype=float) if q_vals is not None else None
        p_arr = np.asarray(p_vals, dtype=float) if p_vals is not None else None

        table = []
        for lag in range(len(acf_arr)):
            low = ""
            high = ""
            q_stat_val = ""
            p_val = ""

            if conf_arr is not None and lag < len(conf_arr):
                low = float(conf_arr[lag][0])
                high = float(conf_arr[lag][1])

            if q_arr is not None and lag > 0 and (lag - 1) < len(q_arr):
                q_stat_val = float(q_arr[lag - 1])
            if p_arr is not None and lag > 0 and (lag - 1) < len(p_arr):
                p_val = float(p_arr[lag - 1])

            table.append([lag, float(acf_arr[lag]), low, high, q_stat_val, p_val])

        return table
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

x *

Time-series observations as a 2D range.

adjusted

Use denominator n-k instead of n in covariance normalization.

nlags

Maximum lag to compute; null uses statsmodels default.

qstat

Return Ljung-Box Q statistics and p-values for lags above zero.

fft

Use FFT-based computation for improved speed on long series.

alpha

Significance level for confidence intervals; null disables intervals.

bartlett_confint

Use Bartlett formula for confidence interval standard errors.

missing

Missing-data handling mode.