Improve documentation of plot_lcsm function

[isaactpetersen]

Thank you very much for developing this helpful package. I'm trying to create a plot of the path diagram of a bivariate latent change score model. I receive the following error when trying to plot the path diagram:

Error in lavParseModelString(model.syntax = model, warn = warn, debug = FALSE): lavaan ERROR: empty model syntax

Here is a reprex using the supplied examples from the documentation:

library("lavaan")
#> This is lavaan 0.6-12
#> lavaan is FREE software! Please report any bugs.
library("lcsm")
#> Warning: package 'lcsm' was built under R version 4.2.2

bivariateLCSM_syntax <- specify_bi_lcsm(
  timepoints = 10,
  var_x = "x",
  model_x = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  var_y = "y",
  model_y = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  coupling = list(
    delta_lag_xy = TRUE,
    delta_lag_yx = TRUE),
  change_letter_x = "g",
  change_letter_y = "j")

bivariateLCSM_fit <- fit_bi_lcsm(
  data = data_bi_lcsm,
  var_x = names(data_bi_lcsm)[2:4],
  var_y = names(data_bi_lcsm)[12:14],
  model_x = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = FALSE),
  model_y = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  coupling = list(
    delta_lag_xy = TRUE,
    xi_lag_yx = TRUE)
)
#> Warning in lav_model_vcov(lavmodel = lavmodel, lavsamplestats = lavsamplestats, : lavaan WARNING:
#>     The variance-covariance matrix of the estimated parameters (vcov)
#>     does not appear to be positive definite! The smallest eigenvalue
#>     (= 3.018389e-16) is close to zero. This may be a symptom that the
#>     model is not identified.

plot_lcsm(bivariateLCSM_fit)
#> Error in lavParseModelString(model.syntax = model, warn = warn, debug = FALSE): lavaan ERROR: empty model syntax

sessionInfo()
#> R version 4.2.0 (2022-04-22 ucrt)
#> Platform: x86_64-w64-mingw32/x64 (64-bit)
#> Running under: Windows 10 x64 (build 19044)
#> 
#> Matrix products: default
#> 
#> locale:
#> [1] LC_COLLATE=English_United States.utf8 
#> [2] LC_CTYPE=English_United States.utf8   
#> [3] LC_MONETARY=English_United States.utf8
#> [4] LC_NUMERIC=C                          
#> [5] LC_TIME=English_United States.utf8    
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] lcsm_0.1.2    lavaan_0.6-12
#> 
#> loaded via a namespace (and not attached):
#>  [1] compiler_4.2.0    pillar_1.8.1      highr_0.9         R.methodsS3_1.8.2
#>  [5] R.utils_2.12.1    tools_4.2.0       digest_0.6.30     tibble_3.1.8     
#>  [9] evaluate_0.17     lifecycle_1.0.3   R.cache_0.16.0    pkgconfig_2.0.3  
#> [13] rlang_1.0.6       reprex_2.0.2      DBI_1.1.3         cli_3.4.1        
#> [17] rstudioapi_0.14   yaml_2.3.6        parallel_4.2.0    pbivnorm_0.6.0   
#> [21] xfun_0.34         fastmap_1.1.0     withr_2.5.0       styler_1.8.0     
#> [25] stringr_1.4.1     dplyr_1.0.10      knitr_1.40        generics_0.1.3   
#> [29] fs_1.5.2          vctrs_0.5.0       tidyselect_1.2.0  stats4_4.2.0     
#> [33] glue_1.6.2        R6_2.5.1          fansi_1.0.3       rmarkdown_2.17   
#> [37] purrr_0.3.5       magrittr_2.0.3    htmltools_0.5.3   MASS_7.3-58.1    
#> [41] assertthat_0.2.1  mnormt_2.1.1      utf8_1.2.2        stringi_1.7.8    
#> [45] R.oo_1.25.0

^{Created on 2022-11-05 with reprex v2.0.2}

Any help would be greatly appreciated. Thanks!

[milanwiedemann]

ah sorry I missed this, thanks for reporting @isaactpetersen! unfortunately this function isn't very well documented and also not very intuitive to use (I need to update the documentation).

you need to specify these three additional arguments that are also needed:

• lavaan_object: the lavaan fit object needs to be specified together with a
• lcsm: a string indicating whether the latent change score model is "univariate" or "bivariate", and
• lavaan_syntax: a separate object with the lavaan syntax as a string

I hope this helps! I know this isn't ideal and needs to be improved! at the time I found that it's quite challenging to automatically generate good looking latent change score path diagrams and I had to do some workarounds.

library("lavaan")
#> This is lavaan 0.6-13
#> lavaan is FREE software! Please report any bugs.
library("lcsm")

bivariateLCSM_syntax <- specify_bi_lcsm(
  timepoints = 10,
  var_x = "x",
  model_x = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  var_y = "y",
  model_y = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  coupling = list(
    delta_lag_xy = TRUE,
    delta_lag_yx = TRUE),
  change_letter_x = "g",
  change_letter_y = "j")

bivariateLCSM_fit <- fit_bi_lcsm(
  data = data_bi_lcsm,
  var_x = names(data_bi_lcsm)[2:4],
  var_y = names(data_bi_lcsm)[12:14],
  model_x = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = FALSE),
  model_y = list(
    alpha_constant = TRUE,
    beta = TRUE,
    phi = TRUE),
  coupling = list(
    delta_lag_xy = TRUE,
    xi_lag_yx = TRUE)
)
#> Warning in lav_model_vcov(lavmodel = lavmodel, lavsamplestats = lavsamplestats, : lavaan WARNING:
#>     The variance-covariance matrix of the estimated parameters (vcov)
#>     does not appear to be positive definite! The smallest eigenvalue
#>     (= 3.018389e-16) is close to zero. This may be a symptom that the
#>     model is not identified.

plot_lcsm(lavaan_object = bivariateLCSM_fit,
          lcsm = "bivariate",
          lavaan_syntax = bivariateLCSM_syntax)

sessionInfo()
#> R version 4.2.2 (2022-10-31)
#> Platform: x86_64-apple-darwin17.0 (64-bit)
#> Running under: macOS Big Sur ... 10.16
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
#> 
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] lcsm_0.1.2    lavaan_0.6-13
#> 
#> loaded via a namespace (and not attached):
#>   [1] nlme_3.1-160        fs_1.5.2            RColorBrewer_1.1-3 
#>   [4] mi_1.1              R.cache_0.16.0      tools_4.2.2        
#>   [7] backports_1.4.1     utf8_1.2.2          R6_2.5.1           
#>  [10] rpart_4.1.19        Hmisc_4.7-2         DBI_1.1.3          
#>  [13] colorspace_2.0-3    nnet_7.3-18         withr_2.5.0        
#>  [16] tidyselect_1.2.0    gridExtra_2.3       mnormt_2.1.1       
#>  [19] compiler_4.2.2      fdrtool_1.2.17      qgraph_1.9.3       
#>  [22] cli_3.4.1           htmlTable_2.4.1     scales_1.2.1       
#>  [25] checkmate_2.1.0     psych_2.2.9         pbapply_1.7-0      
#>  [28] sem_3.1-15          stringr_1.4.1       digest_0.6.30      
#>  [31] pbivnorm_0.6.0      foreign_0.8-83      minqa_1.2.5        
#>  [34] rmarkdown_2.18      R.utils_2.12.2      base64enc_0.1-3    
#>  [37] jpeg_0.1-10         pkgconfig_2.0.3     htmltools_0.5.3    
#>  [40] lme4_1.1-31         styler_1.8.1        lisrelToR_0.1.5    
#>  [43] fastmap_1.1.0       highr_0.9           htmlwidgets_1.5.4  
#>  [46] rlang_1.0.6         rstudioapi_0.14     generics_0.1.3     
#>  [49] gtools_3.9.4        dplyr_1.0.10        zip_2.2.2          
#>  [52] R.oo_1.25.0         magrittr_2.0.3      OpenMx_2.21.1      
#>  [55] Formula_1.2-4       interp_1.1-3        Matrix_1.5-3       
#>  [58] Rcpp_1.0.9          munsell_0.5.0       fansi_1.0.3        
#>  [61] abind_1.4-5         rockchalk_1.8.157   lifecycle_1.0.3    
#>  [64] R.methodsS3_1.8.2   stringi_1.7.8       yaml_2.3.6         
#>  [67] carData_3.0-5       MASS_7.3-58.1       plyr_1.8.8         
#>  [70] grid_4.2.2          parallel_4.2.2      deldir_1.0-6       
#>  [73] lattice_0.20-45     semPlot_1.1.6       kutils_1.70        
#>  [76] splines_4.2.2       knitr_1.40          pillar_1.8.1       
#>  [79] igraph_1.3.5        boot_1.3-28         corpcor_1.6.10     
#>  [82] reshape2_1.4.4      stats4_4.2.2        reprex_2.0.2       
#>  [85] XML_3.99-0.13       glue_1.6.2          evaluate_0.18      
#>  [88] latticeExtra_0.6-30 RcppParallel_5.1.6  data.table_1.14.4  
#>  [91] png_0.1-8           vctrs_0.5.0         nloptr_2.0.3       
#>  [94] gtable_0.3.1        purrr_0.3.5         assertthat_0.2.1   
#>  [97] ggplot2_3.4.0       xfun_0.34           openxlsx_4.2.5.1   
#> [100] xtable_1.8-4        coda_0.19-4         glasso_1.11        
#> [103] survival_3.4-0      tibble_3.1.8        arm_1.13-1         
#> [106] cluster_2.1.4

^{Created on 2023-01-23 with reprex v2.0.2}

[isaactpetersen]

That perfectly answers my question--thank you! I will go ahead and close the issue. Much appreciated, and I agree that additional documentation could be helpful. Thanks, and let me know if there's additional info I can provide that would help!

[milanwiedemann]

thanks! if there's anything in particular that you think would help in the documentation feel free to make a suggestion. I'm hoping to make some updates (similar to my answer in this issue) in the coming weeks

[isaactpetersen]

Perhaps providing a bivariate example in addition to a univariate example in the examples section (https://github.com/milanwiedemann/lcsm/blob/master/man/plot_lcsm.Rd#L90)? That's all I can think of at the moment.

[milanwiedemann]

now on it's way to cran

[isaactpetersen]

Great, thank you! That's very helpful. Do you have recommendations for generating the prototypical (model-implied) trajectory from the model? It's great to have the path diagram and individuals' trajectories, but it'd also be nice to be able to generate the model-implied trajectory? Does that make sense?