Convergence Diagnostics for Growth Mixture Models — diagnose

Provides detailed convergence diagnostics including log-likelihood distribution from multiple random starts, identification of local maxima, and recommendations.

Usage

diagnose_convergence(gmm_object, tolerance = 1e-04, plot = TRUE)

Arguments

gmm_object: A fitted SurveyMixr object from gmm_survey()
tolerance: Tolerance for identifying replicated solutions (default: 1e-4)
plot: Logical, create diagnostic plot? (default: TRUE)

Value

An S4 object of class ConvergenceDiagnostics containing detailed convergence information

Details

Multiple random starts are essential for growth mixture models because the likelihood surface typically has multiple local maxima. This function helps assess whether the best solution is trustworthy by:

Tabulating log-likelihoods from all random starts
Identifying how many times the best solution was replicated
Detecting distinct local maxima
Providing recommendations for improving convergence

Guidelines:

Best solution should be replicated at least 2-3 times
If not replicated, increase starts in gmm_survey()
Multiple distinct local maxima may indicate model instability
Very different log-likelihoods suggest identifiability issues

References

Hipp, J. R., & Bauer, D. J. (2006). Local solutions in the estimation of growth mixture models. Psychological Methods, 11(1), 36-53.

Examples

if (FALSE) { # \dontrun{
fit <- gmm_survey(data = mcs_simulated, id = "id", time = "age",
                  outcome = "selfcontrol", n_classes = 3, starts = 500)

diagnostics <- diagnose_convergence(fit)
print(diagnostics)
} # }