torchcell.losses.distributional.pit_values

pit_values(mode: str, target: Tensor, mu: Tensor | None = None, scale: Tensor | None = None, quantiles: Tensor | None = None, taus: Tensor | None = None, samples: Tensor | None = None) → Tensor[source]

Probability integral transform – ONE calibration diagnostic for every mode.

\[\mathrm{PIT}_{s,f} = \hat F_{s,f}(y_{s,f}) \in [0,1],\]

the predictive CDF of instance s, feature f, evaluated at its own observation. Its whole point is mode-independence: a Gaussian CRPS head, a quantile head and a sample-based energy head all produce PIT values on the same [0, 1] scale, so calibration can be compared ACROSS the distributional sweep even though the losses are not comparable to each other.

Per mode:

  • gaussian / nll_gaussian: \(\Phi\!\big((y-\mu)/\sigma\big)\);

  • laplace: the Laplace CDF at y;

  • quantile: the empirical CDF interpolated through the K knots (see _quantile_pit());

  • energy: \(\frac1m\sum_i \mathbf 1[x_{i,f}\le y_f]\) from predictive samples (per feature – the MARGINAL calibration of a joint model).

If the predictive distribution is correct then PIT ~ Uniform(0, 1). Read the histogram shape as a diagnosis:

  • flat – calibrated;

  • U-shaped (mass piled at 0 and 1) – too many observations land in the tails, so the intervals are too NARROW: OVERCONFIDENT / under-dispersed;

  • n-shaped (hump at 0.5) – observations cluster near the predictive median, so the intervals are too WIDE: UNDERCONFIDENT / over-dispersed. This is the signature of NLL sigma-collapse (see gaussian_nll());

  • skewed / shifted (mass toward 0 or toward 1) – the location is biased, i.e. the predicted mean is systematically high or low.

Parameters:

  • mode – A DistHead mode. point has no predictive distribution and is rejected.

  • target – Observations [..., F].

  • mu – gaussian / nll_gaussian / laplace – predicted location [..., F].

  • scale – gaussian / nll_gaussian – sigma; laplace – b. Already positive (this function does NOT apply the softplus; pass DistHead- transformed values, e.g. via DistHead.pit()).

  • quantiles – quantile – predicted quantiles [..., F, K].

  • taus – quantile – the levels [K].

  • samples – energy – predictive samples [..., m, F].

Returns:

PIT values [..., F] in [0, 1].