Regression variance ratios¶
The Bayesian coefficient of determination (R²) compares variation in conditional
response means with unexplained variation at each posterior draw. The pure
bayesian_r2 function accepts moments from source models, formula models, or
another retained prediction procedure. Formula fits expose the same calculation
through BayesianFit.bayes_r2, using their retained
prediction and response transforms. It preserves chain, draw, and event
coordinates while reducing the observation-row axis.
Supply either observed responses or conditional residual_variance. With
observations, the unexplained component is the sample variance of observed
minus predicted responses, matching the
released brms implementation.
With conditional variances, their row average supplies the unexplained
component, as in the model-based method described in the
brms development reference.
The two definitions can differ at the same parameter draw.
import torch
from quivers.diagnostics import bayesian_r2
means = torch.tensor([[[0., 1., 2.], [1., 2., 3.]]])
observed = torch.tensor([0., 2., 2.])
residual_ratio = bayesian_r2(means, observed=observed)
model_ratio = bayesian_r2(means, residual_variance=1.)
assert residual_ratio.shape == model_ratio.shape == (1, 2)
assert ((residual_ratio >= 0) & (residual_ratio <= 1)).all()
expected has shape (chain, draw, row, *event); observations have shape
(row, *event). Conditional variances broadcast to the expected-response
shape. Each event coordinate receives its own ratio; no independence assumption
is needed to report these marginal quantities. For unordered categories, a
numeric category code does not define a response metric. Use explicitly chosen
indicator coordinates or another justified measurement scale.
Prediction variance uses divisor n - 1. The residual definition uses the same
divisor, while conditional variances are averaged over rows. Finite Float64
arithmetic is applied after checking original integer capacity. Common scaling
avoids overflow and underflow in the variance ratio. Constant means have ratio
zero when unexplained variance is positive; zero total variation produces NaN.
No convergence statistic or correction for a variational approximation is
implied. Results use retained, detached values and do not execute a model.
regression
¶
Regression diagnostics from retained conditional response moments.
bayesian_r2
¶
bayesian_r2(expected: Tensor, *, observed: Tensor | None = None, residual_variance: Tensor | float | None = None) -> Tensor
Compute a variance ratio for each retained posterior draw and event.
| PARAMETER | DESCRIPTION |
|---|---|
expected
|
Conditional response means, shaped chain x draw x row x event axes.
TYPE:
|
observed
|
Responses shaped row x event axes. Their centered residual variance supplies the denominator's unexplained component.
TYPE:
|
residual_variance
|
Conditional response variances broadcastable to expected. Their mean over rows instead supplies the unexplained component. Exactly one of observed and residual_variance is required.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
Float64 ratios on chain, draw, and event axes. A constant prediction has ratio zero when unexplained variance is positive; both components being zero gives NaN because no response variation is defined. Values are detached, as with the other retained-sample diagnostics. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If moments or observations are not real tensors. |
ValueError
|
If axes, finiteness, devices, integer capacity, or variances are invalid. |
Notes
Prediction variance uses the unbiased row variance. The residual method uses the same row variance of observed minus predicted values; the model method uses the average conditional variance. A common scale prevents overflow in either variance and cancels from their ratio.
Source code in src/quivers/diagnostics/regression.py
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | |