Automatically calculate direct, indirect, total, and mediator effects for endogenous (response) variables in a 'piecewise' structural equation model (SEM).

semEff(
sem,
predictors = NULL,
mediators = NULL,
use.raw = FALSE,
ci.conf = 0.95,
ci.type = "bca",
digits = 3,
bci.arg = NULL,
...
)

## Arguments

sem A piecewise SEM, comprising a list of fitted model objects or of boot objects (containing bootstrapped model effects). Alternatively, a "psem" object from piecewiseSEM::psem(). If list is unnamed, response variable names will be used. Names of variables for/through which to calculate effects. If NULL (default), all predictors/mediators in the SEM will be used. Logical, whether to use 'raw' (unstandardised) effects for all calculations (if present in sem). A numeric value specifying the confidence level for confidence intervals on effects. The type of confidence interval to return (defaults to "bca" – see Details). See boot.ci() for further specification details. The number of significant digits to return for numeric values (for summary tables). A named list of any additional arguments to boot.ci(), excepting argument index. Arguments to bootEff().

## Value

A list object of class "semEff" for which several methods and extractor functions exist. Contains:

1. Summary tables of effects and confidence intervals

2. All effects

3. All bootstrapped effects

4. All indirect effects (individual, not summed)

## Details

The eponymous function of this package calculates all direct, indirect, total, and mediator effects for a 'piecewise' structural equation model (SEM), that is, one where parameter estimation is local rather than global (Lefcheck, 2016; Shipley, 2000, 2009). The SEM simply takes the form of a list of fitted models, or bootstrapped estimates from such models, describing hypothesised causal pathways from predictors to response ('endogenous') variables. These are either direct, or operate indirectly via other response variables ('mediators'). This list should represent a directed ('acyclic') causal model, which should be named exactly for each response variable and ordered from 'upstream' or 'causal' variables through to 'downstream' (i.e. those at the end of the pathway). If sem is a list of fitted models, effects will first be bootstrapped using bootEff() (this may take a while!).

Direct effects are calculated as fully standardised model coefficients for each response variable, while indirect effects are the product of these direct effects operating along causal pathways in the SEM. The total effects of any given predictor on a response are then the sum of its direct and (all) its indirect effects. 'Mediator' effects are also calculated, as the sum of all indirect paths which operate through each individual mediator – useful to assess the relative importance of different mediators in affecting the response. All of these effect types can be calculated automatically for all (default) or for a specified subset of predictors and/or mediators in the SEM. As indirect, total, and mediator effects are not directly bootstrapped using the fitted models for response variables (i.e. via bootEff()), their equivalent 'bootstrapped' estimates are calculated instead using each bootstrapped direct effect.

Confidence intervals for all effects are returned in summary tables for each response (see bootCI()), with BCa intervals calculated by default using the bootstrapped estimates for each effect type (Cheung, 2009; Hayes & Scharkow, 2013; MacKinnon et al., 2004). Effects for which the confidence intervals do not contain zero are highlighted with a star (i.e. 'significant' at the ci.conf level). Bootstrap standard errors (standard deviations of the samples) and biases (sample means minus original estimates) are also included. Correlated errors (and confidence intervals) are also returned if their bootstrapped values are present in sem, or if they are specified to argument cor.err or as part of a "psem" object (see bootEff()). These represent residual relationships among response variables, unaccounted for by the hypothesised SEM paths. Use summary() for effect summary tables and print() to return a table of variable names and associated details.

All calculated effects and bootstrapped effects are also returned in lists for each response variable, with all except mediator effects also including the model intercept(s) – required for prediction (these will be zero for ordinary linear models with fully standardised effects). Effects can be conveniently extracted with getEff() and related functions.

## References

Cheung, M. W. L. (2009). Comparison of methods for constructing confidence intervals of standardized indirect effects. Behavior Research Methods, 41(2), 425-438. doi: 10/fnx7xk

Hayes, A. F., & Scharkow, M. (2013). The Relative Trustworthiness of Inferential Tests of the Indirect Effect in Statistical Mediation Analysis: Does Method Really Matter? Psychological Science, 24(10), 1918-1927. doi: 10/bbhr

Lefcheck, J. S. (2016). piecewiseSEM: Piecewise structural equation modelling in R for ecology, evolution, and systematics. Methods in Ecology and Evolution, 7(5), 573-579. doi: 10/f8s8rb

MacKinnon, D. P., Lockwood, C. M., & Williams, J. (2004). Confidence Limits for the Indirect Effect: Distribution of the Product and Resampling Methods. Multivariate Behavioral Research, 39(1), 99. doi: 10/chqcnx

Shipley, B. (2000). A New Inferential Test for Path Models Based on Directed Acyclic Graphs. Structural Equation Modeling: A Multidisciplinary Journal, 7(2), 206-218. doi: 10/cqm32d

Shipley, B. (2009). Confirmatory path analysis in a generalized multilevel context. Ecology, 90(2), 363-368. doi: 10/bqd43d

## Examples

# SEM effects
(shipley.sem.eff <- semEff(shipley.sem.boot))
#>
#> Piecewise SEM with:
#>   * 1 exogenous vs. 4 endogenous variable(s)
#>   * 4 direct vs. 6 indirect effect(s)
#>
#> Variables:#>           Category   Predictor Mediator Response   Dir. Eff. Ind. Eff.
#>           --------   --------- -------- --------   --------- ---------
#>  lat    | Exog.    |     Y        N        N     |         -         - |
#>  DD     | Endog.   |     Y        Y        Y     |         1         0 |
#>  Date   | Endog.   |     Y        Y        Y     |         1         1 |
#>  Growth | Endog.   |     Y        Y        Y     |         1         2 |
#>  Live   | Endog.   |     N        N        Y     |         1         3 |#>
#> Use summary() for effects and confidence intervals for endogenous variables.summary(shipley.sem.eff)
#>
#> SEM direct, summed indirect, total, and mediator effects:#>
#> DD (1/4):#>                  Effect    Bias   Std. Err.   Lower CI Upper CI
#>                  ------   -----   ---------   -------- --------
#>  DIRECT    lat | -0.688 | 0.026 |     0.101 |   -0.828   -0.459 | *
#>
#>  INDIRECT  n/a |      - |     - |         - |        -        - |
#>
#>  TOTAL     lat | -0.688 | 0.026 |     0.101 |   -0.828   -0.459 | *
#>
#>  MEDIATORS n/a |      - |     - |         - |        -        - |
#> #>
#> Date (2/4):#>                  Effect     Bias   Std. Err.   Lower CI Upper CI
#>                  ------   ------   ---------   -------- --------
#>  DIRECT    DD  | -0.628 |  0.000 |     0.057 |   -0.741   -0.519 | *
#>
#>  INDIRECT  lat |  0.432 | -0.012 |     0.089 |    0.239    0.580 | *
#>
#>  TOTAL     lat |  0.432 | -0.012 |     0.089 |    0.239    0.580 | *
#>            DD  | -0.628 |  0.000 |     0.057 |   -0.741   -0.519 | *
#>
#>  MEDIATORS DD  |  0.432 | -0.012 |     0.089 |    0.239    0.580 | *
#> #>
#> Growth (3/4):#>                   Effect     Bias   Std. Err.   Lower CI Upper CI
#>                   ------   ------   ---------   -------- --------
#>  DIRECT    Date |  0.382 |  0.011 |     0.058 |    0.293    0.515 | *
#>
#>  INDIRECT  lat  |  0.165 |  0.001 |     0.048 |    0.086    0.281 | *
#>            DD   | -0.240 | -0.007 |     0.042 |   -0.344   -0.181 | *
#>
#>  TOTAL     lat  |  0.165 |  0.001 |     0.048 |    0.086    0.281 | *
#>            DD   | -0.240 | -0.007 |     0.042 |   -0.344   -0.181 | *
#>            Date |  0.382 |  0.011 |     0.058 |    0.293    0.515 | *
#>
#>  MEDIATORS DD   |  0.165 |  0.001 |     0.048 |    0.086    0.281 | *
#>            Date | -0.075 | -0.006 |     0.017 |   -0.109   -0.049 | *
#> #>
#> Live (4/4):#>                     Effect     Bias   Std. Err.   Lower CI Upper CI
#>                     ------   ------   ---------   -------- --------
#>  DIRECT    Growth |  0.368 |  0.151 |     0.130 |    0.246    0.411 | *
#>
#>  INDIRECT  lat    |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            DD     | -0.088 | -0.039 |     0.037 |   -0.106   -0.055 | *
#>            Date   |  0.141 |  0.063 |     0.059 |    0.093    0.163 | *
#>
#>  TOTAL     lat    |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            DD     | -0.088 | -0.039 |     0.037 |   -0.106   -0.055 | *
#>            Date   |  0.141 |  0.063 |     0.059 |    0.093    0.163 | *
#>            Growth |  0.368 |  0.151 |     0.130 |    0.246    0.411 | *
#>
#>  MEDIATORS DD     |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            Date   | -0.028 | -0.014 |     0.014 |   -0.033   -0.011 | *
#>            Growth |  0.113 |  0.049 |     0.051 |    0.051    0.142 | *
#>
# Effects for selected variables
summary(shipley.sem.eff, response = "Live")
#>
#> SEM direct, summed indirect, total, and mediator effects:#>
#> Live (4/4):#>                     Effect     Bias   Std. Err.   Lower CI Upper CI
#>                     ------   ------   ---------   -------- --------
#>  DIRECT    Growth |  0.368 |  0.151 |     0.130 |    0.246    0.411 | *
#>
#>  INDIRECT  lat    |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            DD     | -0.088 | -0.039 |     0.037 |   -0.106   -0.055 | *
#>            Date   |  0.141 |  0.063 |     0.059 |    0.093    0.163 | *
#>
#>  TOTAL     lat    |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            DD     | -0.088 | -0.039 |     0.037 |   -0.106   -0.055 | *
#>            Date   |  0.141 |  0.063 |     0.059 |    0.093    0.163 | *
#>            Growth |  0.368 |  0.151 |     0.130 |    0.246    0.411 | *
#>
#>  MEDIATORS DD     |  0.061 |  0.025 |     0.032 |    0.007    0.095 | *
#>            Date   | -0.028 | -0.014 |     0.014 |   -0.033   -0.011 | *
#>            Growth |  0.113 |  0.049 |     0.051 |    0.051    0.142 | *
#> # summary(semEff(shipley.sem.boot, predictor = "lat"))
# summary(semEff(shipley.sem.boot, mediator = "DD"))

# Effects calculated using original SEM (models)
# (not typically recommended – better to use saved boot objects)
# system.time(
#  shipley.sem.eff <- semEff(shipley.sem, R = 1000, seed = 13,
#                            ran.eff = "site")
# )