Power analysis for the RI-CLPM (and STARTS model)

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 search_* arguments.
time_points: An integer (vector) with elements at least larger than 3, indicating number of time points.
ICC: A double (vector) with elements between 0 and 1, denoting the proportion of (true score) variance at the between-unit level. When measurement error is included in the data generating model, ICC is computed as the variance of the random intercept factor divided by the true score variance (i.e., controlled for measurement error).
RI_cor: A double between 0 and 1, denoting the correlation between random intercepts.
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 double between 0 and 1, denoting the correlation between the within-unit components.
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 simulateData).
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 simulateData).
estimate_ME: (optional) A logical, denoting if measurement error variance should be estimated in the RI-CLPM (see "Details").
alpha: (optional) A double, denoting the significance criterion.
reps: A positive integer, denoting the number of Monte Carlo replications to be used during simulations.
bootstrap_reps: (optional) A positive integer, denoting the number of bootstrap samples to use for quantifying the uncertainty (i.e., 95% bootstrap confidence interval) around the power analysis results.
seed: An integer of length 1. If multiple cores are used, a seed of length 1 will be used to generate a full L'Ecuyer-CMRG seed for all cores (see furrr_options).
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: ML, see "Details").
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.

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.

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 when estimate_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.

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

Author

Jeroen D. Mulder j.d.mulder@uu.nl

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)
#> Loading required package: future
library(progressr)
future::plan(multisession)

# \donttest{
# 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
  )
})
#> ℹ Checking arguments...
#> ℹ Creating lavaan syntax...
#> ℹ Starting Monte Carlo replications...
# }

# \dontshow{
## Shut down parallel workers (done for sake of example, normally not needed)
future::plan("sequential")
# }