kdiagram.plot.relationship.plot_conditional_quantiles

kdiagram.plot.relationship.plot_conditional_quantiles(y_true, y_preds_quantiles, quantiles, *, bands=None, title='Conditional Quantile Plot', figsize=(8.0, 8.0), cmap='viridis', alpha_min=0.2, alpha_max=0.5, show_grid=True, grid_props=None, mask_angle=False, mask_radius=False, savefig=None, dpi=300, acov='default', ax=None)[source]

Plots polar conditional quantile bands.

This function visualizes how the predicted conditional distribution (represented by quantiles) changes as a function of the true observed value. It is a powerful tool for diagnosing heteroscedasticity, i.e., whether the forecast uncertainty is constant or changes with the magnitude of the target variable.

Parameters:
y_truenp.ndarray

1D array of true observed values, which will be mapped to the angular coordinate.

y_preds_quantilesnp.ndarray

2D array of quantile forecasts, with shape (n_samples, n_quantiles).

quantilesnp.ndarray

1D array of the quantile levels corresponding to the columns of y_preds_quantiles.

bandslist of int, optional

A list of the desired interval percentages to plot as shaded bands (e.g., [90, 50] for the 90% and 50% prediction intervals). Defaults to the widest interval available from the provided quantiles.

titlestr, default=”Conditional Quantile Plot”

The title for the plot.

figsizetuple of (float, float), default=(8, 8)

The figure size in inches.

cmapstr, default=’viridis’

The colormap for the shaded uncertainty bands.

alpha_minfloat, default=0.2

The minimum alpha (transparency) for the outermost band.

alpha_maxfloat, default=0.5

The maximum alpha for the innermost band.

show_gridbool, default=True

Toggle the visibility of the polar grid lines.

grid_propsdict, optional

Custom keyword arguments passed to the grid for styling.

mask_anglebool, default=False

If True, hide the angular tick labels.

mask_radiusbool, default=False

If True, hide the radial tick labels.

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.

acov{‘default’, ‘half_circle’, ‘quarter_circle’, ‘eighth_circle’},

default=’default’ Angular coverage (span) of the plot:

  • 'default': \(2\pi\) (full circle)

  • 'half_circle': \(\pi\)

  • 'quarter_circle': \(\tfrac{\pi}{2}\)

  • 'eighth_circle': \(\tfrac{\pi}{4}\)

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

Notes

This plot is a novel visualization developed as part of the analytics framework in [1]. It provides an intuitive view of the conditional predictive distribution.

  1. Coordinate Mapping: The plot first sorts the data based on the true values \(y_{true}\) to ensure a continuous spiral. The sorted true values are then mapped to the angular coordinate \(\theta\) in the range \([0, 2\pi]\).

    (1)\[\theta_i \propto y_{true,i}^{\text{(sorted)}}\]

    The predicted quantiles \(q_{i, \tau}\) for each observation \(i\) and quantile level \(\tau\) are mapped directly to the radial coordinate \(r\).

  2. Band Construction: For a given prediction interval, for example 80%, the corresponding lower (\(\tau=0.1\)) and upper (\(\tau=0.9\)) quantile forecasts are used to define the boundaries of a shaded band. The function can plot multiple, nested bands (e.g., 80% and 50%) to give a more complete picture of the distribution’s shape. The median forecast (\(\tau=0.5\)) is drawn as a solid central line.

References

Examples

>>> import numpy as np
>>> from kdiagram.plot.relationship import plot_conditional_quantiles
>>>
>>> # Generate synthetic data with heteroscedasticity
>>> np.random.seed(0)
>>> n_samples = 200
>>> y_true = np.linspace(0, 20, n_samples)**1.5
>>> quantiles = np.array([0.1, 0.25, 0.5, 0.75, 0.9])
>>>
>>> # Uncertainty (interval width) increases with the true value
>>> interval_width = 5 + (y_true / y_true.max()) * 15
>>> y_preds = np.zeros((n_samples, len(quantiles)))
>>> y_preds[:, 2] = y_true # Median
>>> y_preds[:, 1] = y_true - interval_width * 0.25 # Q25
>>> y_preds[:, 3] = y_true + interval_width * 0.25 # Q75
>>> y_preds[:, 0] = y_true - interval_width * 0.5  # Q10
>>> y_preds[:, 4] = y_true + interval_width * 0.5  # Q90
>>>
>>> # Generate the plot
>>> ax = plot_conditional_quantiles(
...     y_true,
...     y_preds,
...     quantiles,
...     bands=[80, 50], # Show 80% and 50% intervals
...     title="Conditional Uncertainty (Heteroscedasticity)"
... )