Skip to content

Contrast summaries and region evidence

hypothesis_summary analyzes a retained contrast tensor with shape (chain, draw, *event_shape). Construct derived contrasts within each draw: subtracting two retained coefficient tensors preserves their joint dependence. The function does not sample a guide, replay a model, parse an expression, or estimate a density at a point.

import math
import torch
from quivers.diagnostics import hypothesis_summary

contrast = torch.tensor([[-2., -1., 0., 0., 1., 2., 3., 4.]])
prior_contrast = torch.tensor([[-3., -2., -1., 0., 0., 0., 0., 1.]])
result = hypothesis_summary(contrast, prior=prior_contrast, kind="mcmc")
assert result.above.probability.item() == 0.5
assert result.equal_probability.item() == 0.25
assert result.above.log_odds.item() == 0.0
assert abs(result.above.log_bayes_factor.item() - math.log(7)) < 1e-12

Uncertainty and coordinates

The default estimate and est_error are the pooled mean and sample standard deviation, with divisor S - 1. Set robust=True for the median and normal-consistent median absolute deviation, that is, MAD divided by the standard normal's 0.75 quantile. probs selects linearly interpolated type-7 quantiles in the requested order; an empty sequence omits them. Summaries retain the contrast's original units: null sets the comparison boundary and is not subtracted from the summarized values. A single draw has undefined sample SD, reported as NaN; a constant multi-draw coordinate has zero SD.

Event axes remain separate. name, dims, and coords follow the shared retained-analysis coordinate policy. The result retains event dimension names and labels, chain and draw labels, and original sample counts. Prior draws may have different chain and draw counts, but must have exactly the same event shape and device. Construct the prior contrast jointly as well; independently permuting its parameter draws would change a dependent prior. The caller supplies kind; this records provenance without adding convergence diagnostics or correcting an approximate posterior.

Inputs are detached, finite real tensors. Boolean and integer draws use the shared Float64 conversion policy, including refusal of original integers outside the exact range before conversion. Retained QVR expressions preserve original Int and Bool inputs during checking and evaluation: count / 2 uses QVR integer division, and Boolean inputs remain predicates. The resulting numeric contrast is converted to Float64 for its summary. Posterior and prior inputs must have the same scalar carrier. Missing values are not deleted. Scaled arithmetic preserves finite extreme locations and small spreads; dispersion overflow causes an explicit error, while values below Float64 resolution may underflow to zero. Returned tensors remain on the original device. A tensor null must share that device and broadcast only over event axes, never across chain or draw axes.

Region odds and Bayes factors

below describes the strict region \(R_- = \{c < c_0\}\) and above the strict region \(R_+ = \{c > c_0\}\). Their complements include exact ties. Each record returns an empirical posterior probability and its natural-log odds. Thus these two odds are not generally reciprocals when ties occur. equal_probability reports the frequency of \(c=c_0\) separately.

With aligned prior contrasts, a region record also returns prior probability, prior log odds, and their difference:

\[ \log \widehat{\mathrm{BF}}_{R:R^c} = \log\frac{\widehat P(R\mid y)}{1-\widehat P(R\mid y)} - \log\frac{\widehat P(R)}{1-\widehat P(R)}. \]

This is an empirical encompassing-prior comparison. Its Bayes-factor interpretation requires a common proper prior restricted and renormalized to \(R\) and \(R^c\), with the same likelihood under both models. Both regions must have positive prior mass. Supplied draws must represent that prior and its corresponding posterior, including their hierarchical dependence. A variational posterior may introduce approximation error into the estimate. Posterior region odds alone are not a prior-corrected Bayes factor.

No pseudocounts are added. Empirical posterior probabilities zero and one produce negative and positive infinite log odds; these finite-sample results do not establish exact population probabilities. If the empirical prior probability is zero or one, log_bayes_factor is NaN. Such draws cannot estimate both restricted priors, even when the true prior assigns positive mass to both regions. Without prior draws, prior fields are None.

Exact equality is descriptive. Neither a continuous point null nor a comparison between an atom and a continuous alternative is inferred from an equality count. This API supplies no point-null density estimate, Savage–Dickey ratio, or posterior model probability; those require additional null-model and prior-compatibility assumptions.

Checked expressions over retained draws

PosteriorAnalysis.hypothesis evaluates a QVR value expression over its retained sites, then calls the same summary function. ContrastExpression maps expression aliases to original labels when a label is not a QVR identifier. The expression is checked once with QIEC and evaluated with chain and draw axes protected: sum(a) reduces an event axis rather than pooling samples. Named input event axes remain nominal; equal lengths alone do not make two axes interchangeable.

from quivers.diagnostics import ContrastExpression, PosteriorAnalysis

posterior = PosteriorAnalysis(
    samples={"condition[red]": torch.tensor([[0.2, 0.4, -0.1, 0.3]]),
             "baseline": torch.tensor([[0.1, 0.2, 0.0, 0.1]])},
    log_likelihood={},
    kind="variational",
)
expression = ContrastExpression(
    expression="exp(red)-baseline", bindings={"red": "condition[red]"}
)
contrast = posterior.hypothesis(expression, name="red effect")
assert contrast.sample_shape == (1, 4)
assert contrast.dimension_names == ()

Use dims={"a": ("Item",), "b": ("Item",)} to declare a shared event axis explicitly. Omitting dims assigns distinct site-specific axes; subtracting vectors on distinct axes fails at checking. coords supplies their original labels and optional chain/draw labels. A corresponding prior=other_analysis evaluates the same checked expression on its joint draw stream, with no parameter permutation. Different sample counts are allowed; event shapes and devices must match. These operations reuse retained tensors and do not refit a model.

An explicit point=PointNullSpec(...) request adds the existing marginal density comparison to result.point_evidence. It uses the same checked contrast and joint prior stream, with no extra expression compilation or inference replay. Known Int contrasts fail this continuous-density request before diagnostic conversion. A Real carrier alone does not establish continuity or a compatible null prior; those distributional assumptions remain explicit caller declarations.

contrast

Checked QVR expressions evaluated jointly over retained sample axes.

ContrastExpression didactic-model

ContrastExpression(*, expression: str, bindings: dict[str, str] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_VALUE))

Bases: ValueModel

One QVR value expression over jointly aligned retained variables.

PARAMETER DESCRIPTION
expression

Existing QVR arithmetic, functions, and event-axis indexing. Chain and draw axes are protected from indexing and reductions. Original Int and Bool carriers retain QVR integer arithmetic and predicate typing; conversion to diagnostic Float64 values follows expression evaluation.

TYPE: str

bindings

Optional expression aliases mapped to original variable labels. This permits labels such as condition[a] without changing their spelling. Unused aliases and unknown variables are errors.

TYPE: dict[str, str] DEFAULT: field(default_factory=dict, opaque=True, extras=OPAQUE_BY_VALUE)

hypothesis

Empirical contrast summaries and region evidence from aligned retained draws.

RegionEvidence didactic-model

RegionEvidence(*, probability: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), log_odds: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), prior_probability: Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), prior_log_odds: Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), log_bayes_factor: Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY))

Bases: ValueModel

Empirical evidence for a strict region against its complement.

PARAMETER DESCRIPTION
probability

Posterior region frequency and its natural-log odds. Zero and unit frequencies give negative and positive infinity, without pseudocounts.

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

log_odds

Posterior region frequency and its natural-log odds. Zero and unit frequencies give negative and positive infinity, without pseudocounts.

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

prior_probability

Corresponding frequencies and log odds from jointly aligned prior draws.

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

prior_log_odds

Corresponding frequencies and log odds from jointly aligned prior draws.

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

log_bayes_factor

Posterior minus prior log odds. NaN when the empirical prior region has probability zero or one: both restricted prior models cannot be formed. This empirical region comparison is not point-null density evidence.

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

HypothesisSummary didactic-model

HypothesisSummary(*, estimate: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), est_error: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), probs: tuple[float, ...], quantiles: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), null: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), below: RegionEvidence = field(opaque=True, extras=OPAQUE_BY_VALUE), above: RegionEvidence = field(opaque=True, extras=OPAQUE_BY_VALUE), equal_probability: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), prior_equal_probability: Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), name: str, dimension_names: tuple[str, ...], coordinate_labels: tuple[tuple[object, ...], ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), sample_shape: tuple[int, ...], prior_sample_shape: tuple[int, ...] | None = None, chain_labels: tuple[object, ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), draw_labels: tuple[object, ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), robust: bool, kind: Literal['mcmc', 'variational', 'prior', 'unspecified'], point_evidence: DensityRatio | None = field(default=None, opaque=True, extras=OPAQUE_BY_VALUE))

Bases: ValueModel

Uncertainty and strict-region evidence for an empirical contrast.

PARAMETER DESCRIPTION
estimate

Mean and sample standard deviation, or median and normal-consistent median absolute deviation when robust. These describe the supplied contrast in its original units, without subtracting the null.

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

est_error

Mean and sample standard deviation, or median and normal-consistent median absolute deviation when robust. These describe the supplied contrast in its original units, without subtracting the null.

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

probs

Requested type-7 quantile probabilities and values with a leading probability axis. Remaining axes are the original event coordinates.

TYPE: (tuple[float, ...], Tensor)

quantiles

Requested type-7 quantile probabilities and values with a leading probability axis. Remaining axes are the original event coordinates.

TYPE: (tuple[float, ...], Tensor)

null

Finite comparison value broadcast only across event coordinates.

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

below

Evidence for the strict regions contrast < null and contrast > null. Each complement includes exact ties.

TYPE: RegionEvidence DEFAULT: field(opaque=True, extras=OPAQUE_BY_VALUE)

above

Evidence for the strict regions contrast < null and contrast > null. Each complement includes exact ties.

TYPE: RegionEvidence DEFAULT: field(opaque=True, extras=OPAQUE_BY_VALUE)

equal_probability

Descriptive equality frequencies, without a point-null Bayes factor.

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

prior_equal_probability

Descriptive equality frequencies, without a point-null Bayes factor.

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

name

Original contrast name, named event axes, and their original labels.

TYPE: (str, tuple, tuple)

dimension_names

Original contrast name, named event axes, and their original labels.

TYPE: (str, tuple, tuple)

coordinate_labels

Original contrast name, named event axes, and their original labels.

TYPE: (str, tuple, tuple)

sample_shape

Original chain and draw counts; prior counts may differ.

TYPE: (tuple[int, ...], tuple[int, ...] or None)

prior_sample_shape

Original chain and draw counts; prior counts may differ.

TYPE: (tuple[int, ...], tuple[int, ...] or None)

chain_labels

Original posterior sample-axis labels or their positional defaults.

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

draw_labels

Original posterior sample-axis labels or their positional defaults.

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

robust

Whether location and dispersion use median and scaled MAD.

TYPE: bool

kind

Caller-supplied provenance; no convergence diagnostics are inferred.

TYPE: str

point_evidence

Optional marginal posterior/prior density comparison at the null, separate from strict-region evidence and descriptive equality frequency.

TYPE: DensityRatio or None DEFAULT: field(default=None, opaque=True, extras=OPAQUE_BY_VALUE)

hypothesis_summary

hypothesis_summary(contrast: Tensor, *, null: float | int | Tensor = 0.0, probs: Sequence[float] = (0.025, 0.975), prior: Tensor | None = None, robust: bool = False, point: PointNullSpec | None = None, name: str = 'contrast', kind: Literal['mcmc', 'variational', 'prior', 'unspecified'] = 'unspecified', dims: Sequence[str] | None = None, coords: Mapping[str, Sequence[object]] | None = None) -> HypothesisSummary

Summarize a retained contrast and evidence for each strict null region.

PARAMETER DESCRIPTION
contrast

Finite real draws shaped (chain, draw, *event_shape). Construct any derived contrast jointly within each retained draw before calling.

TYPE: Tensor

null

Finite null value, scalar or broadcastable over event axes only.

TYPE: float, int, or torch.Tensor DEFAULT: 0.0

probs

Quantile probabilities strictly between zero and one, in requested order.

TYPE: Sequence[float] DEFAULT: (0.025, 0.975)

prior

Joint prior contrast draws with the same event shape and device. Its chain and draw counts may differ. No permutation or inference is run.

TYPE: Tensor or None DEFAULT: None

robust

Return median and MAD divided by the standard-normal 0.75 quantile instead of mean and sample SD. Quantiles do not depend on this flag.

TYPE: bool DEFAULT: False

point

Explicit marginal point-density request. Requires finite continuous floating posterior and prior draws; the two strict regions are unchanged.

TYPE: PointNullSpec or None DEFAULT: None

name

Nonempty contrast name, retained without parsing.

TYPE: str DEFAULT: 'contrast'

kind

Explicit provenance of the supplied contrast draws.

TYPE: ('mcmc', 'variational', 'prior', 'unspecified') DEFAULT: "mcmc"

dims

Named event axes, using the shared retained-analysis coordinate policy.

TYPE: Sequence[str] or None DEFAULT: None

coords

Labels for event, chain, or draw axes; labels retain their original values.

TYPE: Mapping[str, Sequence[object]] or None DEFAULT: None

RETURNS DESCRIPTION
HypothesisSummary

Detached Float64 summaries on the original device. Equality frequencies are descriptive. Optional point_evidence retains the shared density estimator's bandwidths and assumption declarations, without inferring posterior model probabilities. Single-draw SD is NaN; constant SD is zero.

RAISES DESCRIPTION
(ValueError, TypeError)

If axes, alignment, domains, numeric capacity, or metadata disagree. Missing values are refused without deletion. Dispersion overflow is refused; values below Float64 resolution may underflow to zero.

Notes

A region Bayes factor compares a common proper encompassing prior restricted and renormalized to that region and its complement, under the same likelihood. Supplied prior draws must represent that prior jointly. A zero empirical prior region frequency makes this estimate undefined (NaN), even though the true prior might assign positive mass. No pseudocounts are added. A posterior zero frequency may instead produce infinite empirical log evidence; finite draws do not establish an exact population probability of zero.

Source code in src/quivers/diagnostics/hypothesis.py
def hypothesis_summary(
    contrast: torch.Tensor,
    *,
    null: float | int | torch.Tensor = 0.0,
    probs: Sequence[float] = (0.025, 0.975),
    prior: torch.Tensor | None = None,
    robust: bool = False,
    point: PointNullSpec | None = None,
    name: str = "contrast",
    kind: Literal["mcmc", "variational", "prior", "unspecified"] = "unspecified",
    dims: Sequence[str] | None = None,
    coords: Mapping[str, Sequence[object]] | None = None,
) -> HypothesisSummary:
    """Summarize a retained contrast and evidence for each strict null region.

    Parameters
    ----------
    contrast : torch.Tensor
        Finite real draws shaped ``(chain, draw, *event_shape)``. Construct any
        derived contrast jointly within each retained draw before calling.
    null : float, int, or torch.Tensor
        Finite null value, scalar or broadcastable over event axes only.
    probs : Sequence[float]
        Quantile probabilities strictly between zero and one, in requested order.
    prior : torch.Tensor or None
        Joint prior contrast draws with the same event shape and device. Its
        chain and draw counts may differ. No permutation or inference is run.
    robust : bool
        Return median and MAD divided by the standard-normal 0.75 quantile
        instead of mean and sample SD. Quantiles do not depend on this flag.
    point : PointNullSpec or None
        Explicit marginal point-density request. Requires finite continuous
        floating posterior and prior draws; the two strict regions are unchanged.
    name : str
        Nonempty contrast name, retained without parsing.
    kind : {"mcmc", "variational", "prior", "unspecified"}
        Explicit provenance of the supplied contrast draws.
    dims : Sequence[str] or None
        Named event axes, using the shared retained-analysis coordinate policy.
    coords : Mapping[str, Sequence[object]] or None
        Labels for event, chain, or draw axes; labels retain their original values.

    Returns
    -------
    HypothesisSummary
        Detached Float64 summaries on the original device. Equality frequencies
        are descriptive. Optional point_evidence retains the shared density
        estimator's bandwidths and assumption declarations, without inferring
        posterior model probabilities. Single-draw SD is NaN; constant SD is zero.

    Raises
    ------
    ValueError, TypeError
        If axes, alignment, domains, numeric capacity, or metadata disagree.
        Missing values are refused without deletion. Dispersion overflow is refused;
        values below Float64 resolution may underflow to zero.

    Notes
    -----
    A region Bayes factor compares a common proper encompassing prior restricted
    and renormalized to that region and its complement, under the same likelihood.
    Supplied prior draws must represent that prior jointly. A zero empirical
    prior region frequency makes this estimate undefined (NaN), even though the
    true prior might assign positive mass. No pseudocounts are added. A posterior
    zero frequency may instead produce infinite empirical log evidence; finite
    draws do not establish an exact population probability of zero.
    """
    if point is not None and not isinstance(point, PointNullSpec):
        raise TypeError("point must be PointNullSpec or None")
    if point is not None and prior is None:
        raise ValueError("point-density evidence requires joint prior draws")
    values = _contrasts(contrast, "contrast")
    levels = probabilities(probs)
    if not isinstance(robust, bool):
        raise TypeError("robust must be Boolean")
    if not isinstance(name, str) or not name:
        raise ValueError("contrast name must be a nonempty string")
    if kind not in {"mcmc", "variational", "prior", "unspecified"}:
        raise ValueError("contrast kind must identify its draw provenance")
    cutoff = _null_value(null, values)
    prior_values = None
    if prior is not None:
        prior_values = _contrasts(prior, "prior contrast")
        if prior_values.device != values.device:
            raise ValueError("prior and posterior contrasts must use the same device")
        if prior_values.shape[1:] != values.shape[1:]:
            raise ValueError(
                "prior and posterior contrasts require the same event shape"
            )
    dimension_names = event_dimensions(
        {name: values.shape[1:]},
        dims={name: dims} if dims is not None else None,
        coords=coords,
    )[name]
    estimate, dispersion, quantiles = empirical_summary(values, levels, robust=robust)
    if bool(torch.isinf(dispersion).any()):
        raise ValueError("contrast dispersion exceeds Float64 capacity")
    return HypothesisSummary(
        estimate=estimate,
        est_error=dispersion,
        probs=levels,
        quantiles=quantiles,
        null=cutoff,
        below=_region(
            values < cutoff, prior_values < cutoff if prior_values is not None else None
        ),
        above=_region(
            values > cutoff, prior_values > cutoff if prior_values is not None else None
        ),
        equal_probability=(values == cutoff).to(torch.float64).mean(0),
        prior_equal_probability=(prior_values == cutoff).to(torch.float64).mean(0)
        if prior_values is not None
        else None,
        name=name,
        dimension_names=dimension_names,
        coordinate_labels=tuple(
            axis_labels(dimension, extent, coords)
            for dimension, extent in zip(dimension_names, values.shape[1:], strict=True)
        ),
        sample_shape=tuple(contrast.shape[:2]),
        prior_sample_shape=tuple(prior.shape[:2]) if prior is not None else None,
        chain_labels=axis_labels("chain", contrast.shape[0], coords),
        draw_labels=axis_labels("draw", contrast.shape[1], coords),
        robust=robust,
        kind=kind,
        point_evidence=(
            density_ratio(
                contrast,
                prior,
                null=null,
                bandwidth=point.bandwidth,
                prior_bandwidth=point.prior_bandwidth,
                adjust=point.adjust,
                assumptions=point.assumptions,
                name=name,
                dims=dimension_names,
                coords=coords,
                max_working_elements=point.max_working_elements,
            )
            if point is not None and prior is not None
            else None
        ),
    )