bselmodel: Bayesian Selection Model

Description

Function for fitting random-effects, meta-regression, multilevel, and location-scale meta-analytic selection models.

Usage

bselmodel(
  yi,
  vi,
  sei,
  weights,
  ni,
  mods,
  scale,
  cluster,
  data,
  slab,
  subset,
  measure,
  prior_effect,
  prior_heterogeneity,
  prior_mods,
  prior_scale,
  prior_heterogeneity_allocation,
  prior_bias,
  standardize_continuous_predictors = TRUE,
  set_contrast_factor_predictors = "treatment",
  prior_unit_information_sd,
  rescale_priors = 1,
  prior_informed_field,
  prior_informed_subfield,
  effect_direction = "detect",
  steps,
  sample = 5000,
  burnin = 2000,
  adapt = 500,
  chains = 3,
  thin = 1,
  parallel = FALSE,
  autofit = FALSE,
  autofit_control = set_autofit_control(),
  convergence_checks = set_convergence_checks(),
  seed = NULL,
  silent,
  ...
)

Value

A fitted object of class c("bselmodel", "brma") containing a single Bayesian selection model fit.

Arguments

yi: a vector of effect sizes, or a formula with the effect size on the left-hand side and location moderators on the right-hand side (for example yi ~ x1 + x2). If a formula is supplied, mods must not be specified.
vi: a vector of sampling variances. Either vi or sei must be supplied for normal models.
sei: a vector of standard errors. Either vi or sei must be supplied for normal models.
weights: an optional vector of positive likelihood weights. For normal/effect-size models, each weight powers the estimate likelihood. For constructors with GLMM raw-count input, each weight powers the paired two-arm likelihood for one study.
ni: an optional vector of sample sizes. Used for measure = "GEN" or when estimating "UISD").
mods: an optional matrix, data.frame, or formula specifying location moderators (meta-regressors). Formula input is evaluated in data.
scale: an optional matrix, data.frame, or formula specifying scale predictors for location-scale models. Formula input is evaluated in data.
cluster: an optional vector of cluster identifiers for multilevel meta-analysis.
data: an optional data frame containing the variables.
slab: an optional vector of study labels.
subset: an optional logical or numeric vector specifying a subset of data to be used.
measure: a character string specifying the effect size measure. Normal/effect-size constructors require an explicit value and support "SMD", "ZCOR", "RR", "OR", "HR", "RD", "IRR", and "GEN". Use "GEN" only for general effect sizes without a known unit information standard deviation. GLMM raw-count constructors support only "OR" and "IRR" and default to "OR".
prior_effect: prior distribution for the effect size (\(\mu\)) parameter (the intercept). If omitted, a default prior is constructed. In single-model functions, explicit NULL or FALSE sets a spike at zero.
prior_heterogeneity: prior distribution for the heterogeneity (\(\tau\)) parameter. If omitted, a default prior is constructed. In single-model functions, explicit NULL or FALSE sets a spike at zero.
prior_mods: prior distribution for the moderators (\(\beta\)) parameters. A single prior applies to all terms; a named list can specify term-specific priors. If omitted or NULL, default priors are used.
prior_scale: prior distribution for the scale (\(\delta\)) parameters. A single prior applies to all terms; a named list can specify term-specific priors. If omitted or NULL, default priors are used.
prior_heterogeneity_allocation: prior distribution for the fraction of heterogeneity allocated to the cluster-level component in multilevel models (\(\rho\)). If omitted or NULL, defaults to Beta(1, 1).
prior_bias: selection-model bias prior, usually created by prior_weightfunction(). If omitted or NULL, a default one-sided weightfunction prior is constructed from steps.
standardize_continuous_predictors: logical. Whether to standardize continuous predictors. Defaults to TRUE.
set_contrast_factor_predictors: character. How to set contrast for factor predictors. Defaults are constructor-specific and shown in each function usage; single-model constructors use "treatment", while model-averaging constructors use "meandif".
prior_unit_information_sd: numeric. The unit information standard deviation (\(\sigma_{unit}\)). Cannot be used together with prior_informed_field.
rescale_priors: numeric. A scaling factor for supported prior distributions. Point and none priors are unchanged. For constructors with publication-bias prior distributions, rescale_priors does not rescale them except for the default PEESE prior's UISD adjustment. Defaults to 1.
prior_informed_field: character. The field of the informed prior distributions. Omit to use the standard default prior specification; explicit NULL is invalid.
prior_informed_subfield: character. The subfield of the informed prior distributions. Omit to use the field-specific default, such as "Cochrane" for prior_informed_field = "medicine"; explicit NULL is invalid.
effect_direction: direction used by publication-bias adjustments. "positive" assumes statistically significant positive estimates are more likely to be selected; "negative" mirrors the selection direction; "detect" infers the direction from the fitted data.
steps: numeric vector of one-sided p-value cut points for the default selection model. If prior_bias is supplied, the prior carries its own side, steps, and weights. If omitted, the default is 0.025, yielding intervals [0, .025] and (.025, 1].
sample: numeric. Number of MCMC samples to save. Defaults to 5000.
burnin: numeric. Number of burn-in iterations. Defaults to 2000.
adapt: numeric. Number of adaptation iterations. Defaults to 500.
chains: numeric. Number of MCMC chains. Defaults to 3.
thin: numeric. Thinning interval. Defaults to 1.
parallel: logical. Whether to run MCMC chains in parallel. Defaults to FALSE.
autofit: logical. Whether to automatically extend the MCMC chains if convergence is not met. Defaults to FALSE.
autofit_control: list of autofit control settings. See set_autofit_control() for details.
convergence_checks: list of convergence check settings. See set_convergence_checks() for details.
seed: numeric. Random seed for reproducibility. Defaults to NULL.
silent: logical. Whether to suppress output. Constructors with no explicit default use RoBMA.get_option("silent") when silent is omitted. Model-averaging wrappers default to TRUE unless explicitly changed.
...: additional advanced arguments. Fitting functions reject unused arguments; currently recognized internal arguments include only_data, only_priors, is_JASP, and is_JASP_prefix.

Details

bselmodel() is a normal/effect-size selection-model constructor. Custom prior_bias can be a weightfunction prior or a supported BayesTools selection-kernel prior; p-hacking kernels are not supported in active RoBMA.

Examples

Run this code

if (FALSE) {
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")

  fit <- bselmodel(
    yi      = yi,
    vi      = vi,
    data    = dat.lehmann2018,
    measure = "SMD",
    steps   = 0.025,
    seed    = 1,
    silent  = TRUE
  )

  summary(fit)
  funnel(fit)
}
}