Density ordinates and point-null evidence¶
log_density_ordinate estimates a marginal density at a specified value from
retained floating contrast draws. density_ratio compares posterior and
joint-prior ordinates at the same null. Both use PyTorch, retain event labels,
and leave inference to the caller. They do not estimate a posterior model
probability.
Direct Gaussian estimates¶
For each scalar event coordinate, the estimator is
where \(\phi\) is the standard Normal density. Input shape is
(chain, draw, *event): chain and draw axes are pooled, while each event
coordinate receives its own marginal estimate. These marginal ordinates do
not supply a joint density at a vector null.
The default bandwidth="nrd0" uses
\(0.9\min(\operatorname{SD},\operatorname{IQR}/1.34)N^{-1/5}\), with SD replacing
a zero IQR for nonconstant draws. This is the
R bandwidth rule
used by the default Gaussian estimator in the
pinned brms density-ratio implementation.
QVR evaluates the Gaussian sum directly. It does not reproduce brms's
FFT-grid interpolation,
cubic spline evaluation, or negative-value clipping.
bandwidth="scott" instead uses \(\operatorname{SD}N^{-1/5}\), following the
one-dimensional covariance-factor convention of
SciPy's gaussian_kde.
A positive scalar or event-shaped tensor supplies an absolute bandwidth.
adjust multiplies the selected bandwidth. The same rule is applied
separately to posterior and prior draws, using each distribution's own scale
and count; prior_bandwidth can override the prior rule or absolute value.
All draw weights are equal. The automatic rules use retained draw counts,
without replacing them by an estimated MCMC effective sample size.
import math
import torch
from quivers.diagnostics import (
PointNullAssumptions, density_ratio, log_density_ordinate,
)
generator = torch.Generator().manual_seed(19)
# theta ~ Normal(0, 1); y=0.6 with known Normal noise SD=0.5.
# The posterior is Normal(0.48, sqrt(0.2)); there are no nuisance parameters.
prior = torch.randn(1, 4096, generator=generator, dtype=torch.float64)
posterior = 0.48 + math.sqrt(0.2) * torch.randn(
1, 4096, generator=generator, dtype=torch.float64,
)
ordinate = log_density_ordinate(posterior, at=0., bandwidth="scott")
evidence = density_ratio(
posterior, prior, null=0., bandwidth="scott",
assumptions=PointNullAssumptions(
proper_continuous_prior=True, compatible_null_prior=True,
),
)
assert ordinate.num_samples == 4096
assert torch.isfinite(evidence.log_bayes_factor_01)
assert evidence.posterior.log_bandwidth.shape == ()
This example declares the assumptions from its stated conjugate model; the arrays alone could not establish them. The result remains a KDE estimate. Bandwidth sensitivity and chain diagnostics matter, especially in tails.
Density ratios and their assumptions¶
DensityRatio.log_ratio always means posterior log density minus prior log
density. Its separate log_bayes_factor_01 field is supplied only when both
PointNullAssumptions declarations are true:
- The encompassing prior is proper and induces a continuous contrast with a finite, positive density at the null; the posterior also has a density there, and neither law has an atom at the null.
- The null model uses the encompassing likelihood restricted to that null, and its nuisance prior equals the encompassing prior conditional on the null, under the same dominating measures.
Under these assumptions, the Savage–Dickey comparison is
The declarations are retained, without mechanical verification. A proper
parameter prior alone does not establish a compatible nuisance prior or a
finite contrast density. A singular nonlinear map, an atom at the null,
or a null outside the prior's support can invalidate the argument.
Gaussian smoothing across a support boundary does not establish positive
underlying prior density there. Without both declarations, the empirical
log_ratio remains available and log_bayes_factor_01 is None.
Posterior and prior contrast tensors may have different sample counts, but must have identical event shapes and devices. Construct a derived prior contrast jointly within each draw, preserving hierarchical dependence. No parameter draws are permuted. Exact equalities and integrated region odds are separate quantities; see the contrast summary. Neither an equality frequency nor a one-sided region probability is a point-density ordinate.
A common smooth one-to-one change of scalar coordinates cancels its nonzero Jacobian from the population density ratio. KDE estimates under an affine change retain that identity when bandwidths change by the same scale. For a nonlinear change, finite-bandwidth smoothing is coordinate-dependent; transforming and re-estimating need not give exactly the same result.
Diagnostics, capacity, and storage¶
Each DensityOrdinate retains log_density, log_bandwidth, the absolute
bandwidth, the selected rule and adjustment, and original sample counts.
name, dims, and coords use the shared
event-coordinate policy.
kernel_effective_count reports
\((\sum_s w_s)^2/\sum_s w_s^2\) for local Gaussian weights. It describes
local weight concentration, without measuring MCMC mixing or approximation
error. None of these values supplies a universal KDE accuracy guarantee.
Inputs must be finite floating tensors with at least two pooled draws and nonzero spread on every coordinate. Known Boolean/integer samples, missing values, constant coordinates, and invalid bandwidths fail explicitly. No missing draws are deleted and no jitter is added. Floating storage or occasional repeated values does not establish continuity; that is part of the caller's distributional argument. Two distinct draws are accepted, but the interface does not assert that this is enough for reliable evidence.
The estimator reuses shared scaled summary arithmetic for automatic
bandwidths. Kernel evaluation tiles both sample and event axes, with
max_working_elements bounding each temporary kernel tile. The budget is a
positive integer, excluding Boolean values. It does not bound input/output
storage or the shared bandwidth workspace. The nrd0 quartiles require a
sort; Scott bandwidth selection avoids that sort.
Direct sums retain Gaussian factors around a nearby sampled value. Ratio calculation factors the quadratic difference before subtraction, so recomputing it from two rounded displayed log densities may lose tail precision. Bandwidths remain authoritative in log space: exponentiation may underflow to zero or overflow to infinity even when the log estimate is representable. A log score beyond Float64 capacity causes an explicit error, rather than a false zero-density estimate.
All numerical outputs are detached Float64 tensors on the original device. There is no inference replay or density-gradient promise. Returned tensor storage remains caller-owned; copying and serialization retain the nested ordinate records and their opaque tensors. CUDA behavior is conditional on a Float64-capable device; this API does not claim MPS Float64 support.
Requests from checked hypotheses¶
PointNullSpec packages the existing bandwidth, assumption, and workspace
options for hypothesis_summary, PosteriorAnalysis.hypothesis, and
BayesianFit.hypothesis. The result places this comparison in
HypothesisSummary.point_evidence, alongside unchanged region and equality
summaries. The checked-expression methods require a Real result; the formula
method also requires prior=True. All methods reuse the same joint contrast
streams for both summaries, preserving hierarchical dependence.
import math
import torch
from quivers.diagnostics import PointNullSpec, PosteriorAnalysis
generator = torch.Generator().manual_seed(29)
prior = PosteriorAnalysis(
samples={"theta": torch.randn(1, 1024, generator=generator)},
log_likelihood={}, kind="prior",
)
posterior = PosteriorAnalysis(
samples={"theta": 0.48 + math.sqrt(0.2) * torch.randn(
1, 1024, generator=generator,
)},
log_likelihood={}, kind="mcmc",
)
comparison = posterior.hypothesis(
"theta", prior=prior,
point=PointNullSpec(bandwidth="scott", max_working_elements=128),
)
assert torch.isfinite(comparison.point_evidence.log_ratio)
assert comparison.point_evidence.log_bayes_factor_01 is None
This request returns a diagnostic density ratio. To request a point-null Bayes
factor, supply assumptions=PointNullAssumptions(...) in the configuration,
with both declarations justified by the model described above. Each event
coordinate remains a separate scalar comparison. The returned log_ratio
retains the factored tail calculation; subtracting the displayed ordinate
fields again may lose precision.
density
¶
Direct Gaussian density ordinates and declared point-null density evidence.
PointNullAssumptions
didactic-model
¶
Bases: ValueModel
Caller declarations needed to interpret a density ratio as point evidence.
| PARAMETER | DESCRIPTION |
|---|---|
proper_continuous_prior
|
The encompassing prior is proper and induces a continuous contrast with a finite, positive density at the null. Its corresponding posterior also has a density there; neither distribution has an atom at the null.
TYPE:
|
compatible_null_prior
|
The null model uses the encompassing likelihood restricted to the null, and its nuisance prior equals the encompassing prior conditional on that null, with the same underlying dominating measures.
TYPE:
|
Notes
These declarations are not mechanically verified from the draws. They do not assert KDE accuracy. Arbitrary nonlinear contrasts may fail the density or compatibility assumptions even when each parameter has a proper prior.
PointNullSpec
didactic-model
¶
PointNullSpec(*, bandwidth: str | float | Tensor = field(default='nrd0', opaque=True, extras=OPAQUE_BY_IDENTITY), prior_bandwidth: str | float | Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY), adjust: float = 1.0, assumptions: PointNullAssumptions | None = field(default=None, opaque=True, extras=OPAQUE_BY_VALUE), max_working_elements: int = 262144)
Bases: ValueModel
Request marginal density evidence from the shared joint contrast streams.
| PARAMETER | DESCRIPTION |
|---|---|
bandwidth
|
Posterior Gaussian bandwidth: nrd0, scott, or a positive scalar/event tensor. Bandwidth tensors retain their original identity.
TYPE:
|
prior_bandwidth
|
Prior bandwidth policy; None estimates it separately under bandwidth.
TYPE:
|
adjust
|
Positive multiplier on both selected bandwidths.
TYPE:
|
assumptions
|
Optional explicit declarations allowing a point-null BF01 interpretation. Without both declarations the result remains a diagnostic density ratio.
TYPE:
|
max_working_elements
|
Positive bound on each shared density estimator's kernel workspace.
TYPE:
|
Notes
Every retained event coordinate is a separate scalar contrast; this request does not estimate a joint multivariate point-null density. The estimator's resource, finite-continuous-sample, and bandwidth checks apply when used.
DensityOrdinate
didactic-model
¶
DensityOrdinate(*, log_density: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), at: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), log_bandwidth: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), bandwidth_rule: str, adjust: float, sample_shape: tuple[int, ...], kernel_effective_count: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), name: str, dimension_names: tuple[str, ...], coordinate_labels: tuple[tuple[object, ...], ...] = field(opaque=True, extras=OPAQUE_BY_IDENTITY), max_working_elements: int)
Bases: ValueModel
A marginal Gaussian KDE ordinate for each scalar event coordinate.
| PARAMETER | DESCRIPTION |
|---|---|
log_density
|
Natural-log density in the original contrast units.
TYPE:
|
at
|
Evaluation point broadcast only over event coordinates.
TYPE:
|
log_bandwidth
|
Absolute Gaussian kernel bandwidth in log space, including adjustment. This representation remains authoritative at extreme numerical scales.
TYPE:
|
bandwidth_rule
|
TYPE:
|
adjust
|
Positive multiplier applied to the selected bandwidth.
TYPE:
|
sample_shape
|
Retained chain and draw counts. Draws are equally weighted and pooled.
TYPE:
|
kernel_effective_count
|
Squared sum of local kernel weights divided by their sum of squares. This measures local weight concentration, not MCMC effective sample size.
TYPE:
|
name
|
Original contrast name, named event dimensions, and original labels.
TYPE:
|
dimension_names
|
Original contrast name, named event dimensions, and original labels.
TYPE:
|
coordinate_labels
|
Original contrast name, named event dimensions, and original labels.
TYPE:
|
max_working_elements
|
Upper bound on each temporary kernel tile, excluding input storage, output coordinates, and the shared bandwidth-reduction workspace.
TYPE:
|
bandwidth
property
¶
bandwidth: Tensor
Return the absolute bandwidth when representable in Float64.
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
Exponentiated log bandwidth. Underflow or overflow may give zero or
infinity; |
num_samples
property
¶
Return the number of equally weighted pooled draws.
| RETURNS | DESCRIPTION |
|---|---|
int
|
Product of original chain and draw counts. |
DensityRatio
didactic-model
¶
DensityRatio(*, posterior: DensityOrdinate = field(opaque=True, extras=OPAQUE_BY_VALUE), prior: DensityOrdinate = field(opaque=True, extras=OPAQUE_BY_VALUE), log_ratio: Tensor = field(opaque=True, extras=OPAQUE_BY_IDENTITY), assumptions: PointNullAssumptions | None = None, log_bayes_factor_01: Tensor | None = field(default=None, opaque=True, extras=OPAQUE_BY_IDENTITY))
Bases: ValueModel
Posterior-to-prior density evidence, separate from probability odds.
| PARAMETER | DESCRIPTION |
|---|---|
posterior
|
Marginal KDE ordinates at the same original-coordinate null.
TYPE:
|
prior
|
Marginal KDE ordinates at the same original-coordinate null.
TYPE:
|
log_ratio
|
Posterior minus prior log density. This always describes the empirical density ratio, independently of any Bayesian interpretation.
TYPE:
|
assumptions
|
Caller declarations, retained without claiming mechanical verification.
TYPE:
|
log_bayes_factor_01
|
Point-null versus encompassing-alternative log Bayes factor only when both declarations are true. KDE approximation error remains; this is neither a region-odds ratio nor a posterior model probability.
TYPE:
|
log_density_ordinate
¶
log_density_ordinate(samples: Tensor, *, at: float | int | Tensor = 0.0, bandwidth: str | float | Tensor = 'nrd0', adjust: float = 1.0, name: str = 'contrast', dims: Sequence[str] | None = None, coords: Mapping[str, Sequence[object]] | None = None, max_working_elements: int = 262144) -> DensityOrdinate
Estimate one marginal Gaussian log density per retained event coordinate.
| PARAMETER | DESCRIPTION |
|---|---|
samples
|
Finite floating draws shaped
TYPE:
|
at
|
Finite evaluation point, broadcasting only over event axes.
TYPE:
|
bandwidth
|
TYPE:
|
adjust
|
Positive finite multiplier applied to the selected bandwidth.
TYPE:
|
name
|
Original contrast name, retained without parsing.
TYPE:
|
dims
|
Event dimension names using the retained-analysis coordinate policy.
TYPE:
|
coords
|
Original labels of event dimensions.
TYPE:
|
max_working_elements
|
Positive integer bound on temporary kernel tiles, including both sample and event-coordinate tiling. Automatic bandwidth reduction uses the shared input-sized summary workspace; nrd0 also sorts for quartiles.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DensityOrdinate
|
Detached Float64 marginal log density, bandwidth, sample counts, and local kernel-weight concentration on the original device. This is a smoothing estimate, not a jointly multivariate density or evidence claim. |
| RAISES | DESCRIPTION |
|---|---|
(TypeError, ValueError)
|
If samples are integer/Boolean, nonfinite, empty, constant, or too few; metadata or settings disagree; or log-score capacity is exceeded. |
Notes
The direct Gaussian sum has no FFT interpolation or negative-density clipping. Finite-sample KDE error depends on bandwidth, tails, dependence, and coordinate choice. Floating storage does not establish a continuous underlying law. No inference, density gradient, or convergence diagnostic is computed.
Source code in src/quivers/diagnostics/density.py
density_ratio
¶
density_ratio(posterior: Tensor, prior: Tensor, *, null: float | int | Tensor = 0.0, bandwidth: str | float | Tensor = 'nrd0', prior_bandwidth: str | float | Tensor | None = None, adjust: float = 1.0, assumptions: PointNullAssumptions | None = None, name: str = 'contrast', dims: Sequence[str] | None = None, coords: Mapping[str, Sequence[object]] | None = None, max_working_elements: int = 262144) -> DensityRatio
Compare posterior and joint-prior ordinates at the same scalar contrast null.
| PARAMETER | DESCRIPTION |
|---|---|
posterior
|
Finite floating contrast draws with aligned event shapes and devices. Chain and draw counts may differ. Form derived prior contrasts jointly, preserving hierarchical dependence; draws are never permuted here.
TYPE:
|
prior
|
Finite floating contrast draws with aligned event shapes and devices. Chain and draw counts may differ. Form derived prior contrasts jointly, preserving hierarchical dependence; draws are never permuted here.
TYPE:
|
null
|
Finite scalar or event-shaped evaluation point.
TYPE:
|
bandwidth
|
Posterior bandwidth rule or positive absolute value.
TYPE:
|
prior_bandwidth
|
Prior bandwidth; None applies the same policy separately to each input. Automatic rules use each distribution's own count and scale.
TYPE:
|
adjust
|
Positive multiplier applied to both selected bandwidths.
TYPE:
|
assumptions
|
Explicit declarations enabling a point-null BF01 interpretation when both are true. These declarations cannot be verified from sample arrays.
TYPE:
|
name
|
Original derived-contrast label.
TYPE:
|
dims
|
Shared event dimensions and original labels.
TYPE:
|
coords
|
Shared event dimensions and original labels.
TYPE:
|
max_working_elements
|
Positive kernel-tile element bound, as for log_density_ordinate.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DensityRatio
|
Posterior/prior log density ratio and separate declaration-dependent BF01 field. It never supplies a posterior null-model probability. |
| RAISES | DESCRIPTION |
|---|---|
(TypeError, ValueError)
|
If alignment, domains, samples, settings, or declarations are invalid. Known integer or Boolean laws and constant samples are refused. |
Notes
Under the declared proper continuous prior and compatible null nuisance prior, posterior density divided by prior density gives the Savage-Dickey point-null BF01. KDE only approximates those densities. An atom at the null, a singular contrast, or incompatible nuisance prior invalidates this argument; an empirical equality frequency or region odds cannot replace an ordinate.
Source code in src/quivers/diagnostics/density.py
671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 | |