RoBMA (version 1.2.0)

update.RoBMA: Updates a fitted RoBMA object

Description

update.RoBMA can be used to

1. add an additional model to an existing "RoBMA" object by specifying either a null or alternative prior for each parameter and the prior odds of the model (prior_odds), see the vignette("CustomEnsembles") vignette,

2. change the prior odds of fitted models by specifying a vector prior_odds of the same length as the fitted models,

3. refitting models that failed to converge with updated settings of control parameters,

4. or changing the convergence criteria and recalculating the ensemble results by specifying new control argument and setting refit_failed == FALSE.

Usage

# S3 method for RoBMA
update(
  object,
  refit_failed = TRUE,
  prior_mu = NULL,
  prior_tau = NULL,
  prior_omega = NULL,
  prior_odds = NULL,
  prior_mu_null = NULL,
  prior_tau_null = NULL,
  prior_omega_null = NULL,
  study_names = NULL,
  control = NULL,
  chains = NULL,
  iter = NULL,
  burnin = NULL,
  thin = NULL,
  parallel = NULL,
  seed = NULL,
  ...
)

Arguments

object

a fitted RoBMA object.

refit_failed

whether failed models should be refitted. Relevant only if new priors or prior_odds are not supplied. Defaults to TRUE.

prior_mu

a prior distribution for the mu parameter that will be treated as belonging to the alternative hypothesis.

prior_tau

a prior distribution for the tau parameter that will be treated as belonging to the alternative hypothesis.

prior_omega

a prior weight function for the omega parameter that will be treated as belonging to the alternative hypothesis.

prior_odds

either a single value specifying prior model odds of a newly specified model using priors argument, or a vector of the same length as already fitted models to update their prior odds.

prior_mu_null

list of prior distribution for the mu parameter that will be treated as belonging to the null hypothesis. Defaults to point distribution with location at 0 ( prior(distribution = "point", parameters = list(location = 0))).

prior_tau_null

a prior distribution for the tau parameter that will be treated as belonging to the null hypothesis.

prior_omega_null

a prior weight function for the omega parameter that will be treated as belonging to the null hypothesis.

study_names

an optional argument with the names of the studies.

control

a list of additional arguments for the MCMC algorithm. Possible options are:

autofit

Whether the models should be refitted until convergence. Defaults to FALSE

max_error

The target MCMC error for the autofit function. The argument is passed to raftery.diag as 'r'. Defaults to .01.

max_rhat

The target Rhat error for the autofit function. The argument is passed to add.summary as 'psrf.target'. Defaults to 1.05.

max_time

A string specifying the maximum fitting time in case of autofit. Defaults to Inf. Can be specified as a number and a unit (Acceptable units include <U+2019>seconds<U+2019>, <U+2019>minutes<U+2019>, <U+2019>hours<U+2019>, <U+2019>days<U+2019>, <U+2019>weeks<U+2019>, or the first letter(s) of each), i.e. "1hr".

adapt

A number of iterations used for MCMC adaptation. Defaults to 1000.

bridge_max_iter

Maximum number of iterations for the bridge_sampler function. Defaults to 10000

allow_max_error

Maximum allowed MCMC error for a model to be taken into consideration. The model will be removed from the ensemble if it fails to achieve the set MCMC error. Defaults to NULL - no model will be removed based on MCMC error.

allow_max_rhat

Maximum allowed Rhat for a model to be taken into consideration. Model will be removed from the ensemble if it fails to achieve the set Rhat. Defaults to NULL - no model will be removed based on Rhat.

allow_min_ESS

Minimum allowed ESS for a model to be taken into consideration. Model will be removed from the ensemble if it fails to achieve the set ESS. Defaults to NULL - no model will be removed based on ESS.

balance_prob

Whether the prior probability of the removed model should be redistributed to other models with the same type if possible (crossing of effect / heterogeneity / publication bias). Defaults to TRUE.

silent

Whether all fitting messages should be suppressed. Defaults to FALSE. Ideal for getting rid of the "full precision may not have been achieved in pntfinal'" warning that cannot be suppressed in any other way.

boost

Whether the likelihood functions implemented using the boost C++ library should be used as the first option. The higher precision of boost allows to estimate models in difficult cases. Defaults to FALSE. The R distributions are used as default and boost is used only if they fail. Warning: the estimation using boost takes about twice as long.

cores

Number of cores to bu used fo parallel computation. If parallel == TRUE, the default number is equal to number of cores - 1, and 1 (no parallel processing otherwise).

chains

a number of chains of the MCMC algorithm.

iter

a number of sampling iterations of the MCMC algorithm. Defaults to 10000, with a minimum of 4000.

burnin

a number of burnin iterations of the MCMC algorithm. Defaults to 5000.

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 cores argument within the control list will overwrite the setting if specified to a number higher than 1.

seed

a seed to be set before model fitting, marginal likelihood computation, and posterior mixing for exact results reproducibility. Defaults to NULL - no seed is set.

...

additional arguments.

Value

RoBMA returns an object of class "RoBMA".

Details

See RoBMA() for more details.

See Also

RoBMA(), summary.RoBMA(), prior(), check_setup()

Examples

# NOT RUN {
# using the example data from Anderson et al. 2010 and fitting the default model
# (note that the model can take a while to fit)
fit <- RoBMA(r = Anderson2010$r, n = Anderson2010$n, study_names = Anderson2010$labels)

# the update function allows us to change the prior model probability of each model
fit1 <- update(fit, prior_odds = c(10,1,1,1,1,1,1,1,1,1,1,1))

# add an additional model with different priors specification (see '?prior' for more information)
fit2 <- update(fit,
               priors_mu_null = prior("point", parameters = list(location = 0)),
               priors_tau = prior("normal",
                                  parameters = list(mean = 0, sd = 1),
                                  truncation = list(lower = 0, upper = Inf)),
               priors_omega = prior("one-sided",
                                    parameters = list(cuts = c(.05), alpha = c(1, 1))))

# change the model convergence criteria to mark models with ESS lower than 2000 as non-covergent
fit3 <- update(fit, control = list(allow_min_ESS = 2000))

# and refit them failed models with increased number of burnin iterations
fit4 <- update(fit3, burnin = 10000)

# }
# NOT RUN {
# }