kdiagram.plot.probabilistic.plot_pit_histogram

kdiagram.plot.probabilistic.plot_pit_histogram(y_true, y_preds_quantiles, quantiles, *, acov='default', n_bins=10, title='PIT Histogram', figsize=(8, 8), color='#3498DB', edgecolor='black', alpha=0.7, show_uniform_line=True, show_grid=True, grid_props=None, mask_radius=False, savefig=None, dpi=300, ax=None)[source]

Plots a Polar Probability Integral Transform (PIT) Histogram.

This function creates a polar bar chart of PIT values to diagnose the calibration of a probabilistic forecast. For a perfectly calibrated forecast, the PIT histogram is uniform, which results in a perfect circle on the polar plot. Deviations from this shape indicate specific model biases.

Parameters:
y_truenp.ndarray

1D array of observed (true) values.

y_preds_quantilesnp.ndarray

2D array of quantile forecasts. Each row corresponds to an observation in y_true, and each column is a specific quantile forecast.

quantilesnp.ndarray

1D array of the quantile levels corresponding to the columns of y_preds_quantiles (e.g., [0.05, 0.1, ..., 0.95]).

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°)

n_binsint, default=10

Number of bins for the histogram, which will correspond to the angular sectors in the polar plot.

titlestr, default=”PIT Histogram”

The title for the plot.

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

The figure size in inches.

colorstr, default=”#3498DB”

The fill color for the histogram bars.

edgecolorstr, default=”black”

The edge color for the histogram bars.

alphafloat, default=0.7

The transparency of the histogram bars.

show_uniform_linebool, default=True

If True, draws a reference circle indicating the expected frequency for a perfectly uniform (calibrated) distribution.

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.

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:
Return type:

Axes

Notes

The Probability Integral Transform (PIT) is a fundamental tool for evaluating the calibration of probabilistic forecasts [1]. For a continuous predictive distribution with CDF \(F\), the PIT value for an observation \(y\) is \(F(y)\). If the forecast is perfectly calibrated, the PIT values are uniformly distributed on \([0, 1]\).

When the predictive CDF is represented by a finite set of \(M\) quantiles, the PIT value for each observation \(y_i\) is approximated as the fraction of forecast quantiles that are less than or equal to the observation:

(1)\[\text{PIT}_i = \frac{1}{M} \sum_{j=1}^{M} \mathbf{1}\{q_{i,j} \le y_i\}\]

where \(q_{i,j}\) is the \(j\)-th quantile forecast for observation \(i\), and \(\mathbf{1}\) is the indicator function.

Deviations from a uniform (flat) histogram indicate miscalibration: - U-shaped: The forecast is overconfident (too narrow). - Hump-shaped: The forecast is underconfident (too wide). - Sloped: The forecast is biased.

References

Examples

>>> import numpy as np
>>> from scipy.stats import norm
>>> from kdiagram.plot.probabilistic import plot_pit_histogram
>>>
>>> # Generate synthetic data
>>> np.random.seed(42)
>>> n_samples = 1000
>>> y_true = np.random.normal(loc=10, scale=5, size=n_samples)
>>> quantiles = np.linspace(0.05, 0.95, 19)
>>>
>>> # A well-calibrated forecast
>>> calibrated_preds = norm.ppf(
...     quantiles, loc=y_true[:, np.newaxis], scale=5
... )
>>>
>>> # Generate the plot
>>> ax = plot_pit_histogram(
...     y_true,
...     calibrated_preds,
...     quantiles,
...     title="PIT Histogram (Well-Calibrated Model)"
... )