Help for package nlpsem

Type:

Package

Title:

Linear and Nonlinear Longitudinal Process in Structural Equation Modeling Framework

Version:

0.3

Description:

Provides computational tools for nonlinear longitudinal models, in particular the intrinsically nonlinear models, in four scenarios: (1) univariate longitudinal processes with growth factors, with or without covariates including time-invariant covariates (TICs) and time-varying covariates (TVCs); (2) multivariate longitudinal processes that facilitate the assessment of correlation or causation between multiple longitudinal variables; (3) multiple-group models for scenarios (1) and (2) to evaluate differences among manifested groups, and (4) longitudinal mixture models for scenarios (1) and (2), with an assumption that trajectories are from multiple latent classes. The methods implemented are introduced in Jin Liu (2023) <doi:10.48550/arXiv.2302.03237>.

License:

GPL (≥ 3.0)

Encoding:

UTF-8

LazyData:

true

Depends:

R (≥ 4.0.0), OpenMx (≥ 2.21.8)

Imports:

ggplot2, dplyr, tidyr, stringr, Matrix, nnet, readr, methods

RoxygenNote:

7.2.3

URL:

https://github.com/Veronica0206/nlpsem

BugReports:

https://github.com/Veronica0206/nlpsem/issues

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2023-09-12 15:23:45 UTC; jinliu

Author:

Jin Liu [aut, cre]

Maintainer:

Jin Liu <Veronica.Liu0206@gmail.com>

Repository:

CRAN

Date/Publication:

2023-09-12 22:20:02 UTC

S4 Class for estimated factor scores and their standard errors.

Description

S4 Class for the output structure for the getIndFS() function.

Slots

scores_est: A matrix of estimated factor scores.
scores_se: A matrix of standard errors of estimated factor scores.

S4 Class for kappa statistic with confidence interval and judgment.

Description

S4 Class for the output structure for the getLatentKappa() function.

Slots

kappa_value: A character vector for the kappa statistic with $95%$ CI.
judgment: A character vector for the judgement for agreement.

S4 Generic for summarizing an optimized MxModel.

Description

Generic function for printing model summary of MxModel object.

Usage

ModelSummary(object)

Arguments

object

An object of the appropriate class.

S4 Method for summarizing an optimized MxModel.

Description

Method for printing model summary of MxModel object.

Usage

## S4 method for signature 'myMxOutput'
ModelSummary(object)

Arguments

object

An object of class "myMxOutput".

ECLS-K (2011) Sample Dataset for Demonstration

Description

A sample dataset extracted from the public-use Early Childhood Longitudinal Study, Kindergarten Class of 2010-11 (ECLS-K:2011) collected by the National Center for Education Statistics (NCES). This dataset is NOT a posting of the original data, and it has been processed and formatted for use in demonstration purposes within this package. For access to the original data, please visit the NCES data products page at https://nces.ed.gov/ecls/dataproducts.asp.

Usage

RMS_dat

Format

A data frame with 500 rows and 49 variables:

ID: Identification number.
R1, R2, R3, R4, R5, R6, R7, R8, R9: Reading scores from 9 study waves.
M1, M2, M3, M4, M5, M6, M7, M8, M9: Math scores from 9 study waves.
S2, S3, S4, S5, S6, S7, S8, S9: Science scores from 8 study waves (starting from the second study wave).
T1, T2, T3, T4, T5, T6, T7, T8, T9: Children's age-in-month at 9 study waves.
SEX: Sex of the child.
RACE: Race of the child.
LOCALE: Locale of the child's school.
INCOME: Family income.
SCHOOL_TYPE: Type of the child's school.
Approach_to_Learning: Teacher's rating on the child's approach to learning.
Self_control: Teacher's rating on the child's self-control.
Interpersonal: Teacher's rating on the child's interpersonal skills.
External_prob_Behavior: Teacher's rating on the child's external problem behaviors.
Internal_prob_Behavior: Teacher's rating on the child's internal problem behaviors.
Attention_focus: Teacher's rating on the child's attention focus.
Inhibitory_Ctrl: Teacher's rating on the child's inhibitory control.
EDU: Highest education level between the child's parents.

Details

The ECLS-K:2011 offers a comprehensive and detailed set of information about children's early life experiences, focusing on children's health, development, education, and experiences in the years leading up to kindergarten.

The sample dataset included in this package is used for demonstrating the functionality of the package's functions and it does not include survey weights. In real analysis, the complex survey weights provided by NCES should be utilized appropriately, for instance, as done in R packages such as lavaan.survey or EdSurvey if not using SEM.

Please note that this data must not be used to attempt to identify respondents. For detailed documentation and proper usage of the ECLS-K:2011 data, please refer to the original source at the National Center for Education Statistics (NCES) website: https://nces.ed.gov/.

Source

https://nces.ed.gov/ecls/dataproducts.asp

S4 Class for p values and confidence intervals (when specified).

Description

S4 Class for the output structure for the getEstimateStats() function.

Slots

wald: A data frame for p values and Wald confidence intervals (when specified).
likelihood: A data frame for Likelihood confidence intervals (when specified).
bootstrap: A data frame for Bootstrap confidence intervals (when specified).

S4 Class for displaying figures

Description

S4 Class to hold the figures output from the getFigure function.

Slots

figures: A list of lists containing figures for each specified sub_model and y_model (when applicable).

Calculate p-Values and Confidence Intervals of Parameters for a Fitted Model

Description

This function calculates p-values and confidence intervals (CIs) of parameters for a given model.It supports different types of CIs, including Wald CIs, likelihood-based CIs, bootstrap CIs, or all three.

Usage

getEstimateStats(
  model = NULL,
  est_in,
  p_values = TRUE,
  CI = TRUE,
  CI_type = "Wald",
  rep = NA,
  conf.level = 0.95
)

Arguments

model

A fitted mxModel object. Specifically, this should be the mxOutput slot from the result returned by one of the estimation functions provided by this package. The default value is NULL. Providing this parameter is essential when generating likelihood-based and bootstrap confidence intervals (CIs).

est_in

The Estimates slot from the result returned by one of the estimation functions provided by this package, which contains a dataframe with point estimates and standard errors.

p_values

A logical flag indicating whether to calculate p-values. Default is TRUE.

CI

A logical flag indicating whether to compute confidence intervals. Default is TRUE.

CI_type

A string specifying the type of confidence interval to compute. Supported options include "Wald", "likelihood", "bootstrap", or "all". Default is "Wald".

rep

An integer specifying the number of replications for bootstrap. This is applicable if CI_type is "bootstrap" or "all". Default is NA.

conf.level

A numeric value representing the confidence level for confidence interval calculation. Default is 0.95.

Value

An object of class StatsOutput with potential slots:

wald: Contains a data frame with, point estimates, standard errors p-values, and Wald confidence intervals (when specified).
likelihood: Contains a data frame with likelihood-based confidence intervals (when specified).
bootstrap: Contains a data frame with bootstrap confidence intervals (when specified).

The content of these slots can be printed using the printTable() method for S4 objects.

References

Casella, G. & Berger, R.L. (2002). Statistical Inference (2nd ed.). Duxbury Press.
Madansky, A. (1965). Approximate Confidence Limits for the Reliability of Series and Parallel Systems. Technometrics, 7(4), 495-503. Taylor & Francis, Ltd. https://www.jstor.org/stable/1266390
Matthews, D. E. (1988). Likelihood-Based Confidence Intervals for Functions of Many Parameters. Biometrika, 75(1), 139-144. Oxford University Press. https://www.jstor.org/stable/2336444
Efron, B. & Tibshirani, R. J. (1994). An Introduction to the Bootstrap. CRC press.

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
# Standardized time-invariant covariates
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)

# Fit bilinear spline latent growth curve model (fixed knots)
paraBLS_LGCM.r <- c(
  "mueta0", "mueta1", "mueta2", "knot",
  paste0("psi", c("00", "01", "02", "11", "12", "22")),
  "residuals"
  )
BLS_LGCM_r <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
  records = 1:9, res_scale = 0.1, paramOut = TRUE, names = paraBLS_LGCM.r)
## Generate P value and Wald confidence intervals
getEstimateStats(
  est_in = BLS_LGCM_r@Estimates, CI_type = "Wald"
  )
# Fit bilinear spline latent growth curve model (random knots) with time-invariant covariates for
# mathematics development
## Define parameter names
paraBLS.TIC_LGCM.f <- c(
  "alpha0", "alpha1", "alpha2", "alphag",
  paste0("psi", c("00", "01", "02", "0g", "11", "12", "1g", "22", "2g", "gg")), "residuals",
  paste0("beta1", c(0:2, "g")), paste0("beta2", c(0:2, "g")), paste0("mux", 1:2),
  paste0("phi", c("11", "12", "22")), "mueta0", "mueta1", "mueta2", "mu_knot"
  )
## Fit the model
BLS_LGCM.TIC_f <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = TRUE, records = 1:9,
  growth_TIC = c("ex1", "ex2"), res_scale = 0.1, paramOut = TRUE, names = paraBLS.TIC_LGCM.f
  )
## Change optimizer to "SLSQP" for getting likelihood-based confidence interval
mxOption(model = NULL, key = "Default optimizer", "SLSQP", reset = FALSE)
## Generate P value and all three types of confidence intervals
getEstimateStats(
  model = BLS_LGCM.TIC_f@mxOutput, est_in = BLS_LGCM.TIC_f@Estimates, CI_type = "all", rep = 1000
  )

Generate Visualization for Fitted Model

Description

This function generates visualizations for the output of a fitted model. When a Latent Growth Curve Model (LGCM) is fitted for the longitudinal process, it provides (class-specific) estimated growth status with 95 intervals. When a Latent Change Score Model (LCSM) is fitted for the longitudinal process, it provides (class-specific) estimated growth rate with 95 visualizations are particularly useful for understanding the results and trajectories of different classes or groups within the model.

Usage

getFigure(
  model,
  nClass = NULL,
  cluster_TIC = NULL,
  grp_var = NULL,
  sub_Model,
  y_var,
  curveFun,
  y_model = NULL,
  t_var,
  records,
  m_var = NULL,
  x_type = NULL,
  x_var = NULL,
  xstarts,
  xlab = "Time",
  outcome = "Process"
)

Arguments

model

A fitted mxModel object. Specifically, this should be the mxOutput slot from the result returned by one of the estimation functions provided by this package.

nClass

An integer specifying the number of latent classes for the mixture model or manifested classes for multiple group model. Default is NULL, indicating a single-group model.

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. Default is NULL, indicating no such time-invariant covariates are present in the model.

grp_var

A string specifying the column that indicates manifested classes when applicable.

sub_Model

A string that specifies the (class-specific) model. Supported sub-models include "LGCM" (for latent growth curve models), "LCSM" (for latent change score models), "TVC" (for latent growth curve models or latent change score models with a time-varying covariate), "MGM" (for multivariate latent growth curve models or latent change score models), and "MED" (for longitudinal mediation models).

y_var

A string or character vector representing the prefix of the column names for the outcome variable(s) at each study wave.

curveFun

A string specifying the functional forms of the growth curve(s). 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").

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". By default, this is NULL as this argument only requires when sub_Model is "TVC" or "MGM".

t_var

A string representing the prefix of the column names corresponding to the time variable at each study wave.

records

A numeric vector representing the indices of the study waves.

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each time point. Default is NULL as this argument only requires when sub_Model is "MED".

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". Default is NULL as this argument only requires when sub_Model is "MED".

x_var

A string specifying the baseline predictor if x_type = "baseline", or the prefix of the column names corresponding to the predictor variable at each study wave if x_type = "longitudinal". Default is NULL as this argument only requires when sub_Model is "MED".

xstarts

A numeric value to indicate the starting time of the longitudinal process.

xlab

A string representing the time unit (e.g., "Week", "Month", or "Year") for the x-axis. Default is "Time".

outcome

A string or character vector representing the name(s) of the longitudinal process(es) under examination.

Value

An object of class figOutput containing a slot named figures. This slot holds a ggplot object or a list of ggplot objects, each representing a figure for the fitted model. If the figures slot contains a list of ggplot objects, individual figures can be visualized using the show() function.

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
xstarts <- mean(baseT)


# Plot single group LGCM model
set.seed(20191029)
BLS_LGCM1 <- getLGCM(dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS",
                     intrinsic = FALSE, records = 1:9, res_scale = 0.1)
Figure1 <- getFigure(
  model = BLS_LGCM1@mxOutput, nClass = NULL, cluster_TIC = NULL, sub_Model = "LGCM",
  y_var = "M", curveFun = "BLS", y_model = "LGCM", t_var = "T", records = 1:9,
  m_var = NULL, x_var = NULL, x_type = NULL, xstarts = xstarts, xlab = "Month",
  outcome = "Mathematics"
)
show(Figure1)
# Plot mixture LGCM model
BLS_LGCM2 <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.45, 0.55), sub_Model = "LGCM",
  cluster_TIC = NULL, y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3)
)
Figure2 <- getFigure(
  model = BLS_LGCM2@mxOutput, nClass = 2, cluster_TIC = NULL, sub_Model = "LGCM",
  y_var = "M", curveFun = "BLS", y_model = "LGCM", t_var = "T", records = 1:9,
  m_var = NULL, x_var = NULL, x_type = NULL, xstarts = xstarts, xlab = "Month",
  outcome = "Mathematics"
)
show(Figure2)

Helper Function to Generate Visualization for a Fitted Model

Description

This is an internal function that generates a ggplot object for a fitted model. It is called by the getFigure function.

Usage

getFitFig(
  model,
  nClass,
  cluster_TIC,
  grp_var,
  sub_Model,
  t_var,
  records,
  y_var,
  curveFun,
  y_model,
  xstarts,
  xlab,
  outcome
)

Arguments

model

A fitted mxModel object. This is the output from one of the estimation functions in this package. It takes value passed from getFigure().

nClass

An integer specifying the number of classes for the mixture model or multiple group model. It takes value passed from getFigure().

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. It takes value passed from getFigure().

grp_var

A string specifying the column that indicates manifested classes when applicable. It takes the value passed from getFigure().

sub_Model

A string that specifies the sub-model for latent classes. Supported sub-models include "LGCM" (for latent growth curve models), "LCSM" (for latent change score models), "TVC" (for latent growth curve models or latent change score models with a time-varying covariate), "MGM" (for multivariate latent growth curve models or latent change score models), and "MED" (for longitudinal mediation models). It takes value passed from getFigure().

t_var

A string representing the prefix of the column names corresponding to the time variable at each study wave. It takes value passed from getFigure().

records

A numeric vector representing the indices of the study waves. It takes value passed from getFigure().

y_var

A string or character vector representing the prefix of the column names for the outcome variable(s) at each study wave. It takes value passed from getFigure().

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: "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), and "nonparametric" (or "NonP"). It takes value passed from getFigure().

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". It takes value passed from getFigure().

xstarts

A numeric value to indicate the starting time of the longitudinal process. It takes value passed from getFigure().

xlab

A string representing the time unit (e.g., "Week", "Month", or "Year") for the x-axis. Default is "Time". It takes value passed from getFigure().

outcome

A string or character vector representing the name(s) of the longitudinal process(es) under examination. It takes value passed from getFigure().

Value

A ggplot object or a list of ggplot objects.

Derive Individual Factor Scores for Each Latent Variable Included in Model

Description

This function computes individual factor scores for each latent variable in a given model. It supports three types of factor scores: maximum likelihood, weighted maximum likelihood, and regression.

Usage

getIndFS(model, FS_type = "Regression")

Arguments

model

A fitted mxModel object. Specifically, this should be the mxOutput slot from the result returned by one of the estimation functions provided by this package.

FS_type

A string specifying the type of factor scores to compute. Supported options include "ML" (for Maximum Likelihood), "WeightedML" (for Weighted Maximum Likelihood), and "Regression". Default is "Regression".

Value

An object of class FSOutput with two slots:

scores_est: Contains the factor score estimates.
scores_se: Contains the standard errors of the factor score estimates.

The content of these slots can be printed using the printTable() method for S4 objects.

References

Estabrook, R. & Neale, M. C. (2013). A Comparison of Factor Score Estimation Methods in the Presence of Missing Data: Reliability and an Application to Nicotine Dependence. Multivariate Behavioral Research, 48, 1-27. doi:10.1080/00273171.2012.730072
Priestley, M. & Subba Rao, T. (1975). The Estimation of Factor Scores and Kalman Filtering For Discrete Parameter Stationary Processes. International Journal of Control, 21, 971-975. doi:10.1080/00207177508922050

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
# Standardized time-invariant covariates
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)

# Fit bilinear spline latent growth curve model (fixed knots)
LIN_LGCM <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "linear",
  intrinsic = FALSE, records = 1:9, growth_TIC = NULL, res_scale = 0.1
)
getIndFS(model = LIN_LGCM@mxOutput, FS_type = "Regression")
# Fit bilinear spline latent growth curve model (random knots) with time-invariant covariates for
# mathematics development
## Fit the model
BLS_LGCM.TIC_f <- getLGCM(dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS",
                          intrinsic = TRUE, records = 1:9, growth_TIC = c("ex1", "ex2"),
                          res_scale = 0.1)
getIndFS(model = BLS_LGCM.TIC_f@mxOutput, FS_type = "Regression")

Fit a Latent Change Score Model with a Time-invariant Covariate (If Any)

Description

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

Usage

getLCSM(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic = TRUE,
  records,
  growth_TIC = NULL,
  starts = NULL,
  res_scale = 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 and 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 latent change score models include: "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), and "nonparametric" (or "NonP").

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. Default is TRUE.

records

A numeric vector specifying indices of the study waves.

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. Default is NULL, indicating no growth TICs are included 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 representing the scaling factor for the initial calculation of the residual variance. This value should be between 0 and 1, exclusive. 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 change score model. 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). "Jenss–Bayley Latent Change Score Model With Individual Ratio of the Growth Acceleration in the Framework of Individual Measurement Occasions." Journal of Educational and Behavioral Statistics, 47(5), 507–543. doi:10.3102/10769986221099919
Grimm, K. J., Zhang, Z., Hamagami, F., & Mazzocco, M. (2013). "Modeling Nonlinear Change via Latent Change and Latent Acceleration Frameworks: Examining Velocity and Acceleration of Growth Trajectories." Multivariate Behavioral Research, 48(1), 117-143. doi:10.1080/00273171.2012.755111

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
# Standardized time-invariant covariates
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)


# Fit nonparametric change score model for reading development
## Fit model
NonP_LCSM <- getLCSM(
  dat = RMS_dat0, t_var = "T", y_var = "R", curveFun = "nonparametric",
  intrinsic = FALSE, records = 1:9, res_scale = 0.1
  )

Construct An Object of mxModel for Latent Change Score Model with Time-invariant Covariates (If Any) To Be Evaluated

Description

This function builds up an object of mxModel for a Latent Change Score Model with user-specified functional form (including whether intrinsically nonlinear) with time-invariant covariates (if any).

Usage

getLCSM.mxModel(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions, and time-invariant covariates (TICs) if any. It takes the value passed from getLCSM().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getLCSM().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getLCSM().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getLCSM().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getLCSM().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getLCSM().

starts

A list of initial values for the parameters, either takes the value passed from getLCSM() or derived by the helper function getUNI.initial().

Value

A pre-optimized mxModel for a Latent Change Score Model.

Extract Point Estimates And Standard Errors of Latent Change Score Model with Time-invariant Covariates (If Any)

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a latent change score model with time-invariant covariates (if any)

Usage

getLCSM.output(model, curveFun, growth_TIC, names)

Arguments

model

An object representing a fitted latent change score model.

curveFun

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getLCSM().

names

A character vector specifying parameter names. It takes the value passed from getLCSM().

Value

A data frame containing the point estimates and standard errors for parameters of a latent change score model with time-invariant covariates (if any).

Fit a Latent Growth Curve Model with Time-invariant Covariate (If Any)

Description

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

Usage

getLGCM(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic = TRUE,
  records,
  growth_TIC = NULL,
  starts = NULL,
  res_scale = 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 and 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 latent growth curve models are: "linear" (or "LIN"), "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), and "bilinear spline" (or "BLS").

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. Default is TRUE.

records

A numeric vector specifying indices of the study waves.

growth_TIC

starts

A list containing initial values for the parameters. Default is NULL, indicating no user-specified initial values.

res_scale

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. 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., Kang, L., Kirkpatrick, R. M., & Sabo, R. T. (2021). "Obtaining Interpretable Parameters from Reparameterizing Longitudinal Models: Transformation Matrices between Growth Factors in Two Parameter Spaces". Journal of Educational and Behavioral Statistics. doi:10.3102/10769986211052009
Sterba, S. K. (2014). "Fitting Nonlinear Latent Growth Curve Models With Individually Varying Time Points". Structural Equation Modeling: A Multidisciplinary Journal, 21(4), 630-647. doi:10.1080/10705511.2014.919828

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
# Standardized time-invariant covariates
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)


# Fit bilinear spline latent growth curve model (fixed knots)
BLS_LGCM_r <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "bilinear spline",
  intrinsic = FALSE, records = 1:9, growth_TIC = NULL, res_scale = 0.1
)
# Fit bilinear spline latent growth curve model (random knots) with
# time-invariant covariates for mathematics development
## Define parameter names
paraBLS.TIC_LGCM.f <- c(
  "alpha0", "alpha1", "alpha2", "alphag",
  paste0("psi", c("00", "01", "02", "0g", "11", "12", "1g", "22", "2g", "gg")),
  "residuals", paste0("beta1", c(0:2, "g")), paste0("beta2", c(0:2, "g")),
  paste0("mux", 1:2), paste0("phi", c("11", "12", "22")),
  "mueta0", "mueta1", "mueta2", "mu_knot"
)
## Fit the model
BLS_LGCM.TIC_f <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "bilinear spline",
  intrinsic = TRUE, records = 1:9, growth_TIC = c("ex1", "ex2"), res_scale = 0.1,
  paramOut = TRUE, names = paraBLS.TIC_LGCM.f
)
## Output point estimate and standard errors
printTable(BLS_LGCM.TIC_f)

Construct An Object of mxModel for Latent Growth Curve Model with Time-invariant Covariates (If Any) To Be Evaluated

Description

his function builds up an object of mxModel for a latent growth curve model with user-specified functional form (including whether intrinsically nonlinear) with time-invariant covariates (if any).

Usage

getLGCM.mxModel(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  growth_TIC,
  starts
)

Arguments

dat

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getLGCM().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getLGCM().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getLGCM().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getLGCM().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getLGCM().

starts

A list containing initial values for the free parameters, either takes the value passed from getLGCM() or derived by the helper function getUNI.initial().

Value

A pre-optimized mxModel for a Latent Growth Curve Model.

Extract Point Estimates and Standard Errors of Latent Growth Curve Model with Time-invariant Covariates (If Any)

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a latent growth curve model with time-invariant covariates (if any)

Usage

getLGCM.output(model, growth_TIC, names)

Arguments

model

An object representing a fitted latent growth curve model.

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getLGCM().

names

A character vector specifying parameter names. It takes the value passed from getLGCM().

Value

A data frame containing the point estimates and standard errors for parameters of a latent growth curve model with time-invariant covariates (if any).

Perform Bootstrap Likelihood Ratio Test for Comparing Full and Reduced Models

Description

This function performs the likelihood ratio test (LRT) to compare a full model (an intrinsically nonlinear longitudinal model) with a corresponding parsimonious alternative (a non-intrinsically nonlinear longitudinal model). It also provides an option to perform bootstrapping for the comparison.

Usage

getLRT(full, reduced, boot = FALSE, rep = NA)

Arguments

full

A fitted mxModel object for the full model. Specifically, this should be the mxOutput slot from the result returned by one of the estimation functions provided by this package.

reduced

A fitted mxModel object for the reduced model. Specifically, this should be the mxOutput slot from the result returned by one of the estimation functions provided by this package.

boot

A logical flag indicating whether to perform bootstrapping for the comparison. Default is FALSE.

rep

An integer specifying the number of bootstrap replications if boot is TRUE. Default is NA.

Value

A data frame containing the number of free parameters, estimated likelihood (-2ll), degrees of freedom, differences in log-likelihood and degrees of freedom, p-values, AIC, and BIC for both the full and reduced models.

Examples


mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT


# Fit bilinear spline growth model with random knot (intrinsically nonlinear model)
BLS_LGCM_f <- getLGCM(dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "bilinear spline",
                      intrinsic = TRUE, records = 1:9, res_scale = 0.1)
# Fit bilinear spline growth model with fix knot (non-intrinsically nonlinear model)
BLS_LGCM_r <- getLGCM(dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "bilinear spline",
                      intrinsic = FALSE, records = 1:9, res_scale = 0.1)
# Likelihood ratio test
getLRT(full = BLS_LGCM_f@mxOutput, reduced = BLS_LGCM_r@mxOutput, boot = FALSE, rep = NA)

Compute Latent Kappa Coefficient for Agreement between Two Latent Label Sets

Description

This function calculates the latent kappa, a measure of agreement between two sets of latent categorical labels. It also computes the confidence interval and provides a qualitative interpretation of the agreement level.

Usage

getLatentKappa(label1, label2, conf.level = 0.95)

Arguments

label1

A factor vector representing the first set of latent categorical labels.

label2

A factor vector representing the second set of latent categorical labels.

conf.level

A numeric value representing the confidence level for the confidence interval of the kappa statistic. The default value is 0.95.

Value

An object of class KappaOutput with the following slots:

kappa_value: A string representing the kappa statistic along with its confidence interval.
judgment: A string describing the level of agreement, such as "Perfect Agreement", "Slight Agreement", etc.

The content of these slots can be printed using the printTable() method for S4 objects.

References

Dumenci, L. (2011). The Psychometric Latent Agreement Model (PLAM) for Discrete Latent Variables Measured by Multiple Items. Organizational Research Methods, 14(1), 91-115. SAGE Publications. doi:10.1177/1094428110374649
Landis, J., & Koch, G. (1977). The Measurement of Observer Agreement for Categorical Data. Biometrics, 33(1), 159-174. doi:10.2307/2529310
Agresti, A. (2012). Models for Matched Pairs. In Categorical Data Analysis (pp. 413-454). Wiley.

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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)
RMS_dat0$gx1 <- scale(RMS_dat0$INCOME)
RMS_dat0$gx2 <- scale(RMS_dat0$EDU)

## Fit a growth mixture model with no TICs
set.seed(20191029)
MIX_BLS_LGCM_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM",
  cluster_TIC = NULL, y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3, 0.3),
  growth_TIC = NULL, tries = 10
)
## Membership of each individual from growth mixture model with no TICs
label1 <- getPosterior(
  model = MIX_BLS_LGCM_r@mxOutput, nClass = 3, label = FALSE, cluster_TIC = NULL
)
set.seed(20191029)
## Fit a growth mixture model with growth TICs and cluster TICs
MIX_BLS_LGCM.TIC_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM",
  cluster_TIC = c("gx1", "gx2"), y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3, 0.3),
  growth_TIC = c("ex1", "ex2"), tries = 10
)
## Membership of each individual from growth mixture model with growth TICs and cluster TICs
label2 <- getPosterior(
  model = MIX_BLS_LGCM.TIC_r@mxOutput, nClass = 3, label = FALSE,
  cluster_TIC = c("gx1", "gx2")
)
## Calcualte the agreement between two sets of membership labels
getLatentKappa(label1 = label1@membership, label2 = label2@membership)

Compute Initial Values for Parameters of Longitudinal Mediation Models

Description

This function computes the initial values of the parameters for a longitudinal mediation model.

Usage

getMED.initial(
  dat,
  t_var,
  y_var,
  m_var,
  x_type,
  x_var,
  curveFun,
  records,
  res_scale,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for multiple longitudinal processes and a baseline predictor when applicable. It takes the value passed from getMediation().

t_var

A vector of strings, with each element representing the prefix for column names related to the time variable for the corresponding longitudinal variable at each study wave. It takes the value passed from getMediation().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMediation().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMediation().

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMediation().

x_var

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMediation().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding longitudinal variable. It takes the value passed from getMediation().

res_scale

A numeric vector with each element representing the scaling factor for the initial calculation of the residual variance. These values should be between 0 and 1, exclusive. It takes the value passed from getMediation().

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal processes to calculate the corresponding initial value. It takes the value passed from getMediation().

Value

A list containing the initial values for parameters related to growth factors and path coefficients of a longitudinal mediation model.

Get Factor Loadings for a Longitudinal Mediation Model with Specified Functional Curves

Description

This function specifies the factor loadings for a longitudinal mediation model with given functional form.

Usage

getMED.loadings(
  t_var,
  y_var,
  m_var,
  x_type,
  x_var,
  curveFun,
  y_records,
  m_records,
  x_records = NULL
)

Arguments

t_var

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMediation().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMediation().

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMediation().

x_var

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMediation().

y_records

A numeric vector specifying indices of the study waves for the outcome variable. It is the first vector in records specified in getMediation().

m_records

A numeric vector specifying indices of the study waves for the mediator variable. It is the second vector in records specified in getMediation().

x_records

A numeric vector specifying indices of the study waves for the predictor variable. Default value is NULL, which is for x_type = "baseline". If x_type = "longitudinal", it is the third vector in records specified in getMediation().

Value

A list containing the specification of definition variables (i.e., individual measurement occasions) and factor loadings of a longitudinal mediation model.

Construct An Object of mxModel for Longitudinal Mediation Models To Be Evaluated

Description

This function builds up an object of mxModel for a longitudinal mediation model with user-specified functional form.

Usage

getMED.mxModel(
  dat,
  t_var,
  y_var,
  m_var,
  x_type,
  x_var,
  curveFun,
  records,
  starts,
  res_cor
)

Arguments

dat

t_var

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMediation().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMediation().

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMediation().

x_var

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMediation().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding longitudinal variable. It takes the value passed from getMediation().

starts

A list of initial values for the parameters, either takes the value passed from getMediation() or derived by the helper function getMED.initial().

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal processes to calculate the corresponding initial value. It takes the value passed from getMediation().

Value

A pre-optimized mxModel for a longitudinal mediation model.

Extract Point Estimates And Standard Errors of Longitudinal Mediation Model

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a longitudinal mediation model.

Usage

getMED.output(model, y_var, m_var, x_type, x_var, curveFun, names)

Arguments

model

An object representing a fitted longitudinal mediation model.

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMediation().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMediation().

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMediation().

x_var

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMediation().

names

A character vector specifying parameter names. It takes the value passed from getMediation().

Value

A data frame containing the point estimates and standard errors for parameters of a longitudinal mediation model.

Fit a Multivariate Latent Growth Curve Model or Multivariate Latent Change Score Model

Description

This function fits a multivariate latent growth curve model or a multivariate latent change score model with the provided data. It manages model setup, optimization, and if requested, outputs parameter estimates and standard errors.

Usage

getMGM(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic = TRUE,
  records,
  y_model,
  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 and occasions for multiple longitudinal outcomes.

t_var

A vector of strings, with each element representing the prefix for column names related to the time variable for the corresponding outcome variable at each study wave.

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave.

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. Default is TRUE.

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable.

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM".

starts

A list containing initial values for the parameters. Default is NULL, indicating no user-specified initial values.

res_scale

A numeric vector with each element representing the scaling factor for the initial calculation of the residual variance. These values should be between 0 and 1, exclusive. 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 or vector for user-specified residual correlation between any two longitudinal outcomes to calculate the corresponding initial value. 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 multivariate latent growth curve model or a multivariate latent change score model. 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. (2021). "Estimating Knots and Their Association in Parallel Bilinear Spline Growth Curve Models in the Framework of Individual Measurement Occasions," Psychological Methods (Advance online publication). doi:10.1037/met0000309
Blozis, S. A. (2004). "Structured Latent Curve Models for the Study of Change in Multivariate Repeated Measures," Psychological Methods, 9(3), 334-353. doi:10.1037/1082-989X.9.3.334

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT


# Fit linear multivariate latent growth curve model
LIN_PLGCM_f <- getMGM(
  dat = RMS_dat0, t_var = c("T", "T"), y_var = c("R", "M"), curveFun = "LIN",
  intrinsic = FALSE, records = list(1:9, 1:9), y_model = "LGCM", res_scale = c(0.1, 0.1),
  res_cor = 0.3
  )
# Fit bilinear spline multivariate latent growth curve model (random knots)
## Define parameter names
paraBLS_PLGCM.f <- c(
  "Y_mueta0", "Y_mueta1", "Y_mueta2", "Y_knot",
  paste0("Y_psi", c("00", "01", "02", "0g", "11", "12", "1g", "22", "2g", "gg")), "Y_res",
  "Z_mueta0", "Z_mueta1", "Z_mueta2", "Z_knot",
  paste0("Z_psi", c("00", "01", "02", "0g", "11", "12", "1g", "22", "2g", "gg")), "Z_res",
  paste0("YZ_psi", c(c("00", "10", "20", "g0", "01", "11", "21", "g1",
                       "02", "12", "22", "g2", "0g", "1g", "2g", "gg"))),"YZ_res"
  )
## Fit model
BLS_PLGCM_f <- getMGM(
  dat = RMS_dat0, t_var = c("T", "T"), y_var = c("R", "M"), curveFun = "BLS", intrinsic = TRUE,
  records = list(1:9, 1:9), y_model = "LGCM", res_scale = c(0.1, 0.1), res_cor = 0.3,
  paramOut = TRUE, names = paraBLS_PLGCM.f
  )
printTable(BLS_PLGCM_f)

Construct An Object of mxModel for Multivariate Latent Growth Curve Models or Multivariate Latent Change Score Models To Be Evaluated

Description

This function builds up an object of mxModel for a multivariate latent growth curve model or a multivariate latent change score model with user-specified functional form (including whether intrinsically nonlinear).

Usage

getMGM.mxModel(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for multiple longitudinal outcomes. It takes the value passed from getMGM().

t_var

A vector of strings, with each element representing the prefix for column names related to the time variable for the corresponding outcome variable at each study wave. It takes the value passed from getMGM().

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGM().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGM().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGM().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGM().

starts

A list of initial values for the parameters, either takes the value passed from getMGM() or derived by the helper function getMULTI.initial().

Value

A pre-optimized mxModel for a multivariate latent growth curve model or a multivariate latent change score model.

Extract Point Estimates And Standard Errors of Multivariate Latent Growth Curve Models Or Multivariate Latent Change Score Models

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a multivariate latent growth curve model or a multivariate latent change score model.

Usage

getMGM.output(model, y_var, records, curveFun, y_model, names)

Arguments

model

An object representing a fitted multivariate latent growth curve model or latent change score model.

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGM().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGM().

curveFun

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGM().

names

A character vector specifying parameter names. It takes the value passed from getMGM().

Value

A data frame containing the point estimates and standard errors for parameters of a multivariate latent growth curve model or a multivariate latent change score model.

Fit a Longitudinal Multiple Group Model

Description

This function fits a longitudinal multiple group model based on the specified sub-model. Supported submodels include:

Latent growth curve models,
Latent change score models,
Latent growth curve models or latent change score models with a time-varying covariate,
Multivariate latent growth curve models or multivariate latent change score models,
Longitudinal mediation models.

For the first three submodels, time-invariant covariates are allowed.

Usage

getMGroup(
  dat,
  grp_var,
  sub_Model,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic = NULL,
  y_model = NULL,
  m_var = NULL,
  x_type = NULL,
  x_var = NULL,
  TVC = NULL,
  decompose = NULL,
  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 and occasions for each longitudinal process, time-invariant covariates (TICs) if any, and a variable that indicates manifested group.

grp_var

A string specifying the column that indicates manifested classes.

sub_Model

A string that specifies the sub-model for manifested classes. Supported sub-models include "LGCM" (for latent growth curve models), "LCSM" (for latent change score models), "TVC" (for latent growth curve models or latent change score models with a time-varying covariate), "MGM" (for multivariate latent growth curve models or latent change score models), and "MED" (for longitudinal mediation models).

t_var

A string specifying the prefix of the column names corresponding to the time variable for each study wave. This applies when sub_Model is "LGCM", "LCSM" or "TVC". For sub_Model being "MGM" or "MED", t_var should be a string vector where each element corresponds to the time variable prefix for each respective longitudinal process.

records

A numeric vector denoting the indices of the observed study waves. This applies when sub_Model is "LGCM", "LCSM" or "TVC". For sub_Model being "MGM" or "MED", records should be a list of numeric vectors, where each vector provides the indices of the observed study waves for each longitudinal process.

y_var

A string defining the prefix of the column names corresponding to the outcome variable for each study wave. This is applicable when sub_Model is not "MGM". For sub_Model being "MGM", y_var should be a string vector where each element corresponds to the prefix of the column names for each outcome variable across the study waves.

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. By default, this is NULL, as it is unnecessary when sub_Model is "MED".

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". By default, this is NULL as this argument only requires when sub_Model is "TVC" or "MGM".

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each study wave. By default, this is NULL as this argument only requires when sub_Model is "MED".

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". By default, this is NULL as this argument only requires when sub_Model is "MED".

x_var

A string specifying the baseline predictor if x_type = "baseline", or the prefix of the column names corresponding to the predictor variable at each study wave if x_type = "longitudinal". By default, this is NULL as this argument only requires when sub_Model is "MED".

TVC

A string that specifies the prefix of the column names corresponding to the time-varying covariate at each time point. By default, this is NULL as this argument only requires when sub_Model is "TVC".

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). By default, this is NULL as this argument only requires when sub_Model is "TVC".

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting 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 list where each element is a (vector of) numeric scaling factor(s) for residual variance to calculate the corresponding initial value for a latent class, between 0 and 1 exclusive. By default, this is NULL, as it is unnecessary when the user specifies the initial values using the starts argument.

res_cor

A list where each element is a (vector of) numeric initial value(s) for residual correlation in each class. It needs to be specified if the sub_Model is "TVC" (when decompose != 0), "MGM", or "MED". 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 longitudinal multiple group model. 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

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

# Fit longitudinal multiple group model of bilinear spline functional form with fixed knot
MGroup_BLS_LGCM.TIC_f <-  getMGroup(
  dat = RMS_dat0, grp_var = "SEX", sub_Model = "LGCM", y_var = "M", t_var = "T",
  records = 1:9, curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3)
)

# Fit longitudinal multiple group model of bilinear spline functional form with random knot
paraBLS.TIC_LGCM.f <- c(
  "alpha0", "alpha1", "alpha2", "alphag",
  paste0("psi", c("00", "01", "02", "0g", "11", "12", "1g", "22", "2g", "gg")),
  "residuals", paste0("beta1", c(0:2, "g")), paste0("beta2", c(0:2, "g")),
  paste0("mux", 1:2), paste0("phi", c("11", "12", "22")),
  "mueta0", "mueta1", "mueta2", "mu_knot"
)
set.seed(20191029)
MGroup_BLS_LGCM.TIC_f <-  getMGroup(
  dat = RMS_dat0, grp_var = "SEX", sub_Model = "LGCM", y_var = "M", t_var = "T",
  records = 1:9, curveFun = "BLS", intrinsic = TRUE, res_scale = list(0.3, 0.3),
  growth_TIC = c("ex1", "ex2"), tries = 10, paramOut = TRUE, names = paraBLS.TIC_LGCM.f
)
printTable(MGroup_BLS_LGCM.TIC_f)

Compute Initial Values for Parameters of Multiple-group Models

Description

This function computes the initial values for the parameters for a longitudinal multiple-group model. The supported submodels (i.e., class-specific models) include (1) latent growth curve models, (2) latent change score models, (3) latent growth curve models or latent change score models with a time varying covariate, (4) multivariate latent growth curve models or multivariate latent change score models, (5) longitudinal mediation models. For the first three submodels, time-invariant covariates are allowed.

Usage

getMGroup.initial(
  dat,
  nClass,
  grp_var,
  sub_Model,
  t_var,
  y_var,
  curveFun,
  records,
  m_var,
  x_var,
  x_type,
  TVC,
  decompose,
  growth_TIC,
  res_scale,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

sub_Model

t_var

y_var

curveFun

records

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMGroup().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMGroup().

TVC

A string that specifies the prefix of the column names corresponding to the time-varying covariate at each time point. It takes the value passed from getMGroup().

decompose

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMGroup().

res_scale

res_cor

Value

A list containing initial values for each class in the specified model.

Construct An Object of mxModel for Longitudinal Multiple Group Models To Be Evaluated

Description

This function builds up an object of mxModel for a longitudinal multiple group model with class-specific models and functional form (including whether intrinsically nonlinear).

Usage

getMGroup.mxModel(
  dat,
  nClass,
  grp_var,
  sub_Model,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  m_var,
  x_var,
  x_type,
  TVC,
  decompose,
  growth_TIC,
  starts,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

sub_Model

t_var

y_var

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGroup().

records

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGroup().

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMGroup().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMGroup().

TVC

A string that specifies the prefix of the column names corresponding to the time-varying covariate at each time point. It takes the value passed from getMGroup().

decompose

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

res_cor

Value

A pre-optimized mxModel for a longitudinal mixture model.

Extract Point Estimates And Standard Errors of Longitudinal Multiple Group Models

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a longitudinal multiple group model.

Usage

getMGroup.output(
  model,
  nClass,
  sub_Model,
  y_var,
  curveFun,
  x_type,
  records,
  growth_TIC,
  y_model,
  decompose,
  names
)

Arguments

model

An object representing a fitted mixture model.

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMGroup().

sub_Model

y_var

curveFun

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMGroup().

records

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMGroup().

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGroup().

decompose

names

A character vector specifying parameter names. It takes the value passed from getMGroup().

Value

A dataframe containing point estimates and standard errors for the parameters of interest for a mixture model.

Fit a Longitudinal Mixture Model

Description

This function fits a longitudinal mixture model based on the specified sub-model. Supported submodels include:

Latent growth curve models,
Latent change score models,
Latent growth curve models or latent change score models with a time-varying covariate,
Multivariate latent growth curve models or multivariate latent change score models,
Longitudinal mediation models.

Time-invariant covariates are allowed for the first three submodels.

Usage

getMIX(
  dat,
  prop_starts,
  sub_Model,
  cluster_TIC = NULL,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic = NULL,
  y_model = NULL,
  m_var = NULL,
  x_type = NULL,
  x_var = NULL,
  TVC = NULL,
  decompose = NULL,
  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

prop_starts

A numeric vector of user-specified initial component proportions of latent classes.

sub_Model

cluster_TIC

t_var

records

y_var

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. By default, this is NULL as it is unnecessary when sub_Model is "MED".

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". By default, this is NULL as this argument only requires when sub_Model is "TVC" or "MGM".

m_var

x_type

x_var

A string specifying the baseline predictor if x_type = "baseline", or the prefix of the column names corresponding to the predictor variable at each study wave if x_type = "longitudinal". By default, this is NULL as this argument only requires when sub_Model is "MED".

TVC

decompose

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting 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

res_cor

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 longitudinal mixture model. 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. (2022). Extending Mixture of Experts Model to Investigate Heterogeneity of Trajectories: When, Where and How to Add Which Covariates. Psychological Methods (Advance online publication). doi:10.1037/met0000436
Liu, J., & Perera, R. A. (2022). Extending Growth Mixture Model to Assess Heterogeneity in Joint Development with Piecewise Linear Trajectories in the Framework of Individual Measurement Occasions. Psychological Methods (Advance online publication). doi:10.1037/met0000500
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. (2023). Further Exploration of the Effects of Time-varying Covariate in Growth Mixture Models with Nonlinear Trajectories. Behavior Research Methods. doi:10.3758/s13428-023-02183-5

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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)
RMS_dat0$ex2 <- scale(RMS_dat0$Attention_focus)
RMS_dat0$gx1 <- scale(RMS_dat0$INCOME)
RMS_dat0$gx2 <- scale(RMS_dat0$EDU)

# Fit longitudinal mixture group model of bilinear spline functional form with fixed knot
# (2 classes)
MIX_BLS_LGCM.TIC_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.45, 0.55), sub_Model = "LGCM",
  cluster_TIC = NULL, y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3)
  )
# Fit longitudinal mixture group model of bilinear spline functional form with fixed knot
# (3 classes)
paraBLS.TIC_LGCM.r <- c(
  "alpha0", "alpha1", "alpha2", "knot",
  paste0("psi", c("00", "01", "02", "11", "12", "22")), "residuals",
  paste0("beta1", 0:2), paste0("beta2", 0:2),
  paste0("mux", 1:2), paste0("phi", c("11", "12", "22")),
  "mueta0", "mueta1", "mueta2"
)
set.seed(20191029)
MIX_BLS_LGCM.TIC_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM",
  cluster_TIC = c("gx1", "gx2"), y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3, 0.3),
  growth_TIC = c("ex1", "ex2"), tries = 10, paramOut = TRUE,
  names = paraBLS.TIC_LGCM.r
)
printTable(MIX_BLS_LGCM.TIC_r)

Compute Initial Values for Parameters of Mixture Models

Description

This function computes the initial values for the parameters for a longitudinal mixture model. The supported submodels (i.e., class-specific models) include (1) latent growth curve models, (2) latent change score models, (3) latent growth curve models or latent change score models with a time varying covariate, (4) multivariate latent growth curve models or multivariate latent change score models, (5) longitudinal mediation models. For the first three submodels, time-invariant covariates are allowed.

Usage

getMIX.initial(
  dat,
  nClass,
  prop_starts,
  sub_Model,
  cluster_TIC,
  t_var,
  records,
  y_var,
  curveFun,
  m_var,
  x_var,
  x_type,
  TVC,
  decompose,
  growth_TIC,
  res_scale,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

prop_starts

A numeric vector of user-specified initial component proportions of latent classes. It takes the value passed from getMIX().

sub_Model

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. It takes the value passed from getMIX().

t_var

records

y_var

curveFun

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMIX().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMIX().

TVC

A string that specifies the prefix of the column names corresponding to the time-varying covariate at each time point. It takes the value passed from getMIX().

decompose

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMIX().

res_scale

res_cor

Value

A list containing initial values for each class in the specified model.

Construct An Object of mxModel for Longitudinal Mixture Models To Be Evaluated

Description

This function builds up an object of mxModel for a mixture model with user-specified number of latent classes, class- specific models and functional form (including whether intrinsically nonlinear).

Usage

getMIX.mxModel(
  dat,
  nClass,
  sub_Model,
  cluster_TIC,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  m_var,
  x_var,
  x_type,
  TVC,
  decompose,
  growth_TIC,
  starts,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

sub_Model

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. It takes the value passed from getMIX().

t_var

y_var

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX().

records

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". It takes the value passed from getMIX().

m_var

A string that specifies the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMIX().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMIX().

TVC

A string that specifies the prefix of the column names corresponding to the time-varying covariate at each time point. It takes the value passed from getMIX().

decompose

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

res_cor

Value

A pre-optimized mxModel for a longitudinal mixture model.

Extract Point Estimates And Standard Errors of Longitudinal Mixture Models

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a mixture model.

Usage

getMIX.output(
  model,
  nClass,
  sub_Model,
  cluster_TIC,
  y_var,
  curveFun,
  x_type,
  records,
  growth_TIC,
  y_model,
  decompose,
  names
)

Arguments

model

An object representing a fitted mixture model.

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

sub_Model

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. It takes the value passed from getMIX().

y_var

curveFun

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMIX().

records

growth_TIC

A string or character vector of column names of time-invariant covariate(s) accounting for the variability of growth factors if any. It takes the value passed from getMIX().

y_model

A string that specifies how to fit longitudinal outcomes. Supported values are "LGCM" and "LCSM". It takes the value passed from getMIX().

decompose

names

A character vector specifying parameter names. It takes the value passed from getMIX().

Value

A dataframe containing point estimates and standard errors for the parameters of interest for a mixture model.

Get Factor Loadings for a Mixture Model or Multiple Group Model with Longitudinal Mediation Model with Specified Functional Curves as Submodels

Description

This function specifies the factor loadings for a mixture model with longitudinal mediation model with given functional form as submodels

Usage

getMIX_MED.loadings(
  nClass,
  t_var,
  y_var,
  m_var,
  x_var,
  x_type,
  curveFun,
  y_records,
  m_records,
  x_records = NULL
)

Arguments

nClass

An integer specifying the number of classes for the mixture model or multiple group model. It takes the value passed from getMIX() or getMGroup().

t_var

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX() or getMGroup().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMIX() or getMGroup().

x_var

A string specifying the baseline predictor if x_type = "baseline", or the prefix of the column names corresponding to the predictor variable at each study wave if x_type = "longitudinal". It takes the value passed from getMIX() or getMGroup().

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMIX() or getMGroup().

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMIX() or getMGroup().

y_records

A numeric vector specifying indices of the study waves for the outcome variable. It is the first vector in records specified in getMIX() or getMGroup().

m_records

A numeric vector specifying indices of the study waves for the mediator variable. It is the second vector in records specified in getMIX() or getMGroup().

x_records

Value

A list containing the specification of definition variables (i.e., individual measurement occasions) and factor loadings of a longitudinal mediation model.

Get Additional Parameters Related to Interval-specific Slopes, Interval-specific Changes and Values of Change-from- baseline for Mixture Model with Multivariate Latent Change Score Models as Submodels

Description

This function derives additional parameters for mixture model with multivariate latent change score models as submodels. It specifies the means and variances of interval-specific slopes, interval-specific changes, and values of change-from- baseline.

Usage

getMIX_MULTI.addpara(
  dat,
  nClass,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic = NULL,
  starts
)

Arguments

dat

Data frame. Contains the observed variables, including repeated measurements and occasions, and covariates if any. It takes the value passed from 'getMIX()'.

nClass

Numeric. Indicates the number of latent classes. It takes the value passed from 'getMIX()'.

t_var

String. Prefix of the column names corresponding to the time variable at each time point. It takes the value passed from 'getMIX()'.

records

Numeric vector. Indices of the observed time points. It takes the value passed from 'getMIX()'.

y_var

String. Prefix of the column names corresponding to the outcome variable at each time point. It takes the value passed from 'getMIX()'.

curveFun

String. The functional form of the growth curve. Supported options include: "linear" (or "LIN"), "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), "bilinear spline" (or "BLS"), and "nonparametric" (or "NonP"). It takes the value passed from 'getMIX()'.

intrinsic

Logical. Whether an intrinsically nonlinear longitudinal model is built up. It takes the value passed from 'getMIX()'.

starts

A list of initial values for free parameters, either takes the value passed from 'getMIX()' or derived by the helper function 'getMIX.initial()'.

Value

A list containing the specification of the means and variances of interval-specific slopes, interval-specific changes, and values of change-from-baseline for a mixture model with multivariate latent change score models as submodels.

Get Factor Loadings for a Mixture Model with MGM as Submodels

Description

This function specifies the factor loadings for a mixture model with MGM as submodels. The longitudinal outcomes are fit by Latent Growth Curve Models or a Latent Change Score Models.

Usage

getMIX_MULTI.loadings(
  nClass,
  y_model,
  t_var,
  y_var,
  curveFun,
  intrinsic = NULL,
  records
)

Arguments

nClass

A numeric value to indicate the number of latent classes.

y_model

A character string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from 'getMIX()'.

t_var

t_var A character vector where each element represents a prefix for column names corresponding to the time variables for the respective longitudinal process. It takes the value passed from 'getMIX()'.

y_var

A character vector where each element represents a prefix for column names corresponding to the outcome variables for the respective longitudinal process. It takes the value passed from 'getMIX()'.

curveFun

The specified functional form of the growth curve. Supported options include: "linear" (or "LIN"), "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), "bilinear spline" (or "BLS"), and "nonparametric" (or "NonP"). It takes the value passed from 'getMIX()'.

intrinsic

A boolean flag for whether an intrinsically nonlinear longitudinal model is built up. It takes the value passed from 'getMIX()'.

records

A list of numeric vectors where each vector contains indices of the observed time points for the respective longitudinal processes. It takes the value passed from 'getMIX()'.

Value

A list containing the specification of definition variables (i.e., individual measurement occasions) and factor loadings of multivariate longitudinal outcomes.

Get the Time-Varying Covariate (TVC) Information for a Mixture Model or Multiple Group Model with a Time-varying Covariate

Description

This function constructs the OpenMx model paths and parameters for a TVC and its relationship with the parameters related to growth factors of a longitudinal outcome.

Usage

getMIX_TVC.info(nClass, y_var, records, growth_TIC, TVC, decompose, starts)

Arguments

nClass

An integer specifying the number of classes for the mixture model or multiple group model. It takes the value passed from getMIX() or getMGroup().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX() or getMGroup().

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getMIX() or getMGroup().

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. It takes the value passed from getMIX() or getMGroup().

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getMIX() or getMGroup().

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). It takes the value passed from getMIX() or getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or getMGroup(), or derived by the helper function getMIX.initial() or getMGroup.initial().

Value

A list with each sub-list containing a list of OpenMx paths and parameters for the TVC and an OpenMx path for the state effect of the TVC on the corresponding longitudinal outcome.

Get Additional Parameters Related to Interval-specific Slopes, Interval-specific Changes and Values of Change-from- baseline for a Mixture Model or Multiple Group Model with Latent Change Score Models for Longitudinal Outcome

Description

This function derives additional parameters for a mixture model with latent change score models as submodels. In particular, it specifies the means and variances of interval-specific slopes, interval-specific changes, and values of change-from-baseline.

Usage

getMIX_UNI.addpara(
  dat,
  nClass,
  curveFun,
  intrinsic,
  t_var,
  records,
  growth_TIC,
  decompose,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX() or getMGroup().

nClass

An integer specifying the number of classes for the mixture model or multiple group model. It takes the value passed from getMIX() or getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX() or getMGroup().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMIX() or getMGroup().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMIX() or getMGroup().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getMIX() or getMGroup().

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). It takes the value passed from getTVCmodel(). It takes the value passed from getMIX() or getMGroup(). The argument is set as NULL when the submodel is a latent change score model.

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or getMGroup(), or derived by the helper function getMIX.initial() or getMGroup.initial().

Value

A list containing the specification of the means and variances of interval-specific slopes, interval- specific changes, and values of change-from-baseline for latent change score models.

Get Factor Loadings for a Mixture Model or Multiple Group Model with Univariate Longitudinal Outcome

Description

This function specifies the factor loadings for a mixture model with a univariate longitudinal outcome. The longitudinal outcome is fit by a Latent Growth Curve Model or a Latent Change Score Model.

Usage

getMIX_UNI.loadings(
  nClass,
  y_model,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic
)

Arguments

nClass

An integer specifying the number of classes for the mixture model or multiple group model. It takes the value passed from getMIX() or getMGroup().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMIX() or getMGroup().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMIX() or getMGroup().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMIX() or getMGroup().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX() or getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX() or getMGroup().

Value

A list containing the specification of definition variables (i.e., individual time points for the latent growth curve models, and individual time points and individual time lags (intervals) between adjacent time points for latent change score models) and factor loadings of a univariate longitudinal outcome.

Get Additional Parameters Related to Interval-specific Slopes, Interval-specific Changes and Values of Change-from- baseline for Multivariate Latent Change Score Models

Description

This function derives additional parameters for multivariate latent change score models. It specifies the means and variances of interval-specific slopes, interval-specific changes, and values of change-from-baseline.

Usage

getMULTI.addpara(dat, t_var, y_var, curveFun, intrinsic, records, starts)

Arguments

dat

t_var

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGM().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGM().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGM().

starts

A list of initial values for the parameters, either takes the value passed from getMGM() or derived by the helper function getMULTI.initial().

Value

A list containing the specification of the means and variances of interval-specific slopes, interval-specific changes, and values of change-from-baseline for multivariate latent change score models.

Compute Initial Values for Parameters of Multivariate Latent Growth Curve Models or Latent Change Score Models

Description

This function computes the initial values for the parameters for a multivariate latent growth curve model or a latent change score model.

Usage

getMULTI.initial(dat, t_var, y_var, curveFun, records, res_scale, res_cor)

Arguments

dat

t_var

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGM().

curveFun

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGM().

res_scale

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal outcomes to calculate the corresponding initial value. It takes the value passed from getMGM().

Value

A list containing the initial values for the parameters in the multivariate latent growth curve model or a latent change score model growth curve model.

Get Factor Loadings for a Multivariate Longitudinal Outcomes with Specified Functional Curves

Description

This function specifies the factor loadings for a multivariate longitudinal outcomes with a given functional form. The longitudinal outcomes are fit by Latent Growth Curve Models or a Latent Change Score Models.

Usage

getMULTI.loadings(y_model, t_var, y_var, curveFun, intrinsic, records)

Arguments

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGM().

t_var

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGM().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGM().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGM().

Value

Fit a Longitudinal Mediation Model

Description

This function fits a longitudinal mediation model to the provided data. It manages model setup, optimization, and if requested, outputs parameter estimates and standard errors.

Usage

getMediation(
  dat,
  t_var,
  y_var,
  m_var,
  x_type,
  x_var,
  curveFun,
  records,
  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

t_var

A vector of strings, with each element representing the prefix for column names related to the time variable for the corresponding longitudinal 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.

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave.

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal".

x_var

A string specifying the baseline predictor if x_type = "baseline", or the prefix of the column names corresponding to the predictor variable at each study wave if x_type = "longitudinal".

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS").

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding longitudinal variable.

starts

A list containing initial values for the parameters. Default is NULL, indicating no user-specified initial values.

res_scale

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal processes to calculate the corresponding initial value. 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 longitudinal mediation model. 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. (2022). Assessing Mediational Processes Using Piecewise Linear Growth Curve Models with Individual Measurement Occasions. Behavior Research Methods (Advance online publication). doi:10.3758/s13428-022-01940-2
MacKinnon, D. P. (2008). Introduction to Statistical Mediation Analysis. Taylor & Francis Group/Lawrence Erlbaum Associates.
Cheong, J., Mackinnon, D. P., & Khoo, S. T. (2003). Investigation of Mediational Processes Using Parallel Process Latent Growth Curve Modeling. Structural equation modeling: a multidisciplinary journal, 10(2), 238-262. doi:10.1207/S15328007SEM1002_5
Soest, T., & Hagtvet, K. A. (2011). Mediation Analysis in a Latent Growth Curve Modeling Framework. Structural equation modeling: a multidisciplinary journal, 18(2), 289-314. doi:10.1080/10705511.2011.557344

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT
# Standardized time-invariant covariates
RMS_dat0$ex1 <- scale(RMS_dat0$Approach_to_Learning)


# Example 1: Baseline predictor, linear functional form
## Fit model
set.seed(20191029)
Med2_LGCM_LIN <- getMediation(
  dat = RMS_dat0, t_var = rep("T", 2), y_var = "M", m_var = "R", x_type = "baseline",
  x_var = "ex1", curveFun = "LIN", records = list(1:9, 1:9), res_scale = c(0.1, 0.1),
  res_cor = 0.3
  )

# Example 2: Longitudinal predictor, bilinear spline functional form
## Define parameter names
paraMed3_BLS <- c(
  "muetaX1", "muetaXr", "muetaX2", "mugX",
  paste0("psi", c("X1X1", "X1Xr", "X1X2", "XrXr", "XrX2", "X2X2")),
  "alphaM1", "alphaMr", "alphaM2", "mugM",
  paste0("psi", c("M1M1", "M1Mr", "M1M2", "MrMr", "MrM2", "M2M2"), "_r"),
  "alphaY1", "alphaYr", "alphaY2", "mugY",
  paste0("psi", c("Y1Y1", "Y1Yr", "Y1Y2", "YrYr", "YrY2", "Y2Y2"), "_r"),
  paste0("beta", c("X1Y1", "X1Yr", "X1Y2", "XrYr", "XrY2", "X2Y2",
                   "X1M1", "X1Mr", "X1M2", "XrMr", "XrM2", "X2M2",
                   "M1Y1", "M1Yr", "M1Y2", "MrYr", "MrY2", "M2Y2")),
  "muetaM1", "muetaMr", "muetaM2", "muetaY1", "muetaYr", "muetaY2",
  paste0("mediator", c("111", "11r", "112", "1rr", "1r2",
                       "122", "rr2", "r22", "rrr", "222")),
  paste0("total", c("11", "1r", "12", "rr", "r2", "22")),
  "residualsX", "residualsM", "residualsY", "residualsMX", "residualsYX", "residualsYM"
  )

## Fit model
set.seed(20191029)
Med3_LGCM_BLS <- getMediation(
  dat = RMS_dat0, t_var = rep("T", 3), y_var = "S", m_var = "M", x_type = "longitudinal",
  x_var = "R", curveFun = "bilinear spline", records = list(2:9, 1:9, 1:9),
  res_scale = c(0.1, 0.1, 0.1), res_cor = c(0.3, 0.3), tries = 10, paramOut = TRUE,
  names = paraMed3_BLS
  )
printTable(Med3_LGCM_BLS)

Compute Posterior Probabilities, Cluster Assignments, and Model Entropy for a Longitudinal Mixture Model

Description

This function computes posterior probabilities, cluster assignments, and model entropy for a given mixture model with a predefined number of classes. If the true labels are available, it can also compute the model accuracy.

Usage

getPosterior(model, nClass, label = FALSE, cluster_TIC = NULL)

Arguments

model

A fitted mxModel object. Specifically, this should be the mxOutput slot from the output of getMIX().

nClass

An integer representing the predefined number of latent classes in the model.

label

A logical value indicating whether the data contains true labels, which are often available in a simulated data set. Default is FALSE.

cluster_TIC

A string or character vector representing the column name(s) for time-invariant covariate(s) indicating cluster formations. Default is NULL, indicating that no such time-invariant covariates are present in the model.

Value

An object of class postOutput. Depending on the label argument, the object may contain the following slots:

prob: A matrix of posterior probabilities.
membership: A vector indicating class membership based on maximum posterior probability.
entropy: The entropy of the model, a measure of uncertainty in class assignment.
accuracy (optional): If label = TRUE, the model's accuracy based on true labels.

The content of these slots can be printed using the printTable() method for S4 objects.

References

Peugh, J., & Fan, X. (2015). Enumeration Index Performance in Generalized Growth Mixture Models: A Monte Carlo Test of Muthén's (2003) Hypothesis. Structural Equation Modeling: A Multidisciplinary Journal, 22(1), 115-131. Routledge. doi:10.1080/10705511.2014.919823
Lubke, G., & Muthén, B.O. (2007). Performance of Factor Mixture Models as a Function of Model Size, Covariate Effects, and Class-Specific Parameters. Structural Equation Modeling: A Multidisciplinary Journal, 14(1), 26-47. Routledge. doi:10.1080/10705510709336735

Examples

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

# Fit longitudinal mixture group model of bilinear spline functional form with fixed knot but no
# cluster TICs or growth TICs
set.seed(20191029)
MIX_BLS_LGCM_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM",
  cluster_TIC = NULL, y_var = "M", t_var = "T", records = 1:9, curveFun = "BLS",
  intrinsic = FALSE, res_scale = list(0.3, 0.3, 0.3), growth_TIC = NULL, tries = 10
)
label1 <- getPosterior(
  model = MIX_BLS_LGCM_r@mxOutput, nClass = 3, label = FALSE, cluster_TIC = NULL
)
# Fit longitudinal mixture group model of bilinear spline functional form with fixed knot, cluster
# TICs, and growth TICs
set.seed(20191029)
MIX_BLS_LGCM.TIC_r <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM",
  cluster_TIC = c("gx1", "gx2"), y_var = "M", t_var = "T", records = 1:9,
  curveFun = "BLS", intrinsic = FALSE, res_scale = list(0.3, 0.3, 0.3),
  growth_TIC = c("ex1", "ex2"), tries = 10
)
label2 <- getPosterior(
  model = MIX_BLS_LGCM.TIC_r@mxOutput, nClass = 3, label = FALSE, cluster_TIC = c("gx1", "gx2")
)

Summarize Model Fit Statistics for Fitted Models

Description

This function summarizes the model fit statistics for a list of fitted models. The summary includes the number of parameters, estimated likelihood (-2ll), AIC, BIC, and other relevant statistics.

Usage

getSummary(model_list, HetModels = FALSE)

Arguments

model_list

A list of fitted mxModel objects. Specifically, each element of the list should be the mxOutput slot from the result returned by one of the estimation functions provided by this package.

HetModels

A logical flag indicating whether a mixture model or a multiple group model is included in the list. If set to TRUE, the function can also be used for the enumeration process, allowing the determination of the optimal number of latent classes based on model fit statistics such as BIC. The default value is FALSE.

Value

A data frame summarizing model fit statistics (number of parameters, estimated likelihood, AIC, BIC, etc.) for each model.

Examples

mxOption(model = NULL, key = "Default optimizer", "CSOLNP", reset = FALSE)
# 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
RMS_dat0$T2 <- RMS_dat0$T2 - baseT
RMS_dat0$T3 <- RMS_dat0$T3 - baseT
RMS_dat0$T4 <- RMS_dat0$T4 - baseT
RMS_dat0$T5 <- RMS_dat0$T5 - baseT
RMS_dat0$T6 <- RMS_dat0$T6 - baseT
RMS_dat0$T7 <- RMS_dat0$T7 - baseT
RMS_dat0$T8 <- RMS_dat0$T8 - baseT
RMS_dat0$T9 <- RMS_dat0$T9 - baseT

# Fit bilinear spline growth model with fix knot
## Single group model
BLS_LGCM1 <- getLGCM(
  dat = RMS_dat0, t_var = "T", y_var = "M", curveFun = "BLS", intrinsic = FALSE,
  records = 1:9, res_scale = 0.1
  )
getSummary(model_list = list(BLS_LGCM1@mxOutput), HetModels = FALSE)
## Mixture model with two latent classes
set.seed(20191029)
BLS_LGCM2 <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.45, 0.55), sub_Model = "LGCM", cluster_TIC = NULL,
  y_var = "M", t_var = "T", records = 1:9, curveFun = "BLS", intrinsic = FALSE,
  res_scale = list(0.3, 0.3), growth_TIC = NULL, tries = 10
  )
## Mixture model with three latent classes
set.seed(20191029)
BLS_LGCM3 <-  getMIX(
  dat = RMS_dat0, prop_starts = c(0.33, 0.34, 0.33), sub_Model = "LGCM", cluster_TIC = NULL,
  y_var = "M", t_var = "T", records = 1:9, curveFun = "BLS", intrinsic = FALSE,
  res_scale = list(0.3, 0.3, 0.3), growth_TIC = NULL, tries = 10
  )

getSummary(model_list = list(BLS_LGCM1@mxOutput, BLS_LGCM2@mxOutput, BLS_LGCM3@mxOutput),
  HetModels = TRUE)

Get the Time-Varying Covariate (TVC) Information for a One-group Longitudinal Model with Time-varying Covariate

Description

This function constructs the OpenMx model paths and parameters for a TVC and its relationship with the parameters related to growth factors of a longitudinal outcome.

Usage

getTVC.info(y_var, records, growth_TIC, TVC, decompose, starts)

Arguments

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getTVCmodel().

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getTVCmodel().

growth_TIC

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getTVCmodel().

decompose

starts

A list of initial values for the parameters, either takes the value passed from getTVCmodel() or derived by the helper function getTVC.initial().

Value

A list containing two elements: X_PARAM and KAPPA. X_PARAM is a list of OpenMx paths and parameters for the TVC, and KAPPA is an OpenMx path for the temporal effect of the TVC on the corresponding longitudinal outcome.

Compute Initial Values for Parameters of Latent Growth Curve Models or Latent Change Score Models with a Time-varying Covariate and Time-invariant Covariates (if any)

Description

This function computes the initial values of the parameters for a latent growth curve model or a latent change score model with a time-varying covariate and time-invariant covariates (if any).

Usage

getTVC.initial(
  dat,
  t_var,
  y_var,
  curveFun,
  records,
  growth_TIC,
  TVC,
  decompose,
  res_scale,
  res_cor
)

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. It takes the value passed from getTVCmodel().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getTVCmodel().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getTVCmodel().

curveFun

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getTVCmodel().

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. It takes the value passed from getTVCmodel().

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getTVCmodel().

decompose

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. It takes the value passed from getTVCmodel().

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. It takes the value passed from getTVCmodel().

Value

A list containing the initial values for parameters related to growth factors, TVC, TICs (if any), and path coefficients (if any) for a latent growth curve model or a latent change score model with a time-varying covariate and time-invariant covariates (if any).

Construct An Object of mxModel for Latent Growth Curve Models or Latent Change Score Models with a Time Varying Covariate and Time-invariant Covariates (If Any) To Be Evaluated

Description

This function builds up an object of mxModel for a latent growth curve model or latent change score model with user-specified functional form (including whether intrinsically nonlinear), time-varying covariate, and with time-invariant covariates (if any).

Usage

getTVC.mxModel(
  dat,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  TVC,
  decompose,
  growth_TIC,
  starts
)

Arguments

dat

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getTVCmodel().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getTVCmodel().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getTVCmodel().

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getTVCmodel().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getTVCmodel().

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getTVCmodel().

decompose

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. It takes the value passed from getTVCmodel().

starts

A list of initial values for the parameters, either takes the value passed from getTVCmodel() or derived by the helper function getTVC.initial().

Value

A pre-optimized mxModel for a latent growth curve model or a latent change score model with a time-varying covariate and time-invariant covariates (if any).

Extract Point Estimates And Standard Errors of Latent Growth Curve Model Or Latent Change Score Model with a Time-varying Covariate and Time-invariant Covariates (If Any)

Description

This function computes and returns a data frame containing point estimates and standard errors for the parameters of a latent growth curve model or a latent change score model with a time-varying covariate and time-invariant covariates (if any)

Usage

getTVC.output(model, curveFun, records, y_model, decompose, growth_TIC, names)

Arguments

model

An object representing a fitted latent growth curve model or a latent change score model with a TVC. It takes the value passed from getTVCmodel().

curveFun

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getTVCmodel().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getTVCmodel().

decompose

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. It takes the value passed from getTVCmodel().

names

A character vector specifying parameter names. It takes the value passed from getTVCmodel().

Value

A data frame containing the point estimates and standard errors for parameters of a latent growth curve model or a latent change score model with a time-varying covariate and time-invariant covariates (if any).

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

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

growth_TIC

starts

A list containing initial values for the parameters. Default is NULL, indicating no user-specified initial values.

res_scale

res_cor

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)

Derive Individual Growth Factors for Latent Growth Curve Models or Latent Change Score Models with Time-Invariant Covariates (If Any)

Description

This function derives individual growth factors for the specified latent growth curve model or latent change score model from raw data. These individual growth factors help further compute initial values for parameters related to growth factors, time-invariant covariates (if any), and path coefficients (if any).

Usage

getUNI.GF(dat_traj, dat_time, nT, curveFun)

Arguments

dat_traj

A data frame containing the records for the repeated measurements.

dat_time

A data frame containing the records for measurement occasions associated with the repeated measurements.

nT

An integer representing the number of repeated measurements.

curveFun

Value

A data frame containing the derived individual growth factors from the raw data.

Get Additional Parameters Related to Interval-specific Slopes, Interval-specific Changes and Values of Change-from-baseline for Latent Change Score Models for Longitudinal Outcome

Description

This function derives additional parameters for latent change score models. In particular, it specifies the means and variances of interval-specific slopes, interval-specific changes, and values of change- from-baseline.

Usage

getUNI.addpara(
  dat,
  curveFun,
  intrinsic = NULL,
  t_var,
  records,
  growth_TIC,
  decompose,
  starts
)

Arguments

dat

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getLCSM() or getTVCmodel().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getLCSM() or getTVCmodel().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getLCSM() or getTVCmodel().

growth_TIC

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). It takes the value passed from getTVCmodel(). The argument is set as NULL when fitting a latent change score model.

starts

A list containing initial values for the parameters, either takes the value passed from getLCSM() or getTVCmodel(), or derived by the helper function getUNI.initial() or getTVC.initial().

Value

A list containing the specification of the means and variances of interval-specific slopes, interval-specific changes, and values of change-from-baseline for latent change score models.

Compute Initial Values for Parameters of Latent Growth Curve Models or Latent Change Score Models with Time-invariant Covariates (If Any)

Description

This function computes the initial values of the parameters for a latent growth curve model or a latent change score model with time-invariant covariates (if any).

Usage

getUNI.initial(dat, t_var, y_var, curveFun, records, growth_TIC, res_scale)

Arguments

dat

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getLGCM() or getLCSM().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getLGCM() or getLCSM().

curveFun

A string specifying the functional form of the growth curve. Supported options for latent growth curve models include: "linear" (or "LIN"), "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), and "bilinear spline" (or "BLS"). Supported options for latent change score models include: "quadratic" (or "QUAD"), "negative exponential" (or "EXP"), "Jenss-Bayley" (or "JB"), and "nonparametric" (or "NonP"). It takes the value passed from getLGCM() or getLCSM().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getLGCM() or getLCSM().

growth_TIC

res_scale

A numeric value representing the scaling factor for the initial calculation of the residual variance. This value should be between 0 and 1, exclusive. It takes the value passed from getLGCM() or getLCSM().

Value

A list containing the initial values for parameters related to growth factors, TICs (if any), and path coefficients (if any) of a latent growth curve model or a latent change score model. The returned list has the following structure:

Y_starts:

A list containing three elements:

alpha0 or mean0:: Depends on whether growth_TIC is provided,
psi_r or psi0:: Depends on whether growth_TIC is provided,
residuals.

TIC_starts:

Only provided when growth_TIC is not NULL.

beta0:

Only provided when growth_TIC is not NULL.

Each of these elements is a numeric vector or matrix containing the initial parameter estimates.

Get Factor Loadings for a Univariate Longitudinal Outcome with Specified Functional Curves

Description

This function specifies the factor loadings for a univariate longitudinal outcome with given functional form. The longitudinal outcome is fit by a Latent Growth Curve Model or a Latent Change Score Model.

Usage

getUNI.loadings(y_model, t_var, y_var, curveFun, intrinsic, records)

Arguments

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It is "LGCM" or "LCSM", or takes the value passed from getTVCmodel().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getLGCM() or getLCSM() or getTVCmodel().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getLGCM() or getLCSM() or getTVCmodel().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getLGCM() or getLCSM() or getTVCmodel().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getLGCM() or getLCSM() or getTVCmodel().

Value

Define Latent Change Score Models as Class-specific Models (Submodels) for a Longitudinal Mixture Model

Description

This function defines latent change score models as class-specific models (submodels) for a longitudinal mixture model.

Usage

getsub.LCSM_l(
  dat,
  nClass,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMIX().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMIX().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Latent Change Score Models as Class-specific Models (Submodels) for a Longitudinal Multiple Group Model

Description

This function defines latent change score models as class-specific models (submodels) for a longitudinal multiple group model.

Usage

getsub.LCSM_m(
  dat,
  nClass,
  grp_var,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMGroup().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGroup().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMGroup().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Latent Growth Curve Models as Class-specific Models (Submodels) for a Longitudinal Mixture Model

Description

This function defines latent growth curve models as class-specific models (submodels) for a longitudinal mixture model.

Usage

getsub.LGCM_l(
  dat,
  nClass,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMIX().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMIX().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Latent Growth Curve Models as Class-specific Models (Submodels) for a Longitudinal Multiple Group Model

Description

This function defines latent growth curve models as class-specific models (submodels) for a longitudinal multiple group model.

Usage

getsub.LGCM_m(
  dat,
  nClass,
  grp_var,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMGroup().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGroup().

records

A numeric vector specifying indices of the study waves. It takes the value passed from getMGroup().

growth_TIC

A string or character vector specifying the column name(s) of time-invariant covariate(s) contributing to the variability of growth factors if any. It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Longitudinal Mediation Models as Class-specific Models (Submodels) for a Longitudinal Mixture Model

Description

This function defines longitudinal mediation models as class-specific models (submodels) for a longitudinal mixture model.

Usage

getsub.MED_l(
  dat,
  nClass,
  t_var,
  records,
  y_var,
  curveFun,
  m_var,
  x_var,
  x_type,
  starts,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

t_var

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding longitudinal variable. It takes the value passed from getMIX().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX().

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMIX().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMIX().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal processes to calculate the corresponding initial value. It takes the value passed from getMIX().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Longitudinal Mediation Models as Class-specific Models (Submodels) for a Longitudinal Multiple Group Model

Description

This function defines longitudinal mediation models as class-specific models (submodels) for a longitudinal multiple group model.

Usage

getsub.MED_m(
  dat,
  nClass,
  grp_var,
  t_var,
  y_var,
  curveFun,
  records,
  m_var,
  x_var,
  x_type,
  starts,
  res_cor
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

t_var

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMGroup().

curveFun

A string specifying the functional form of the growth curve. Supported options include: "linear" (or "LIN"), and "bilinear spline" (or "BLS"). It takes the value passed from getMGroup().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding longitudinal variable. It takes the value passed from getMGroup().

m_var

A string specifying the prefix of the column names corresponding to the mediator variable at each study wave. It takes the value passed from getMGroup().

x_var

x_type

A string indicating the type of predictor variable used in the model. Supported values are "baseline" and "longitudinal". It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

res_cor

A numeric value or vector for user-specified residual correlation between any two longitudinal processes to calculate the corresponding initial value. It takes the value passed from getMGroup().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Multivariate Latent Growth Curve Models or Multivariate Latent Change Score Models as Class-specific Models (Submodels) for a Longitudinal Mixture Model

Description

This function defines multivariate latent growth curve models or multivariate latent change score models as class- specific models (submodels) for a longitudinal mixture model.

Usage

getsub.MGM_l(
  dat,
  nClass,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

t_var

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMIX().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMIX().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define Multivariate Latent Growth Curve Models or Multivariate Latent Change Score Models as Class-specific Models (Submodels) for a Longitudinal Multiple Group Model

Description

This function defines multivariate latent growth curve models or multivariate latent change score models as class- specific models (submodels) for a longitudinal multiple group model.

Usage

getsub.MGM_m(
  dat,
  nClass,
  grp_var,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

t_var

y_var

A vector of strings, with each element representing the prefix for column names corresponding to a particular outcome variable at each study wave. It takes the value passed from getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGroup().

records

A list of numeric vectors, with each vector specifying the indices of the observed study waves for the corresponding outcome variable. It takes the value passed from getMGroup().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define a Latent Growth Curve Model or Latent Change Score Model with a Time-varying Covariate as Class-specific Models (Submodels) for a Longitudinal Mixture Model.

Description

This function defines a latent growth curve model or latent change score model with time-varying covariate as class- specific models (submodels) for a longitudinal mixture model.

Usage

getsub.TVC_l(
  dat,
  nClass,
  t_var,
  records,
  y_var,
  curveFun,
  intrinsic,
  y_model,
  TVC,
  decompose,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMIX().

nClass

An integer specifying the number of latent classes for the mixture model. It takes the value passed from getMIX().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMIX().

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getMIX().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMIX().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMIX().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMIX().

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getMIX().

decompose

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. It takes the value passed from getMIX().

starts

A list of initial values for the parameters, either takes the value passed from getMIX() or derived by the helper function getMIX.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Define a Latent Growth Curve Model or Latent Change Score Model with a Time-varying Covariate as Class-specific Models (Submodels) for a Longitudinal Multiple Group Model.

Description

This function defines a latent growth curve model or latent change score model with time-varying covariate as class- specific models (submodels) for a longitudinal multiple group model.

Usage

getsub.TVC_m(
  dat,
  nClass,
  grp_var,
  t_var,
  y_var,
  curveFun,
  intrinsic,
  records,
  y_model,
  TVC,
  decompose,
  growth_TIC,
  starts
)

Arguments

dat

A wide-format data frame, with each row corresponding to a unique ID. It contains the observed variables with repeated measurements and occasions for each longitudinal process, and time-invariant covariates (TICs) if any. It takes the value passed from getMGroup().

nClass

An integer specifying the number of manifested classes for the multiple group model. It takes the value passed from getMGroup().

grp_var

A string specifying the column that indicates manifested classes. It takes the value passed from getMGroup().

t_var

A string specifying the prefix of the column names corresponding to the time variable at each study wave. It takes the value passed from getMGroup().

y_var

A string specifying the prefix of the column names corresponding to the outcome variable at each study wave. It takes the value passed from getMGroup().

curveFun

intrinsic

A logical flag indicating whether to build an intrinsically nonlinear longitudinal model. It takes the value passed from getMGroup().

records

A numeric vector specifying the indices of the observed study waves. It takes the value passed from getMGroup().

y_model

A string specifying how to fit the longitudinal outcome. Supported values are "LGCM" and "LCSM". It takes the value passed from getMGroup().

TVC

A string specifying the prefix of the column names corresponding to the time-varying covariate at each study wave. It takes the value passed from getMGroup().

decompose

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. It takes the value passed from getMGroup().

starts

A list of initial values for the parameters, either takes the value passed from getMGroup() or derived by the helper function getMGroup.initial().

Value

A list of manifest and latent variables and paths for an mxModel object.

Standard Methods (S4) for the package

Description

S4 Class for the output structure for estimate functions.

Slots

mxOutput: An object of class "MxModel".
Estimates: A data frame of estimates.

S4 Class for posterior probabilities, membership, entropy, and accuracy (when applicable)

Description

S4 Class for the output structure for the getPosterior() function.

Slots

prob: A matrix of posterior probabilities.
membership: A numeric vector for membership.
entropy: A numeric value for entropy.
accuracy: A numeric value for accuracy.

S4 Generic for displaying output in a table format.

Description

Generic function for printing output that are tables.

Usage

printTable(object)

Arguments

object

An object of the appropriate class.

S4 Method for printing estimated factor scores and their standard errors

Description

Method for printing estimated factor scores and their standard errors.

Usage

## S4 method for signature 'FSOutput'
printTable(object)

Arguments

object

An object of class "FSOutput".

S4 Method for printing kappa statistic with $95%$ CI and judgement for agreement.

Description

Method for printing kappa statistic with $95%$ CI and judgement for agreement.

Usage

## S4 method for signature 'KappaOutput'
printTable(object)

Arguments

object

An object of class "KappaOutput".

S4 Method for printing p values and confidence intervals (when applicable)

Description

Method for printing p values and confidence intervals.

Usage

## S4 method for signature 'StatsOutput'
printTable(object)

Arguments

object

An object of class "StatsOutput".

S4 Method for printing point estimates with standard errors

Description

Method for printing point estimates and standard errors.

Usage

## S4 method for signature 'myMxOutput'
printTable(object)

Arguments

object

An object of class "myMxOutput".

S4 Method for printing posterior probabilities, membership, entropy, and accuracy.

Description

Method for printing posterior probabilities, membership, entropy, and accuracy.

Usage

## S4 method for signature 'postOutput'
printTable(object)

Arguments

object

An object of class "postOutput".

S4 Method for displaying figures.

Description

Method to display a summary of the figOutput object when printed.

Usage

## S4 method for signature 'figOutput'
show(object)

Arguments

object

An object of class "figOutput".