kdiagram.plot.anomaly.plot_cas_profile

kdiagram.plot.anomaly.plot_cas_profile(df, actual_col, q_low_col, q_up_col, *, window_size=21, title=None, figsize=(12.0, 6.0), cmap='plasma', s=60, alpha=0.85, ax=None, savefig=None, **kwargs)[source]

Visualizes clustered anomaly severity on a Cartesian plot.

This function creates a non-polar “profile” of forecast failures. It is highly effective for sequential data (like time series) where the x-axis represents the sample index or time. It visualizes an anomaly’s location, magnitude, type, and clustering density.

Parameters:
dfpd.DataFrame

The input DataFrame containing the actual and predicted quantile values.

actual_colstr

The name of the column containing the true observed values.

q_low_colstr

The name of the column for the lower bound of the prediction interval.

q_up_colstr

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

window_sizeint, default=21

The size of the moving window used to calculate the local anomaly density, which determines the point color.

titlestr, optional

A custom title for the plot. If None, a default title including the CAS score is generated.

figsizetuple of (float, float), default=(12.0, 6.0)

The figure size in inches.

cmapstr, default=’plasma’

The colormap for coloring points based on local density.

sint, default=60

The marker size for the points.

alphafloat, default=0.85

The transparency of the points.

axmatplotlib.axes.Axes, optional

An existing Cartesian axes to draw the plot on. If None, a new figure and axes are created.

savefigstr, optional

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

Returns:
axmatplotlib.axes.Axes or None

The Matplotlib Axes object containing the plot, or None if no anomalies are detected in the data.

Parameters:
Return type:

Axes | None

See also

plot_anomaly_glyphs

A polar version using informative glyphs.

clustered_anomaly_severity_score

The underlying metric function.

Notes

This plot provides a direct, sequential view of forecast failures, making it easy to spot trends or regime changes in model performance over time [1].

Visual Mapping:

  • X-axis: The sample index, showing when or where in the sequence the failure occurred.

  • Y-axis: The Anomaly Magnitude. The height of a point shows its severity.

  • Color: The Local Anomaly Density. Hotter colors show “hotspots” where failures are concentrated.

  • Shape: The Type of anomaly.

    • ▲ (up-triangle): Over-prediction (risk underestimated).

    • ▼ (down-triangle): Under-prediction (risk overestimated).

References

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from kdiagram.plot.anomaly import plot_anomaly_profile_cartesian
>>>
>>> # Simulate data with a failure hotspot in the middle
>>> np.random.seed(0)
>>> n_samples = 400
>>> y_true = np.zeros(n_samples)
>>> y_qlow = y_true - 10
>>> y_qup = y_true + 10
>>> y_true[180:220] = y_qup[180:220] + np.random.uniform(5, 15, 40)
>>>
>>> df = pd.DataFrame({
...     "actual": y_true, "q10": y_qlow, "q90": y_qup
... })
>>>
>>> ax = plot_anomaly_profile_cartesian(
...     df,
...     actual_col="actual",
...     q_low_col="q10",
...     q_up_col="q90",
...     title="Cartesian Anomaly Severity Profile"
... )