plot_acf_diagnostics

plot_acf_diagnostics(
    data,
    date_column,
    value_column,
    ccf_columns=None,
    lags=1000,
    show_white_noise=True,
    title='Lag Diagnostics',
    x_lab='',
    y_lab='Correlation',
    width=None,
    height=None,
    plotly_dropdown=False,
    plotly_dropdown_x=1.05,
    plotly_dropdown_y=1.05,
    group_ncols=None,
    group_label_sep=', ',
    line_color='#2c3e50',
    line_width=2.0,
    line_dash='solid',
    marker_color=None,
    marker_size=6.0,
    marker_symbol='circle',
    marker_line_color=None,
    marker_line_width=0.0,
    show_markers=True,
    show_legend=False,
    zero_line_color='#999999',
    zero_line_width=1.0,
    zero_line_dash='dash',
    white_noise_color='#A6CEE3',
    white_noise_dash='dot',
    white_noise_width=1.0,
    hovertemplate=None,
)

Visualise ACF, PACF, and optional CCF diagnostics with Plotly, including grouped facets and extensive styling controls. Polars DataFrames are supported (they are converted internally to pandas).

Parameters

Name	Type	Description	Default
data	pd.DataFrame or pd.core.groupby.generic.DataFrameGroupBy	Time series data or grouped data produced via `DataFrame.groupby`.	required
date_column	str or ColumnSelector	Name of the datetime column, or a tidy selector resolving to one column.	required
value_column	str or ColumnSelector	Numeric column to diagnose, or a tidy selector resolving to one column.	required
ccf_columns	str or sequence	Additional numeric columns whose cross-correlations should be drawn. Accepts literal names or tidy selectors from :mod:`pytimetk.utils.selection`.	`None`
lags	int, sequence, slice, or str	Lag specification forwarded to :func:`pytimetk.acf_diagnostics`. Defaults to `1000`.	`1000`
show_white_noise	bool	Draw white-noise confidence bands around each subplot. Defaults to `True`.	`True`
title	str	Figure title. Defaults to `"Lag Diagnostics"`.	`'Lag Diagnostics'`
x_lab	str	Axis labels for the bottom row / first column. `x_lab` defaults to an empty string.	`''`
y_lab	str	Axis labels for the bottom row / first column. `x_lab` defaults to an empty string.	`''`
width	int	Figure dimensions in pixels.	`None`
height	int	Figure dimensions in pixels.	`None`
plotly_dropdown	bool	When `True` and grouped data are supplied, render a single set of panels with a Plotly dropdown to switch between groups. Defaults to `False`.	`False`
plotly_dropdown_x	float	Position of the dropdown menu (only used when `plotly_dropdown` is `True`).	`1.05`
plotly_dropdown_y	float	Position of the dropdown menu (only used when `plotly_dropdown` is `True`).	`1.05`
group_ncols	int	Number of facet columns when grouped data are supplied. Defaults to a single row.	`None`
group_label_sep	str	Separator used when concatenating multiple group labels for facet titles.	`', '`
line_color	str	Colour of the ACF/PACF/CCF traces.	`'#2c3e50'`
line_width	float	Line width in pixels. Defaults to `2.0`.	`2.0`
line_dash	str	Dash style for correlation lines (`"solid"`, `"dash"`, etc.).	`'solid'`
marker_color	str	Colour for scatter markers. Defaults to `line_color`.	`None`
marker_size	float	Marker size in pixels. Defaults to `6.0`.	`6.0`
marker_symbol	str	Plotly marker symbol (`"circle"`, `"square"`, …).	`'circle'`
marker_line_color	str	Outline colour for markers. Defaults to `marker_color`.	`None`
marker_line_width	float	Outline width for markers. Defaults to `0.0`.	`0.0`
show_markers	bool	Toggle markers on/off. Defaults to `True`.	`True`
show_legend	bool	Display a legend for the metric traces. Defaults to `False`.	`False`
zero_line_color	optional	Styling for the horizontal zero reference line.	`'#999999'`
zero_line_width	optional	Styling for the horizontal zero reference line.	`'#999999'`
zero_line_dash	optional	Styling for the horizontal zero reference line.	`'#999999'`
white_noise_color	optional	Styling for the white-noise confidence bands.	`'#A6CEE3'`
white_noise_dash	optional	Styling for the white-noise confidence bands.	`'#A6CEE3'`
white_noise_width	optional	Styling for the white-noise confidence bands.	`'#A6CEE3'`
hovertemplate	str	Custom Plotly hover template. Defaults to `"Lag=%{x}<br>Correlation=%{y}<extra></extra>"`.	`None`

Returns

Name	Type	Description
	plotly.graph_objects.Figure	A Plotly figure with one subplot per diagnostic metric (ACF, PACF, CCF traces) and optional facets for grouped series.

Examples

import numpy as np
import pandas as pd
import pytimetk as tk

rng = pd.date_range("2020-01-01", periods=40, freq="D")
df = pd.DataFrame(
    {
        "id": ["A"] * 20 + ["B"] * 20,
        "date": list(rng[:20]) + list(rng[:20]),
        "value": np.sin(np.linspace(0, 4 * np.pi, 40)),
        "driver": np.cos(np.linspace(0, 4 * np.pi, 40)),
    }
)

fig = tk.plot_acf_diagnostics(
    data=df.groupby("id"),
    date_column="date",
    value_column="value",
    ccf_columns="driver",
    lags=15,
    group_ncols=1,
    show_legend=True,
)
fig

# Dropdown example without tidy selectors
fig_dropdown = df.groupby("id").plot_acf_diagnostics(
    date_column="date",
    value_column="value",
    ccf_columns=["driver"],
    lags="20 days",
    plotly_dropdown=True,
    height=700,
)
fig_dropdown

# Dopdown example with tidy selectors
from pytimetk.utils.selection import contains

fig_dropdown = tk.plot_acf_diagnostics(
    data=df,
    date_column="date",
    value_column=contains("value", case=False),
    ccf_columns=contains("driver"),
    lags="20 days",
    plotly_dropdown=True,
    height=700,
)
fig_dropdown