Skip to content

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 a ConvergenceSummary.

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 rhat only, 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

EssMethod = Literal['bulk', 'tail', 'mean', 'sd', 'quantile']

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

McseMethod = Literal['mean', 'sd', 'quantile']

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: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

sd

Posterior standard deviation over all chains and draws (one degree of freedom subtracted); NaN for a coordinate with any nonfinite draw.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

probs

The probabilities at which quantiles are taken.

TYPE: tuple[float, ...]

quantiles

Posterior quantiles at probs (linear interpolation between order statistics of the pooled draws); NaN for a coordinate with a non-finite draw.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

r_hat

Rank-normalized split :math:\hat R (see rhat).

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

ess_bulk

Bulk effective sample size (see ess).

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

ess_tail

Tail effective sample size at the 5% and 95% quantiles.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

mcse_mean

Monte Carlo standard error of the mean.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

mcse_sd

Monte Carlo standard error of the standard deviation.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

mcse_quantiles

Monte Carlo standard error of each quantile in quantiles.

TYPE: Tensor DEFAULT: field(opaque=True, extras=OPAQUE_BY_IDENTITY)

rhat

rhat(draws: Tensor) -> Tensor

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 (num_chains, num_draws, *event_shape).

TYPE: Tensor

RETURNS DESCRIPTION
Tensor

Float64 tensor of shape event_shape on draws.device. NaN for a coordinate with fewer than two chains, fewer than four draws per chain, a non-finite draw, or a constant value. inf when each split chain is constant but the chains differ.

RAISES DESCRIPTION
TypeError

If draws is not a real tensor.

ValueError

If draws has fewer than two axes, or no chains or draws.

Source code in src/quivers/diagnostics/convergence.py
def rhat(draws: torch.Tensor) -> torch.Tensor:
    """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.

    Parameters
    ----------
    draws : torch.Tensor
        Draws laid out ``(num_chains, num_draws, *event_shape)``.

    Returns
    -------
    torch.Tensor
        Float64 tensor of shape ``event_shape`` on ``draws.device``.
        NaN for a coordinate with fewer than two chains, fewer than
        four draws per chain, a non-finite draw, or a constant value.
        ``inf`` when each split chain is constant but the chains
        differ.

    Raises
    ------
    TypeError
        If ``draws`` is not a real tensor.
    ValueError
        If ``draws`` has fewer than two axes, or no chains or draws.
    """
    return _per_coordinate(draws, _rank_rhat, min_chains=2)

ess

ess(draws: Tensor, *, method: EssMethod = 'bulk', prob: float | None = None) -> Tensor

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 at prob and 1 - prob (prob defaults 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 the prob quantile; prob is required.
PARAMETER DESCRIPTION
draws

Draws laid out (num_chains, num_draws, *event_shape).

TYPE: Tensor

method

Which effective sample size to compute.

TYPE: EssMethod DEFAULT: 'bulk'

prob

The tail probability for "tail" (default 0.05) or the quantile's probability for "quantile" (required). Must be None for the other methods.

TYPE: float or None DEFAULT: None

RETURNS DESCRIPTION
Tensor

Float64 tensor of shape event_shape on draws.device. NaN for a coordinate with fewer than four draws per chain, a non-finite draw, or a constant value.

RAISES DESCRIPTION
TypeError

If draws is not a real tensor.

ValueError

If draws has fewer than two axes or no chains or draws, if method is unknown, or if prob is missing, out of (0, 1), or given to a method that takes none.

Source code in src/quivers/diagnostics/convergence.py
def ess(
    draws: torch.Tensor,
    *,
    method: EssMethod = "bulk",
    prob: float | None = None,
) -> torch.Tensor:
    """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 at ``prob``
      and ``1 - prob`` (``prob`` defaults 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 the
      ``prob`` quantile; ``prob`` is required.

    Parameters
    ----------
    draws : torch.Tensor
        Draws laid out ``(num_chains, num_draws, *event_shape)``.
    method : EssMethod
        Which effective sample size to compute.
    prob : float or None
        The tail probability for ``"tail"`` (default 0.05) or the
        quantile's probability for ``"quantile"`` (required). Must be
        ``None`` for the other methods.

    Returns
    -------
    torch.Tensor
        Float64 tensor of shape ``event_shape`` on ``draws.device``.
        NaN for a coordinate with fewer than four draws per chain, a
        non-finite draw, or a constant value.

    Raises
    ------
    TypeError
        If ``draws`` is not a real tensor.
    ValueError
        If ``draws`` has fewer than two axes or no chains or draws, if
        ``method`` is unknown, or if ``prob`` is missing, out of
        ``(0, 1)``, or given to a method that takes none.
    """
    statistic: Callable[[torch.Tensor], float]
    if method == "tail":
        tail_prob = _check_prob(_DEFAULT_TAIL_PROB if prob is None else prob, "prob")
        statistic = partial(_ess_tail, prob=tail_prob)
    elif method == "quantile":
        if prob is None:
            raise ValueError('ess(method="quantile") requires prob')
        statistic = partial(_ess_quantile, prob=_check_prob(prob, "prob"))
    elif method in ("bulk", "mean", "sd"):
        if prob is not None:
            raise ValueError(f'ess(method="{method}") takes no prob')
        statistic = {"bulk": _ess_bulk, "mean": _ess_mean, "sd": _ess_sd}[method]
    else:
        raise ValueError(
            f"unknown ESS method {method!r}; expected one of "
            "'bulk', 'tail', 'mean', 'sd', 'quantile'"
        )
    return _per_coordinate(draws, statistic, min_chains=1)

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); prob is required.
PARAMETER DESCRIPTION
draws

Draws laid out (num_chains, num_draws, *event_shape).

TYPE: Tensor

method

Which summary's standard error to compute.

TYPE: McseMethod DEFAULT: 'mean'

prob

The quantile's probability for "quantile" (required). Must be None for the other methods.

TYPE: float or None DEFAULT: None

RETURNS DESCRIPTION
Tensor

Float64 tensor of shape event_shape on draws.device. NaN for a coordinate with fewer than four draws per chain, a non-finite draw, or a constant value.

RAISES DESCRIPTION
TypeError

If draws is not a real tensor.

ValueError

If draws has fewer than two axes or no chains or draws, if method is unknown, or if prob is missing, out of (0, 1), or given to a method that takes none.

Source code in src/quivers/diagnostics/convergence.py
def mcse(
    draws: torch.Tensor,
    *,
    method: McseMethod = "mean",
    prob: float | None = None,
) -> torch.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); ``prob`` is required.

    Parameters
    ----------
    draws : torch.Tensor
        Draws laid out ``(num_chains, num_draws, *event_shape)``.
    method : McseMethod
        Which summary's standard error to compute.
    prob : float or None
        The quantile's probability for ``"quantile"`` (required).
        Must be ``None`` for the other methods.

    Returns
    -------
    torch.Tensor
        Float64 tensor of shape ``event_shape`` on ``draws.device``.
        NaN for a coordinate with fewer than four draws per chain, a
        non-finite draw, or a constant value.

    Raises
    ------
    TypeError
        If ``draws`` is not a real tensor.
    ValueError
        If ``draws`` has fewer than two axes or no chains or draws, if
        ``method`` is unknown, or if ``prob`` is missing, out of
        ``(0, 1)``, or given to a method that takes none.
    """
    statistic: Callable[[torch.Tensor], float]
    if method == "quantile":
        if prob is None:
            raise ValueError('mcse(method="quantile") requires prob')
        statistic = partial(_mcse_quantile, prob=_check_prob(prob, "prob"))
    elif method in ("mean", "sd"):
        if prob is not None:
            raise ValueError(f'mcse(method="{method}") takes no prob')
        statistic = {"mean": _mcse_mean, "sd": _mcse_sd}[method]
    else:
        raise ValueError(
            f"unknown MCSE method {method!r}; expected one of 'mean', 'sd', 'quantile'"
        )
    return _per_coordinate(draws, statistic, min_chains=1)

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 (num_chains, num_draws, *event_shape), such as quivers.inference.MCMCResult.samples.

TYPE: Mapping[str, Tensor]

probs

Probabilities of the quantiles to report, each in (0, 1).

TYPE: Sequence[float] DEFAULT: (0.05, 0.5, 0.95)

RETURNS DESCRIPTION
dict[str, ConvergenceSummary]

One summary per site, in the order of samples.

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 (0, 1), or an original integer exceeds exact Float64 capacity.

Source code in src/quivers/diagnostics/convergence.py
def summary(
    samples: Mapping[str, torch.Tensor],
    *,
    probs: Sequence[float] = (0.05, 0.5, 0.95),
) -> dict[str, ConvergenceSummary]:
    """Posterior summaries and convergence diagnostics for every site.

    Parameters
    ----------
    samples : Mapping[str, torch.Tensor]
        Per-site draws, each laid out
        ``(num_chains, num_draws, *event_shape)``, such as
        `quivers.inference.MCMCResult.samples`.
    probs : Sequence[float]
        Probabilities of the quantiles to report, each in ``(0, 1)``.

    Returns
    -------
    dict[str, ConvergenceSummary]
        One summary per site, in the order of ``samples``.

    Raises
    ------
    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 ``(0, 1)``, or an original
        integer exceeds exact Float64 capacity.
    """
    levels = tuple(_check_prob(p, "probs") for p in probs)
    summaries: dict[str, ConvergenceSummary] = {}
    for name, draws in samples.items():
        pooled = _as_chains(draws)
        event_shape = draws.shape[2:]
        mean, sd, quantiles = empirical_summary(
            pooled.reshape(-1, pooled.shape[2]), levels
        )
        mcse_rows = [mcse(draws, method="quantile", prob=p) for p in levels]
        summaries[name] = ConvergenceSummary(
            mean=mean.reshape(event_shape).to(device=draws.device),
            sd=sd.reshape(event_shape).to(device=draws.device),
            probs=levels,
            quantiles=quantiles.reshape(len(levels), *event_shape).to(
                device=draws.device
            ),
            r_hat=rhat(draws),
            ess_bulk=ess(draws, method="bulk"),
            ess_tail=ess(draws, method="tail"),
            mcse_mean=mcse(draws, method="mean"),
            mcse_sd=mcse(draws, method="sd"),
            mcse_quantiles=(
                torch.stack(mcse_rows)
                if mcse_rows
                else torch.empty((0, *event_shape), dtype=torch.float64)
            ).to(device=draws.device),
        )
    return summaries

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.