quivers.diagnostics.convergence¶
These estimators assess whether Markov chains have mixed
and how precisely their draws estimate posterior summaries. They take any tensor laid out
(num_chains, num_draws, *event_shape), so a derived quantity or the output of a hand-written
sampling loop is diagnosed with the same estimators that
MCMCResult reports. Rank-normalized split
R-hat,
bulk and tail effective sample size,
and the Monte Carlo standard errors of the mean, standard deviation, and quantiles follow
Vehtari et al. (Vehtari et al., 2021). The module needs only PyTorch, and its tests check it against ArviZ.
convergence
¶
Convergence diagnostics for chain-by-draw tensors.
The functions here take draws laid out (num_chains, num_draws,
*event_shape) and return one value per event coordinate, with shape
event_shape. They implement the estimators of Vehtari, Gelman,
Simpson, Carpenter, and Bürkner (2021,
doi:10.1214/20-BA1221 <https://doi.org/10.1214/20-BA1221>_):
rhat: rank-normalized split :math:\hat R, reported as the maximum of the bulk (rank-normalized) and tail (folded, rank-normalized) statistics.ess: effective sample size for the bulk (rank-normalized split chains), the tails (the smaller of the 5% and 95% quantile ESS by default), the mean, the standard deviation, or one quantile.mcse: Monte Carlo standard error of the mean, the standard deviation, or one quantile.summary: every diagnostic above for each site of a mapping of draws, as aConvergenceSummary.
Autocorrelations pool the chains and include the between-chain variance, and the effective sample size truncates the autocorrelation sum with Geyer's initial monotone sequence. R-hat, ESS, and mean and quantile MCSE follow ArviZ's definitions on finite, non-constant input. SD-MCSE uses the fourth central moment and the ESS of squared deviations.
The module needs only torch. quivers.inference.MCMCResult computes
its r_hat, ess, and ess_tail through these functions, so
diagnostics of derived quantities and of draws from custom sampling
loops are directly comparable with the diagnostics a run reports.
Degenerate coordinates return NaN rather than a number that would read as a valid diagnostic:
- a coordinate with any non-finite value (NaN or infinite);
- a coordinate with fewer than four draws per chain;
- a constant coordinate, whose largest and smallest draws differ by
less than the float64 resolution (
1e-15); a chain stuck at one value has no estimable mixing, so its effective sample size is NaN rather than the total draw count ArviZ reports; - for
rhatonly, fewer than two chains.
The diagnostics are not differentiable: draws are detached and computed in float64 on the CPU, and results return on the input's device as float64.
EssMethod
module-attribute
¶
The quantity an effective sample size refers to: "bulk"
(rank-normalized split chains, for location summaries), "tail"
(the smaller of two tail-quantile ESS values), "mean" (the
unnormalized split chains), "sd" (the squared deviations from the
mean), or "quantile" (the indicator of falling at or below one
quantile).
McseMethod
module-attribute
¶
The posterior summary a Monte Carlo standard error refers to: the
"mean", the standard deviation ("sd"), or one "quantile".
ConvergenceSummary
didactic-model
¶
ConvergenceSummary(*, mean: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), sd: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), probs: tuple[float, ...], quantiles: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), r_hat: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), ess_bulk: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), ess_tail: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), mcse_mean: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), mcse_sd: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), mcse_quantiles: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Posterior summaries and convergence diagnostics for one site.
Every tensor field except quantiles and mcse_quantiles has
the site's event shape (the shape after the chain and draw axes);
those two have shape (len(probs), *event_shape). All are
float64.
| PARAMETER | DESCRIPTION |
|---|---|
mean
|
Posterior mean over all chains and draws; NaN for a coordinate with any nonfinite draw.
TYPE:
|
sd
|
Posterior standard deviation over all chains and draws (one degree of freedom subtracted); NaN for a coordinate with any nonfinite draw.
TYPE:
|
probs
|
The probabilities at which
TYPE:
|
quantiles
|
Posterior quantiles at
TYPE:
|
r_hat
|
Rank-normalized split :math:
TYPE:
|
ess_bulk
|
Bulk effective sample size (see
TYPE:
|
ess_tail
|
Tail effective sample size at the 5% and 95% quantiles.
TYPE:
|
mcse_mean
|
Monte Carlo standard error of the mean.
TYPE:
|
mcse_sd
|
Monte Carlo standard error of the standard deviation.
TYPE:
|
mcse_quantiles
|
Monte Carlo standard error of each quantile in
TYPE:
|
rhat
¶
Rank-normalized split :math:\hat R per event coordinate.
Each chain is split in half (the middle draw is dropped when the draw count is odd), the pooled draws are replaced by the normal scores of their average ranks, and the potential scale reduction factor is computed for those scores (the bulk statistic) and for the scores of the absolute deviations from the median (the tail statistic). The reported value is the larger of the two, following Vehtari et al. (2021). Values near 1 are consistent with the chains sampling one distribution; the authors suggest 1.01 as a threshold.
| PARAMETER | DESCRIPTION |
|---|---|
draws
|
Draws laid out
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
Float64 tensor of shape |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If |
ValueError
|
If |
Source code in src/quivers/diagnostics/convergence.py
ess
¶
Effective sample size per event coordinate.
All methods split each chain in half and pool the autocorrelations across chains (Vehtari et al., 2021):
"bulk": ESS of the rank-normalized draws, the measure for location summaries such as the mean and median."tail": the smaller of the"quantile"ESS atproband1 - prob(probdefaults to 0.05, giving the 5% and 95% quantiles), the measure for interval endpoints."mean": ESS of the untransformed draws."sd": ESS of the squared deviations from the mean."quantile": ESS of the indicator of falling at or below theprobquantile;probis required.
| PARAMETER | DESCRIPTION |
|---|---|
draws
|
Draws laid out
TYPE:
|
method
|
Which effective sample size to compute.
TYPE:
|
prob
|
The tail probability for
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
Float64 tensor of shape |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If |
ValueError
|
If |
Source code in src/quivers/diagnostics/convergence.py
mcse
¶
mcse(draws: Tensor, *, method: McseMethod = 'mean', prob: float | None = None) -> Tensor
Monte Carlo standard error per event coordinate.
"mean": the posterior standard deviation over the square root of the"mean"ESS."sd": the delta-method error of the standard deviation, from the fourth central moment and the ESS of the squared deviations."quantile": half the distance between the order statistics at the central one-sd interval of the beta distribution that the quantile's ESS implies for its probability level (Vehtari et al., 2021);probis required.
| PARAMETER | DESCRIPTION |
|---|---|
draws
|
Draws laid out
TYPE:
|
method
|
Which summary's standard error to compute.
TYPE:
|
prob
|
The quantile's probability for
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
Float64 tensor of shape |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If |
ValueError
|
If |
Source code in src/quivers/diagnostics/convergence.py
summary
¶
summary(samples: Mapping[str, Tensor], *, probs: Sequence[float] = (0.05, 0.5, 0.95)) -> dict[str, ConvergenceSummary]
Posterior summaries and convergence diagnostics for every site.
| PARAMETER | DESCRIPTION |
|---|---|
samples
|
Per-site draws, each laid out
TYPE:
|
probs
|
Probabilities of the quantiles to report, each in
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, ConvergenceSummary]
|
One summary per site, in the order of |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If a site's draws are not a real tensor. |
ValueError
|
If a site's draws have fewer than two axes or no chains or
draws, a probability lies outside |
Source code in src/quivers/diagnostics/convergence.py
Cited sources¶
Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner. Rank-Normalization, Folding, and Localization: An Improved R-hat for Assessing Convergence of MCMC (with Discussion). Bayesian Analysis, 16(2):667–718, 2021. URL: https://doi.org/10.1214/20-BA1221, doi:10.1214/20-BA1221.