# Examples of Longitudinal Models with Time-varying Covariates

## Load nlpsem package, dependent packages and set CSOLNP as the optimizer

    library(nlpsem)
    mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)

## Load pre-computed models

    load(system.file("extdata", "getTVCmodel_examples.RData", package = "nlpsem"))

## Load example data and preprocess data

    # Load ECLS-K (2011) data
    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
    # Standardize time-invariant covariates (TICs)
    ## ex1 is standardized growth TIC in models
    RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
    # Standardize time-varying covariate (TVC)
    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)
    xstarts <- mean(baseT)

## Example 1: This example includes two models. Model 1 is a full bilinear spline LGCM with a TVC to examine the influence of baseline teacher-reported approach to learning and the development in reading ability on the development of mathematics ability. It also includes a visualization showcasing the growth status of mathematics ability. Model 2 is a full bilinear spline LGCM with a decomposed TVC (interval-specific slopes) to examine the influence of baseline teacher-reported approach to learning and the development in reading ability on the development of mathematics ability. P values and Wald confidence intervals of all parameters are provided. It also includes a visualization showcasing the growth status of mathematics ability.

    set.seed(20191029)
    Math_TVC_BLS_f <- getTVCmodel(
      dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = TRUE,
      records = 1:9, y_model = "LGCM", TVC = "Rs", decompose = 0, growth_TIC = "ex1",
      tries = 10
      )
    set.seed(20191029)
    Math_TVCslp_BLS_f <- getTVCmodel(
      dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = TRUE,
      records = 1:9, y_model = "LGCM", TVC = "Rs", decompose = 1, growth_TIC = "ex1",
      tries = 10, paramOut = TRUE
      )

    getEstimateStats(est_in = Math_TVCslp_BLS_f@Estimates, CI_type = "Wald")
    #> An object of class "StatsOutput"
    #> Slot "wald":
    #>             Estimate     SE p.value wald_lbound wald_ubound
    #> Y_alpha0     37.5074 0.4472 <0.0001     36.6309     38.3839
    #> Y_alpha1     21.3721 0.2169 <0.0001     20.9470     21.7972
    #> Y_alpha2     10.1234 0.1538 <0.0001      9.8220     10.4248
    #> Y_alphag      2.5680 0.0012 <0.0001      2.5656      2.5704
    #> Y_psi00      46.8045 4.1979 <0.0001     38.5768     55.0322
    #> Y_psi01      -0.9137 1.6982  0.5905     -4.2421      2.4147
    #> Y_psi02      -2.9771 1.6315   0.068     -6.1748      0.2206
    #> Y_psi0g      -0.1955 0.4317  0.6506     -1.0416      0.6506
    #> Y_psi11      12.5392 1.2829 <0.0001     10.0248     15.0536
    #> Y_psi12       1.6075 0.8834  0.0688     -0.1239      3.3389
    #> Y_psi1g      -0.7566 0.2347  0.0013     -1.2166     -0.2966
    #> Y_psi22       5.9502 1.1953 <0.0001      3.6075      8.2929
    #> Y_psi2g      -1.3326 0.2623 <0.0001     -1.8467     -0.8185
    #> Y_psigg       0.6003 0.0785 <0.0001      0.4464      0.7542
    #> Y_residuals  28.8523 0.8171 <0.0001     27.2508     30.4538
    #> X_mueta0     -0.0142 0.0561  0.8002     -0.1242      0.0958
    #> X_mueta1      2.5659 0.0737 <0.0001      2.4215      2.7103
    #> X_psi00       1.2100 0.0856 <0.0001      1.0422      1.3778
    #> X_psi01      -0.0783 0.0207   2e-04     -0.1189     -0.0377
    #> X_psi11       0.1017 0.0112 <0.0001      0.0797      0.1237
    #> X_rel_rate2   0.6742 0.0390 <0.0001      0.5978      0.7506
    #> X_rel_rate3   1.2330 0.0438 <0.0001      1.1472      1.3188
    #> X_rel_rate4   0.4810 0.0310 <0.0001      0.4202      0.5418
    #> X_rel_rate5   0.6394 0.0317 <0.0001      0.5773      0.7015
    #> X_rel_rate6   0.2919 0.0172 <0.0001      0.2582      0.3256
    #> X_rel_rate7   0.3023 0.0167 <0.0001      0.2696      0.3350
    #> X_rel_rate8   0.2471 0.0163 <0.0001      0.2152      0.2790
    #> X_abs_rate2   2.5659 0.0737 <0.0001      2.4215      2.7103
    #> X_abs_rate3   1.7298 0.0694 <0.0001      1.5938      1.8658
    #> X_abs_rate4   3.1639 0.0684 <0.0001      3.0298      3.2980
    #> X_abs_rate5   1.2343 0.0719 <0.0001      1.0934      1.3752
    #> X_abs_rate6   1.6407 0.0671 <0.0001      1.5092      1.7722
    #> X_abs_rate7   0.7489 0.0390 <0.0001      0.6725      0.8253
    #> X_abs_rate8   0.7758 0.0372 <0.0001      0.7029      0.8487
    #> X_abs_rate9   0.6340 0.0381 <0.0001      0.5593      0.7087
    #> X_residuals   0.3596 0.0088 <0.0001      0.3424      0.3768
    #> betaTIC0      0.9865 0.3889  0.0112      0.2243      1.7487
    #> betaTIC1      0.0917 0.2131   0.667     -0.3260      0.5094
    #> betaTIC2     -0.1590 0.1918  0.4071     -0.5349      0.2169
    #> betaTICg      0.0172 0.0470  0.7144     -0.0749      0.1093
    #> betaTVC0      7.6341 0.3802 <0.0001      6.8889      8.3793
    #> betaTVC1      0.8416 0.2070 <0.0001      0.4359      1.2473
    #> betaTVC2     -0.4071 0.1959  0.0377     -0.7911     -0.0231
    #> betaTVCg     -0.0622 0.0495  0.2089     -0.1592      0.0348
    #> muTIC         0.0000 0.0447 >0.9999     -0.0876      0.0876
    #> phiTIC        0.9980 0.0631 <0.0001      0.8743      1.1217
    #> Y_mueta0     37.3989 0.5788 <0.0001     36.2645     38.5333
    #> Y_mueta1     21.3601 0.2176 <0.0001     20.9336     21.7866
    #> Y_mueta2     10.1292 0.1546 <0.0001      9.8262     10.4322
    #> Y_mu_knot     2.5689 0.0037 <0.0001      2.5616      2.5762
    #> covBL         0.3997 0.0523 <0.0001      0.2972      0.5022
    #> kappa         1.4377 0.1004 <0.0001      1.2409      1.6345
    #> Cov_XYres     0.5725 0.0646 <0.0001      0.4459      0.6991
    #>
    #> Slot "likelihood":
    #> data frame with 0 columns and 0 rows
    #>
    #> Slot "bootstrap":
    #> data frame with 0 columns and 0 rows
    Figure1 <- getFigure(
      model = Math_TVC_BLS_f@mxOutput, sub_Model = "TVC", y_var = "M", curveFun = "BLS",
      y_model = "LGCM", t_var = "T", records = 1:9, xstarts = xstarts, xlab = "Year",
      outcome = "Mathematics"
    )
    #> Treating first argument as an object that stores a character
    show(Figure1)
    #> figOutput Object
    #> --------------------
    #> Trajectories: 1
    #> Figure 1:
    #> `geom_smooth()` using method = 'gam' and formula = 'y ~ s(x, bs = "cs")'

    Figure2 <- getFigure(
      model = Math_TVCslp_BLS_f@mxOutput, sub_Model = "TVC", y_var = "M", curveFun = "BLS",
      y_model = "LGCM", t_var = "T", records = 1:9, xstarts = xstarts, xlab = "Year",
      outcome = "Mathematics"
    )
    #> Treating first argument as an object that stores a character
    show(Figure2)
    #> figOutput Object
    #> --------------------
    #> Trajectories: 1
    #> Figure 1:
    #> `geom_smooth()` using method = 'gam' and formula = 'y ~ s(x, bs = "cs")'

A comparison between Figure 1 and Figure 2 demonstrates that incorporating a TVC directly results in underestimation of the growth factor means.

## Example 2: Fit reduced bilinear spline LGCMs with a decomposed TVC (interval-specific slopes, interval-specific changes, and change from baseline) to examine the influence of baseline teacher-reported approach to learning and the development in reading ability on the development of mathematics ability. It also includes a visualization showcasing the growth status of mathematics ability.

    set.seed(20191029)
    Math_TVCslp_BLS_r <- getTVCmodel(
      dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
      records = 1:9, y_model = "LGCM", TVC = "R", decompose = 1, growth_TIC = "ex1",
      tries = 10, paramOut = TRUE)
    set.seed(20191029)
    Math_TVCchg_BLS_r <- getTVCmodel(
      dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
      records = 1:9, y_model = "LGCM", TVC = "R", decompose = 2, growth_TIC = "ex1",
      tries = 10, paramOut = TRUE)
    set.seed(20191029)
    Math_TVCchgBL_BLS_r <- getTVCmodel(
      dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
      records = 1:9, y_model = "LGCM", TVC = "R", decompose = 3, growth_TIC = "ex1",
      tries = 10, paramOut = TRUE)

    Figure3 <- getFigure(
      model = Math_TVCslp_BLS_r@mxOutput, sub_Model = "TVC", y_var = "M", curveFun = "BLS",
      y_model = "LGCM", t_var = "T", records = 1:9, xstarts = xstarts, xlab = "Year",
      outcome = "Mathematics"
    )
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    show(Figure3)
    #> figOutput Object
    #> --------------------
    #> Trajectories: 1
    #> Figure 1:
    #> `geom_smooth()` using method = 'gam' and formula = 'y ~ s(x, bs = "cs")'

    Figure4 <- getFigure(
      model = Math_TVCchg_BLS_r@mxOutput, sub_Model = "TVC", y_var = "M", curveFun = "BLS",
      y_model = "LGCM", t_var = "T", records = 1:9, xstarts = xstarts, xlab = "Year",
      outcome = "Mathematics"
    )
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    show(Figure4)
    #> figOutput Object
    #> --------------------
    #> Trajectories: 1
    #> Figure 1:
    #> `geom_smooth()` using method = 'gam' and formula = 'y ~ s(x, bs = "cs")'

    Figure5 <- getFigure(
      model = Math_TVCchgBL_BLS_r@mxOutput, sub_Model = "TVC", y_var = "M", curveFun = "BLS",
      y_model = "LGCM", t_var = "T", records = 1:9, xstarts = xstarts, xlab = "Year",
      outcome = "Mathematics"
    )
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    #> Treating first argument as an object that stores a character
    show(Figure5)
    #> figOutput Object
    #> --------------------
    #> Trajectories: 1
    #> Figure 1:
    #> `geom_smooth()` using method = 'gam' and formula = 'y ~ s(x, bs = "cs")'