---
title: "Extensions"
output: rmarkdown::html_vignette
bibliography: references.bib
vignette: >
  %\VignetteIndexEntry{Extensions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The basic power analysis as described in the vignette [Getting Started](https://jeroendmulder.github.io/powRICLPM/articles/start.html) can be extended to using bounded estimation, estimation with constraints over time, inclusion of measurement error in the generated data and estimation model (i.e., the STARTS model), and generating data with skewness and kurtosis. These extensions are described below.

## Bounded estimation with `lavaan`
To prevent non-convergence for small sample sizes (say, less than 100), bounds can be imposed on the parameter space during estimation of the model using `bounds = TRUE` [@dejonckere_using_2022]. This can aid the optimization algorithm to find unique solutions and prevents it from searching in the completely wrong direction for one, or multiple parameters. Sensible lower bounds involve those on the (residual) variances of latent variables (e.g., the random intercept variances), as negative variances are theoretically not possible. Upper bound for variances are determined based on the observed variances for variable. In the context of the RI-CLPM, the factor loadings are (usually) fixed, and hence these parameters are not estimated. The lagged effects are theoretically infinite, and hence there are no sensible bounds we can place à priori on these parameters. 

The use of bounded estimation is theoretically appealing for models that are known to have convergence issues, such as the stable trait autoregressive trait state (STARTS) model. The Special Topics vignette [Measurement Error](https://jeroendmulder.github.io/powRICLPM/articles/measurement_error.html) uses the powRICLPM package to explore the impact of unmodeled measurement error in the RI-CLPM, and the use of bounded estimation to aid the convergence of the STARTS model. 

## Constraints over time
`powRICLPM()` offers users the option to impose various constraints over time on the estimation model through the `constraints` argument. This has statistical advantages as constraints over time reduce model complexity, thereby potentially reducing convergence issues and increasing power. Moreover, some researchers are interested in so called 'stationarity' constraints for theoretical reasons. A disadvantage of such constraints is that they assume certain parameters to be time-invariant. This might not be an assumption researchers are willing to make, especially in developmental contexts where you expect lagged effects might change over time (e.g., the variable `wA` gets more important in driving `wB` as one gets older). Therefore, by default `constraints = "none"`, implying that all lagged effects, and within-components (residual) variances and covariances are freely estimated over time. 

Constraint options include:

- `constraints = "lagged"`: Autoregressive and cross-lagged effects are constrained to be equal over time. 
- `constraints = "residuals`: Within-unit residual variances and covariance (from wave 2 onward) are constrained to be equal over time.
- `constraints = "within"`: Both lagged effects and residual variances and covariances are constrained to be equal over time.
- `constraints = "stationary"`: Constraints are imposed on the variances of the within-components at the first wave, and residual variances at wave 2 and further, such that the variances of the within-components themselves are all 1. This implies that the variances at the first wave are fixed to 1, and that the residual variances are a function of the lagged effects, and correlation between within-components at the same wave. These constraints are deduced in the supplementary materials of @mulder_three_2021, see the FAQ ["How can I constrain the *standardized* parameters to be invariant over time?"](https://jeroendmulder.github.io/RI-CLPM/faq.html#Standardization).
- `constraints = "ME"`: Constraints are imposed on the measurement error variances across time (separately for each variable). This constraint is only possible when `estimate_ME = TRUE`. 

## Measurement error
While it is generally advisable to include measurement error when analyzing psychological data, the RI-CLPM does not include it. Adding measurement error to the model would result in the bivariate STARTS model by @kenny_trait-state_2001, and requires at least 4 waves of data to be identified. Users can add measurement error variances to the estimation model by specifying `estimate_ME = TRUE`. Measurement error can be added to the simulated data using the `reliability` argument.

Note, however, that the STARTS model has been shown to be prone to empirical under-identification, often requiring upwards of 8 waves of data and sample sizes larger than 500. The Special Topics vignette [Measurement Error](https://jeroendmulder.github.io/powRICLPM/articles/measurement_error.html) uses the powRICLPM package to explore the impact of unmodeled measurement error in the RI-CLPM, and the use of bounded estimation to aid the convergence of the STARTS model. 

## Data with skewness and kurtosis
Asymmetry in the empirical distributions of psychometric measurements is rather common [@micceri_unicorn_1989], and this can impact the power of SEM models that assume normally distributed variables. The powRICLPM package allows researchers to investigate power under asymmetrically distributed data by setting values for the `skewness` and `kurtosis` arguments (default: 0). For example, suppose we have reason to believe the $A$ and $B$ variables are positively skewed, and have heavy tails (i.e., a higher kurtosis) we can include the arguments `skewness = 1` and `kurtosis = 0.5`. When the `skewness` and `kurtosis` arguments are set to values other than 0, the powRICLPM package defaults to using robust maximum likelihood (`estimator = "MLR"`). 

## References