Title: Bayesian Multilevel Mediation
Version: 1.3.15
Date: 2023-09-25
Description: Easy estimation of Bayesian multilevel mediation models with Stan.
URL: https://github.com/mvuorre/bmlm/
BugReports: https://github.com/mvuorre/bmlm/issues/
License: GPL (≥ 3)
LazyData: true
NeedsCompilation: yes
Depends: R (≥ 3.4.0), Rcpp (≥ 0.12.0)
Imports: ggplot2 (≥ 2.0.0), methods, RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), rstantools (≥ 2.3.1.1)
Suggests: qgraph, knitr, rmarkdown, reshape2, dplyr
LinkingTo: BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), StanHeaders (≥ 2.26.0)
RoxygenNote: 7.1.2
Encoding: UTF-8
SystemRequirements: GNU make
Biarch: true
Packaged: 2023-09-25 11:42:03 UTC; matti
Author: Matti Vuorre ORCID iD [aut, cre]
Maintainer: Matti Vuorre <m.j.vuorre@tilburguniversity.edu>
Repository: CRAN
Date/Publication: 2023-09-25 14:22:24 UTC

bmlm: Easy estimation of Bayesian multilevel mediation models with Stan.

Description

See https://mvuorre.github.io/bmlm/ for a short tutorial.

Relationship between work stressors, work dissatisfaction, and relationship dissatisfaction.

Description

Simulated data from Intensive Longitudinal Methods: An Introduction to Diary and Experience Sampling Research. (Bolger, & Laurenceau, 2013, chapter 9; http://www.intensivelongitudinal.com/index.html).

Usage

data(BLch9)

Format

A data frame with 2100 rows and 8 variables:

id

ID of study participant

time

Time

fwkstrs

Number of work stressors

fwkdis

Work dissatisfaction rating

freldis

Relationship dissatisfaction

x

Subject-mean deviated number of work stressors

m

Subject-mean deviated work dissatisfaction rating

y

Subject-mean deviated relationship dissatisfaction

Source

http://www.intensivelongitudinal.com/datasets.html

Judgments of performance in a video game

Description

Data from an experiment where participants rated their performance in a video game in two conditions. (Experiment 1 in Metcalfe, Eich, & Castel, 2010; https://www.sciencedirect.com/science/article/pii/S0010027710001113).

Usage

data(MEC2010)

Format

A data frame with 344 rows and 4 variables:

subj

Subject id number.

lag

Lag condition (0 = no lag, 1 = 250ms lag).

hr

Hit rate.

jop

Judgment of Performance.

Source

Metcalfe, J., Eich, T. S., & Castel, A. D. (2010). Metacognition of agency across the lifespan. Cognition, 116(2), 267-282. doi:10.1016/j.cognition.2010.05.009

Create isolated within- (and optionally between-) person variables.

Description

Creates variables that represent pure within- and between-person predictors.

Usage

isolate(d = NULL, by = NULL, value = NULL, z = FALSE, which = "within")

Arguments

d

A data.frame.

by

A vector of values in d by which the data is clustered. i.e. a vector of unique participant IDs.

value

Names of columns in d to isolate. Multiple values can be given by value = c("var1", "var2", "var3")

z

Should the created values be standardized (defaults to FALSE).

which

Which component to return. "within" (default) returns within-person deviations only; "between" returns between-person means only; "both" returns both.

Value

A data.frame with additional columns for the within- and between-person variables. The new columns are labelled _cw for centered-within and _cb for centered-between.

Author(s)

Matti Vuorre mv2521@columbia.edu

Examples

# Create within-person deviations of work stressors in BLch9.
data(BLch9)
BLch9 <- isolate(BLch9, by = "id", value = "fwkstrs")
head(BLch9)  # Now has new column for within-person work stressors.

Estimate a multilevel mediation model

Description

Estimates a Bayesian multilevel mediation model using Stan.

Usage

mlm(
  d = NULL,
  id = "id",
  x = "x",
  m = "m",
  y = "y",
  priors = NULL,
  binary_y = FALSE,
  ...
)

Arguments

d

A data.frame or a data_frame.

id

Column of participant IDs in data.

x

Column of X values in data.

m

Column of M values in data.

y

Column of Y values in data.

priors

A list of named values to be used as the prior scale parameters. See details.

binary_y

Set to TRUE if y is binary and should be modelled with logistic regression. Defaults to FALSE (y treated as continuous.) This feature is experimental.

...

Other optional parameters passed to rstan::stan().

Details

Draw samples from the joint posterior distribution of a multilevel mediation model using Stan.

Priors

Users may pass a list of named values for the priors argument. The values will be used to define the scale parameter of the respective prior distributions. This list may specify some or all of the following parameters:

dy, dm

Regression intercepts (for Y and M as outcomes, respectively.)

a, b, cp

Regression slopes.

tau_x

Varying effects SDs for above parameters (e.g replace x with a.)

lkj_shape

Shape parameter for the LKJ prior.

See examples for specifying the following: Gaussian distributions with SD = 10 as priors for the intercepts, Gaussians with SD = 2 for the slopes, Half-Cauchy distributions with scale parameters 1 for the varying effects SDs, and an LKJ prior of 2.

Value

An object of S4 class stanfit, with all its available methods.

Author(s)

Matti Vuorre mv2521@columbia.edu

Examples

## Not run: 
## Run example from Bolger and Laurenceau (2013)
data(BLch9)
fit <- mlm(BLch9)
mlm_summary(fit)

### With priors
Priors <- list(dy = 10, dm = 10, a = 2, b = 2, cp = 2,
               tau_dy = 1, tau_dm = 1, tau_a = 1, tau_b = 1, tau_cp = 1,
               lkj_shape = 2)
fit <- mlm(BLch9, priors = Priors)

## End(Not run)

Plot estimated parameters of multilevel mediation model

Description

Plot the model's estimated parameters as histograms or a coefficient plot.

Usage

mlm_pars_plot(
  mod = NULL,
  type = "hist",
  color = "black",
  p_shape = 15,
  p_size = 1.2,
  level = 0.95,
  nrow = 3,
  pars = c("a", "b", "cp", "covab", "me", "c", "pme")
)

Arguments

mod

A Stanfit model estimated with mlm().

type

Type of the plot, hist, coef, or violin.

color

Color (and fill) for plots.

p_shape

Shape of points for coefplot.

p_size

Size of points for coefplot.

level

X level for Credible Intervals. (Defaults to .95.)

nrow

Number of rows for multiple histograms.

pars

Which parameters to plot.

Details

The point estimate for the coefficient plot is the posterior mean.

Value

A ggplot2 object.

Author(s)

Matti Vuorre mv2521@columbia.edu

Plot bmlm's mediation model as a path diagram

Description

Plots a path diagram for an estimated multilevel mediation model.

Usage

mlm_path_plot(
  mod = NULL,
  xlab = "X",
  ylab = "Y",
  mlab = "M",
  level = 0.95,
  random = TRUE,
  text = FALSE,
  id = NULL,
  digits = 2,
  ...
)

Arguments

mod

A Stanfit model estimated with mlm().

xlab

Label for X

ylab

Label for Y

mlab

Label for M

level

"Confidence" level for credible intervals. (Defaults to .95.)

random

Should the "random" effects SDs be displayed? (Default = TRUE)

text

Should additional parameter values be displayed? (Defaults to FALSE.)

id

Plot an individual-level path diagram by specifying ID number.

digits

Number of significant digits to show on graph. (Default = 2.)

...

Other arguments passed on to qgraph::qgraph().

Details

Plots a path diagram of the mediation model, with estimated parameter values and credible intervals. Can also be used to draw a template diagram of the mediation model by not specifying input to the mod argument.

To modify various settings of the underlying qgraph object, see qgraph.

Value

A qgraph object.

Author(s)

Matti Vuorre mv2521@columbia.edu

Examples

# Draw a template path diagram of the mediation model
mlm_path_plot()

Plot fitted values of M and Y from multilevel mediation model

Description

Plot population-level fitted values and X values, for M and Y.

Usage

mlm_spaghetti_plot(
  mod = NULL,
  d = NULL,
  id = "id",
  x = "x",
  m = "m",
  y = "y",
  level = 0.95,
  n = 12,
  binary_y = FALSE,
  mx = "fitted",
  fixed = TRUE,
  random = TRUE,
  h_jitter = 0,
  v_jitter = 0,
  bar_width = 0.2,
  bar_size = 0.75,
  n_samples = NA
)

Arguments

mod

A multilevel mediation model estimated with mlm().

d

A data.frame or a data_frame used in fitting model.

id

Name of id variable (identifying subjects) in data (d).

x

Name of X variable in data.

m

Name of M variable in data.

y

Name of Y variable in data.

level

X level for Credible Intervals. (Defaults to .95.)

n

Number of points along X to evaluate fitted values on. See details.

binary_y

Set to TRUE if the outcome variable (Y) is 0/1.

mx

Should the X axis of the M-Y figure be "fitted" values, or "data" values. Defaults to "fitted".

fixed

Should the population-level ("fixed") fitted values be shown?

random

Should the subject-level ("random") fitted values be shown?

h_jitter

Horizontal jitter of points. Defaults to 0.

v_jitter

Vertical jitter of points. Defaults to 0.

bar_width

Width of the error bars. Defaults to 0.2.

bar_size

Thickness of the error bars. Defaults to 0.75.

n_samples

Number of MCMC samples to use in calculating fitted values. See details.

Details

If n = 2, the fitted values will be represented as points with X line with a Confidence Ribbon instead. If a very large model is fitted with a large number of MCMC iterations, the function might take a long time to run. In these cases, users can set n_samples to a smaller value (e.g. 1000), in which case the fitted values (and the CIs) will be based on a random subset of n_samples MCMC samples. The default value is NA, meaning that all MCMC samples are used.

Value

A list of two ggplot2 objects.

Author(s)

Matti Vuorre mv2521@columbia.edu

Print a summary of the estimated multilevel mediation model

Description

Prints the estimated parameters (numerical summaries of the marginal posterior distributions).

Usage

mlm_summary(
  mod = NULL,
  level = 0.95,
  pars = c("a", "b", "cp", "me", "c", "pme"),
  digits = 2
)

Arguments

mod

A stanfit object obtained from mlm()

level

"Confidence" level; Defines the limits of the credible intervals. Defaults to .95 (i.e. displays 95% CIs.)

pars

Parameters to summarize. Defaults to main average-level parameters. See Details for more information.

digits

How many decimal points to display in the output. Defaults to 2.

Details

After estimating a model (drawing samples from the joint posterior probability distribution) with mlm(), show the estimated results by using mlm_summary(fit), where fit is an object containing the fitted model.

The function shows, for each parameter specified with pars, the posterior mean, and limits of the Credible Interval as specified by level. For example, level = .91 shows a 91% Credible Interval, which summarizes the central 91% mass of the marginal posterior distribution.

Parameters

By default, mlm() estimates and returns a large number of parameters, including the varying effects, and their associated standard deviations. However, mlm_summay() by default only displays a subset of the estimated parameters:

a

Regression slope of the X -> M relationship.

b

Regression slope of the M -> Y relationship.

cp

Regression slope of the X -> Y relationship. (Direct effect.)

me

Mediated effect (a * b + \sigma_{{a_j}{b_j}}).

c

Total effect of X on Y. ( cp + me )

pme

Percent mediated effect.

The user may specify pars = NULL to display all estimated parameters. Other options include e.g. pars = "tau" to display the varying effects' standard deviations. To display all the group-level parameters (also known as random effects) only, specify pars = "random". With this argument, mlm_summary() prints the following parameters:

tau_a

Standard deviation of subject-level a_js.

tau_b

Standard deviation of subject-level b_js.

tau_cp

Standard deviation of subject-level c\'_js.

covab

Estimated covariance of a_j and b_js.

corrab

Estimated correlation of a_j and b_js.

To learn more about the additional parameters, refer to the Stan code (cat(get_stancode(fit))).

Value

A data.frame summarizing the estimated multilevel mediation model:

Parameter

Name of parameter

Mean

Mean of parameter's posterior distribution.

Median

Median of parameter's posterior distribution.

SE

Standard deviation of parameter's posterior distribution.

ci_lwr

The lower limit of Credible Intervals.

ci_upr

The upper limit of Credible Intervals.

n_eff

Number of efficient samples.

Rhat

Should be 1.00.

Author(s)

Matti Vuorre mv2521@columbia.edu