RoBMA is used to estimate a robust Bayesian
meta-regression. The interface allows a complete customization of
the ensemble with different prior (or list of prior) distributions
for each component.
RoBMA.reg(
formula,
data,
test_predictors = TRUE,
study_names = NULL,
study_ids = NULL,
transformation = if (any(colnames(data) != "y")) "fishers_z" else "none",
prior_scale = if (any(colnames(data) != "y")) "cohens_d" else "none",
standardize_predictors = TRUE,
effect_direction = "positive",
priors = NULL,
model_type = NULL,
rescale_priors = 1,
priors_effect = set_default_priors("effect", rescale = rescale_priors),
priors_heterogeneity = set_default_priors("heterogeneity", rescale = rescale_priors),
priors_bias = set_default_priors("bias", rescale = rescale_priors),
priors_effect_null = set_default_priors("effect", null = TRUE),
priors_heterogeneity_null = set_default_priors("heterogeneity", null = TRUE),
priors_bias_null = set_default_priors("bias", null = TRUE),
priors_hierarchical = set_default_priors("hierarchical"),
priors_hierarchical_null = set_default_priors("hierarchical", null = TRUE),
prior_covariates = set_default_priors("covariates", rescale = rescale_priors),
prior_covariates_null = set_default_priors("covariates", null = TRUE),
prior_factors = set_default_priors("factors", rescale = rescale_priors),
prior_factors_null = set_default_priors("factors", null = TRUE),
algorithm = "bridge",
chains = 3,
sample = 5000,
burnin = 2000,
adapt = 500,
thin = 1,
parallel = FALSE,
autofit = TRUE,
autofit_control = set_autofit_control(),
convergence_checks = set_convergence_checks(),
save = "all",
seed = NULL,
silent = TRUE,
...
)RoBMA.reg returns an object of class 'RoBMA.reg'.
a formula for the meta-regression model
a data.frame containing the data for the meta-regression. Note that the
column names have to correspond to the effect sizes (d, logOR, OR,
r, z), a measure of sampling variability (se, v, n,
lCI, uCI, t), and the predictors.
See combine_data() for a complete list of reserved names and additional information
about specifying input data.
vector of predictor names to test for the presence
of moderation (i.e., assigned both the null and alternative prior distributions).
Defaults to TRUE, all predictors are tested using the default
prior distributions (i.e., prior_covariates,
prior_covariates_null, prior_factors, and
prior_factors_null). To only estimate
and adjust for the effect of predictors use FALSE. If
priors is specified, any settings in test_predictors
is overridden.
an optional argument with the names of the studies
an optional argument specifying dependency between the
studies (for using a multilevel model). Defaults to NULL for
studies being independent.
transformation to be applied to the supplied
effect sizes before fitting the individual models. Defaults to
"fishers_z". We highly recommend using "fishers_z"
transformation since it is the only variance stabilizing measure
and does not bias PET and PEESE style models. The other options are
"cohens_d", correlation coefficient "r" and "logOR".
Supplying "none" will treat the effect sizes as unstandardized and
refrain from any transformations.
an effect size scale used to define priors. Defaults to "cohens_d".
Other options are "fishers_z", correlation coefficient "r",
and "logOR". The prior scale does not need to match the effect sizes measure -
the samples from prior distributions are internally transformed to match the
transformation of the data. The prior_scale corresponds to
the effect size scale of default output, but can be changed within the summary function.
whether continuous predictors should be standardized prior to
estimating the model. Defaults to TRUE. Continuous predictor standardization is important
for applying the default prior distributions for continuous predictors. Note that the resulting
output corresponds to standardized meta-regression coefficients.
the expected direction of the effect. Correctly specifying
the expected direction of the effect is crucial for one-sided selection models,
as they specify cut-offs using one-sided p-values. Defaults to "positive"
(another option is "negative").
named list of prior distributions for each predictor
(with names corresponding to the predictors). It allows users to
specify both the null and alternative hypothesis prior distributions
for each predictor by assigning the corresponding element of the named
list with another named list (with "null" and
"alt").
If only one prior is specified for a given parameter, it is
assumed to correspond to the alternative hypotheses and the default null
hypothesis is specified (i.e., prior_covariates_null or
prior_factors_null).
If a named list with only one named prior distribution is provided (either
"null" or "alt"), only this prior distribution is used and no
default distribution is filled in.
Parameters without specified prior distributions are assumed to be only adjusted
for using the default alternative hypothesis prior distributions (i.e.,
prior_covariates or prior_factors).
If priors is specified, test_predictors is ignored.
string specifying the RoBMA ensemble. Defaults to NULL.
The other options are "PSMA", "PP", and "2w" which override
settings passed to the priors_effect, priors_heterogeneity,
priors_effect, priors_effect_null, priors_heterogeneity_null,
priors_bias_null, and priors_effect. See details for more information
about the different model types.
a re-scaling factor for the prior distributions. The re-scaling
factor allows to adjust the width of all default priors simultaneously. Defaults to 1.
list of prior distributions for the effect size (mu)
parameter that will be treated as belonging to the alternative hypothesis. Defaults to
a standard normal distribution
prior(distribution = "normal", parameters = list(mean = 0, sd = 1)).
list of prior distributions for the heterogeneity tau
parameter that will be treated as belonging to the alternative hypothesis. Defaults to
prior(distribution = "invgamma", parameters = list(shape = 1, scale = .15)) that
is based on heterogeneities estimates from psychology erp2017estimatesRoBMA.
list of prior distributions for the publication bias adjustment
component that will be treated as belonging to the alternative hypothesis.
Defaults to list(
prior_weightfunction(distribution = "two.sided", parameters = list(alpha = c(1, 1),
steps = c(0.05)), prior_weights = 1/12),
prior_weightfunction(distribution = "two.sided", parameters = list(alpha = c(1, 1, 1),
steps = c(0.05, 0.10)), prior_weights = 1/12),
prior_weightfunction(distribution = "one.sided", parameters = list(alpha = c(1, 1),
steps = c(0.05)), prior_weights = 1/12),
prior_weightfunction(distribution = "one.sided", parameters = list(alpha = c(1, 1, 1),
steps = c(0.025, 0.05)), prior_weights = 1/12),
prior_weightfunction(distribution = "one.sided", parameters = list(alpha = c(1, 1, 1),
steps = c(0.05, 0.5)), prior_weights = 1/12),
prior_weightfunction(distribution = "one.sided", parameters = list(alpha = c(1, 1, 1, 1),
steps = c(0.025, 0.05, 0.5)), prior_weights = 1/12),
prior_PET(distribution = "Cauchy", parameters = list(0,1), truncation = list(0, Inf),
prior_weights = 1/4),
prior_PEESE(distribution = "Cauchy", parameters = list(0,5), truncation = list(0, Inf),
prior_weights = 1/4)
), corresponding to the RoBMA-PSMA model introduce by bartos2021no;textualRoBMA.
list of prior distributions for the effect size (mu)
parameter that will be treated as belonging to the null hypothesis. Defaults to
a point null hypotheses at zero,
prior(distribution = "point", parameters = list(location = 0)).
list of prior distributions for the heterogeneity tau
parameter that will be treated as belonging to the null hypothesis. Defaults to
a point null hypotheses at zero (a fixed effect meta-analytic models),
prior(distribution = "point", parameters = list(location = 0)).
list of prior weight functions for the omega parameter
that will be treated as belonging to the null hypothesis. Defaults no publication
bias adjustment, prior_none().
list of prior distributions for the correlation of random effects
(rho) parameter that will be treated as belonging to the alternative hypothesis. This setting allows
users to fit a hierarchical (three-level) meta-analysis when study_ids are supplied.
Note that this is an experimental feature and see News for more details. Defaults to a beta distribution
prior(distribution = "beta", parameters = list(alpha = 1, beta = 1)).
list of prior distributions for the correlation of random effects
(rho) parameter that will be treated as belonging to the null hypothesis. Defaults to NULL.
a prior distributions for the regression parameter
of continuous covariates on the effect size under the alternative hypothesis
(unless set explicitly in priors). Defaults to a relatively wide normal
distribution prior(distribution = "normal", parameters = list(mean = 0, sd = 0.25)).
a prior distributions for the regression parameter
of continuous covariates on the effect size under the null hypothesis
(unless set explicitly in priors). Defaults to a no effect
prior("spike", parameters = list(location = 0)).
a prior distributions for the regression parameter
of categorical covariates on the effect size under the alternative hypothesis
(unless set explicitly in priors). Defaults to a relatively wide
multivariate normal distribution specifying differences from the mean contrasts
prior_factor("mnormal", parameters = list(mean = 0, sd = 0.25), contrast = "meandif").
a prior distributions for the regression parameter
of categorical covariates on the effect size under the null hypothesis
(unless set explicitly in priors). Defaults to a no effect
prior("spike", parameters = list(location = 0)).
a string specifying the algorithm used for the model averaging. Defaults to "bridge"
which results in estimating individual models using JAGS and computing the marginal likelihood using bridge
sampling. An alternative is "ss" which uses spike and slab like parameterization to approximate the
Bayesian model averaging with a single model. Note that significantly more sample, burnin, and
adapt iterations are needed for the "ss" algorithm.
a number of chains of the MCMC algorithm.
a number of sampling iterations of the MCMC algorithm.
Defaults to 5000.
a number of burnin iterations of the MCMC algorithm.
Defaults to 2000.
a number of adaptation iterations of the MCMC algorithm.
Defaults to 500.
a thinning of the chains of the MCMC algorithm. Defaults to
1.
whether the individual models should be fitted in parallel.
Defaults to FALSE. The implementation is not completely stable
and might cause a connection error.
whether the model should be fitted until the convergence
criteria (specified in autofit_control) are satisfied. Defaults to
TRUE.
allows to pass autofit control settings with the
set_autofit_control() function. See ?set_autofit_control for
options and default settings.
automatic convergence checks to assess the fitted
models, passed with set_convergence_checks() function. See
?set_convergence_checks for options and default settings.
whether all models posterior distributions should be kept
after obtaining a model-averaged result. Defaults to "all" which
does not remove anything. Set to "min" to significantly reduce
the size of final object, however, some model diagnostics and further
manipulation with the object will not be possible.
a seed to be set before model fitting, marginal likelihood
computation, and posterior mixing for reproducibility of results. Defaults
to NULL - no seed is set.
whether all print messages regarding the fitting process
should be suppressed. Defaults to TRUE. Note that parallel = TRUE
also suppresses all messages.
additional arguments.
The vignette("/MetaRegression", package = "RoBMA")
vignette describes how to use RoBMA.reg() function to fit Bayesian meta-regression ensembles. See
bartos2023robust;textualRoBMA for more details about the methodology and
RoBMA() for more details about the function options. By default, the function standardizes
continuous predictors. As such, the output should be interpreted as standardized meta-regression
coefficients.
The RoBMA.reg function first generates models from a combination of the provided priors for each of the model parameters. Then, the individual models are fitted using autorun.jags function. A marginal likelihood is computed using bridge_sampler function. The individual models are then combined into an ensemble using the posterior model probabilities using BayesTools package.
Generic summary.RoBMA(), print.RoBMA(), and plot.RoBMA() functions are
provided to facilitate manipulation with the ensemble. A visual check of the
individual model diagnostics can be obtained using the diagnostics() function.
The fitted model can be further updated or modified by update.RoBMA() function.
Estimated marginal means can be computed by marginal_summary() function and
visualized by the marginal_plot() function.
RoBMA() summary.RoBMA(), update.RoBMA(), check_setup.reg()
if (FALSE) {
# using the example data from Andrews et al. (2021) and reproducing the example from
# Bartos et al. (2024) with measure and age covariate.
# note the the Andrews2021 data.frame columns identify the effect size "r" and
# the standard error "se" of the effect size that are used to estimate the model
fit_RoBMA <- RoBMA.reg(~ measure + age, data = Andrews2021, parallel = TRUE, seed = 1)
# summarize the results
summary(fit_RoBMA, output_scale = "r")
# compute effect size estimates for each group
marginal_summary(fit_RoBMA, output_scale = "r")
# visualize the effect size estimates for each group
marginal_plot(fit_RoBMA, parameter = "measure", output_scale = "r", lwd = 2)
}
Run the code above in your browser using DataLab