Conditional effects and empirical marginalization¶
A conditional effect evaluates a fitted model while varying specified predictors and holding the remaining predictors at explicit values. This workflow has two parts: (i) construct a bounded prediction grid; and (ii) retain the joint predictions before summarizing their uncertainty. The brms conditional-effects interface likewise supplies conditioning rows for predictor effects. QVR makes those rows explicit, so selecting a reference category or a numeric mean remains visible.
Condition on selected predictor values¶
prediction_grid crosses named effect coordinates with each row of
conditions. The insertion order of the named axes determines point order;
the conditioning rows retain their original order within each point. Grid
coordinates replace matching columns in the conditioning frame.
Core source workflows can supply conditions={"z": [-2., 2.]} instead of a
dataframe; conditions={} specifies one empty row for a single-predictor grid.
This mapping interface and grid.to_mapping() need only the core dependencies.
Dataframe inputs use the selected Narwhals backend without conversion to pandas.
The formula adapter's grid.to_frame() uses pandas from the formula frontend's
dependencies.
import pandas as pd
from quivers.diagnostics import prediction_grid
from quivers.formulas import fit
data = pd.DataFrame({
"y": [0., 1., 0., 1.],
"x": [-1., 0., 1., 2.],
"z": [-2., 2., -2., 2.],
})
fitted = fit("y ~ x + z", data=data, family="bernoulli",
method="svi", num_steps=2, seed=7)
grid = prediction_grid(
{"x": [0., 1., 2.]}, conditions=pd.DataFrame({"z": [-2., 2.]}),
)
effects = fitted.conditional_effects(grid, num_samples=5, seed=11)
assert effects.draws.shape == (1, 5, 3, 2)
uncertainty = effects.summary(probs=(0.05, 0.5, 0.95))
assert uncertainty.mean.shape == (3, 2)
The axes are (chain, draw, point, condition, *event). The singleton leading
axis of a variational fit is a layout axis; it does not supply MCMC convergence
diagnostics. Categorical or ordinal expected responses retain a final category
axis and its effects.labels.
The default method="epred" evaluates expected responses. Use
method="linpred" for linear predictors, with optional parameter and
transform, or method="predict" for response replications. Replications
include response noise, so their uncertainty differs from uncertainty about
the expected response. The existing prediction methods retain their response,
trial-count, and finite-moment checks.
Average over an empirical reference population¶
Empirical marginalization evaluates each point at every supplied reference row, then averages those predictions within each posterior draw. It thus retains the joint uncertainty of the average. This generally differs from conditioning on mean predictor values when the model includes a nonlinear link or interaction.
reference = prediction_grid(
{"x": [0., 1., 2.]}, conditions=data[["z"]], marginalize=True,
)
marginal = fitted.conditional_effects(reference, num_samples=5, seed=11)
assert marginal.draws.shape == (1, 5, 3)
paired_change = marginal.draws[:, :, 2] - marginal.draws[:, :, 0]
assert paired_change.shape == (1, 5)
joint = marginal.analysis()
covariance = joint.covariance()
assert covariance.covariance.shape == (3, 3)
The reference-row axis disappears after averaging. Optional
weights=[...] in prediction_grid supplies finite, nonnegative empirical
weights with positive total; the grid normalizes them for this average. These
weights describe the reference population and do not alter the fitted
likelihood. Averaging interval endpoints or independently resampling each grid
point would discard the dependence retained by this workflow.
Retain prediction policies and bound allocation¶
Each effects request calls the selected posterior prediction method once for
all grid rows. Fitted transforms, contrasts, offsets, auxiliary formulas,
trial counts, and grouping encodings follow the ordinary new-data contract.
re_formula, allow_new_levels, and sample_new_levels have their existing
meanings. Repeated group identities across points share each joint group draw.
Setting re_formula="~0" excludes varying effects; it does not integrate over
their distribution. Empirical averaging integrates only over the reference
rows that were explicitly supplied.
Supply any retained sampling-law columns needed by the prediction, including
exposures, truncation bounds, measurement errors, or trial columns. Neural
predictors require predictor_data aligned with the entire generated grid.
Fresh groups follow the fitted prediction policy, including its order-support
checks for constrained ordinal models.
Before allocating the Cartesian product, prediction_grid checks
number_of_points * number_of_conditions <= max_rows; the default limit is
10,000. A larger request requires an explicit larger limit. This check bounds
the row expansion, while the requested draw count and response event dimensions
still determine prediction storage. Grid coordinates are finite scalar
numbers, strings, Boolean values, or explicit missing-group values None;
structured inputs can use the underlying prediction interface directly.
The retained result reuses posterior analysis for covariance and checked contrasts. No additional fitting, convergence estimator, or contrast parser is introduced. See the conditional-effects API for the grid and result records.
Expected responses from QVR source¶
Source fits use the same grid and result records. ModelFit.posterior_epred
reads the native response law at each retained joint draw; it preserves recorded
chain boundaries and uses the leading requested draws from each chain. It
returns category probabilities for categorical and ordinal responses, and native
means for other laws. It does not estimate an analytic mean by averaging response
replications.
import torch
from quivers.modeling import Model, VariationalMethod
source = """object Row : FinSet _
object Out : Real 1
program regression(x : Tensor[Real]([Row]), y : Tensor[Real]([Row])) : Row -> Out
sample slope <- Normal(loc=0.0, scale=1.0)
let mu = slope * x
observe y : Row <- Normal(loc=mu, scale=1.0)
return slope
export regression
"""
source_fit = Model(source).fit(
{"x": torch.tensor([0., 1., 2.]), "y": torch.tensor([0., 1., 2.])},
method=VariationalMethod(num_steps=5, seed=4),
)
source_grid = prediction_grid({"x": [0., 1., 2.]}, conditions={})
source_effects = source_fit.conditional_effects(source_grid, num_samples=5, seed=8)
assert source_effects.draws.shape == (1, 5, 3, 1)
expectations = source_fit.posterior_epred(num_samples=5, seed=8)
assert expectations["y"].shape == (1, 5, 3)
Source grid binding uses the selected observation's nominal leading axis.
For instance, equally sized Row and Other objects remain distinct: changing
Row predictors retains a fitted tensor indexed by Other. Every required
row predictor needs an explicit grid or conditioning column. Scalar inputs may
be supplied as constant conditioning columns; varying them requires a declared
row tensor. Explicit finite cardinalities remain fixed, while open extents may
specialize to the grid size. Source grouping inputs retain their checked numeric
index maps and fitted latent dimensions.
With several observations, select one through site="response_name". These
are conditional response expectations: supplied upstream observations and
lexically computed values retain their conditioning semantics. They are not an
analytic integration over other responses. Recording-event likelihood weights
and censoring do not change the response law; truncation does. If a native
analytic mean is unavailable, mc_samples permits an explicit, seeded
approximation only for bounded laws or laws with a finite-mean certificate.
Undefined means remain errors. Raw log likelihoods keep their ordinary recorded
event semantics.
The lower-level posterior expectation collector also accepts exact Scan occurrence names. Repeated occurrences are stacked in execution order on their native batch/event layouts, including any retained run axis. Selecting an exact occurrence alongside its base name gives that occurrence to the exact selector and leaves the others under the base selector.