q_mediation: Mediation Models By Regression

Description

Simple-to-use functions for fitting regression models and testing indirect effects using just one function.

Usage

q_mediation(
  x,
  y,
  m = NULL,
  cov = NULL,
  data = NULL,
  boot_ci = TRUE,
  level = 0.95,
  R = 100,
  seed = NULL,
  boot_type = c("perc", "bc"),
  model = NULL,
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = TRUE
)
q_simple_mediation(
  x,
  y,
  m = NULL,
  cov = NULL,
  data = NULL,
  boot_ci = TRUE,
  level = 0.95,
  R = 100,
  seed = NULL,
  boot_type = c("perc", "bc"),
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = TRUE
)
q_serial_mediation(
  x,
  y,
  m = NULL,
  cov = NULL,
  data = NULL,
  boot_ci = TRUE,
  level = 0.95,
  R = 100,
  seed = NULL,
  boot_type = c("perc", "bc"),
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = TRUE
)
q_parallel_mediation(
  x,
  y,
  m = NULL,
  cov = NULL,
  data = NULL,
  boot_ci = TRUE,
  level = 0.95,
  R = 100,
  seed = NULL,
  boot_type = c("perc", "bc"),
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = TRUE
)
# S3 method for q_mediation
print(
  x,
  digits = 4,
  annotation = TRUE,
  pvalue = TRUE,
  pvalue_digits = 4,
  se = TRUE,
  for_each_path = FALSE,
  se_ci = TRUE,
  wrap_computation = TRUE,
  lm_ci = TRUE,
  lm_beta = TRUE,
  lm_ci_level = 0.95,
  ...
)

Value

The function q_mediation() returns a q_mediation class object, with its print method.

The function q_simple_mediation() returns a q_simple_mediation class object, which is a subclass of q_mediation.

The function q_serial_mediation() returns a q_serial_mediation class object, which is a subclass of q_mediation.

The function q_parallel_mediation() returns a q_parallel_mediation class object, which is a subclass of q_mediation.

Arguments

x: For q_mediation(), q_simple_mediation(), q_serial_mediation(), and q_parallel_mediation(), it is the name of the predictor. For the print method of these functions, x is the output of these functions.
y: The name of the outcome.
m: A character vector of the name(s) of the mediator(s). For a simple mediation model, it must has only one name. For serial and parallel mediation models, it can have one or more names. For a serial mediation models, the direction of the paths go from the first names to the last names. For example, c("m1", "m3", "m4") denoted that the path is m1 -> m3 -> m4.
cov: The names of the covariates, if any. If it is a character vector, then the outcome (y) and all mediators (m) regress on all the covariates. If it is a named list of character vectors, then the covariates in an element predict only the variable with the name of this element. For example, list(m1 = "c1", dv = c("c2", "c3")) indicates that c1 predicts "m1", while c2 and c3 predicts "dv". Default is NULL, no covariates.
data: The data frame. Note that listwise deletion will be used and only cases with no missing data on all variables in the model (e.g., x, m, y and cov) will be retained.
boot_ci: Logical. Whether bootstrap confidence interval will be formed. Default is TRUE.
level: The level of confidence of the confidence interval. Default is .95 (for 95% confidence intervals).
R: The number of bootstrap samples. Default is 100. Should be set to 5000 or at least 10000.
seed: The seed for the random number generator. Default is NULL. Should nearly always be set to an integer to make the results reproducible.
boot_type: The type of the bootstrap confidence intervals. Default is "perc", percentile confidence interval. Set "bc" for bias-corrected confidence interval.
model: The type of model. For q_mediation(), it can be "simple" (simple mediation model), "serial" (serial mediation model), or "parallel" (parallel mediation model). It is recommended to call the corresponding wrappers directly (q_simple_mediation(), q_serial_mediation(), and q_parallel_mediation()) instead of call q_mediation().
parallel: If TRUE, default, parallel processing will be used when doing bootstrapping.
ncores: Integer. The number of CPU cores to use when parallel is TRUE. Default is the number of non-logical cores minus one (one minimum). Will raise an error if greater than the number of cores detected by parallel::detectCores(). If ncores is set, it will override make_cluster_args in do_boot().
progress: Logical. Display bootstrapping progress or not. Default is TRUE.
digits: Number of digits to display. Default is 4.
annotation: Logical. Whether the annotation after the table of effects is to be printed. Default is TRUE.
pvalue: Logical. If TRUE, asymmetric p-values based on bootstrapping will be printed if available. Default is TRUE.
pvalue_digits: Number of decimal places to display for the p-values. Default is 4.
se: Logical. If TRUE and confidence intervals are available, the standard errors of the estimates are also printed. They are simply the standard deviations of the bootstrap estimates. Default is TRUE.
for_each_path: Logical. If TRUE, each of the paths will be printed individually, using the print-method of the output of indirect_effect(). Default is FALSE.
se_ci: Logical. If TRUE and confidence interval has not been computed, the function will try to compute them from stored standard error if the original standard error is to be used. Ignored if confidence interval has already been computed. Default is TRUE.
wrap_computation: Logical. If TRUE, the default, long computational symbols and values will be wrapped to fit to the screen width.
lm_ci: If TRUE, when printing the regression results of stats::lm(), confidence interval based on t statistic and standard error will be computed and added to the output. Default is TRUE.
lm_beta: If TRUE, when printing the regression results of stats::lm(), standardized coefficients are computed and included in the printout. Only numeric variables will be computed, and any derived terms, such as product terms, will be formed after standardization. Default is TRUE.
lm_ci_level: The level of confidence of the confidence interval. Ignored if lm_ci is not TRUE.
...: Other arguments. If for_each_path is TRUE, they will be passed to the print method of the output of indirect_effect(). Ignored otherwise.

Methods (by generic)

print(q_mediation): The print method of the outputs of q_mediation(), q_simple_mediation(), q_serial_mediation(), and q_parallel_mediation().

Functions

q_mediation(): The general "q" function for common mediation models. Not to be used directly.
q_simple_mediation(): A wrapper of q_mediation() for simple mediation models (a model with only one mediator).
q_serial_mediation(): A wrapper of q_mediation() for serial mediation models.
q_parallel_mediation(): A wrapper of q_mediation() for parallel mediation models.

Details

The family of "q" (quick) functions are for testing mediation effects in common models. These functions do the following in one single call:

Fit the regression models.
Compute and test all the indirect effects.

They are easy-to-use and are suitable for common models which are not too complicated. For now, there are "q" functions for these models:

A simple mediation: One predictor (x), one mediator (m), one outcome (y), and optionally some control variables (covariates) (q_simple_mediation())
A serial mediation model: One predictor (x), one or more mediators (m), one outcome (y), and optionally some control variables (covariates). The mediators positioned sequentially between x and y (q_serial_mediation()):
- x -> m1 -> m2 -> ... -> y
A parallel mediation model: One predictor (x), one or more mediators (m), one outcome (y), and optionally some control variables (covariates). The mediators positioned in parallel between x and y (q_parallel_mediation()):
- x -> m1 -> y
- x -> m2 -> y
- ...

Users only need to specify the x, m, and y variables, and covariates or control variables, if any (by cov), and the functions will automatically identify all indirect effects and total effects.

Note that they are not intended to be flexible. For models that are different from these common models, it is recommended to fit the models manually, either by structural equation modelling (e.g., lavaan::sem()) or by regression analysis using stats::lm() or lmhelprs::many_lm(). See https://sfcheung.github.io/manymome/articles/med_lm.html for an illustration on how to compute and test indirect effects for an arbitrary mediation model.

Workflow

This is the workflow of the "q" functions:

Do listwise deletion based on all the variables used in the models.
Generate the regression models based on the variables specified.
Fit all the models by OLS regression using stats::lm().
Call all_indirect_paths() to identify all indirect paths.
Call many_indirect_effects() to compute all indirect effects and form their confidence intervals.
Call total_indirect_effect() to compute the total indirect effect.
Return all the results for printing.

The output of the "q" functions have a print method for printing all the major results.

Notes

Flexibility

The "q" functions are designed to be easy to use. They are not designed to be flexible. For maximum flexibility, fit the models manually and call functions such as indirect_effect() separately. See https://sfcheung.github.io/manymome/articles/med_lm.html for illustrations.

Monte Carlo Confidence Intervals

We do not recommend using Monte Carlo confidence intervals for models fitted by regression because the covariances between parameter estimates are assumed to be zero, which may not be the case in some models. Therefore, the "q" functions do not support Monte Carlo confidence intervals. If Monte Carlo intervals are desired, please fit the model by structural equation modeling using lavaan::sem().

Examples

Run this code


# ===== Simple mediation

# Set R to 5000 or 10000 in real studies
# Remove 'parallel' or set it to TRUE for faster bootstrapping
# Remove 'progress' or set it to TRUE to see a progress bar

out <- q_simple_mediation(x = "x",
                          y = "y",
                          m = "m",
                          cov = c("c2", "c1"),
                          data = data_med,
                          R = 40,
                          seed = 1234,
                          parallel = FALSE,
                          progress = FALSE)
# Suppressed printing of p-values due to the small R
# Remove `pvalue = FALSE` when R is large
print(out,
      pvalue = FALSE)

# # Different control variables for m and y
# out <- q_simple_mediation(x = "x",
#                           y = "y",
#                           m = "m",
#                           cov = list(m = "c1",
#                                      y = c("c1", "c2")),
#                           data = data_med,
#                           R = 100,
#                           seed = 1234,
#                           parallel = FALSE,
#                           progress = FALSE)
# out


# ===== Serial mediation

# Set R to 5000 or 10000 in real studies
# Remove 'parallel' or set it to TRUE for faster bootstrapping
# Remove 'progress' or set it to TRUE to see a progress bar

# out <- q_serial_mediation(x = "x",
#                           y = "y",
#                           m = c("m1", "m2"),
#                           cov = c("c2", "c1"),
#                           data = data_serial,
#                           R = 40,
#                           seed = 1234,
#                           parallel = FALSE,
#                           progress = FALSE)

# # Suppressed printing of p-values due to the small R
# # Remove `pvalue = FALSE` when R is large
# print(out,
#       pvalue = FALSE)

# # Different control variables for m and y
# out <- q_serial_mediation(x = "x",
#                           y = "y",
#                           m = c("m1", "m2"),
#                           cov = list(m1 = "c1",
#                                      m2 = c("c2", "c1"),
#                                      y = "c2"),
#                           data = data_serial,
#                           R = 100,
#                           seed = 1234,
#                           parallel = FALSE,
#                           progress = FALSE)
# out


# ===== Parallel mediation

# Set R to 5000 or 10000 in real studies
# Remove 'parallel' or set it to TRUE for faster bootstrapping
# Remove 'progress' or set it to TRUE to see a progress bar

# out <- q_parallel_mediation(x = "x",
#                             y = "y",
#                             m = c("m1", "m2"),
#                             cov = c("c2", "c1"),
#                             data = data_parallel,
#                             R = 40,
#                             seed = 1234,
#                             parallel = FALSE,
#                             progress = FALSE)
# # Suppressed printing of p-values due to the small R
# # Remove `pvalue = FALSE` when R is large
# print(out,
#       pvalue = FALSE)

# # Different control variables for m and y
# out <- q_parallel_mediation(x = "x",
#                             y = "y",
#                             m = c("m1", "m2"),
#                             cov = list(m1 = "c1",
#                                        m2 = c("c2", "c1"),
#                                        y = "c2"),
#                             data = data_parallel,
#                             R = 100,
#                             seed = 1234,
#                             parallel = FALSE,
#                             progress = FALSE)
# out

Run the code above in your browser using DataLab