predict.brma predicts values
# S3 method for brma
predict(
object,
newdata = NULL,
type = "terms",
as_measure = TRUE,
output_measure = NULL,
transform = NULL,
probs = c(0.025, 0.975),
bias_adjusted = FALSE,
quiet = FALSE,
conditional = FALSE,
...
)A brma_samples object containing posterior samples. When printed,
displays a summary table via BayesTools::ensemble_estimates_table. The
underlying samples matrix can be accessed directly (the object inherits from matrix)
or via summary() to obtain the summary table. The samples can also be converted
to posterior draws formats using as_draws() and related functions.
a fitted brma object
specification for prediction data. Defaults to NULL which
corresponds to prediction for the observed data. Alternatives are:
TRUE returns a single aggregated prediction (either the scalar
parameter for models without moderators/scale, or the average across the
model matrix for regression models). Not available for type = "response"
since observation-level sampling variance is required.
A data.frame (for meta-regression) or a named list with effect size
measure and variability metrics (for meta-analysis) for new studies. The input
must contain the variables used by the requested prediction type. Outcome
columns are optional for type = "terms" unless PET/PEESE bias terms
are included via bias_adjusted = FALSE.
type of prediction to be performed. Options are:
"terms" (alias: "marginal"): Fixed-effect parameters only (mu).
Produces the mean effect size estimate at the given predictor levels,
not accounting for random effects.
"cluster": Fixed effects plus cluster-level random effects (mu + gamma).
Only available for multilevel (3-level) models.
"estimate" (aliases: "effect", "blup"): True
effects (mu + gamma + theta). For existing normal data, returns posterior
draws of conditional BLUP means, not simulated latent-effect draws. For
new data, samples estimate-level random effects.
"response" (alias: "outcome"): Predicted observed values (yi).
Incorporates both heterogeneity and sampling variability.
"terms.scale": Scale parameter (tau), incorporating scale
regression if present.
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 with type = "response". When FALSE, returns raw
frequency data (counts). Use type = "estimate" for latent logOR/logIRR
predictions.
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. Use transform = "EXP" for ratio-scale output from
log-scale measures.
optional display transformation. Currently "EXP"
exponentiates log-scale measures "OR", "RR", "HR",
and "IRR".
quantiles of the posterior samples to be displayed when the
returned brma_samples object is printed. Defaults to c(.025, .975).
whether predictions should adjust for publication bias.
Defaults to FALSE. When TRUE:
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.
logical; whether to suppress informational messages about prediction scale and bias adjustment.
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.
additional arguments
Type hierarchy:
"terms": mu (fixed effects only)
"cluster": mu + gamma (adds cluster-level random effect)
"estimate": mu + gamma + theta (adds estimate-level random effect)
"response": mu + gamma + theta + epsilon (adds sampling error)
For existing normal observations, type = "estimate" reports the
conditional BLUP mean \(E(\theta_i \mid y_i, \mu_i, \tau_i)\) for each
posterior draw. It is therefore an empirical-Bayes summary, not a draw from
the full latent-effect posterior \(\theta_i \mid y_i\). For new data,
estimate-level random effects are sampled from their model distribution.
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).
pooled_effect(), pooled_heterogeneity(), blup()
if (FALSE) {
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, type = "estimate")
}
}
Run the code above in your browser using DataLab