Choosing Joint-Model Software by Supported Model Structure

Choose the Model Structure Before the Package

A package name is not a model specification. Two programs both described as “joint-model software” may differ in which longitudinal response distributions, event processes, association structures, and estimation methods they implement. A package that runs successfully can still fit the wrong scientific model if one of those pieces does not match the analysis question.

The useful first step is to describe the intended joint model independently of software. Specify the longitudinal outcome and its conditional distribution, the event-time model, the way the longitudinal and event processes are associated, and the required estimation approach. Then check whether a particular package version implements that complete combination. The purpose is not to rank packages universally: suitability depends on the structure required for the question.

Definition: A package is structurally compatible with an analysis if its implemented model class covers every essential component of the intended specification: the longitudinal response model, event model, association structure, and estimation approach. Compatibility does not establish that the assumptions are plausible, that the model will converge, or that the data are adequate.

For a conventional shared-random-effects joint model, a longitudinal outcome is described by a subject-specific trajectory, and the event hazard depends on a feature of that trajectory or its random effects. A generic form is

Y_i(t)=m_i(t)+\epsilon_i(t), \qquad h_i(t)=h_0(t)\exp\{\boldsymbol{\gamma}^{\mathsf T}\mathbf{w}_i+\alpha\,g_i(t)\}.

Here \(Y_i(t)\) is the longitudinal response for subject \(i\), \(m_i(t)\) is the modeled trajectory, \(\mathbf{w}_i\) contains event-model covariates, and \(g_i(t)\) is the selected feature of the trajectory or its latent effects. For example, \(g_i(t)\) could be the current value \(m_i(t)\), its slope, a cumulative history, or a function of shared random effects. These choices are not interchangeable: they encode different ways that longitudinal history is associated with event risk.

The model also relies on assumptions that software cannot decide for the analyst. Examples include the chosen response distribution and link, the random-effects distribution, the event hazard form, and the conditional-independence structure linking the processes. In a standard shared-effects interpretation, the longitudinal and event outcomes are conditionally independent given the relevant latent effects and covariates. If this is not a reasonable representation, a package match alone does not solve the problem.

Build a Requirements Checklist

Write down essential requirements separately from preferences. The essential list should be strict: if the package cannot express one required feature, it is not a compatible choice for that analysis. Preferences—such as a familiar interface or convenient summaries—can distinguish among compatible choices but cannot compensate for a missing model component.

Longitudinal response: Is it continuous and approximately Gaussian, binary, ordinal, a count, or another type? Is one outcome modeled or are several outcomes modeled jointly?
Trajectory and random effects: What mean trajectory and subject-specific variation are needed? Are the available model and link structures appropriate?
Event process: Is there one event type, a competing-risks outcome, recurrent events, or a multistate process? What event-model and baseline-hazard structures are required?
Association: Does the science call for current value, slope, cumulative exposure, shared random effects, or a combination? Confirm that the exact association form is implemented.
Estimation: Is maximum likelihood or Bayesian estimation required? Are the desired uncertainty summaries and computational tools available?
Practical constraints: Is the package maintained and documented for the required model, and can the analysis be reproduced in the working R environment?

As a broad orientation, JM is commonly used for a continuous Gaussian longitudinal process linked to a single event-time outcome, with maximum-likelihood fitting and several familiar association options. JMbayes2 targets Bayesian joint modeling and offers a wider range of longitudinal and event structures, including settings such as multiple longitudinal outcomes and competing risks; the precise supported combination should be checked in the documentation for the installed version. joineR and joineRML provide likelihood-based approaches for particular shared-effects settings, with joineRML aimed at multiple longitudinal outcomes. lcmm is relevant when a latent-class joint model is the scientific target; latent classes are a substantive modeling choice, not merely a software convenience.

Implementation	Useful initial screen	Important qualification
JM	Gaussian longitudinal model linked to a single event process; maximum-likelihood framework	Check the required event model and exact association option, rather than assuming every joint-model structure is available.
JMbayes2	Bayesian joint models with broader response and event-process options	Confirm that the desired response family, event type, and association structure are supported together.
joineR	Likelihood-based shared-effects models for particular longitudinal and survival settings	Check whether the specific response and association specification fits its supported model class.
joineRML	Likelihood-based joint modeling with multiple longitudinal outcomes	Multiple outcomes do not imply unrestricted response families or event structures.
lcmm	Joint models involving latent trajectory classes	Use when class-specific heterogeneity is scientifically intended, not simply to obtain a different fitting routine.

This is a screening guide, not a guarantee of current feature availability. Package capabilities and interfaces change. For a real analysis, inspect the installed version’s reference manual, vignettes, and function documentation for the exact combination of features. A package’s general description is not enough: a feature may be supported for one response family or event model but not for another.

Worked Example: A Gaussian Marker and One Event Type

Hypothetical analysis. A team plans to model a continuous biomarker measured repeatedly, with one time-to-event outcome. It wants a Gaussian linear mixed-effects trajectory, a Cox-type event model, a current-value association, and maximum-likelihood estimation. Treat all four as essential requirements.

Represent the requirements by \(r=(1,1,1,1)\), where 1 means required. For a candidate package, let \(c_j=1\) if requirement \(j\) is documented for the relevant model combination and 0 otherwise. A simple coverage score is

C=\sum_{j=1}^{4} r_j c_j.

Suppose the team verifies in the documentation for its candidate JM version that all four requirements are supported in the intended setting. Then \(c=(1,1,1,1)\), and

$$ C=(1)(1)+(1)(1)+(1)(1)+(1)(1)=4. $$

The candidate passes this structural screen. JM is a natural package to investigate for this conventional specification. The score is only a checklist: it is not evidence that the model fits well, that the Gaussian or hazard assumptions hold, or that the estimated association is meaningful. Before fitting, the team still needs to examine the trajectory, event process, and assumptions against the study design.

Worked Example: Binary Outcome and Competing Risks

Hypothetical analysis. Investigators record a binary clinical status repeatedly and observe time to one of two competing event types. They require a binary longitudinal model, a competing-risks event model, a current-value association, and Bayesian estimation.

A package that supports only a Gaussian longitudinal response fails the first requirement. A package that fits a single event type but not competing risks fails the second. Even if a package supports each feature somewhere, the team must verify that they are supported together with the desired association and estimator.

JMbayes2 is a reasonable candidate to investigate because it is designed for Bayesian joint models with broader longitudinal and event-process options than a basic Gaussian/single-event workflow. Suppose the documentation for the installed version confirms all four requirements for the intended combination. Then \(r=(1,1,1,1)\), \(c=(1,1,1,1)\), and \(C=4\). If the documentation instead confirms the response family, association, and Bayesian estimation but not the required competing-risks structure, then \(c=(1,0,1,1)\) and

$$ C=(1)(1)+(1)(0)+(1)(1)+(1)(1)=3. $$

That version is not compatible with the stated analysis, despite its score of 3 out of 4. Every item was declared essential, so a single missing feature is disqualifying. The appropriate next step is to find a documented implementation of the full model or revise the scientific specification with a clear justification—not to treat a single-event model as if it were a competing-risks model.

Worked Example: Multiple Outcomes Versus Latent Classes

Hypothetical analysis. A study measures two continuous biomarkers and observes one event type. The primary question is whether the biomarkers jointly inform event risk, without positing unobserved trajectory subgroups. Multiple longitudinal outcomes are essential; latent classes are not part of the scientific question.

The team should investigate a multivariate joint-model implementation, such as joineRML or an appropriate JMbayes2 specification, and check whether the chosen version supports the required outcome and association structure. For a four-item checklist—two outcomes, the required event model, the chosen association, and the preferred estimator—suppose a documented candidate supports the first three but not the preferred estimator. With all four initially marked essential, \(C=3\), so it does not pass. If the estimator is genuinely a preference rather than an essential requirement, the checklist should be revised before screening; the candidate then covers all three essential items.

A latent-class approach such as one available in lcmm would answer a different question: it represents heterogeneity through discrete latent trajectory groups. Choosing it just because the data contain multiple biomarkers would change the model’s interpretation. Latent classes should be included only when that structure is scientifically defensible and relevant to the target estimand.

Compare Estimation and Association Options Carefully

Maximum-likelihood and Bayesian implementations can target related model structures, but they are not interchangeable software labels. Maximum-likelihood procedures estimate parameters by optimizing a likelihood, with uncertainty commonly summarized using likelihood-based or asymptotic methods. Bayesian procedures combine a likelihood with prior distributions and use posterior summaries; computational approaches may involve Markov chain Monte Carlo. The choice affects the inferential framework and computation, and should be made before package selection if it is a requirement.

Likewise, association structures should be read as scientific assumptions rather than menu options. A current-value association links the hazard to the marker’s latent level at time \(t\). A slope association links it to the instantaneous rate of change. A cumulative association uses some summary of past trajectory. A shared-random-effects structure links outcomes through latent subject effects. These formulations answer different questions and may yield different interpretations for the association parameter. Confirm the exact form, time dependence, and any scaling conventions in the package documentation.

A practical comparison should also distinguish a package’s general capabilities from the exact model it can fit. For instance, support for binary longitudinal data does not automatically imply support for every event model, association, or estimator in combination. Check a small specification table or example from the package documentation, and record the package name and version alongside the intended model components.

Diagnostics, Failure Modes, and Limitations

Software selection does not replace diagnostics. After choosing a compatible implementation, assess whether the chosen model is credible and computationally adequate. Warning signs include repeated convergence failures, estimates at boundaries, very large standard errors, sensitivity to starting values, unstable Bayesian chains, or results that change sharply under modest, scientifically reasonable changes in model specification. These signs can reflect difficult computation, weak information, model misspecification, or a mismatch between the model and data; they do not identify a single cause by themselves.

Check the implemented model, not just the function name. Read the formula and argument documentation for the chosen version. Confirm the event type, response family, association, and estimator match the analysis plan.
Check whether the estimator matches the goal. A package’s available uncertainty summaries and computational behavior may not meet the analysis requirements.
Check the data and design separately. Sparse events, few measurements, or limited variation can make a structurally supported model difficult to estimate.
Keep the model interpretation intact. Do not substitute a latent-class model, a simpler event process, or a different association merely because it is easier to fit without explaining the change.

A compatibility score is deliberately limited: it records whether documented capabilities meet stated requirements. It is not a measure of model quality, predictive accuracy, convergence probability, or evidence for a scientific hypothesis. Nor does a package comparison establish which model is preferable when several structures are scientifically plausible. Those questions require substantive reasoning and appropriate model evaluation.

Common mistake: “This package fits joint models, so it can fit the model I need.” That reasoning skips the response family, event structure, association, and estimator. The correction is to list those components first, verify their joint availability in a specific package version, and treat any missing essential component as a mismatch—not as a minor software inconvenience.

A Defensible Selection Workflow

A short, documented process makes the choice easier to review and reproduce.

Write the scientific specification.
Name the longitudinal outcomes, event process, association structure, and estimation approach before comparing packages.

Mark requirements and preferences.
Do not allow a preference to substitute for an essential feature. Record any scientifically justified alternatives separately.

Verify the exact combination.
Use version-specific documentation and examples to confirm that every essential component is implemented together.

Compare compatible candidates.
Among candidates that pass, consider estimator, documentation, maintenance, and practical reproducibility.

Record the decision and revisit it after fitting.
Save the package version and specification. If diagnostics reveal problems, investigate the model and data before changing the scientific target.

Check Your Understanding

Answer each question by referring to model structure rather than package reputation.

A team requires a Gaussian marker, one event type, current-value association, and maximum-likelihood estimation. What should it verify before selecting a package?
Why does a package that supports a binary longitudinal response not necessarily satisfy a binary-marker, competing-risks analysis?
A researcher wants to describe discrete latent trajectory groups. Why might lcmm be relevant, and why is it not a generic replacement for a standard shared-effects model?
In a four-requirement checklist, all four requirements are essential and a candidate covers three. Is the candidate compatible? Explain.
Name two warning signs after fitting that call for investigation, and explain why neither alone proves that the package is unsuitable.

Solutions. (1) Verify in the documentation for a specific version that the response model, event model, current-value association, and maximum-likelihood estimator are supported together. (2) Response-family support does not imply support for the required event process, association, or estimator in the same model. (3) It is relevant because it targets joint models with latent classes; those classes change the scientific structure and should be used only when justified. (4) No. A missing essential component makes the candidate structurally incompatible, regardless of its 3-of-4 score. (5) Examples include convergence failures, boundary estimates, large standard errors, or unstable chains. They can arise from computational difficulty, limited information, or misspecification, so diagnosis requires further checks.