q_mediation: Mediation Models By Regression or SEM

In manymome: Mediation, Moderation and Moderated-Mediation After Model Fitting

Mediation Models By Regression or SEM

Description

Simple-to-use functions for fitting linear models by regression or structural equation modeling and testing indirect effects, using just one function.

Usage

q_mediation(
  x,
  y,
  m = NULL,
  cov = NULL,
  data = NULL,
  boot_ci = TRUE,
  mc_ci = FALSE,
  level = 0.95,
  R = 100,
  seed = NULL,
  ci_type = NULL,
  boot_type = c("perc", "bc"),
  model = NULL,
  fit_method = c("lm", "regression", "sem", "lavaan"),
  missing = "fiml",
  fixed.x = TRUE,
  sem_args = list(),
  na.action = "na.pass",
  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,
  mc_ci = FALSE,
  level = 0.95,
  R = 100,
  seed = NULL,
  ci_type = NULL,
  boot_type = c("perc", "bc"),
  fit_method = c("lm", "regression", "sem", "lavaan"),
  missing = "fiml",
  fixed.x = TRUE,
  sem_args = list(),
  na.action = "na.pass",
  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,
  mc_ci = FALSE,
  level = 0.95,
  R = 100,
  seed = NULL,
  ci_type = NULL,
  boot_type = c("perc", "bc"),
  fit_method = c("lm", "regression", "sem", "lavaan"),
  missing = "fiml",
  fixed.x = TRUE,
  sem_args = list(),
  na.action = "na.pass",
  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,
  mc_ci = FALSE,
  level = 0.95,
  R = 100,
  seed = NULL,
  ci_type = NULL,
  boot_type = c("perc", "bc"),
  fit_method = c("lm", "regression", "sem", "lavaan"),
  missing = "fiml",
  fixed.x = TRUE,
  sem_args = list(),
  na.action = "na.pass",
  parallel = TRUE,
  ncores = max(parallel::detectCores(logical = FALSE) - 1, 1),
  progress = TRUE
)

## S3 method for class '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,
  sem_style = c("lm", "lavaan"),
  ...
)

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.
mc_ci	Logical. Whether Monte Carlo confidence interval will be formed. Default is FALSE. Only supported if fit_method is "sem" or "lavaan".
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.
ci_type	The type of confidence intervals to be formed. Can be either "boot" (bootstrapping) or "mc" (Monte Carlo). If not supplied or is NULL, will check other arguments (e.g, boot_ci and mc_ci). If supplied, will override boot_ci and mc_ci. If fit_method is "regression" or "lm", then only "boot" is supported.
boot_type	The type of the bootstrap confidence intervals. Default is "perc", percentile confidence interval. Set "bc" for bias-corrected confidence interval. Ignored if ci_type is not "boot".
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().
fit_method	How the model is to be fitted. If set to "lm" or "regression", linear regression will be used (fitted by stats::lm()). If set to "sem" or "lavaan", structural equation modeling will be used and the model will be fitted by lavaan::sem(). Default is "lm".
missing	If fit_method is set to "sem" or "lavaan", this argument determine how missing data is handled. The default value is "fiml" and full information maximum likelihood will be used to handle missing data. Please refer to lavaan::lavOptions for other options.
fixed.x	If fit_method is set to "sem" or "lavaan", this determines whether the observed predictors ("x" variables, including control variables) are treated as fixed variables or random variables. Default is TRUE, to mimic the same implicit setting in regression fitted by stats::lm().
sem_args	If fit_method is set to "sem" or "lavaan", this is a named list of arguments to be passed to lavaan::sem(). Arguments listed here will not override missing and fixed.x.
na.action	How missing data is handled. Used only when fit_method is set to "sem" or "lavaan". If "na.pass", the default, then all data will be passed to lavaan, and full information maximum likelihood (fiml) will be used to handle missing data. If "na.omit", then listwise deletion will be used.
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 progress or not.
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.
sem_style	How the for the model is to be printed if the model is fitted by structural equation modeling (using lavaan). Default is "lm" and the results will be printed in a style similar to that of summary() output of stats::lm(). If "lavaan", the results will be printed in usual lavaan style.
...	Other arguments. If for_each_path is TRUE, they will be passed to the print method of the output of indirect_effect(). Ignored otherwise.

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 linear models.

• Compute and test all the indirect effects.

They are easy-to-use and are suitable for common models with mediators. 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

  • ...

• An arbitrary mediation model: One predictor (x), one or more mediators (m), one outcome (y), and optionally some control variables (covariates). The mediators positioned in an arbitrary form between x and y, as long as there are no feedback loops (q_mediation()). For example:

  • x -> m1

  • m1 -> m21 -> y

  • m1 -> m22 -> 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 more complex 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.

Specifying a Model of an Arbitrary Form

If a custom model is to be estimated, instead of setting model to a name of the form ("simple","serial", or "parallel"), set ⁠model to the paths between ⁠xandy'. It can take one of the following two forms:

A character vector, each element a string of a path, with variable names connected by "->" (the spaces are optional):

c("x -> m11 -> m12 -> y",
  "x -> m2 -> y")

A list of character vectors, each vector is a vector of names representing a path, going from the first element to the last element:

list(c("x", "m11, "m12", "y"),
     c("x", "m2", "y")

The two forms above specify the same model.

Paths not included are fixed to zero (i.e., does not "exist" in the model). A path can be specified more than once if this can enhance readability. For example:

c("x1 -> m1 -> m21 -> y1",
  "x1 -> m1 -> m22 -> y1")

The path "x1 -> m1" appears twice, to indicate two different pathways from x1 to y1.

Workflow

The coefficients of the model can be estimated by one of these two methods: OLS (ordinary least squares) regression (setting fit_method to "regression" or "lm"), or path analysis (SEM, structural equation modeling, by setting fit_method to "sem" or "lavaan").

Regression

This is the workflow of the "q" functions when estimating the coefficients by regression:

• 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.

Path Analysis

This is the workflow of the "q" functions when estimating the coefficients by path analysis (SEM):

• By default, cases with missing data only on the mediators and the outcome variable will be retained, and full information maximum likelihood (FIML) will be used to estimate the coefficients. (Controlled by missing, default to "fiml") using lavaan::sem().

• Generate the SEM (lavaan) model syntax based on the model specified.

• Fit the model by path analysis using lavaan::sem().

• 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.

Testing the Indirect Effects

Two methods are available for testing the indirect effects: nonparametric bootstrap confidence intervals (ci_type set to "boot") and Monte Carlo confidence intervals (ci_type set to "mc").

If the coefficients are estimated by OLS regression, only nonparametric bootstrap confidence intervals are supported.

If the coefficients are estimated by path analysis (SEM), then both methods are supported.

Printing the Results

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 OLS regression is used.

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.

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.

Author(s)

Idea to fit a model by structural equation modeling by Rong wei Sun https://orcid.org/0000-0003-0034-1422, implemented by Shu Fai Cheung https://orcid.org/0000-0002-9871-9448.

See Also

lmhelprs::many_lm() for fitting several regression models using model syntax, indirect_effect() for computing and testing a specific path, all_indirect_paths() for identifying all paths in a model, many_indirect_effects() for computing and testing indirect effects along several paths, and total_indirect_effect() for computing and testing the total indirect effects.

Examples

# ===== A user-specified mediation model

# 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_mediation(x = "x1",
                   y = "y1",
                   model = c("x1 -> m11 -> m2 -> y1",
                             "x1 -> m12 -> m2 -> y1"),
                   cov = c("c2", "c1"),
                   data = data_med_complicated,
                   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)


# ===== 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 = 20,
                          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

manymome documentation built on Jan. 8, 2026, 9:09 a.m.