kdiagram.plot.context.plot_time_series

kdiagram.plot.context.plot_time_series(df, x_col=None, actual_col=None, pred_cols=None, names=None, q_lower_col=None, q_upper_col=None, title=None, xlabel=None, ylabel=None, figsize=(12, 6), cmap='viridis', show_grid=True, grid_props=None, savefig=None, dpi=300)[source]

Plots one or more time series from a DataFrame.

This function creates a standard time series plot, which is a fundamental tool for visualizing and comparing actual observed values against one or more model forecasts over time. It serves as an essential first-look diagnostic in any forecasting workflow.

More details in Time Series Plot User Guide

Parameters:
dfpd.DataFrame

The input DataFrame containing the time series data.

x_colstr, optional

The name of the column to use for the x-axis (e.g., a datetime column). If None, the DataFrame’s index is used.

actual_colstr, optional

The name of the column containing the true observed values. This is typically plotted as a solid reference line.

pred_colslist of str, optional

A list of one or more column names containing the point forecasts from different models.

nameslist of str, optional

Display names for each of the prediction series, to be used in the legend.

q_lower_colstr, optional

The name of the column for the lower bound of a prediction interval. If provided with q_upper_col, a shaded uncertainty band will be drawn.

q_upper_colstr, optional

The name of the column for the upper bound of a prediction interval.

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=(12, 6)

The figure size in inches.

cmapstr, default=’viridis’

The colormap used to assign unique colors to the different prediction series.

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.

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

See also

plot_scatter_correlation

A Cartesian plot for correlation.

plot_actual_vs_predicted

A polar plot for comparing true vs. predicted.

Notes

This function provides a direct visualization of time-dependent variables by mapping a time-like variable to the x-axis and the series values to the y-axis. It is a foundational plot for assessing a model’s ability to track trends and seasonality.

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from kdiagram.plot.context import plot_time_series
>>>
>>> # Generate synthetic time series data
>>> np.random.seed(0)
>>> n_samples = 100
>>> time = pd.date_range("2024-01-01", periods=n_samples, freq='D')
>>> y_true = 50 + np.linspace(0, 10, n_samples) + \
...          5 * np.sin(np.arange(n_samples) * 2 * np.pi / 15)
>>>
>>> y_pred = y_true + np.random.normal(0, 1.5, n_samples)
>>> df = pd.DataFrame({
...     'time': time,
...     'actual': y_true,
...     'forecast': y_pred,
...     'q10': y_pred - 3,
...     'q90': y_pred + 3,
... })
>>>
>>> # Generate the plot
>>> ax = plot_time_series(
...     df,
...     x_col='time',
...     actual_col='actual',
...     pred_cols=['forecast'],
...     q_lower_col='q10',
...     q_upper_col='q90',
...     title="Forecast vs. Actuals with 80% Uncertainty"
... )