Title:	Within-Subject Mediation Analysis Using Structural Equation Modeling
Version:	1.0.2
Description:	Within-subject mediation analysis using structural equation modeling. Examine how changes in an outcome variable between two conditions are mediated through one or more variables. Supports within-subject mediation analysis using the 'lavaan' package by Rosseel (2012) <doi:10.18637/jss.v048.i02>, and extends Monte Carlo confidence interval estimation to missing data scenarios using the 'semmcci' package by Pesigan and Cheung (2023) <doi:10.3758/s13428-023-02114-4>.
License:	GPL (≥ 3)
Depends:	R (≥ 4.1.0)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Suggests:	rmarkdown, devtools, testthat
Config/testthat/edition:	3
Imports:	knitr, lavaan, semmcci, mice, semboottools, MASS, rlang, dplyr, ggplot2, methods, stats
VignetteBuilder:	knitr
LazyData:	true
URL:	https://yangzhen1999.github.io/wsMed/
BugReports:	https://github.com/Yangzhen1999/wsMed/issues
NeedsCompilation:	no
Packaged:	2025-12-06 12:34:07 UTC; Administrator
Author:	Wendie Yang [aut, cre], Shu Fai Cheung [aut]
Maintainer:	Wendie Yang <1581075494q@gmail.com>
Repository:	CRAN
Date/Publication:	2025-12-11 13:30:02 UTC

Clean all CI column names into the standard form

Description

Clean all CI column names into the standard form

Usage

.clean_ci_names(df, ci_level = 0.95)

Fit SEM and run Monte-Carlo draws

Description

Fit SEM and run Monte-Carlo draws

Usage

.fit_and_mc(
  sem_model,
  data,
  Na = c("DE", "FIML"),
  R = 20000,
  alpha = 0.05,
  fixed.x = FALSE,
  verbose = TRUE,
  run_mc = TRUE
)

Make CI column names like "2.5%CI.Lo / 97.5%CI.Up"

Description

Make CI column names like "2.5%CI.Lo / 97.5%CI.Up"

Usage

.make_ci_names(ci)

Create moderation output for wsMed

Description

Create moderation output for wsMed

Usage

.make_moderation(
  mc_res,
  data,
  W = NULL,
  MP = NULL,
  W_type = c("categorical", "continuous", "none"),
  alpha = 0.05,
  verbose = FALSE
)

Verbose message wrapper (internal)

Description

Verbose message wrapper (internal)

Usage

.v(..., verbose = TRUE)

Average Relative Increase in Variance

Description

Average Relative Increase in Variance

Usage

ARIVwrapper(between, within, M, k)

Arguments

Details

The average relative increase in variance is given by

\mathrm{ARIV} = \left( 1 + M^{-1} \right) \mathrm{tr} \left( \mathbf{V}_{\mathrm{between}} \mathbf{V}_{\mathrm{within}}^{-1} \right)

Value

Returns a numeric vector of length one.

Author(s)

Ivan Jacob Agaloos Pesigan

Generate Chained Mediation Model

Description

Dynamically generates a structural equation modeling (SEM) syntax for chained mediation analysis based on the prepared dataset. The function computes regression equations for mediators and the outcome variable, indirect effects along multi-step mediation paths, total effects, contrasts between indirect effects, and coefficients in different conditions.

Usage

GenerateModelCN(prepared_data, MP = character(0))

Arguments

      The function detects and inserts the correct interaction terms (e.g., \code{int_M2diff_W1}) based on these labels.

Details

This function is used to construct SEM models for chained mediation analysis. It automatically parses variable names from the prepared dataset and dynamically creates the necessary model syntax, including:

• Outcome regression: Defines the relationship between the difference scores of the outcome (Ydiff) and the mediators (Mdiff) as well as their average scores (Mavg).

• Mediator regressions: Defines the sequential regression models for each mediator's difference score, incorporating prior mediators as predictors.

• Indirect effects: Computes the indirect effects along all possible multi-step mediation paths using the product of path coefficients.

• Total indirect effect: Calculates the sum of all indirect effects from the chained mediation paths.

• Total effect: Combines the direct effect (cp) and the total indirect effect.

• Contrasts of indirect effects: Optionally calculates the pairwise contrasts between the indirect effects for different mediation paths.

• Coefficients in different 'X' conditions: Calculates path coefficients in different X conditions to observe the moderation effect of X.

This model is suitable for chained mediation designs where mediators influence each other in a sequential manner, forming multi-step mediation paths.

Value

A character string representing the SEM model syntax for the specified chained mediation analysis.

See Also

PrepareData(), wsMed(), GenerateModelP()

Examples

# Example prepared data
prepared_data <- data.frame(
  M1diff = rnorm(100),
  M2diff = rnorm(100),
  M3diff = rnorm(100),
  M1avg = rnorm(100),
  M2avg = rnorm(100),
  M3avg = rnorm(100),
  Ydiff = rnorm(100)
)

# Generate SEM model syntax
sem_model <- GenerateModelCN(prepared_data)
cat(sem_model)

Generate Combined Parallel and Chained Mediation Model

Description

Dynamically generates a structural equation modeling (SEM) syntax for combined parallel and chained mediation analysis based on the prepared dataset. The function computes regression equations for mediators and the outcome variable, indirect effects for both parallel and chained mediation paths, total effects, contrasts between indirect effects, and coefficients in different X conditions.

Usage

GenerateModelCP(prepared_data, MP = character(0))

Arguments

      Each entry triggers inclusion of W’s main effect or interaction terms (e.g., \code{int_Mdiff_W}).

Details

This function is used to construct SEM models that combine parallel and chained mediation analysis. It automatically parses variable names from the prepared dataset and dynamically creates the necessary model syntax, including:

• Outcome regression: Defines the relationship between the difference scores of the outcome (Ydiff), the chained mediator (M1diff), and the parallel mediators (M2diff, M3diff, etc.).

• Mediator regressions: Defines the sequential regression models for the chained mediator and each parallel mediator.

• Indirect effects: Computes the indirect effects for both chained and parallel mediation paths, including multi-step indirect effects involving both chained and parallel mediators.

• Total indirect effect: Calculates the sum of all indirect effects from chained and parallel mediation paths.

• Total effect: Combines the direct effect (cp) and the total indirect effect.

• Contrasts of indirect effects: Optionally calculates the pairwise contrasts between the indirect effects for different mediation paths.

• Coefficients in different 'X' conditions: Calculates path coefficients in different X conditions to observe the moderation effect of X.

This model is suitable for designs where mediators include both a sequential chain (chained mediation) and independent parallel mediators.

Value

A character string representing the SEM model syntax for the specified combined parallel and chained mediation analysis.

See Also

PrepareData(), wsMed(), GenerateModelP(), GenerateModelCN()

Examples

# Example prepared data
prepared_data <- data.frame(
  M1diff = rnorm(100),
  M2diff = rnorm(100),
  M3diff = rnorm(100),
  M1avg = rnorm(100),
  M2avg = rnorm(100),
  M3avg = rnorm(100),
  Ydiff = rnorm(100)
)

# Generate SEM model syntax
sem_model <- GenerateModelCP(prepared_data)
cat(sem_model)

Generate Parallel Mediation Model

Description

Dynamically generates a structural equation modeling (SEM) syntax for parallel mediation analysis based on the prepared dataset. The function computes regression equations for mediators and the outcome variable, indirect effects, total effects, contrasts between indirect effect, and .

Usage

GenerateModelP(prepared_data, MP = character(0))

Arguments

      This argument controls which interaction terms (e.g., \code{int_Mdiff_W}, \code{int_Mavg_W}) are
      added to the corresponding regression equations.

Details

This function is used to construct SEM models for parallel mediation analysis. It automatically parses variable names from the prepared dataset and dynamically creates the necessary model syntax, including:

• Outcome regression: Defines the relationship between the difference scores of the outcome (Ydiff) and the mediators (Mdiff) as well as their average scores (Mavg).

• Mediator regressions: Defines the intercept models for each mediator's difference score.

• Indirect effects: Computes the indirect effects for each mediator using the product of path coefficients (e.g., a * b).

• Total indirect effect: Calculates the sum of all indirect effects.

• Total effect: Combines the direct effect (cp) and the total indirect effect.

• Contrasts of indirect effects: Optionally calculates the pairwise contrasts between the indirect effects when multiple mediators are present.

• coefficients in different 'X' conditions: Calculates path coefficients in different X conditions to observe the moderation effect of ‘X'.

This model is suitable for parallel mediation designs where multiple mediators act independently.

Value

A character string representing the SEM model syntax for the specified parallel mediation analysis.

See Also

PrepareData(), wsMed(), GenerateModelCN()

Examples

# Example prepared data
prepared_data <- data.frame(
  M1diff = rnorm(100),
  M2diff = rnorm(100),
  M1avg = rnorm(100),
  M2avg = rnorm(100),
  Ydiff = rnorm(100)
)

# Generate SEM model syntax
sem_model <- GenerateModelP(prepared_data)
cat(sem_model)

Generate Parallel and Chained Mediation Model

Description

Dynamically generates a structural equation modeling (SEM) syntax for mediation analysis that integrates both parallel and chained mediators. Unlike the Combined Parallel and Chained mediation model (GenerateModelCP), this function assumes that the chained mediator receives inputs from the parallel mediators and directly influences the outcome variable, emphasizing a downstream role for the chained mediator.

Usage

GenerateModelPC(prepared_data, MP = character(0))

Arguments

      This argument controls which interaction terms (e.g., \code{int_Mdiff_W}, \code{int_Mavg_W}) are included
      in the regression equations. Variable names are automatically matched using the naming convention
      \code{"int_<predictor>_W<index>"}.

Details

This function is designed to build SEM models that integrate parallel and chained mediation structures. It automatically identifies variable names from the prepared dataset and generates the necessary model syntax, including:

• Outcome regression: Defines the relationship between the difference scores of the outcome (Ydiff), the chained mediator (M1diff), and the parallel mediators (M2diff, M3diff, etc.).

• Mediator regressions: Constructs separate regression models for the parallel mediators and the chained mediator. The chained mediator incorporates predictors from all parallel mediators.

• Indirect effects: Computes indirect effects for:

  • Parallel mediators (M2diff, M3diff, etc.) directly influencing the outcome.

  • The chained mediator (M1diff) directly influencing the outcome.

  • Combined paths where parallel mediators influence the chained mediator, which in turn influences the outcome.

• Total indirect effect: Summarizes all indirect effects from parallel and chained mediation paths.

• Total effect: Combines the direct effect (cp) and the total indirect effect.

• Contrasts of indirect effects: Optionally computes pairwise contrasts between indirect effects for different mediation paths.

• Coefficients in different 'X' conditions: Computes path coefficients under different X conditions to analyze moderation effects.

This model is suitable for designs where mediators include both independent parallel paths and sequential chained paths, providing a comprehensive mediation analysis framework.

Value

A character string representing the SEM model syntax for the specified parallel and chained mediation analysis.

See Also

PrepareData(), wsMed(), GenerateModelP(), GenerateModelCN()

Examples

# Example prepared data
prepared_data <- data.frame(
  M1diff = rnorm(100),
  M2diff = rnorm(100),
  M3diff = rnorm(100),
  M1avg = rnorm(100),
  M2avg = rnorm(100),
  M3avg = rnorm(100),
  Ydiff = rnorm(100)
)

# Generate SEM model syntax
sem_model <- GenerateModelPC(prepared_data)
cat(sem_model)

Impute Missing Data Using Multiple Imputation

Description

The ImputeData function performs multiple imputation on a data frame with missing values using the mice package. It handles missing data by creating multiple imputed datasets based on a specified imputation method and returns a list of completed data frames.

Usage

ImputeData(
  data_missing,
  m = 5,
  method = "pmm",
  seed = 123,
  predictorMatrix = NULL
)

Arguments

Details

This function replaces specified missing value placeholders (e.g., -999) with NA, and then applies the multiple imputation by chained equations (MICE) procedure to generate multiple imputed datasets. It supports flexible imputation methods and allows for specifying a custom predictor matrix.

Value

A list of m imputed data frames.

Author(s)

Wendie Yang, Shufai Cheung

Examples

# Example data with missing values
data <- data.frame(
  M1 = c(rnorm(99), rep(NA, 1)),
  M2 = c(rnorm(99), rep(NA, 1)),
  Y1 = rnorm(100),
  Y2 = rnorm(100)
)
# Perform multiple imputation
imputed_data_list <- ImputeData(data, m = 5)
# Display the first imputed dataset
head(imputed_data_list[[1]])

Convert Lavaan Model to RAM Matrices

Description

Converts a lavaan-style matrix list into RAM (Reticular Action Model) format, including the A (asymmetric paths), S (symmetric paths), F (filter matrix), and M (means/intercepts) matrices.

Usage

Lav2RAM2(lav_mod)

Arguments

Details

This function reorganizes the lavaan-style matrices into the RAM representation, commonly used for model standardization and transformation.

Value

A list with components:

A

Asymmetric path matrix (including factor loadings and structural paths)

S

Symmetric path matrix (variances and covariances)

F

Filter matrix mapping latent and observed variables

M

Row vector of intercepts/means

Process Monte Carlo Samples for Defined Parameters in SEM

Description

A wrapper for the internal .MCDef() function from the semmcci package. This function processes Monte Carlo samples to compute defined parameters for structural equation modeling (SEM).

Usage

MCDefWrapper(object, thetahat, thetahatstar_orig)

Arguments

Details

This function takes Monte Carlo samples of parameter estimates and a fitted SEM model object to compute the defined parameters (e.g., indirect effects or user-defined contrasts) based on the model syntax. It is particularly useful for examining derived quantities in SEM analyses using Monte Carlo methods.

Value

A matrix of computed defined parameters for each Monte Carlo sample.

See Also

MCMI2(), RunMCMIAnalysis()

Monte Carlo Confidence Intervals for Multiple Imputation SEM Models

Description

Computes Monte Carlo confidence intervals (MCCI) for structural equation models (SEM) fitted to multiple imputed datasets. This function integrates SEM fitting across imputed datasets, pools the results, and generates confidence intervals through Monte Carlo sampling.

Usage

MCMI2(
  sem_model,
  imputations,
  R = 20000L,
  alpha = c(0.001, 0.01, 0.05),
  decomposition = "eigen",
  pd = TRUE,
  tol = 1e-06,
  seed = NULL,
  estimator = "ML",
  se = "standard",
  missing = "listwise"
)

Arguments

Details

This function is designed for SEM models that require multiple imputation to handle missing data. It performs the following steps:

• SEM Fitting: Fits the specified SEM model to each imputed dataset using lavaan::sem().

• Pooling Results: Combines parameter estimates and covariance matrices across imputations using Rubin's rules.

• Monte Carlo Sampling: Generates Monte Carlo samples based on the pooled estimates and covariance matrices, and calculates confidence intervals for model parameters.

This function supports custom estimators, handling of missing data, and precision adjustments for Monte Carlo sampling. It is particularly useful for mediation analysis or complex SEM models where missing data are addressed using multiple imputation.

Value

An object of class semmcci containing:

• call: The matched function call.

• args: A list of input arguments.

• thetahat: The pooled parameter estimates.

• thetahatstar: Monte Carlo samples for parameter estimates.

• fun: The name of the function ("MCMI2").

See Also

lavaan::sem(), semmcci::MC(), semmcci::MCStd()

Examples

# Example SEM model
sem_model <- "
  Ydiff ~ b1 * M1diff + cp * 1
  M1diff ~ a1 * 1
  indirect := a1 * b1
  total := cp + indirect
"

# Example imputed datasets
imputations <- list(
  data.frame(M1diff = rnorm(100), Ydiff = rnorm(100)),
  data.frame(M1diff = rnorm(100), Ydiff = rnorm(100))
)

# Compute Monte Carlo confidence intervals
result <- MCMI2(
  sem_model = sem_model,
  imputations = imputations,
  R = 1000,
  alpha = c(0.05, 0.01),
  seed = 123
)

Monte Carlo Summary for Standardized Estimates

Description

Computes standardized estimates, standard errors, and confidence intervals based on Monte Carlo samples from a semmcci object. This function fully standardizes both point estimates and sampling distributions (including intercepts).

Usage

MCStd2(mc, alpha = c(0.001, 0.01, 0.05))

Arguments

Details

The function standardizes the sampling distribution using StdLav2() on each Monte Carlo draw, then summarizes the distribution into SEs and quantile-based confidence intervals.

Value

A data frame containing:

Parameter

Parameter name

Estimate

Standardized point estimate

SE

Standard deviation of standardized samples

R

Number of Monte Carlo replications

CI columns

Multiple confidence intervals based on alpha

Wrapper for Internal Multiple Imputation Combining Function

Description

A wrapper function for the internal .MICombine() function from the semmcci package. This function pools parameter estimates and covariance matrices from multiple imputed datasets using Rubin's rules.

Usage

MICombineWrapper(coefs, vcovs, M, k, adj = FALSE)

Arguments

Details

This wrapper provides an abstraction over the internal .MICombine() function from the semmcci package, allowing it to be used within your package without directly exposing the internal function. It is primarily designed for use within workflows that involve multiple imputation and structural equation modeling (SEM). Rubin's rules are applied to compute pooled parameter estimates and their covariance matrices.

Value

A list containing the pooled estimates and covariance matrix:

• est: A numeric vector of pooled parameter estimates.

• total: A numeric matrix representing the pooled covariance matrix.

See Also

RunMCMIAnalysis()

Prepare Data for Two-Condition Within-Subject Mediation (WsMed)

Description

PrepareData() transforms raw pre/post data into the set of variables required by the WsMed workflow. It handles mediators, outcome, within-subject controls, between-subject controls, moderators, and all necessary interaction terms, while automatically centering / dummy-coding variables as needed.

Usage

PrepareData(
  data,
  M_C1,
  M_C2,
  Y_C1,
  Y_C2,
  C_C1 = NULL,
  C_C2 = NULL,
  C = NULL,
  C_type = NULL,
  W = NULL,
  W_type = NULL,
  center_W = TRUE,
  keep_W_raw = TRUE,
  keep_C_raw = TRUE
)

Arguments

Details

The function performs the following steps:

1. Outcome difference: Ydiff = Y_C2 - Y_C1.

2. Mediator variables for each pair (M_C1[i], M_C2[i]):

   • Mi_diff = M_C2 - M_C1

   • Mi_avg is the mean-centered average of the two occasions.

3. Between-subject controls C:

   • Continuous variables are grand-mean centered (Cb1, Cb2, ...).

   • Categorical variables (binary or multi-level) are expanded into k - 1 dummy variables (Cb1_1, Cb2_1, Cb2_2, ...), using the first level as the reference.

4. Within-subject controls Cw: difference and centered-average versions (Cw1diff, Cw1avg, ...).

5. Moderators W (one or more):

   • Continuous variables are grand-mean centered (W1, W2, ...).

   • Categorical variables are dummy-coded in the same way as C.

6. Interaction terms between each moderator column and each mediator column:

   • int_<Mi_diff>_<Wj>, int_<Mi_avg>_<Wj>.

7. Two attributes are added to the returned data:

   • "W_info": raw names, dummy names, level mapping

   • "C_info": same structure for between-subject controls.

Row counts are preserved even if input factors contain NA values (model.matrix is called with na.action = na.pass).

Value

A data frame containing at minimum:

• Ydiff

• Mi_diff, Mi_avg for each mediator

• centered or dummy-coded Cb*, Cw*diff, Cw*avg

• centered or dummy-coded W* and all int_* interaction terms

plus the attributes "W_info" and "C_info" described above.

See Also

PrepareMissingData, GenerateModelP, wsMed

Examples

set.seed(1)
raw <- data.frame(
  A1 = rnorm(50), A2 = rnorm(50),   # mediator 1
  B1 = rnorm(50), B2 = rnorm(50),   # mediator 2
  C1 = rnorm(50), C2 = rnorm(50),   # outcome
  D1 = rnorm(50), D2 = rnorm(50),   # within-subject control
  W_bin  = sample(0:1, 50, TRUE),   # between-subject binary C
  W_fac3 = factor(sample(c("Low","Med","High"), 50, TRUE)) # moderator W
)

prep <- PrepareData(
  data  = raw,
  M_C1  = c("A1","B1"), M_C2 = c("A2","B2"),
  Y_C1  = "C1",         Y_C2 = "C2",
  C_C1  = "D1",         C_C2 = "D2",
  C     = "W_bin",      C_type = "categorical",
  W     = "W_fac3",     W_type = "categorical"
)
head(prep)

Prepare Data with Missing Values for Mediation Analysis

Description

Handles missing values in the dataset through multiple imputation and prepares the imputed datasets for within-subject mediation analysis. The function imputes missing data, processes each imputed dataset, and provides diagnostics for the imputation process.

Usage

PrepareMissingData(
  data_missing,
  m = 5,
  method_num = "pmm",
  seed = 123,
  M_C1,
  M_C2,
  Y_C1,
  Y_C2,
  C_C1 = NULL,
  C_C2 = NULL,
  C = NULL,
  C_type = NULL,
  W = NULL,
  W_type = NULL,
  center_W = TRUE,
  keep_W_raw = TRUE,
  keep_C_raw = TRUE
)

Arguments

Details

This function is designed to preprocess datasets with missing values for mediation analysis. It performs the following steps:

• Multiple imputation: Uses specified imputation methods (for example, predictive mean matching) to generate m imputed datasets.

• Data preparation: Applies PrepareData to each of the m imputed datasets to calculate difference scores and centered averages for mediators and the outcome variable.

• Imputation diagnostics: Provides summary diagnostics for the imputation process, including information about missing data patterns and convergence.

This function integrates imputation and data preparation, ensuring that the resulting datasets are ready for subsequent mediation analysis.

Value

A list containing:

processed_data_list

A list of m data frames, each representing an imputed and processed dataset ready for within-subject mediation analysis.

imputation_summary

A summary of the imputation process, including diagnostics and convergence information.

See Also

PrepareData, ImputeData, wsMed

Examples

# Example dataset with missing values
data("example_data", package = "wsMed")
set.seed(123)
example_dataN <- mice::ampute(
  data = example_data,
  prop = 0.1
)$amp

# Prepare the dataset with multiple imputations
prepared_missing_data <- PrepareMissingData(
  data_missing = example_dataN,
  m = 5,
  M_C1 = c("A2", "B2"),
  M_C2 = c("A1", "B1"),
  Y_C1 = "C2",
  Y_C2 = "C1"
)

# Access processed datasets
processed_data_list <- prepared_missing_data$processed_data_list
imputation_summary  <- prepared_missing_data$imputation_summary

Convert Standardized RAM Back to Lavaan Matrices

Description

Converts a standardized RAM object back to lavaan-style matrix structure. Optionally ensures correlations for theta and psi matrices.

Usage

RAM2Lav2(ram, lav_mod, standardized = FALSE)

Arguments

Details

This function restores the internal lavaan model matrix structure from a RAM representation.

Value

A modified lavaan-style matrix list with updated lambda, beta, theta, psi, and alpha.

Generate Random Variates from the Gaussian Distribution (Singular Value Decomposition)

Description

Generate Random Variates from the Gaussian Distribution (Singular Value Decomposition)

Usage

RandomGaussianSVDwrapper(Z, svd)

Arguments

Value

Numeric matrix.

Author(s)

Ivan Jacob Agaloos Pesigan

Monte Carlo SEM with Multiple Imputation (WsMed Workflow)

Description

RunMCMIAnalysis() is a helper that:

1. imputes missing data via PrepareMissingData;

2. generates all WsMed variables in each completed data set;

3. fits the user-supplied SEM model to each replicate; and

4. pools the results via MCMI2(), producing Monte Carlo confidence intervals (MCCI) for all model parameters.

Usage

RunMCMIAnalysis(
  data_missing,
  m = 5,
  method_num = "pmm",
  seed = 123,
  M_C1,
  M_C2,
  Y_C1,
  Y_C2,
  C_C1 = NULL,
  C_C2 = NULL,
  C = NULL,
  C_type = NULL,
  W = NULL,
  W_type = NULL,
  keep_W_raw = TRUE,
  keep_C_raw = TRUE,
  sem_model,
  Na = "MI",
  R = 20000L,
  alpha = c(0.001, 0.01, 0.05),
  decomposition = "eigen",
  pd = TRUE,
  tol = 1e-06
)

Arguments

Details

Internally the function calls:

• PrepareMissingData() – performs multiple imputation (logreg / polyreg for categorical variables, and method_num for numeric) and applies PrepareData to each imputed set;

• MCMI2() – pools parameter estimates across the m imputations and draws R Monte Carlo samples.

Only the missing-data strategy Na = "MI" is supported.

Value

A list with three elements:

mc_result

A semmcci object returned by MCMI2().

first_imputed_data

The first processed data frame (useful for inspection or plotting).

imputation_summary

Diagnostics from PrepareMissingData().

See Also

PrepareMissingData, PrepareData, MCMI2, wsMed

Standardize Parameter Estimates in a Lavaan Model

Description

Applies full standardization (including intercepts) to a fitted lavaan model by converting to RAM form, performing standardization, and converting back to lavaan matrix structure.

Usage

StdLav2(est, object)

Arguments

Details

The function extracts the model's RAM representation via Lav2RAM2, applies StdRAM2 standardization, restores the standardized GLIST via RAM2Lav2, and retrieves standardized user-defined parameter estimates with lav_model_get_parameters().

Value

A numeric vector of fully standardized parameter estimates (including intercepts and defined parameters).

Standardize RAM Matrices

Description

Performs standardization of RAM matrices by rescaling path and variance structures using the implied covariance matrix. Intercepts are also standardized.

Usage

StdRAM2(ram_est)

Arguments

Details

The function computes the implied covariance matrix \Sigma = (I - A)^{-1} S (I - A)^{-T}, extracts standard deviations, and performs standardization via D^{-1} scaling.

Value

A list of standardized RAM matrices:

A

Standardized asymmetric path matrix

S

Standardized symmetric path matrix

F

Unchanged filter matrix

M

Standardized intercept vector

Test for a Positive Definite Matrix

Description

Returns TRUE if input is a positive definite matrix, and FALSE otherwise.

Usage

TestPositiveDefinitewrapper(eigen, tol = 1e-06)

Arguments

Details

A k \times k symmetric matrix \mathbf{A} is positive definite if all of its eigenvalues are positive.

Value

Logical.

References

Wikipedia: Definite matrix

Monte Carlo Sampling for Parameter Estimates

Description

Generates Monte Carlo samples for parameter estimates using a covariance matrix and a location vector. This function is a wrapper for the internal .ThetaHatStar() function from the semmcci package.

Usage

ThetaHatStarWrapper(
  R = 20000L,
  scale,
  location,
  decomposition = "eigen",
  pd = TRUE,
  tol = 1e-06
)

Arguments

Value

A list containing:

• thetahatstar: A matrix of simulated parameter estimates with dimensions ⁠R x length(location)⁠.

• decomposition: The decomposition method used.

See Also

MCMI2(), RunMCMIAnalysis()

Compute Updated Parameter Estimates for SEM Models

Description

A wrapper for the internal .ThetaHat() function from the semmcci package. This function computes updated parameter estimates for structural equation models (SEM) using pooled estimates from multiple imputations or Monte Carlo simulations.

Usage

ThetaHatWrapper(object, est = NULL)

Arguments

Details

The function takes a fitted SEM model object and pooled parameter estimates to calculate the updated parameter values. It is particularly useful for combining results from multiple imputations or Monte Carlo samples to refine parameter estimates.

Value

A numeric vector of updated parameter estimates.

See Also

MCMI2(), RunMCMIAnalysis()

Examples

NULL

Adjusted Total Sampling Covariance Matrix

Description

Adjusted Total Sampling Covariance Matrix

Usage

TotalAdjwrapper(ariv, within)

Arguments

Details

The adjusted total sampling covariance matrix is given by

\tilde{\mathbf{V}}_{\mathrm{total}} = \left( 1 + \mathrm{ARIV} \right) \mathbf{V}_{\mathrm{within}}

Author(s)

Ivan Jacob Agaloos Pesigan

Apply PrepareData to Imputed Datasets and Return New MIDS Object

Description

This function applies the PrepareData() preprocessing step to each imputed dataset in a mids object and returns a new mids object with the transformed data. It is designed for use in within-subject mediation analysis pipelines when working with multiply imputed data.

Usage

TransformMidsWithPrepareData(mids_obj, M_C1, M_C2, Y_C1, Y_C2)

Arguments

Details

The function performs the following steps:

• Extracts all imputed datasets from the original mids object.

• Applies PrepareData() to each imputed dataset using the specified within-subject mediator and outcome variables.

• Combines all processed datasets into a long format and reconstructs a new mids object via mice::as.mids().

This enables subsequent analyses to operate on a version of the multiply imputed data where difference scores and averages have already been computed.

Value

A new mids object where each imputed dataset has been processed using PrepareData().

Append significance stars based on CI

Description

Append significance stars based on CI

Usage

add_sig(df)

Conditional Indirect Effects with a Continuous Moderator

Description

Summarises Monte-Carlo draws from a semmcci object when the moderator W is continuous. The function outputs:

1. mod_coeff – table of every moderated path coefficient (aw, bw, dw, cpw) with its base counterpart and 95 % CI;

2. beta_coef – indirect effect at three reference points of W (–1 SD, mean, +1 SD);

3. path_HML – likewise, the moderated primary paths (a, b, …) at the three W levels;

4. theta_curve – full curve of the indirect effect over a user-defined grid of centred W;

5. path_curve – full curve for every moderated base path.

Significance stars ("*") are added where the CI excludes 0.

Usage

analyze_mm_continuous(
  mc_result,
  data,
  MP,
  W_raw_name = "W",
  ci_level = 0.95,
  W_values = NULL,
  n_curve = 120,
  digits = 8
)

Arguments

Value

A named list with components:

mod_coeff

Moderated path coefficients (aw, bw, …).

beta_coef

Indirect effect at –1 SD / 0 SD / +1 SD.

path_HML

Moderated base paths at the three W levels.

theta_curve

Data frame of the indirect effect curve.

path_curve

Data frame of each moderated base-path curve.

Apply Standardization to Parameter Definitions

Description

Replaces parameters in expressions with their standardized versions.

Usage

apply_standardization(definitions, std_map, path_std_map = list())

Arguments

Value

A list of standardized parameter expressions.

Assert a scalar (whole-number) integer with optional bounds

Description

Assert a scalar (whole-number) integer with optional bounds

Usage

assert_scalar_int(
  x,
  name = deparse(substitute(x)),
  lower = NULL,
  upper = NULL,
  allow_null = FALSE
)

Bootstrap Standard Deviations for Standardization

Description

Performs bootstrap sampling to estimate SDs of variables used in standardization.

Usage

bootstrap_sd_list(data, var_names, nboot = 20000, seed = NULL)

Arguments

Value

A named list of numeric vectors (bootstrapped SD samples).

Build Unstandardized Parameter Definitions

Description

Extracts parameter definition expressions from a fitted model.

Usage

build_definitions(fit)

Arguments

Value

A named list of parameter definitions.

Build Standardization Maps PATH

Description

Constructs mapping of parameter labels to variables for standardization.

Usage

build_path_std_map(fit)

Arguments

Value

A named list: slopes (path_std_map).

Build Standardization Maps

Description

Constructs mapping of parameter labels to variables for standardization.

Usage

build_std_map(fit)

Arguments

Value

A named list: intercepts (std_map).

Basic Contrasts for Indirect Effects and Pre/Post Path Coefficients

Description

calc_basic_contrasts() extracts two convenient sets of contrasts from a Monte-Carlo SEM result (semmcci object):

1. All pairwise differences between indirect effects (⁠indirect_*⁠ columns);

2. Pre-test (X_0) and post-test (X_1) coefficients for every primary b path, obtained with X_1 = (2b + d)/2, X_0 = X_1 - d.

Usage

calc_basic_contrasts(mc_result, ci_level = 0.95, digits = 3)

Arguments

Details

• Indirect-effect columns are detected by the regular expression ⁠^indirect_⁠.

• A primary b path is any coefficient named b1, b_1_2, … Its matching d path (d1, d_1_2, …) is paired automatically.

Each contrast is summarised with its Monte-Carlo mean, SD, and a symmetric 100(1-\alpha) % confidence interval. Helper functions mc_summary_pct() and fix_pct_names() ensure that the final CI columns are named, for example, ⁠2.5%CI.Lo⁠ and ⁠97.5%CI.Up⁠.

Value

A list with up to two data frames:

IE_contrasts

Pairwise contrasts of indirect effects, or NULL if fewer than two are present.

Xcoef

Rows ⁠X1_b*⁠ and ⁠X0_b*⁠ for every detected b path, or NULL if no b path is found.

Debug printer with indentation (internal)

Description

Debug printer with indentation (internal)

Usage

dbg(..., .lvl = 0, verbose = TRUE)

Evaluate Unstandardized Monte Carlo Definitions

Description

Evaluates user-defined parameter expressions from Monte Carlo samples without any standardization.

Usage

evaluate_definitions_unstd_v2(theta_star, definitions)

Arguments

Value

A data frame with R rows (simulations) and p + d columns (p = number of free parameters, d = number of defined parameters).

Evaluate Standardized Monte Carlo Expressions

Description

Evaluates user-defined parameters (defined via expressions) and standardized free parameters from Monte Carlo simulated samples. This version supports both intercept-based standardization and path-based standardization.

Usage

evaluate_definitions_v3(
  theta_star,
  definitions,
  std_map,
  sd_boot_list,
  sd_var_boot,
  path_std_map
)

Arguments

Value

A data frame of R rows (simulations) * all parameters (standardized free + defined).

Example Data for within subject mediation

Description

A simulated dataset containing variables for within-subject mediation analysis. The dataset includes four within-subject variables (A, B, C, D), each measured at three levels:

• A1, A2, A3: Levels of within-subject variable A (e.g., mediator conditions).

• B1, B2, B3: Levels of within-subject variable B (e.g., outcome conditions).

• C1, C2, C3: Levels of within-subject variable.

• D1, D2, D3: Levels of within-subject variable.

Usage

example_data

Format

A tibble (data frame) with 100 rows and 12 variables:

A1

Numeric variable

A2

Numeric variable

A3

Numeric variable

B1

Numeric variable

B2

Numeric variable

B3

Numeric variable

C1

Numeric variable

C2

Numeric variable

C3

Numeric variable

D1

Numeric variable

D2

Numeric variable

D3

Numeric variable

Examples

data(example_data)
head(example_data)

Extract All Parameters and Definitions

Description

Extracts free and defined parameters from a fitted lavaan model, and builds a dependency map of user-defined parameters.

Usage

extract_all_parameters(fit)

Arguments

Value

A list with:

• free: Names of free parameters.

• defined: Names of defined parameters.

• definition_map: A list mapping defined parameters to their dependencies.

Fix legacy CI column names in a data.frame

Description

Converts columns like CI[LL] / CI[UL] or CI.LL / CI.UL to the standard produced by .make_ci_names().

Usage

fix_ci_names(df, ci = 0.95)

Fix % characters mangled by make.names()

Description

Fix % characters mangled by make.names()

Usage

fix_pct_names(df)

Generate Monte Carlo Samples

Description

Generates a Monte Carlo sample of model parameters from a multivariate normal distribution.

Usage

generate_mc_samples(fit, resolved_map, R = 20000, seed = NULL)

Arguments

Value

A numeric matrix of Monte Carlo samples.

Extract All Variables Needed for Standardization

Description

Extracts predictor and outcome variable names from a path standardization map.

Usage

get_all_variables_from_path_map(path_std_map)

Arguments

Value

A character vector of variable names.

Parse All Possible Indirect Paths from Column Names

Description

Infers every unique mediation chain that can be constructed from a set of coefficient names following the WsMed naming convention (e.g., a1, b_1_3, d_2_1, b3). The function returns a list; each element describes one indirect effect:

• path_name – canonical name, e.g.\ "indirect_effect_1_3"
  (mediators are concatenated in the encountered order);

• coefs – vector of coefficient names that define the path;

• mediators – readable label such as "M1 M3".

Usage

get_indirect_paths(col_names)

Arguments

Details

Internally the function:

1. identifies all a, b, and d coefficients available in col_names;

2. constructs a directed graph from X → Mi, Mi → Y, and Mi → Mj edges;

3. runs a depth-first search from the exposure (X) to the outcome (Y);

4. converts every node sequence (X → … → Y) into the corresponding coefficient sequence.

Duplicate paths (identical mediator ordering) are removed.

Value

A list of path descriptors; each element is itself a list with components path_name, coefs, and mediators. If no valid path exists, an empty list is returned.

Get safe number of CPUs for parallel processing

Description

Automatically returns 1 when on CI to avoid errors.

Usage

get_safe_ncpus()

Extract Target Variables for Standardization

Description

Extracts variable names from a fitted SEM model and a definition map that are required for computing standardized estimates in Monte Carlo simulations. Specifically, it identifies intercept terms (e.g., ~1) involved in user-defined parameters such as indirect effects (e.g., indirect := a * b) that require standard deviations for standardization.

Usage

get_sd_target_variables(fit, definition_map, data)

Arguments

Value

A character vector of variable names whose standard deviations are needed to standardize the intercept estimates in Monte Carlo confidence interval analysis.

make_contrasts

Description

make_contrasts

Usage

make_contrasts(df, value_col = "Estimate", contrast_col = "Contrast")

Compute Monte Carlo Estimates, Standard Errors, and CIs (with Percent Labels)

Description

mc_summary_pct() summarizes a numeric vector of Monte Carlo samples x by computing its mean, standard deviation, and percentile-based confidence interval. The result is returned as a data.frame with column names that include percentage signs. This function is typically used to generate tables of mediation effects or path coefficient estimates with path labels.

Returned columns include:

• Path: Path label.

• Estimate: Sample mean.

• SE: Sample standard deviation.

• ⁠<p%CI.Lo>⁠, ⁠<p%CI.Up>⁠: Lower and upper bounds of the percentile CI, with ⁠%⁠ in the column names.

Usage

mc_summary_pct(x, label, ci_level = 0.95, digits = 3)

Arguments

Value

A data.frame containing the path label, estimate, standard error, and CI. Column names are formatted like "2.5%CI.Lo" and "97.5%CI.Up".

Null-coalescing operator

Description

Returns x unless it is NULL, otherwise returns y.

Usage

x %||% y

Plot moderation curves with Johnson-Neyman highlights

Description

plot_moderation_curve() visualises how an indirect effect (theta_curve) or a path coefficient (path_curve) varies along a continuous moderator W.

The routine

• extracts the requested record (path_name) from result$moderation, preferring theta_curve when it is available in both curves;

• draws the conditional effect (Estimate) against the raw moderator grid (W_raw);

• overlays the Monte-Carlo confidence band (CI.LL, CI.UL) and finds every Johnson–Neyman segment whose 95 % CI excludes zero (CI.LL * CI.UL > 0);

• shades these significant regions and annotates each with its start / end percentiles (for example, "sig 12.5%-38.3%").

Visual elements

• Red ribbon – overall 95 % confidence band (ns_fill);

• Green ribbon – significant Johnson–Neyman intervals (sig_fill);

• Solid line – point estimate;

• Dashed h-line – zero reference;

• Dashed v-lines – J–N bounds.

Usage

plot_moderation_curve(
  result,
  path_name,
  title = NULL,
  x_label = "Moderator (W)",
  y_label = "Estimate",
  ns_fill = "#FEE0D2",
  sig_fill = "#C7E9C0",
  alpha_ci = 0.35,
  alpha_sig = 0.35,
  base_size = 14
)

Arguments

Value

A ggplot object (add layers or save with ggsave()).

Print Method for wsMed Objects

Description

Provides a comprehensive summary of results from a wsMed object, including:

• Input and computed variables with sample size.

• Model fit indices, regression paths, and variance estimates.

• Total, direct, and indirect effects with pairwise contrasts.

• Moderation effects and Monte Carlo confidence intervals for raw and standardized estimates (if applicable).

• Diagnostic notes for bootstrapping, imputation, and analysis parameters.

The output is formatted for clarity, ensuring an intuitive presentation of mediation analysis results, including dynamic confidence intervals, moderation keys, and C1-C2 coefficients.

Usage

## S3 method for class 'wsMed'
print(x, digits = 3, ...)

Arguments

Details

This function is specifically designed to display results from the within-subject mediation analysis conducted using the wsMed function. Key features include:

• Variables:

  • Shows input variables (M_C1, M_C2, Y_C1, Y_C2) and computed variables like Ydiff, Mdiff, and Mavg.

  • Reports the sample size used in the analysis.

• Model Fit Indices:

  • Displays SEM fit indices (e.g., Chi-square, CFI, TLI, RMSEA, SRMR) to assess model quality.

• Regression Paths and Variance Estimates:

  • Summarizes path coefficients, intercepts, variances, and confidence intervals.

• Effects:

  • Reports total, direct, and indirect effects with their significance.

  • Highlights pairwise contrasts between indirect effects for mediation paths.

• Moderation Effects:

  • Provides moderation results for identified variables with corresponding coefficients and paths.

• Monte Carlo Confidence Intervals:

  • Includes results for raw and standardized estimates obtained using methods such as MI or FIML.

• Diagnostics:

  • Summarizes analysis parameters like bootstrapping, imputation settings, Monte Carlo iterations, and random seeds.

Value

Invisibly returns the input wsMed object for further use.

See Also

wsMed, sem, standardizedSolution_boot_ci

Examples

# Perform within-subject mediation analysis
data("example_data", package = "wsMed")
result1 <- wsMed(
  data = example_data,
  M_C1 = c("A1", "B1"),
  M_C2 = c("A2", "B2"),
  Y_C1 = "C1",
  Y_C2 = "C2",
  form = "P",
  Na = "FIML",
  standardized = FALSE,
  alpha = 0.05
)

# Print the results
print(result1)

Print Formatted SEM Model Syntax

Description

Formats and prints the SEM model syntax generated by GenerateModelCN, GenerateModelCP, GenerateModelP, and GenerateModelPC. It organizes the equations into labeled sections for better readability.

Usage

printGM(x, ...)

Arguments

Value

Invisibly returns the formatted SEM model syntax.

Examples

data(example_data)
head(example_data)
prepared_data <- PrepareData(
  data = example_data,
  M_C1 = c("A1", "B1"),
  M_C2 = c("A2", "B2"),
  Y_C1 = "C1",
  Y_C2 = "C2"
)
sem_model <- GenerateModelPC(prepared_data)
printGM(sem_model)

Resolve Dependencies of Defined Parameters

Description

Recursively resolves all free parameters involved in each defined parameter.

Usage

resolve_all_dependencies(def_map)

Arguments

Value

A list mapping each defined parameter to its dependent free parameters.

Run Monte Carlo-Based Mediation Inference

Description

Performs Monte Carlo simulation to estimate confidence intervals for both unstandardized and (optionally) standardized mediation parameters, based on fitted SEM models.

Usage

run_mc_mediation(
  fit,
  data,
  standardized = FALSE,
  R = 20000,
  seed = 123,
  alpha = 0.05,
  alphastd = 0.05
)

Arguments

Value

A list with unstandardized and (if requested) standardized results. Each result includes Monte Carlo estimates, SEs, and CIs.

Sort Parameters for Printing in SEM Output

Description

Sorts a parameter table by conceptual priority for presentation purposes. This function is designed to support formatted output of mediation and SEM results by organizing parameters such as a-paths, b-paths, indirect effects, contrasts, etc.

Usage

sort_parameters(df)

Arguments

Details

This is an internal helper function used by print.WsMed() to ensure that printed tables of standardized or unstandardized estimates appear in a logical and human-readable order.

Value

A reordered version of the same data frame, with rows sorted according to a predefined logical structure:

1. a-paths (e.g., a1, a2, ...)

2. b-paths (e.g., b1, b2, ...)

3. d-paths (e.g., d1, d2, ...)

4. indirect effects (e.g., ind1, ind2, ...)

5. direct effect

6. total indirect

7. total effect

8. contrasts (e.g., ind1-ind2, ind2-ind3)

9. X-condition path terms (e.g., X1_b1, X0_b1, ...)

Summarize Monte Carlo Simulation Results

Description

Computes summary statistics for Monte Carlo simulation results, including the mean estimate, standard error (SE), and confidence intervals (CIs).

Usage

summarize_mc_ci(mc_result, alpha = 0.05)

Arguments

Value

A data frame with one row per parameter and the following columns:

Parameter

The name of the parameter.

Estimate

The average estimate across all Monte Carlo replications.

SE

The standard deviation of the estimates (standard error).

CI_lower

The lower bound of the confidence interval.

CI_upper

The upper bound of the confidence interval.

Validate user inputs for wsMed()

Description

All checks stop() with an informative message when they fail. Invisibly returns TRUE on success.

Usage

validate_wsMed_inputs(
  data,
  M_C1,
  M_C2,
  Y_C1,
  Y_C2,
  C_C1 = NULL,
  C_C2 = NULL,
  C = NULL,
  W = NULL,
  W_type = NULL,
  MP = NULL,
  form = c("P", "CN", "CP", "PC"),
  Na = c("DE", "FIML", "MI"),
  R = 20000L,
  bootstrap = 1000L,
  m = 5L,
  ci_level = 0.95,
  ci_method = NULL,
  MCmethod = NULL
)

Within-Subject Mediation Analysis (Two-Condition)

Description

wsMed() fits a structural equation model (SEM) for two-condition within-subject mediation. It can handle missing data (DE, FIML, MI) and computes both unstandardized and standardized effects with bootstrap or Monte Carlo confidence intervals.

Usage

wsMed(
  data,
  M_C1,
  M_C2,
  Y_C1,
  Y_C2,
  C_C1 = NULL,
  C_C2 = NULL,
  C = NULL,
  C_type = NULL,
  W = NULL,
  W_type = NULL,
  MP = NULL,
  form = c("P", "CN", "CP", "PC"),
  Na = c("DE", "FIML", "MI"),
  alpha = 0.05,
  mi_args = list(),
  R = 20000L,
  bootstrap = 2000,
  boot_ci_type = "perc",
  iseed = 123,
  fixed.x = FALSE,
  ci_method = c("mc", "bootstrap", "both"),
  MCmethod = NULL,
  seed = 123,
  standardized = FALSE,
  verbose = FALSE
)

Arguments

Details

Model structures:

• "P": parallel mediation

• "CN": chained (serial) mediation

• "CP": chained then parallel

• "PC": parallel then chained

Missing-data strategies:

• "DE": list-wise deletion

• "FIML": full-information maximum likelihood

• "MI": multiple imputation via mice

Confidence-interval engines:

• Bootstrap: percentile, BC, or BCa (DE and FIML only)

• Monte Carlo: draws via semmcci (all Na options)

For Na = "FIML", you may choose MCmethod = "mc" (default) or "bootSD" to add a finite-sample SD correction.

Workflow: (1) preprocess -> (2) generate SEM syntax -> (3) fit -> (4) compute confidence intervals -> (5) optional: standardize estimates.

Value

An object of class "wsMed" with elements:

data

Preprocessed data frame.

sem_model

Generated lavaan syntax.

mc

List with Monte Carlo draws, bootstrap tables (if any), and the fitted model.

moderation

Conditional or moderated effect tables.

form,Na,alpha

Analysis settings.

input_vars

Names of all user-supplied variables.

Examples

data("example_data", package = "wsMed")
set.seed(123)
result <- wsMed(
  data = example_data,
  M_C1 = c("A2", "B2"),
  M_C2 = c("A1", "B1"),
  Y_C1 = "C1", Y_C2 = "C2",
  form = "P", Na = "DE"
)
print(result)