kdiagram.plot.context.plot_error_autocorrelation

kdiagram.plot.context.plot_error_autocorrelation(df, actual_col, pred_col, title=None, xlabel=None, ylabel=None, figsize=(10, 5), show_grid=True, grid_props=None, savefig=None, dpi=300, **acf_kwargs)[source]

Plots the autocorrelation of forecast errors.

This function creates an Autocorrelation Function (ACF) plot of the forecast errors (residuals). It is a critical diagnostic for time series models, used to check if there is any remaining temporal structure (i.e., patterns) in the residuals. A well- specified model should have errors that are uncorrelated over time, behaving like random noise.

Additional details can be found in Error Distribution Plot User Guide

Parameters:
dfpd.DataFrame

The input DataFrame containing the actual and predicted values.

actual_colstr

The name of the column containing the true observed values.

pred_colstr

The name of the column containing the point forecast values.

titlestr, optional

The title for the plot.

xlabelstr, optional

The label for the x-axis.

ylabelstr, optional

The label for the y-axis.

figsizetuple of (float, float), default=(10, 5)

The figure size in inches.

show_gridbool, default=True

Toggle the visibility of the plot’s grid lines.

grid_propsdict, optional

Custom keyword arguments passed to the grid for styling.

savefigstr, optional

The file path to save the plot. If None, the plot is displayed interactively.

dpiint, default=300

The resolution (dots per inch) for the saved figure.

**acf_kwargs

Additional keyword arguments passed directly to the underlying pandas.plotting.autocorrelation_plot function.

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

See also

plot_error_pacf

The companion plot for partial autocorrelation.

Notes

The Autocorrelation Function (ACF) at lag \(k\) measures the correlation between a time series and its own past values. For a series of errors \(e_t\), the ACF is defined as:

(1)\[\rho_k = \frac{\text{Cov}(e_t, e_{t-k})}{\text{Var}(e_t)}\]

This plot displays the values of \(\rho_k\) for a range of different lags \(k\). The plot also includes significance bands (typically at 95% and 99% confidence), which provide a threshold for determining if a correlation is statistically significant or likely due to random chance.

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from kdiagram.plot.context import plot_error_autocorrelation
>>>
>>> # Generate synthetic data with autocorrelated errors
>>> np.random.seed(0)
>>> n_samples = 200
>>> y_true = np.linspace(0, 50, n_samples)
>>> # Errors have an AR(1) structure
>>> errors = [0]
>>> for _ in range(n_samples - 1):
...     errors.append(0.7 * errors[-1] + np.random.normal(0, 1))
>>> y_pred = y_true + np.array(errors)
>>>
>>> df = pd.DataFrame({'actual': y_true, 'predicted': y_pred})
>>>
>>> # Generate the plot
>>> ax = plot_error_autocorrelation(
...     df,
...     actual_col='actual',
...     pred_col='predicted',
...     title="Autocorrelation of Dependent Errors"
... )