Shared posterior analysis¶
ModelFit.analysis and BayesianFit.analysis produce the same
PosteriorAnalysis: constrained posterior draws, raw observation likelihoods,
observed responses, and recorded sampler statistics. A request samples a
variational guide once; later methods reuse the retained tensors. Tensor mappings
are held by identity, so callers own their storage.
summary returns means, sample standard deviations, and requested quantiles on
each latent site's event coordinates. Recorded MCMC chains also supply a
ConvergenceSummary; variational draws supply None. Their one pseudo-chain
records array shape, without asserting MCMC convergence. Original integer
capacity is checked before Float64 conversion. A coordinate containing a
nonfinite draw has NaN mean, SD, and quantiles; draws are not deleted, and
valid coordinates remain independent of that failure. The same scaled
arithmetic and type-7 quantile kernel serve recorded-chain and retained
uncertainty summaries.
A source program with no latent sites can still supply observation likelihoods. Its recorded posterior count determines the chain/draw layout; the checked registry must establish that no unobserved variable is missing. Such an analysis has an empty parameter summary, while raw likelihoods, WAIC, and LOO remain available. No placeholder parameter or convergence statistic is introduced. Covariance and contrast requests still require their selected parameter values.
Joint covariance and correlation¶
analysis.covariance(var_names=None, ddof=1) returns a PosteriorCovariance
containing both empirical covariance and Pearson correlation. It pools chain
and draw axes by default; chainwise=True returns one matrix per retained
chain axis. The divisor is the reduced sample count minus ddof, which must be a
nonnegative integer smaller than that count. No convergence diagnostic is
implied by either matrix.
Selected variables retain their requested order. Each event flattens in
row-major order, while coordinates retains each exact (site, index_tuple);
variables, event_shapes, and sample_shape retain the original layout.
Pass dims and coords as for to_datatree: the same validator checks named
axis extents and label lengths. dimension_names and coordinate_labels
identify each matrix column without parsing a rendered name. Chain and draw
labels remain available even when those axes were reduced.
These summaries use retained tensors and one joint Float64 matrix, without resampling or likelihood evaluation. Boolean and integer prior draws are numeric inputs; original integers outside the exact Float64 range are refused before conversion. Coordinate labels retain their original values. Missing and nonfinite draws are refused, without pairwise deletion. A constant coordinate has zero covariance and NaN correlations with every coordinate, including itself. Mathematical covariances below Float64 resolution may underflow; correlations are computed from scaled coordinates independently of that underflow. Unrepresentable covariance magnitudes cause an explicit error. Tensor mappings and returned tensor storage remain caller-owned.
Observation units and predictive scores¶
Log-likelihood tensors have shape (chain, draw, *observation_shape), after
reducing event coordinates. They contain raw conditional densities, excluding
priors and likelihood weights. Multiple responses require an explicit var_name;
combining their scores requires a justified common predictive unit. An observation
hidden inside exact marginalization requires a corresponding likelihood observer.
waic needs only PyTorch and at least two pooled posterior draws with finite
scores. It uses unbiased sample log-score variances, with divisor S - 1,
matching the loo implementation.
WAICResult exposes elpd_waic, effective parameter estimate p_waic, and
waic = -2 * elpd_waic. se is the standard error on the ELPD scale;
se_waic is twice that value, and se_p_waic describes the effective parameter
estimate. These standard errors are undefined for one observation unit.
elpd_i, variance_i, and waic_i retain the observation axes.
A pointwise log-score variance above 0.4 sets warning, following the
loo diagnostic.
to_datatree and loo require the optional diagnostics extra. The DataTree
retains chain and draw axes and records quivers_posterior_kind in its attributes.
Pass coords={"row": [...]} and dims={"y": ["row"]} to label observation
axes, or assign event-axis labels to latent variables. The shared converter
uses the same sampler-statistic names and integer/Boolean dtypes for direct
MCMC results and retained analysis snapshots; conversion detaches tensors
without changing the retained draws.
PSIS-LOO exposes ArviZ 1 results, including elpd, elpd_i, and pareto_k.
Variational draws use relative efficiency one; this does not correct approximation
error. If every selected likelihood column is finite and constant across draws,
LOO uses exact uniform importance weights through ArviZ's
precomputed-weight interface.
The pointwise score is unchanged; Pareto shapes are NaN because no tail was
fitted. This also applies when retained parameters vary but do not affect the
selected response likelihood. Varying-score analyses retain ordinary PSIS.
Unstable importance weights may require exact refitting or a different
predictive unit (Vehtari et al., 2017).
The formula workflow
gives an executable fit and analysis. Low-level samplers can construct
PosteriorAnalysis directly with explicit tensor mappings and provenance.
Retained analysis storage¶
A posterior archive retains the analysis tensors and their coordinate contract.
to_netcdf writes the existing ArviZ DataTree groups, and from_netcdf restores
owned CPU tensors without replaying the model. from_datatree accepts the same
groups directly. The optional diagnostics extra supplies this storage path.
Archives retain (i) original tensor dtypes and draw provenance, (ii) chain, draw, and event labels, and (iii) group-specific event dimensions. The last distinction matters for vector observations: their recorded response can retain a category axis even when each raw likelihood has already reduced that event to one score. The same converter serves ordinary ArviZ analysis and storage.
coords and dims on PosteriorAnalysis supply defaults for later conversion and
covariance requests; explicit method arguments override them. group_dims
preserves dimensions that differ between observed data and reduced likelihoods.
Readers validate sample-axis labels across groups, rather than matching draws by
array extent. External trees need explicit kind; chain count alone cannot
establish MCMC provenance. Unknown format versions, lossy dtype metadata, and
conflicting sampler-statistic aliases are refused.
Float16 and BFloat16 values use exact Float32 storage where the NumPy or NetCDF backend lacks their dtype, then restore their recorded dtype. Integer draws keep their original capacity; reading them does not bypass summary checks before a Float64 conversion. Writes use an atomic sibling file, shared with source migration, so an interrupted write preserves the previous destination.
from pathlib import Path
from tempfile import TemporaryDirectory
import torch
from quivers.diagnostics import PosteriorAnalysis
analysis = PosteriorAnalysis(
samples={"theta": torch.tensor([[[0.2, 0.7], [0.4, 0.6], [0.3, 0.8]]])},
log_likelihood={}, kind="variational",
coords={"coefficient": ["intercept", "slope"]},
dims={"theta": ["coefficient"]},
)
with TemporaryDirectory() as directory:
path = Path(directory) / "posterior.nc"
analysis.to_netcdf(path)
restored = PosteriorAnalysis.from_netcdf(path)
assert restored.kind == "variational"
torch.testing.assert_close(restored.samples["theta"], analysis.samples["theta"])
assert restored.covariance().coordinate_labels == (("intercept",), ("slope",))
This archive stores retained analysis. Executable prediction also requires the fitted program, its deterministic parameters, and preprocessing state; those objects are not reconstructed from posterior draws alone. The file layout uses xarray DataTree NetCDF storage.
posterior
¶
Reusable posterior analysis over explicit chain, draw, and observation axes.
PosteriorSummary
didactic-model
¶
PosteriorSummary(*, 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), convergence: ConvergenceSummary | None = field(default=None, opaque=True, extras=OPAQUE_BY_VALUE))
Bases: ValueModel
Pooled uncertainty summaries, with MCMC diagnostics when applicable.
| PARAMETER | DESCRIPTION |
|---|---|
mean
|
Mean and sample standard deviation on the site's event coordinates.
TYPE:
|
sd
|
Mean and sample standard deviation on the site's event coordinates.
TYPE:
|
probs
|
Requested quantile probabilities.
TYPE:
|
quantiles
|
Quantiles with shape
TYPE:
|
convergence
|
Recorded-chain diagnostics, or None for variational draws.
TYPE:
|
PosteriorCovariance
didactic-model
¶
PosteriorCovariance(*, covariance: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), correlation: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), coordinates: tuple[tuple[str, tuple[int, ...]], ...] = field(opaque=True, extras=OPAQUE_BY_VALUE), dimension_names: tuple[tuple[str, ...], ...], coordinate_labels: tuple[tuple[object, ...], ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), variables: tuple[str, ...], event_shapes: tuple[tuple[int, ...], ...], sample_shape: tuple[int, int] = field(opaque=True, extras=OPAQUE_BY_VALUE), chain_labels: tuple[object, ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), draw_labels: tuple[object, ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), ddof: int, chainwise: bool, kind: Literal['mcmc', 'variational', 'prior'])
Bases: ValueModel
Joint empirical covariance and correlation of retained coordinates.
| PARAMETER | DESCRIPTION |
|---|---|
covariance
|
Float64 square matrices, or one matrix per chain when
TYPE:
|
correlation
|
Float64 square matrices, or one matrix per chain when
TYPE:
|
coordinates
|
Matrix columns as an exact variable name and row-major event index. The same coordinates label matrix rows; no string parsing is needed.
TYPE:
|
dimension_names
|
Event dimension names and their original labels for each matrix column.
TYPE:
|
coordinate_labels
|
Event dimension names and their original labels for each matrix column.
TYPE:
|
variables
|
Selected variable order and corresponding original event shapes.
TYPE:
|
event_shapes
|
Selected variable order and corresponding original event shapes.
TYPE:
|
sample_shape
|
Original chain and draw counts, before the empirical reduction.
TYPE:
|
chain_labels
|
Original sample-axis labels, or their positional defaults.
TYPE:
|
draw_labels
|
Original sample-axis labels, or their positional defaults.
TYPE:
|
ddof
|
Degrees of freedom subtracted from the pooled or per-chain draw count.
TYPE:
|
chainwise
|
Whether each chain was summarized separately.
TYPE:
|
kind
|
Original draw provenance; this record adds no convergence diagnostics.
TYPE:
|
WAICResult
didactic-model
¶
WAICResult(*, elpd_waic: float, p_waic: float, waic: float, se: float, se_p_waic: float, elpd_i: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), variance_i: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), warning: bool, num_samples: int, num_observations: int)
Bases: ValueModel
Pointwise WAIC estimates using sample log-likelihood variances.
| PARAMETER | DESCRIPTION |
|---|---|
elpd_waic
|
Expected log predictive density, effective parameter count, and
deviance-scale criterion
TYPE:
|
p_waic
|
Expected log predictive density, effective parameter count, and
deviance-scale criterion
TYPE:
|
waic
|
Expected log predictive density, effective parameter count, and
deviance-scale criterion
TYPE:
|
se
|
Standard errors of elpd_waic and p_waic across observation units; NaN for one unit.
TYPE:
|
se_p_waic
|
Standard errors of elpd_waic and p_waic across observation units; NaN for one unit.
TYPE:
|
elpd_i
|
Pointwise ELPD and unbiased sample variance over pooled posterior draws.
TYPE:
|
variance_i
|
Pointwise ELPD and unbiased sample variance over pooled posterior draws.
TYPE:
|
warning
|
Whether any pointwise log-likelihood variance exceeds 0.4.
TYPE:
|
num_samples
|
Pooled posterior draw count and number of observation units.
TYPE:
|
num_observations
|
Pooled posterior draw count and number of observation units.
TYPE:
|
se_waic
property
¶
Standard error of the deviance-scale WAIC estimate.
| RETURNS | DESCRIPTION |
|---|---|
float
|
Twice the ELPD-scale standard error. |
PosteriorAnalysis
didactic-model
¶
PosteriorAnalysis(*, samples: Mapping[str, Tensor] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), log_likelihood: Mapping[str, Tensor] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), observed_data: Mapping[str, Tensor] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_IDENTITY), sample_stats: Mapping[str, Tensor] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_IDENTITY), kind: Literal['mcmc', 'variational', 'prior'] = 'mcmc', coords: Mapping[str, Sequence[object]] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_IDENTITY), dims: Mapping[str, Sequence[str]] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_IDENTITY), group_dims: Mapping[str, Mapping[str, Sequence[str]]] = field(default_factory=dict, opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
A reusable tensor posterior and its raw observation likelihoods.
| PARAMETER | DESCRIPTION |
|---|---|
samples
|
Constrained draws with chain and draw axes.
TYPE:
|
log_likelihood
|
Raw pointwise scores retaining observation axes.
TYPE:
|
observed_data
|
Responses corresponding to the score units.
TYPE:
|
sample_stats
|
Recorded per-draw sampler statistics, empty for variational draws.
TYPE:
|
kind
|
Provenance of the draws. Variational and independent prior layout axes never supply MCMC convergence diagnostics.
TYPE:
|
group_dims
|
Optional group-specific event dimensions, preserving observed vector events alongside their reduced pointwise likelihood axes.
TYPE:
|
coords
|
Retained coordinate labels and event dimension names, used by default for DataTree conversion and covariance. Explicit method arguments override them.
TYPE:
|
dims
|
Retained coordinate labels and event dimension names, used by default for DataTree conversion and covariance. Explicit method arguments override them.
TYPE:
|
Notes
Methods consume these retained tensors without replaying the model. Tensor mappings are held by identity; callers own their storage.
summary
¶
summary(*, probs: Sequence[float] = (0.05, 0.5, 0.95)) -> dict[str, PosteriorSummary]
Summarize uncertainty, attaching diagnostics only to recorded chains.
| PARAMETER | DESCRIPTION |
|---|---|
probs
|
Quantile probabilities strictly between zero and one.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, PosteriorSummary]
|
Float64 summaries on each site's event axes. Any coordinate with a nonfinite draw has NaN location, dispersion, and quantiles; no draws are deleted. Original integer capacity is checked before conversion, including independent prior draws. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If sample axes or quantile probabilities are invalid, or an original integer exceeds exact Float64 capacity. |
Source code in src/quivers/diagnostics/posterior.py
covariance
¶
covariance(var_names: Sequence[str] | None = None, *, ddof: int = 1, chainwise: bool = False, coords: Mapping[str, Sequence[object]] | None = None, dims: Mapping[str, Sequence[str]] | None = None) -> PosteriorCovariance
Summarize joint empirical dependence without replaying a posterior.
| PARAMETER | DESCRIPTION |
|---|---|
var_names
|
Distinct selected sites, in matrix order; None selects insertion order. Each site's event coordinates flatten in row-major order.
TYPE:
|
ddof
|
Nonnegative degrees of freedom, strictly below the reduced count.
TYPE:
|
chainwise
|
Retain a separate matrix per chain instead of pooling chain and draw.
TYPE:
|
coords
|
Labels for named event axes and optional chain/draw axes.
TYPE:
|
dims
|
Event-axis names per site, following the DataTree convention.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PosteriorCovariance
|
Float64 covariance and Pearson correlation, structural coordinate labels, sample-axis labels, and provenance. Constants have NaN correlations. No convergence statistics are manufactured. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If axes, labels, selection, ddof, devices, or numeric carriers are invalid; missing/nonfinite draws are refused, without deletion. Integer values outside the exact Float64 range are refused before casting, as are unrepresentable covariance results. |
Source code in src/quivers/diagnostics/posterior.py
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 | |
hypothesis
¶
hypothesis(expression: str | ContrastExpression, *, prior: PosteriorAnalysis | None = None, null: float | int | Tensor = 0.0, probs: Sequence[float] = (0.025, 0.975), robust: bool = False, point: PointNullSpec | None = None, name: str = 'contrast', dims: Mapping[str, Sequence[str]] | None = None, coords: Mapping[str, Sequence[object]] | None = None) -> HypothesisSummary
Evaluate one checked QVR contrast over retained joint draws.
| PARAMETER | DESCRIPTION |
|---|---|
expression
|
QVR value expression and optional aliases to original site names.
TYPE:
|
prior
|
Joint draws from the corresponding proper encompassing prior. Draw counts may differ; event shapes and devices must agree.
TYPE:
|
null
|
Finite comparison value on event axes only.
TYPE:
|
probs
|
Requested quantile probabilities in output order.
TYPE:
|
robust
|
Use median and scaled MAD instead of mean and sample SD.
TYPE:
|
point
|
Optional marginal density comparison on the same joint prior and posterior contrast; requires a checked Real result and prior draws.
TYPE:
|
name
|
Original label of the derived contrast.
TYPE:
|
dims
|
Input event-axis identities and labels, with optional sample labels. Distinct axes remain distinct even when their extents coincide.
TYPE:
|
coords
|
Input event-axis identities and labels, with optional sample labels. Distinct axes remain distinct even when their extents coincide.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HypothesisSummary
|
Existing uncertainty, strict-region posterior odds, and optional prior-corrected region evidence. Equality frequencies are descriptive; requested point_evidence retains a separate marginal density ratio. |
Source code in src/quivers/diagnostics/posterior.py
waic
¶
waic(*, var_name: str | None = None) -> WAICResult
Compute WAIC for one response's retained raw observation scores.
| PARAMETER | DESCRIPTION |
|---|---|
var_name
|
Observation variable; required for multiple response variables.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WAICResult
|
Pointwise and aggregate WAIC estimates. |
Source code in src/quivers/diagnostics/posterior.py
to_datatree
¶
to_datatree(*, coords: Mapping[str, list] | None = None, dims: Mapping[str, list[str]] | None = None) -> DataTree
Convert retained tensors for the optional ArviZ diagnostics package.
| PARAMETER | DESCRIPTION |
|---|---|
coords
|
Coordinate labels for named event or observation dimensions.
TYPE:
|
dims
|
Dimension names per variable, excluding chain and draw axes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DataTree
|
Posterior, likelihood, observed-data, and sampler-stat groups. Chain and draw axes are retained for both posterior kinds. |
Source code in src/quivers/diagnostics/posterior.py
from_datatree
classmethod
¶
from_datatree(tree: DataTree, *, kind: Literal['mcmc', 'variational', 'prior'] | None = None) -> PosteriorAnalysis
Restore retained analysis tensors and labels from an ArviZ DataTree.
| PARAMETER | DESCRIPTION |
|---|---|
tree
|
Canonical posterior, likelihood, observed-data, and sample-stat groups.
TYPE:
|
kind
|
Explicit provenance for external trees. QVR trees retain it in metadata; an override must agree. Chain count never determines provenance.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PosteriorAnalysis
|
Independently owned CPU tensors, dimensions, labels, and provenance. This restores analysis, rather than an executable predictor or optimizer. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If provenance, format, labels, groups, or sampled axes are inconsistent. |
Source code in src/quivers/diagnostics/posterior.py
to_netcdf
¶
Write retained analysis through the existing DataTree NetCDF format.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Output NetCDF file. Requires the diagnostics extra.
TYPE:
|
Source code in src/quivers/diagnostics/posterior.py
from_netcdf
classmethod
¶
from_netcdf(path: str | Path) -> PosteriorAnalysis
Read a QVR retained analysis without reconstructing a fitted evaluator.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
NetCDF file written from a QVR posterior DataTree.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PosteriorAnalysis
|
Owned CPU tensors and coordinate metadata, after axis validation. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If the stored tree does not satisfy the retained analysis contract. |
OSError
|
If the input file is missing or cannot be opened as NetCDF. |
Source code in src/quivers/diagnostics/posterior.py
reloo
¶
reloo(refit: Callable[[FoldSplit], FoldPrediction], *, var_name: str | None = None, k_threshold: float | None = None, seed: int = 0, pointwise: bool = True) -> object
Replace problematic PSIS terms with raw held-out refit predictions.
| PARAMETER | DESCRIPTION |
|---|---|
refit
|
Existing source, formula, or user refit adapter. Each requested split excludes one original observation and scores that row alone.
TYPE:
|
var_name
|
Selected response; required when several responses are retained.
TYPE:
|
k_threshold
|
Refit Pareto shapes above this value. None uses ArviZ's threshold based on retained sample count. Negative infinity refits all rows. Undefined tail fits are refitted unless the threshold is infinity.
TYPE:
|
seed
|
Nonnegative base seed for independent, order-invariant row refits.
TYPE:
|
pointwise
|
Retain individual ELPD values and Pareto diagnostics in the result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ELPDData
|
ArviZ's updated criterion, on the natural-log scale. Refit terms retain the supplied fitter's approximation and Monte Carlo error. |
| RAISES | DESCRIPTION |
|---|---|
(ValueError, TypeError)
|
If options, raw held-out scores, or observation axes are invalid. |
ImportError
|
If the optional diagnostics dependencies are unavailable. |
Source code in src/quivers/diagnostics/posterior.py
loo
¶
Run optional ArviZ PSIS-LOO without recomputing model likelihoods.
| PARAMETER | DESCRIPTION |
|---|---|
var_name
|
Observation variable; required for multiple responses.
TYPE:
|
pointwise
|
Include observation-level ELPD and Pareto shape diagnostics.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ELPDData
|
ArviZ's PSIS-LOO result. Variational draws use relative efficiency one; this does not correct variational approximation error. If every likelihood column is constant across draws, exact uniform weights replace an undefined tail fit, and Pareto shapes are NaN. |
Source code in src/quivers/diagnostics/posterior.py
waic
¶
waic(log_likelihood: Tensor) -> WAICResult
Estimate WAIC from raw conditional log likelihoods.
| PARAMETER | DESCRIPTION |
|---|---|
log_likelihood
|
Finite real scores with shape
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WAICResult
|
Log-mean-exp predictive scores minus sample log-score variances. The variance convention matches R's loo::waic (divisor S - 1). |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If scores are nonfinite, empty, or supply fewer than two pooled draws. |
TypeError
|
If scores are not a real floating-point tensor. |
Source code in src/quivers/diagnostics/posterior.py
Cited sources¶
Aki Vehtari, Andrew Gelman, and Jonah Gabry. Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC. Statistics and Computing, 27:1413–1432, 2017. URL: https://link.springer.com/article/10.1007/s11222-016-9696-4, doi:10.1007/s11222-016-9696-4.