R: Estimate a Robust Bayesian Meta-Analysis Meta-Regression

RoBMA.reg {RoBMA}

R Documentation

Estimate a Robust Bayesian Meta-Analysis Meta-Regression

Description

RoBMA is used to estimate a Robust Bayesian Meta-Analysis. The interface allows a complete customization of the ensemble with different prior (or list of prior) distributions for each component.

Usage

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,
  priors_effect = prior(distribution = "normal", parameters = list(mean = 0, sd = 1)),
  priors_heterogeneity = prior(distribution = "invgamma", parameters = list(shape = 1,
    scale = 0.15)),
  priors_bias = 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.1)), 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)),
  priors_effect_null = prior(distribution = "point", parameters = list(location = 0)),
  priors_heterogeneity_null = prior(distribution = "point", parameters = list(location =
    0)),
  priors_bias_null = prior_none(),
  priors_hierarchical = prior("beta", parameters = list(alpha = 1, beta = 1)),
  priors_hierarchical_null = NULL,
  prior_covariates = prior("normal", parameters = list(mean = 0, sd = 0.25)),
  prior_covariates_null = prior("spike", parameters = list(location = 0)),
  prior_factors = prior_factor("mnormal", parameters = list(mean = 0, sd = 0.25),
    contrast = "meandif"),
  prior_factors_null = prior_factor("spike", parameters = list(location = 0), contrast =
    "meandif"),
  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,
  ...
)

Arguments

`formula`	a formula for the meta-regression model
`data`	a data object created by the `combine_data` function. This is an alternative input entry to specifying the `d`, `r`, `y`, etc... directly. I.e., you cannot pass the a data.frame and reference to the columns.
`test_predictors`	vector of predictor names that will be test (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.
`study_names`	an optional argument with the names of the studies
`study_ids`	an optional argument specifying dependency between the studies (for using a multilevel model). Defaults to `NULL` for studies being independent.
`transformation`	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.
`prior_scale`	a 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 scale of default output, but can be changed within the summary function.
`standardize_predictors`	whether continuous predictors should be standardized prior to estimating the model. Defaults to `TRUE`.
`effect_direction`	the expected direction of the effect. The one-sided selection sets the weights omega to 1 to significant results in the expected direction. Defaults to `"positive"` (another option is `"negative"`).
`priors`	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.
`model_type`	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.
`priors_effect`	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))`.
`priors_heterogeneity`	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 (van Erp et al. 2017).
`priors_bias`	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 Bartoš et al. (2022).
`priors_effect_null`	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))`.
`priors_heterogeneity_null`	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))`.
`priors_bias_null`	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()`.
`priors_hierarchical`	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))`.
`priors_hierarchical_null`	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`.
`prior_covariates`	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))`.
`prior_covariates_null`	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))`.
`prior_factors`	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")`.
`prior_factors_null`	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))`.
`chains`	a number of chains of the MCMC algorithm.
`sample`	a number of sampling iterations of the MCMC algorithm. Defaults to `5000`.
`burnin`	a number of burnin iterations of the MCMC algorithm. Defaults to `2000`.
`adapt`	a number of adaptation iterations of the MCMC algorithm. Defaults to `500`.
`thin`	a thinning of the chains of the MCMC algorithm. Defaults to `1`.
`parallel`	whether the individual models should be fitted in parallel. Defaults to `FALSE`. The implementation is not completely stable and might cause a connection error.
`autofit`	whether the model should be fitted until the convergence criteria (specified in `autofit_control`) are satisfied. Defaults to `TRUE`.
`autofit_control`	allows to pass autofit control settings with the `set_autofit_control()` function. See `?set_autofit_control` for options and default settings.
`convergence_checks`	automatic convergence checks to assess the fitted models, passed with `set_convergence_checks()` function. See `?set_convergence_checks` for options and default settings.
`save`	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.
`seed`	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.
`silent`	whether all print messages regarding the fitting process should be suppressed. Defaults to `TRUE`. Note that `parallel = TRUE` also suppresses all messages.
`...`	additional arguments.

Details

See RoBMA() for more details.

Note that these default prior distributions are relatively wide and more informed prior distributions for testing for the presence of moderation should be considered.

Value

RoBMA.reg returns an object of class 'RoBMA.reg'.

References

Bartoš F, Maier M, Wagenmakers E, Doucouliagos H, Stanley TD (2022). “Robust Bayesian meta-analysis: Model-averaging across complementary publication bias adjustment methods.” Research Synthesis Methods. doi:10.1002/jrsm.1594.

van Erp S, Verhagen J, Grasman RP, Wagenmakers E (2017). “Estimates of between-study heterogeneity for 705 meta-analyses reported in Psychological Bulletin from 1990–2013.” Journal of Open Psychology Data, 5(1). doi:10.5334/jopd.33.