modmed.mlm.brms: Custom model fitting function for a 1-1-1 (moderated)...

In falkcarl/multilevelmediation: Utility Functions for Multilevel Mediation Analysis

Custom model fitting function for a 1-1-1 (moderated) mediation for the brms code

Description

Custom model fitting function for a 1-1-1 (moderated) mediation for the brms code

Usage

modmed.mlm.brms(
  data,
  L2ID,
  X,
  Y,
  M,
  moderator = NULL,
  mod.a = FALSE,
  mod.b = FALSE,
  mod.cprime = FALSE,
  covars.m = NULL,
  covars.y = NULL,
  random.a = FALSE,
  random.b = FALSE,
  random.cprime = FALSE,
  random.mod.a = FALSE,
  random.mod.b = FALSE,
  random.mod.cprime = FALSE,
  random.mod.m = FALSE,
  random.mod.y = FALSE,
  random.covars.m = NULL,
  random.covars.y = NULL,
  random.int.m = TRUE,
  random.int.y = TRUE,
  returndata = FALSE,
  family = gaussian,
  iter = 7000,
  control = list(adapt_delta = 0.95),
  chains = 4,
  ...
)

Arguments

data	Data frame in long format.
L2ID	(Character) Name of column that contains grouping variable in data (e.g., "SubjectID").
X	(Character) Name of column that contains the X independent variable in data.
Y	(Character) Name of column that contains the Y dependent variable in data.
M	(Character) Name of column that contains the M mediating variable in data.
moderator	Optional Character that contains name of column that contains the moderator variable in data
mod.a	(Logical) Add moderator to 'a' path (i.e., SmX:W, where W is the moderator)?
mod.b	(Logical) Add moderator to 'b' path (i.e., SyM:W, where W is the moderator)?
mod.cprime	(Logical) Add moderator to 'c' path (i.e., SyX:W, where W is the moderator)
covars.m	(Character vector) Optional covariates to include in the model for M.
covars.y	(Character vector) Optional covariates to include in the model for Y.
random.a	(Logical) Add random slope for 'a' path (i.e,. SmX)?
random.b	(Logical) Add random slope for 'b' path (i.e., SyM)?
random.cprime	(Logical) Add random slope for 'cprime' direct effect path (i.e., SyX)?
random.mod.a	(Logical) Add random slope for 'a' path moderator?
random.mod.b	(Logical) Add random slope for 'b' path moderator?
random.mod.cprime	(Logical) Add random slope for 'c' path moderator?
random.mod.m	(Logical) Add random slope for effect of moderator on M?
random.mod.y	(Logical) Add random slope for effect of moderator on Y?
random.covars.m	(Logical vector) Add random slopes for covariates on M?
random.covars.y	(Logical vector) Add random slopes for covariates on Y?
random.int.m	(Logical) Add random intercept for M? (defaults to TRUE)
random.int.y	(Logical) Add random intercept for Y? (defaults to TRUE)
returndata	(Logical) Whether to save restructured data in its own slot. Defaults to FALSE.
family	Argument passed to brm A character string naming the distribution of the response variable to be used in the model.
iter	Argument passed to brm Number of total iterations.
control	Argument passed to brm To decrease (or eliminate at best) the number of divergent transitions that cause a bias in the obtained posterior samples.
chains	Argument passed to brm Set the number of chains
...	Additional arguments to pass to brm

Details

Implements custom function to do (moderated) mediation with two-level multilevel models with Bayesian estimation via the brms package. Does not handle covariates at the moment. Bayesian estimation using brms was studied by Falk, Vogel, Hammami & Miočević (in press). It is suggested if you use this function that you also do cite("brms") to figure out how to cite that package.

Value

A list with the following elements:

• model The fitted model from brm. Use as you would a fitted model from that package.

• args Arguments used to call the function. Useful for later automating extraction of the indirect effect or other quantities.

• conv Whether brm finished estimation, not diagnostic of convergence.

References

Falk, C. F., Vogel, T., Hammami, S., & Miočević, M. (in press). Multilevel mediation analysis in R: A comparison of bootstrap and Bayesian approaches. Behavior Research Methods. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3758/s13428-023-02079-4")} Preprint: \Sexpr[results=rd]{tools:::Rd_expr_doi("10.31234/osf.io/ync34")}

Paul-Christian Bürkner (2017). brms: An R Package for Bayesian Multilevel Models Using Stan. Journal of Statistical Software, 80(1), 1-28. doi:10.18637/jss.v080.i01

Examples

# Note: 2000 iterations is just an example so that run time is not too long.
# Pick something larger (e.g., 5000+) in practice

# Example data for 1-1-1 w/o moderation
data(BPG06dat)

# random effects for a and b paths (and intercept), no moderation
# (For moderation, note that modmed.mlm syntax is typically the same)
fit<-modmed.mlm.brms(BPG06dat,"id", "x", "y" , "m", cores=2,
                     random.a=TRUE, random.b=TRUE,
                     iter = 2000, control = list(adapt_delta=0.95),
                     seed = 1234)

# Examine model results and some diagnostics
summary(fit$model)

# Potential scale reduction (PSR) or Rhat guidelines vary but the largest
#  should be close to 1 ( < 1.1, < 1.05, < 1.01).
# It is also possible to extract all of them.
max(brms::rhat(fit$model)) # largest rhat

# Fit (loo and WAIC)
brms::loo(fit$model)
brms::waic(fit$model)

# Point and interval estimates, diagnostics, for quantities of interest

# Traceplots: TODO, list conversions for how brms represents parameters with
# How these are colloquially referred to in mediation literature.
plot(fit$model, variable="b_SmX") # this is traceplot for one parameter

# Example of extracting/computing intervals for particular quantities
res.indirect <- extract.modmed.mlm.brms(fit, "indirect")
res.a <- extract.modmed.mlm.brms(fit, "a")
res.b <- extract.modmed.mlm.brms(fit, "b")
res.cprime <- extract.modmed.mlm.brms(fit, "cprime")

# Summary of results is in CI slot, example:
res.indirect$CI

# 99% CI
res.indirect <- extract.modmed.mlm.brms(fit, "indirect", ci.conf = .99)

falkcarl/multilevelmediation documentation built on Jan. 11, 2025, 5:16 a.m.