getMIX {nlpsem}

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

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.

prop_starts

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

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).

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.

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

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").

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 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)