R: Fit a Latent Growth Curve Model or Latent Change Score Model...

getTVCmodel {nlpsem}

R Documentation

Fit a Latent Growth Curve Model or Latent Change Score Model with Time-varying and Time-invariant Covariates

Description

This function fits a latent growth curve model or latent change score model with a time-varying covariate and potential time-invariant covariates to the provided data. It manages model setup, optimization, and if requested, outputs parameter estimates and standard errors.

Usage

getTVCmodel(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic = TRUE,
  records,
  y_model,
  TVC,
  decompose,
  growth_TIC = NULL,
  starts = NULL,
  res_scale = NULL,
  res_cor = NULL,
  tries = NULL,
  OKStatus = 0,
  jitterD = "runif",
  loc = 1,
  scale = 0.25,
  paramOut = FALSE,
  names = NULL
)

Arguments

`dat`	A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements (for the longitudinal outcome and time-varying covariates), occasions, and time-invariant covariates (TICs) if any.
`t_var`	A string specifying the prefix of the column names corresponding to the time variable at each study wave.
`y_var`	A string specifying the prefix of the column names corresponding to the outcome variable at each study wave.
`curveFun`	A string specifying the functional form of the growth curve. Supported options for `y_model = "LGCM"` include: `"linear"` (or `"LIN"`), `"quadratic"` (or `"QUAD"`), `"negative exponential"` (or `"EXP"`), `"Jenss-Bayley"` (or `"JB"`), and `"bilinear spline"` (or `"BLS"`). Supported options for `y_model = "LCSM"` include: `"nonparametric"` (or `"NonP"`), `"quadratic"` (or `"QUAD"`), `"negative exponential"` (or `"EXP"`), and `"Jenss-Bayley"` (or `"JB"`.
`intrinsic`	A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. Default is `TRUE`.
`records`	A numeric vector specifying the indices of the observed study waves.
`y_model`	A string specifying how to fit the longitudinal outcome. Supported values are `"LGCM"` and `"LCSM"`.
`TVC`	A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave.
`decompose`	An integer specifying the decomposition option for temporal states. Supported values include `0` (no decomposition), `1` (decomposition with interval-specific slopes as temporal states), `2` (decomposition with interval- specific changes as temporal states), and `3` (decomposition with change-from-baseline as temporal states).
`growth_TIC`	A string or character vector specifying the column name(s) of time-invariant covariate(s) that account for the variability of growth factors, if any. Default is `NULL`, indicating no growth TICs present in the model.
`starts`	A list containing initial values for the parameters. Default is `NULL`, indicating no user-specified initial values.
`res_scale`	A numeric value or numeric vector. For a model with `decompose = 0`, it is a numeric value representing the scaling factor used to calculate the initial value for the residual variance of the longitudinal outcome. In cases where `decompose != 0`, it is a numeric vector of user-specified scaling factors used to calculate the initial values for the residual variance of both the longitudinal outcome and the time-varying covariate. By default, this is `NULL`, as it is unnecessary when the user specifies the initial values using the `starts` argument.
`res_cor`	A numeric value. When `decompose != 0`, this represents the user-specified residual correlation between the longitudinal outcome and the time-varying covariate, which is used to calculate the corresponding initial value. If `decompose = 0`, this should be `NULL`. By default, this is `NULL`, as it is unnecessary when the user specifies the initial values using the `starts` argument.
`tries`	An integer specifying the number of additional optimization attempts. Default is `NULL`.
`OKStatus`	An integer (vector) specifying acceptable status codes for convergence. Default is `0`.
`jitterD`	A string specifying the distribution for jitter. Supported values are: `"runif"` (uniform distribution), `"rnorm"` (normal distribution), and `"rcauchy"` (Cauchy distribution). Default is `"runif"`.
`loc`	A numeric value representing the location parameter of the jitter distribution. Default is `1`.
`scale`	A numeric value representing the scale parameter of the jitter distribution. Default is `0.25`.
`paramOut`	A logical flag indicating whether to output the parameter estimates and standard errors. Default is `FALSE`.
`names`	A character vector specifying parameter names. Default is `NULL`.

Value

An object of class myMxOutput. Depending on the paramOut argument, the object may contain the following slots:

mxOutput: This slot contains the fitted latent growth curve model or latent change score model with a time-varying covariate. A summary of this model can be obtained using the ModelSummary() function.
Estimates (optional): If paramOut = TRUE, a data frame with parameter estimates and standard errors. The content of this slot can be printed using the printTable() method for S4 objects.

References

Liu, J., & Perera, R. A. (2023). Estimating Rate of Change for Nonlinear Trajectories in the Framework of Individual Measurement Occasions: A New Perspective on Growth Curves. Behavior Research Methods. doi:10.3758/s13428-023-02097-2
Liu, J. (2022). "Decomposing Impact on Longitudinal Outcome of Time-varying Covariate into Baseline Effect and Temporal Effect." arXiv. https://arxiv.org/abs/2210.16916

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
data("RMS_dat")
RMS_dat0 <- RMS_dat
# Re-baseline the data so that the estimated initial status is for the starting point of the study
baseT <- RMS_dat0$T1
RMS_dat0$T1 <- (RMS_dat0$T1 - baseT)/12
RMS_dat0$T2 <- (RMS_dat0$T2 - baseT)/12
RMS_dat0$T3 <- (RMS_dat0$T3 - baseT)/12
RMS_dat0$T4 <- (RMS_dat0$T4 - baseT)/12
RMS_dat0$T5 <- (RMS_dat0$T5 - baseT)/12
RMS_dat0$T6 <- (RMS_dat0$T6 - baseT)/12
RMS_dat0$T7 <- (RMS_dat0$T7 - baseT)/12
RMS_dat0$T8 <- (RMS_dat0$T8 - baseT)/12
RMS_dat0$T9 <- (RMS_dat0$T9 - baseT)/12
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)

# Standardize reading ability over time with its baseline value
BL_mean <- mean(RMS_dat0[, "R1"])
BL_var <- var(RMS_dat0[, "R1"])
RMS_dat0$Rs1 <- (RMS_dat0$R1 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs2 <- (RMS_dat0$R2 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs3 <- (RMS_dat0$R3 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs4 <- (RMS_dat0$R4 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs5 <- (RMS_dat0$R5 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs6 <- (RMS_dat0$R6 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs7 <- (RMS_dat0$R7 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs8 <- (RMS_dat0$R8 - BL_mean)/sqrt(BL_var)
RMS_dat0$Rs9 <- (RMS_dat0$R9 - BL_mean)/sqrt(BL_var)


# Fit bilinear spline latent growth curve model (fixed knot) with a time-varying
# reading ability for mathematics development
BLS_TVC_LGCM1 <- getTVCmodel(
 dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
 records = 1:9, y_model = "LGCM", TVC = "Rs", decompose = 0,  growth_TIC = NULL,
 res_scale = 0.1
 )

# Fit negative exponential latent growth curve model (random ratio) with a
# decomposed time-varying reading ability and time-invariant covariates for
# mathematics development
paraEXP_LGCM3.f <- c(
  "Y_alpha0", "Y_alpha1", "Y_alphag",
  paste0("Y_psi", c("00", "01", "0g", "11", "1g", "gg")), "Y_residuals",
  "X_mueta0", "X_mueta1", paste0("X_psi", c("00", "01", "11")),
  paste0("X_rel_rate", 2:8), paste0("X_abs_rate", 1:8), "X_residuals",
  paste0("betaTIC", c(0:1, "g")), paste0("betaTIC", c(0:1, "g")),
  paste0("betaTVC", c(0:1, "g")),
  "muTIC1", "muTIC2", "phiTIC11", "phiTIC12", "phiTIC22",
  "Y_mueta0", "Y_mueta1", "Y_mu_slp_ratio",
  "covBL1", "covBL2", "kappa", "Cov_XYres")
set.seed(20191029)
EXP_TVCslp_LGCM3.f <- getTVCmodel(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "EXP", intrinsic = TRUE,
  records = 1:9, y_model = "LGCM", TVC = "Rs", decompose = 1,
  growth_TIC = c("ex1", "ex2"), res_scale = c(0.1, 0.1),
  res_cor = 0.3, tries = 10, paramOut = TRUE, names = paraEXP_LGCM3.f
)
printTable(EXP_TVCslp_LGCM3.f)

[Package nlpsem version 0.3 Index]