getFigure {nlpsem}

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)