Growth Mixture Model with Random Effects — gmm_survey

Extends gmm_survey to include random effects (individual-level variance) in growth parameters. Allows for random intercepts, random slopes, or both within each latent class, while maintaining survey design integration.

Usage

gmm_survey_re(
  data,
  id,
  time,
  outcome,
  n_classes,
  random = ~1,
  growth_model = "linear",
  strata = NULL,
  cluster = NULL,
  weights = NULL,
  covariates = NULL,
  variance_components = c("class_specific", "pooled", "heterogeneous"),
  correlation_structure = c("unstructured", "independent", "compound_symmetry"),
  starts = 500,
  cores = parallel::detectCores() - 1,
  convergence_threshold = 1e-06,
  max_iterations = 1000,
  seed = NULL,
  verbose = TRUE
)

Arguments

data: Data frame in long format containing repeated measurements
id: Character string specifying the individual ID variable name
time: Character string specifying the time variable name
outcome: Character string specifying the outcome variable name
n_classes: Integer number of latent classes (default: 2)
random: Formula specifying random effects structure. Use standard lme4 syntax: ~ 1 for random intercepts only, ~ 1 + time for random intercepts and slopes, ~ 0 + time for random slopes only.
growth_model: Character string specifying growth model type: "linear" (default), "quadratic", "nonlinear", or "free_basis"
strata: Character string specifying stratification variable (optional)
cluster: Character string specifying cluster/PSU variable (optional)
weights: Character string specifying sampling weights variable (optional)
covariates: Character vector of time-varying covariate names (not yet implemented)
variance_components: Character string specifying variance structure: "class_specific" (default, separate variance for each class), "pooled" (common variance across classes), or "heterogeneous" (fully heterogeneous within-class variances)
correlation_structure: Character string for random effects correlation: "unstructured" (default), "independent", "compound_symmetry"
starts: Integer number of random starts (default: 500)
cores: Integer number of CPU cores for parallel processing (default: 1)
convergence_threshold: Numeric convergence criterion for EM algorithm (default: 1e-6)
max_iterations: Integer maximum number of EM iterations (default: 1000)
seed: Integer random seed for reproducibility (optional)
verbose: Logical, print progress messages? (default: TRUE)

Value

An S4 object of class SurveyMixrRE (extends SurveyMixr) with additional slots:

random_effects: Data frame with predicted random effects (BLUPs) for each individual
variance_components: Estimated variance-covariance matrices $\Psi_k$ for each class
residual_variance: Residual variance $\sigma^2_k$ for each class
icc: Intraclass correlation for each class
random_formula: Formula used for random effects

Details

**Model Specification:**

For individual i in latent class k, the model with random effects is:

$$Y_{it} = (\beta_{0k} + b_{0ik}) + (\beta_{1k} + b_{1ik}) t_{it} + \epsilon_{it}$$

where: - $\beta_{0k}, \beta_{1k}$ are fixed effects (class-specific means) - $b_{0ik}, b_{1ik}$ are random effects (individual deviations) - $(b_{0ik}, b_{1ik})' \sim N(0, \Psi_k)$ with variance-covariance matrix $\Psi_k$ - $\epsilon_{it} \sim N(0, \sigma^2_k)$

**Variance Components:**

The variance-covariance matrix $\Psi_k$ for class k:

$$\Psi_k = \begin{pmatrix} \psi^2_{0k} & \psi_{01k} \\ \psi_{01k} & \psi^2_{1k} \end{pmatrix}$$

where $\psi^2_{0k}$ is variance of random intercepts, $\psi^2_{1k}$ is variance of random slopes, and $\psi_{01k}$ is their covariance.

**Survey Weight Integration:**

Survey weights affect both: 1. Fixed effect estimation (class-specific means) 2. Variance component estimation (but not random effect prediction)

Random effects are predicted using empirical Bayes (BLUP) methods, properly accounting for the survey design in the fixed effects.

**Intraclass Correlation (ICC):**

The ICC within each class measures correlation between observations from the same individual:

$$ICC_k = \frac{\psi^2_{0k}}{\psi^2_{0k} + \sigma^2_k}$$

References

Verbeke, G., & Molenberghs, G. (2000). *Linear Mixed Models for Longitudinal Data*. New York: Springer.

Muthén, B., & Asparouhov, T. (2009). Growth mixture modeling: Analysis with non-Gaussian random effects. In G. Fitzmaurice, M. Davidian, G. Verbeke, & G. Molenberghs (Eds.), *Longitudinal Data Analysis* (pp. 143-165). Boca Raton, FL: CRC Press.

Hedeker, D., & Gibbons, R. D. (2006). *Longitudinal Data Analysis*. Hoboken, NJ: Wiley.

Examples

if (FALSE) { # \dontrun{
# Note: Random effects functionality is under development
# These examples will work once implementation is complete
data(mcs_simulated)

# Random intercepts only
fit_ri <- gmm_survey_re(
  data = mcs_simulated,
  id = "id",
  time = "age",
  outcome = "selfcontrol",
  n_classes = 3,
  random = ~ 1,  # Random intercepts
  strata = "stratum",
  cluster = "cluster",
  weights = "weight",
  starts = 200
)

# Examine variance components
summary(fit_ri)
variance_components(fit_ri)

# Random intercepts and slopes
fit_ris <- gmm_survey_re(
  data = mcs_simulated,
  id = "id",
  time = "age",
  outcome = "selfcontrol",
  n_classes = 3,
  random = ~ 1 + age,  # Random intercepts and slopes
  strata = "stratum",
  cluster = "cluster",
  weights = "weight",
  starts = 200
)

# Extract predicted random effects
random_effs <- get_random_effects(fit_ris)
head(random_effs)

# Plot random effects
plot_random_effects(fit_ris)
} # }