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

## Usage

```
semEff(
sem,
predictors = NULL,
mediators = NULL,
excl.other.med = FALSE,
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.- predictors, mediators
Names of variables for/through which to calculate effects. If

`NULL`

(default), all predictors/mediators in the SEM will be used.- excl.other.med
Logical, whether to exclude other SEM mediators from calculating indirect effects, i.e., those not specified in the

`mediators`

argument. Useful for examining individual effect pathways with only the specified mediators, rather than including all paths involving them (default). Ignored if`mediators = NULL`

.- use.raw
Logical, whether to use 'raw' (unstandardised) effects for all calculations (if present in

`sem`

).- ci.conf
A numeric value specifying the confidence level for confidence intervals on effects.

- ci.type
The type of confidence interval to return (defaults to

`"bca"`

– see Details). See`boot::boot.ci()`

for further specification details.- digits
The number of decimal places to return for numeric values (for summary tables).

- bci.arg
A named list of any additional arguments to

`boot::boot.ci()`

, excepting argument`index`

.- ...
Arguments to

`bootEff()`

.

## Value

A list object of class `"semEff"`

for which several methods and
extractor functions are available. Contains:

Summary tables of effects and confidence intervals

All effects

All bootstrapped effects

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 (see `stdEff()`

for details), 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 BC*a* 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. | x - - | - - |
#> DD | Endog. | x x x | 1 0 |
#> Date | Endog. | x x x | 1 1 |
#> Growth | Endog. | x x x | 1 2 |
#> Live | Endog. | - - x | 1 3 |
#>
#> Use summary() for effects and confidence intervals for endogenous variables.
#> See ?getEff() for extracting (unformatted) effects.
summary(shipley.sem.eff)
#>
#> SEM direct, summed indirect, total, and mediator effects:
#>
#> Response 'DD' (1/4):
#> Effect Bias Std. Err. Lower CI Upper CI
#> ------ ----- --------- -------- --------
#> DIRECT: lat | -0.688 | 0.026 | 0.101 | -0.828 -0.459 | *
#> | | | | |
#> INDIRECT: - | - | - | - | - - |
#> | | | | |
#> TOTAL: lat | -0.688 | 0.026 | 0.101 | -0.828 -0.459 | *
#> | | | | |
#> MEDIATORS: - | - | - | - | - - |
#>
#>
#> Response '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 | *
#>
#>
#> Response '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 | *
#>
#>
#> Response '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:
#>
#> Response '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")
# )
```