kdiagram.plot.probabilistic.plot_credibility_bands

kdiagram.plot.probabilistic.plot_credibility_bands(df, q_cols, theta_col, *, theta_period=None, theta_bins=24, acov='default', title='Forecast Credibility Bands', figsize=(8.0, 8.0), color='#3498DB', show_grid=True, grid_props=None, mask_radius=False, savefig=None, dpi=300, theta_ticks=None, theta_ticklabels=None, zero_at='N', clockwise=True, ax=None, **fill_kws)

Plots Polar Credibility Bands to visualize forecast uncertainty.

This function creates a polar plot that shows how the median forecast and the prediction interval bounds change as a function of another binned variable (e.g., month, hour). It is a descriptive tool for understanding the structure of a model’s predictions and its uncertainty estimates.

Parameters:

dfpd.DataFrame

The input DataFrame containing the forecast data.

q_colstuple of (str, str, str)

A tuple of three column names for the lower quantile, the median (Q50), and the upper quantile, in that order.

theta_colstr

The name of the column to bin against for the angular axis.

theta_periodfloat, optional

The period of the cyclical data in theta_col (e.g., 24 for hours, 12 for months). This ensures the data wraps correctly around the polar plot.

theta_binsint, default=24

The number of angular bins to group the data into.

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

‘eighth_circle’}, default=’default’ Angular coverage of the polar sector.

• 'default' : full circle, \(2\pi\) (360°)

• 'half_circle' : \(\pi\) (180°)

• 'quarter_circle' : \(\pi/2\) (90°)

• 'eighth_circle' : \(\pi/4\) (45°)

titlestr, default=”Forecast Credibility Bands”

The title for the plot.

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

The figure size in inches.

colorstr, default=”#3498DB”

The color for the shaded credibility 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_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.

**fill_kws

Additional keyword arguments passed to the ax.fill_between call for the shaded band (e.g., alpha).

Returns:

axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

• df (DataFrame)

• q_cols (tuple[str, str, str])

• theta_col (str)

• theta_period (float | None)

• theta_bins (int)

• acov (Literal['default', 'half_circle', 'quarter_circle', 'eighth_circle'])

• title (str)

• figsize (tuple[float, float])

• color (str)

• show_grid (bool)

• grid_props (dict[str, Any] | None)

• mask_radius (bool)

• savefig (str | None)

• dpi (int)

• theta_ticks (Sequence[float] | None)

• theta_ticklabels (Sequence[str] | Mapping[int, str] | None)

• zero_at (Literal['N', 'E', 'S', 'W'])

• clockwise (bool)

• ax (Axes | None)

Return type:

Axes | None

Notes

This plot visualizes the conditional expectation of the forecast quantiles. It is a novel visualization developed as part of the analytics framework in Kouadio[1].

1. Binning: The data is first partitioned into \(K\) bins, \(B_k\), based on the values in theta_col.

2. Conditional Means: For each bin \(B_k\), the mean of the lower quantile (\(\bar{q}_{low,k}\)), median quantile (\(\bar{q}_{med,k}\)), and upper quantile (\(\bar{q}_{up,k}\)) are calculated.

   (1)\[\bar{q}_{j,k} = \frac{1}{|B_k|} \sum_{i \in B_k} q_{j,i}\]

   where \(j \in \{\text{low, med, up}\}\).

3. Visualization: The plot displays:

   • A central line representing the mean median forecast (\(\bar{q}_{med,k}\)).

   • A shaded band between the mean lower and upper bounds (\(\bar{q}_{low,k}\) and \(\bar{q}_{up,k}\)). The width of this band represents the average forecast sharpness for that bin.

References

[1]

Kouao Laurent Kouadio. k-diagram: technical report — derivations and details. Technical Report, School of Geosciences and Info-physics, Central South University, Sep 2025. Software technical report accompanying the k-diagram package. URL: https://doi.org/10.5281/zenodo.17051183, doi:10.5281/zenodo.17051183.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from kdiagram.plot.probabilistic import plot_credibility_bands
>>>
>>> # Simulate a forecast with seasonal uncertainty
>>> np.random.seed(0)
>>> n_points = 500
>>> month = np.random.randint(1, 13, n_points)
>>> median = 50 + 20 * np.sin((month - 3) * np.pi / 6)
>>> width = 10 + 8 * np.cos(month * np.pi / 6)**2
>>>
>>> df = pd.DataFrame({
...     'month': month,
...     'q50': median + np.random.randn(n_points),
...     'q10': median - width / 2,
...     'q90': median + width / 2,
... })
>>>
>>> # Generate the plot
>>> ax = plot_credibility_bands(
...     df=df,
...     q_cols=('q10', 'q50', 'q90'),
...     theta_col='month',
...     theta_period=12,
...     theta_bins=12,
...     title="Seasonal Forecast Credibility"
... )