# Fit a Latent Growth Curve Model or Latent Change Score Model with Time-varying and Time-invariant Covariates 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. ```r 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`. ## Returns 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. ## Examples ```r 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) ``` ## 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. tools:::Rd_expr_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

getTVCmodel function