predict.brma predicts values
Arguments
- object
a fitted brma object
- newdata
prediction data. Defaults to
NULL, which predicts the observed design rows.TRUEreturns a single aggregated prediction at the average fitted design (the scalar parameter for models without moderators or scale predictors, otherwise the arithmetic mean across the fitted rows of the location and of the observation-specific heterogeneity): the pooled location (type = "terms"), the pooled heterogeneity ("terms.scale"), a new true effect ("estimate"), or a new cluster effect added to the pooled location ("cluster", multilevel models only). It is the quantity reported bypooled_effectandpooled_heterogeneitywithout the prediction interval columns, requires marginal depth, and is not available fortype = "response", which needs observation-level sampling variance. Marginal new-effect predictions may use an explicit data frame or named list with one row per target effect and every variable used by the requested fixed, scale, and random-effect designs. Missing ordinary grouping-only identifiers are synthesized as row-specific new levels; known-Rgrouping identifiers must be supplied. Outcome columns are optional fortype = "terms"unless PET/PEESE bias terms are included viabias_adjusted = FALSE. Missing values are rejected; prediction never drops rows silently. Binomial GLMM response predictions require arm totalsn1iandn2i; supply the totals alone, optionally with event countsaiandci, or supply the four cell countsai,bi,ci, anddi. Supplied cells and totals must agree. Poisson GLMM response predictions require exposurest1iandt2i; event countsx1iandx2iare optional. For known-Vbrma.mv()response prediction, explicitnewdataalso requires sampling covariance throughV_new. Product-only selection models require no publication-group column. Unadjusted normal selected latent predictions (type = "estimate") requireseiorviin explicitnewdata. If an active selection branch usesweight_rule = "best", its publication groups must also be resolvable in the prediction data.- type
type of prediction to be performed. Options are:
"terms"(alias:"marginal"): fixed location parameters only, \(X\beta\)."estimate"(alias:"effect"): latent true effects. The random-effect distribution is selected byconditioning_depth."response"(alias:"outcome"): Predicted observed values (yi). Adds the outcome sampling distribution to the corresponding latent-effect target."terms.scale": Scale parameter (tau), incorporating scale regression if present. Forbrma.mv()random-formula models, returns a named list of component-specificbrma_samplesmatrices, whether or not scale formulas are present.
The released
"cluster"and"blup"spellings are retained as compatibility shortcuts for conditional location samples: they fixconditioning_depth = "cluster"and"estimate", respectively. Usefitted()orblup()when conditional means are the intended quantity.- as_measure
logical; whether to convert GLMM response predictions from simulated counts to continuity-corrected effect-size estimators (logOR for binomial, logIRR for Poisson). Defaults to
TRUE. Only relevant for GLMM models withtype = "response". WhenFALSE, returns raw frequency data (counts). Usetype = "estimate"for latent logOR/logIRR predictions.- output_measure
effect-size measure for location/effect predictions. Defaults to the fitted measure. Supported conversions are among
"SMD","COR","ZCOR", and"OR";"RR","HR","IRR","RD", and"GEN"can only be returned on their fitted measure. Usetransform = "EXP"for ratio-scale output from log-scale measures.- transform
optional display transformation. Currently
"EXP"exponentiates log-scale measures"OR","RR","HR", and"IRR".- probs
quantiles of the posterior samples to be displayed when the returned
brma_samplesobject is printed. Defaults toc(.025, .975).- bias_adjusted
whether predictions should adjust for publication bias. Defaults to
FALSE. WhenTRUE:PET/PEESE terms are NOT added to the mean parameter (mu), returning the bias-corrected effect estimate.
For
type = "response"with selection models, samples from the ordinary normal predictive distribution instead of the selected-normal distribution, simulating what would be observed without publication bias.
When
FALSE:PET/PEESE terms ARE added to mu, returning predictions that include the expected bias (i.e., what we expect to observe given publication bias).
For
type = "response"with selection models, samples from the selected-normal distribution reflecting the selective publishing process.
For new outcomes, selection predictions draw retained contexts from their original Gaussian law, then sample each full publication event conditional on that context. Selected latent predictions additionally reconstruct the integrated true effects conditional on the selected response. At estimate depth, response prediction is a new replication event conditional on the fitted latent true effects; LOO-PIT instead uses deletion within the original publication event. Retained estimate-level effects use their fitted posterior values at estimate depth and fresh Gaussian draws for a new estimate within a fitted cluster. The fitted selection specification and prediction conditioning depth are separate choices.
- quiet
logical; whether to suppress the informational message when conditional posterior samples are flattened to one chain.
- conditional
whether to return conditional posterior predictions for RoBMA product-space objects. For location predictions, samples are conditioned on the effect component; for
type = "terms.scale", samples are conditioned on the heterogeneity component. Conditional samples are flattened to one chain after subsetting posterior rows.- V_new
optional sampling covariance for explicit
newdataresponse or selected latent predictions from known-Vbrma.mv()models. Accepts a vector of diagonal variances, a square covariance matrix, a list of block covariance matrices, or aknown_v_factordeclaration. Its total dimension must matchnrow(newdata). It is required for explicit-newdata response predictions and unadjusted selected latent predictions. Cross-covariance with observed rows is not supported. Numerical symmetry is handled as forV: accepted off-diagonal pairs are averaged internally; the supplied object and diagonal are unchanged.- conditioning_depth
random-effect conditioning depth for
type = "estimate"and"response"."marginal"(default) predicts new latent effects,"cluster"conditions on the fitted cluster effect and predicts a new estimate within that cluster, and"estimate"predicts the fitted latent effect. Cluster depth is available only for specialized multilevel models fitted withcluster. Non-marginal prediction is currently restricted tonewdata = NULL, where fitted identities are unambiguous.- ...
unused additional arguments. Supplied arguments trigger a warning.
Value
A brma_samples object containing posterior samples. For
brma.mv() random-formula type = "terms.scale" predictions,
returns a named list of component-specific brma_samples objects; with
newdata = TRUE this component result is the component = "all"
result of pooled_heterogeneity (a named list for several
components, one brma_samples object for a single component), computed
with the arithmetic mean of the observation-specific tau of a scale formula;
its components are titled “Pooled Heterogeneity (<block>)” and
“Total Pooled Heterogeneity”.
When printed, each brma_samples object displays a summary table via
BayesTools::ensemble_estimates_table. The underlying samples matrix
can be accessed directly because the object inherits from matrix. For a
single brma_samples object, use summary(), or
as.data.frame(summary(x)), to obtain the summary table with component
and parameter identifiers; as.data.frame(x) returns the posterior
draws. A list of results (a brma_samples_list) coerces directly:
as.data.frame() of the list gives the summary table, and
as.data.frame(format = "list") retains separate tables. The samples
can also be converted to posterior draws formats
using as_draws() and related functions.
Details
Prediction has two independent axes. type selects the quantity:
fixed location ("terms"), latent true effect ("estimate"), or
observed outcome ("response"). conditioning_depth selects how
much of the fitted random-effect hierarchy is retained. In the specialized
multilevel model fitted with cluster,
\(y_{ij} = X_{ij}\beta + u_j + v_{ij} + \epsilon_{ij}\), the targets are:
"marginal": condition on neither \(u_j\) nor \(v_{ij}\);"cluster": condition on fitted \(u_j\), but draw a new \(v_{ij}\);"estimate": draw the fitted latent effect from its posterior.
type = "response" adds \(\epsilon\) to the selected latent-effect
target. For normal fitted effects this includes the conditional latent
uncertainty, not only the BLUP mean. blup() and fitted(...,
conditioning_depth = "estimate") remain the conditional-mean interfaces.
For admitted weighted Gaussian selection models, reconstruction of fitted
integrated true effects uses the normalized conditional kernel
\(N(u;0,\tau^2)N(y;c+u,s^2)^w\). Its conditioning variance is
\(s^2/w\); the fitted global posterior and retained latent contributions
remain the supplied posterior. This post-fit augmentation does not assert
that likelihood powering commutes with integrating a latent effect.
Estimate-depth estimate and response targets record this policy and the
row-aligned likelihood weights in RoBMA_target$latent_augmentation.
Response replication adds the original sampling variance \(s^2\).
Ordinary independent Gaussian selection predictions use exact diagonal-cell
chunk pricing after conservative fixed-geometry and output reserves. Other
model structures retain the dense covariance charge under the same budget.
The RoBMA.known_v_covariance_max_bytes option controls covariance
chunk memory. Selected predictions are reproducible for a fixed seed and
chunk budget, but changing this option can change the returned seeded draw
sequence because chunking changes the order of random-number consumption.
newdata supplies design values and grouping identities; it does not
select an estimand. Consequently, marginal prediction has the same law for
newdata = NULL and an equivalent explicit design. Matching fitted
grouping labels retains the requested dependence among new marginal draws
but does not reuse fitted random effects. Cluster- and estimate-depth
predictions require fitted identities and therefore currently reject
explicit newdata.
For binomial and Poisson GLMM response predictions, estimate depth uses the fitted posterior nuisance base rate \(\pi_i\) or rate \(\phi_i\). Marginal and cluster depths describe a new estimate and therefore draw a new nuisance rate independently from its model prior. Those predictions contain a prior-predictive nuisance-rate component, which can dominate their width when the nuisance prior is diffuse; fitted \(\pi_i\)/\(\phi_i\) values are never silently reused for a marginal or cluster target.
For RoBMA product-space objects, conditional posterior predictions subset
posterior rows according to model indicators. This removes the original
chain structure, so returned brma_samples objects are intentionally
stored as one flattened chain.
Note that in contrast to predict, the type = "response" produces
predictions for the new effect size estimates. To obtain results corresponding to
metafor's predict function, use type = "terms" for the mean effect size
and type = "estimate" for true effects (prediction interval).
Likelihood weights: If the model was fitted with weights,
the weights affect the posterior fit, log-likelihood, LOO/WAIC, and
existing-data conditional diagnostics such as BLUP shrinkage and leverage.
They do not change the observation-level sampling error used by
type = "response" for normal models: response predictions simulate
raw future effect-size estimates with the supplied sei, not
sei / sqrt(weight).
For known-V brma.mv() models, explicit newdata
response and unadjusted selected latent prediction require V_new.
Random-formula models preserve
the joint random-effect structure selected by conditioning_depth and
then add V or V_new sampling noise. Cross-covariance with
observed rows is not supported. Explicit
newdata estimate/response predictions are not
available for brma.mv() objects with marginalized known-R
blocks, because their row multipliers are fitted-row metadata.
brma.mv() prediction results carry a
brma_mv_prediction_target attribute recording the formula,
random-effect, and response-generation target used.
For known-V models, the conditional random-effect predictions require
applying the inverse of the marginal covariance. A covariance that is too
ill-conditioned for that (a reciprocal condition number of about 2e-10
or less in any posterior draw used) is unavailable: the call stops with an
error of class RoBMA_known_v_precision_unavailable, whose parent class
is RoBMA_numerical_unavailable, instead of returning a rounded number.
The condition carries the draw positions (rows) and their
reciprocal_condition.
Examples
if (FALSE) { # \dontrun{
if (requireNamespace("metadat", quietly = TRUE) &&
requireNamespace("metafor", quietly = TRUE)) {
data(dat.bcg, package = "metadat")
dat <- metafor::escalc(
measure = "RR",
ai = tpos,
bi = tneg,
ci = cpos,
di = cneg,
data = dat.bcg
)
fit <- brma(
yi = yi,
vi = vi,
mods = ~ ablat + year,
data = dat,
measure = "RR",
seed = 1,
silent = TRUE
)
predict(fit, type = "terms")
predict(fit, newdata = TRUE, type = "terms")
predict(fit, newdata = data.frame(ablat = 50, year = 1970),
type = "estimate")
predict(fit, type = "estimate")
}
} # }