powRICLPM {powRICLPM} | R Documentation |
Power analysis for the RI-CLPM (and STARTS model)
Description
Perform a Monte Carlo power analysis for the random intercept cross-lagged panel model (RI-CLPM). This function computes performance metrics (e.g., bias, mean square error, coverage, power, etc) for all RI-CLPM parameters, and can perform power analyses across multiple experimental conditions simultaneously. Conditions are defined in terms of sample size, number of time points, and proportion of between-unit variance (ICC). See "Details" for information on a) the data simulation, b) model estimation, c) internal naming conventions of parameters, d) the option to include measurement errors (i.e., estimating the Stable Trait Autoregressive Trait State model), e) imposing various constraints over time, and f) parallel execution capabilities for speeding up the analysis.
Usage
powRICLPM(
target_power,
search_lower = NULL,
search_upper = NULL,
search_step = 20,
sample_size = NULL,
time_points,
ICC,
RI_cor,
Phi,
within_cor,
reliability = 1,
skewness = 0,
kurtosis = 0,
estimate_ME = FALSE,
alpha = 0.05,
reps = 20,
bootstrap_reps = 1000,
seed = NA,
constraints = "none",
bounds = FALSE,
estimator = NA,
save_path = NULL
)
Arguments
target_power |
A numeric value between 0 and 1, denoting the targeted power level. |
search_lower |
A positive integer, denoting the lower bound of a range of sample sizes. |
search_upper |
A positive integer, denoting the upper bound of a range of sample sizes. |
search_step |
A positive integer, denoting an increment in sample size. |
sample_size |
(optional) An integer (vector), indicating specific sample sizes at which to evaluate power, rather than specifying a range using the |
time_points |
An integer (vector) with elements at least larger than 3, indicating number of time points. |
ICC |
A |
RI_cor |
A |
Phi |
A matrix, with standardized autoregressive effects (on the diagonal) and cross-lagged effects (off-diagonal) in the population. Columns represent predictors and rows represent outcomes. |
within_cor |
A |
reliability |
(optional) A numeric value between 0 and 1, denoting the reliability of the variables. |
skewness |
(optional) A numeric value, denoting the skewness values for the observed variables (see |
kurtosis |
(optional) A numeric value, denoting the excess kurtosis values (i.e., compared to the kurtosis of a normal distribution) for the observed variables (see |
estimate_ME |
(optional) A logical, denoting if measurement error variance should be estimated in the RI-CLPM (see "Details"). |
alpha |
(optional) A |
reps |
A positive |
bootstrap_reps |
(optional) A positive |
seed |
An |
constraints |
(optional) A character string, specifying the type of constraints that should be imposed on the estimation model (see "Details"). |
bounds |
(optional) A logical, denoting if bounded estimation should be used for the latent variable variances in the model (see "Details"). |
estimator |
(options) A character, denoting the estimator to be used (default: |
save_path |
A character string naming the directory to save (data) files to (used for validation purposes of this package). Variables are saved in alphabetical and numerical order. |
Details
A rationale for the power analysis strategy implemented in this package can be found in Mulder (2022).
Data generation
Data are generated using simulateData
from the lavaan package. Based on Phi
and within_cor
, the residual variances and covariances for the within-components at wave 2 and later are computed, such that the within-components themselves have a variance of 1. This implies that the lagged effects in Phi
can be interpreted as standardized effects.
Model estimation
Data are analyzed using lavaan
from the lavaan package. The default estimator is maximum likelihood (ML
). Other maximum likelihood based estimators implemented in lavaan can be specified as well. When skewed or kurtosed data are generated (using the skewness
and kurtosis
arguments), the estimator defaults to robust maximum likelihood MLR
. The population parameter values are used as starting values.
Parameter estimates from non-converged model solutions are discarded from the results. When bounds = FALSE
, inadmissible parameter estimates from converged solutions (e.g., a negative random intercept variance) are discarded. When bounds = TRUE
, inadmissible parameter estimates are retained following advice by De Jonckere and Rosseel (2022). The results include the minimum estimates for all parameters across replications to diagnose which parameter(s) is (are) the cause of the inadmissible solution.
Naming conventions for observed and latent variables
The observed variables in the RI-CLPM are given default names, namely capital letters in alphabetical order, with numbers denoting the measurement occasion. For example, for a bivariate RICLPM with 3 time points, we observe A1
, A2
, A3
, B1
, B2
, and B3
. Their within-components are denoted by wA1
, wA2
, ..., wB3
, respectively. The between-components have RI_
prepended to the variable name, resulting in RI_A
and RI_B
.
Parameters are denoted using lavaan model syntax (see the lavaan website). For example, the random intercept variances are denoted by RI_A~~RI_A
and RI_B~~RI_B
, the cross-lagged effects at the first wave as wB2~wA1
and wA2~wB1
, and the autoregressive effects as wA2~wA1
and wB2~wB1
. Use give(object, "names")
to extract parameter names from the powRICLPM
object.
Measurement errors (STARTS model)
Including measurement error to the RI-CLPM makes the model equivalent to the Stable Trait Autoregressive Trait State (STARTS) model by Kenny and Zautra (2001) without constraints over time. Measurement error can be added to the generated data through the reliability
argument. Setting reliability = 0.8
implies that 80% is true score variance and 20% is measurement error variance; ICC
then denotes the proportion of true score variance captured by the random intercept factors. Estimating measurement errors (i.e., the STARTS model) is done by setting est_ME = TRUE
.
Imposing constraints
The following constraints can be imposed on the estimation model using the constraints = "..."
argument:
-
lagged
: Time-invariant autoregressive and cross-lagged effects. -
residuals
: Time-invariant residual variances. -
within
: Time-invariant lagged effects and residual variances. -
stationarity
: Constraints such that at the within-unit level a stationary process is estimated. This included time-invariant lagged effects, and constraints on the residual variances. -
ME
: Time-invariant measurement error variances. Only possible whenestimate_ME = TRUE
.
Bounded estimation
Bounded estimation is useful to avoid nonconvergence in small samples (< 100). Here, automatic wide bounds are used as advised by De Jonckere and Rosseel (2022), see optim.bounds
in lavOptions
. This option can only be used when no constraints are imposed on the estimation model.
Parallel processing using furrr
To speed up the analysis, power analysis for multiple experimental conditions can be executed in parallel. This has been implemented using furrr. By default the analysis is executed sequentially (i.e., single-core). Parallel execution (i.e., multicore) can be setup using plan
, for example plan(multisession, workers = 4)
. For more information and options, see https://furrr.futureverse.org.
A progress bar displaying the status of the power analysis has been implemented using progressr. By default, a simple progress bar will be shown. For more information on how to control this progress bar and several other notification options (e.g., auditory notifications), see https://progressr.futureverse.org.
Value
A list
containing a conditions
and session
element. condition
itself is a list
of experimental conditions, where each element is again a list
containing the input and output of the power analysis for that particular experimental condition. session
is a list
containing information common to all experimental conditions.
Author(s)
Jeroen D. Mulder j.d.mulder@uu.nl
References
De Jonckere, J., & Rosseel, Y. (2022). Using bounded estimation to avoid nonconvergence in small sample structural equation modeling. Structural Equation Modeling, 29(3), 412-427. doi:10.1080/10705511.2021.1982716
Kenny, D. A., & Zautra, A. (2001). Trait–state models for longitudinal data. New methods for the analysis of change (pp. 243–263). American Psychological Association. doi:10.1037/10409-008
Mulder, J. D. (2022). Power analysis for the random intercept cross-lagged panel model using the powRICLPM R-package. Structural Equation Modeling. doi:10.1080/10705511.2022.2122467
See Also
-
powRICLPM_Mplus
: Create Mplus model syntax for RI-CLPM power analysis. -
summary.powRICLPM
: Summarize the setup ofpowRICLPM
object. -
give
: Extract information frompowRICLPM
objects. -
plot.powRICLPM
: Visualize resultspowRICLPM
object for a specific parameter.
Examples
# Define population parameters for lagged effects
Phi <- matrix(c(.4, .1, .2, .3), ncol = 2, byrow = TRUE)
# (optional) Set up parallel computing (i.e., multicore, speeding up the analysis)
library(furrr)
library(progressr)
future::plan(multisession)
# Run analysis ("reps" is small, because this is an example)
with_progress({
out_preliminary <- powRICLPM(
target_power = 0.8,
search_lower = 500,
search_upper = 800,
search_step = 100,
time_points = c(3, 4),
ICC = c(0.4, 0.6),
RI_cor = 0.3,
Phi = Phi,
within_cor = 0.3,
reps = 100,
seed = 1234
)
})