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:
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:
|
bindings
|
Optional expression aliases mapped to original variable labels. This
permits labels such as
TYPE:
|
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:
|
log_odds
|
Posterior region frequency and its natural-log odds. Zero and unit frequencies give negative and positive infinity, without pseudocounts.
TYPE:
|
prior_probability
|
Corresponding frequencies and log odds from jointly aligned prior draws.
TYPE:
|
prior_log_odds
|
Corresponding frequencies and log odds from jointly aligned prior draws.
TYPE:
|
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:
|
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
TYPE:
|
est_error
|
Mean and sample standard deviation, or median and normal-consistent
median absolute deviation when
TYPE:
|
probs
|
Requested type-7 quantile probabilities and values with a leading probability axis. Remaining axes are the original event coordinates.
TYPE:
|
quantiles
|
Requested type-7 quantile probabilities and values with a leading probability axis. Remaining axes are the original event coordinates.
TYPE:
|
null
|
Finite comparison value broadcast only across event coordinates.
TYPE:
|
below
|
Evidence for the strict regions
TYPE:
|
above
|
Evidence for the strict regions
TYPE:
|
equal_probability
|
Descriptive equality frequencies, without a point-null Bayes factor.
TYPE:
|
prior_equal_probability
|
Descriptive equality frequencies, without a point-null Bayes factor.
TYPE:
|
name
|
Original contrast name, named event axes, and their original labels.
TYPE:
|
dimension_names
|
Original contrast name, named event axes, and their original labels.
TYPE:
|
coordinate_labels
|
Original contrast name, named event axes, and their original labels.
TYPE:
|
sample_shape
|
Original chain and draw counts; prior counts may differ.
TYPE:
|
prior_sample_shape
|
Original chain and draw counts; prior counts may differ.
TYPE:
|
chain_labels
|
Original posterior sample-axis labels or their positional defaults.
TYPE:
|
draw_labels
|
Original posterior sample-axis labels or their positional defaults.
TYPE:
|
robust
|
Whether location and dispersion use median and scaled MAD.
TYPE:
|
kind
|
Caller-supplied provenance; no convergence diagnostics are inferred.
TYPE:
|
point_evidence
|
Optional marginal posterior/prior density comparison at the null, separate from strict-region evidence and descriptive equality frequency.
TYPE:
|
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
TYPE:
|
null
|
Finite null value, scalar or broadcastable over event axes only.
TYPE:
|
probs
|
Quantile probabilities strictly between zero and one, in requested order.
TYPE:
|
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:
|
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:
|
point
|
Explicit marginal point-density request. Requires finite continuous floating posterior and prior draws; the two strict regions are unchanged.
TYPE:
|
name
|
Nonempty contrast name, retained without parsing.
TYPE:
|
kind
|
Explicit provenance of the supplied contrast draws.
TYPE:
|
dims
|
Named event axes, using the shared retained-analysis coordinate policy.
TYPE:
|
coords
|
Labels for event, chain, or draw axes; labels retain their original values.
TYPE:
|
| 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
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 | |