Why Audit the Fitted Object?
A successful software call does not guarantee that the fitted model is the one the analyst intended. A variable may be omitted from a formula, a random slope may be absent, or the event submodel may link risk to the biomarker’s current value when the plan called for its slope. The optimizer can converge for that unintended model and produce a plausible-looking summary.
A specification audit checks the identity of the fitted model: its longitudinal fixed-effects formula, random-effects structure, event formula, association terms, and relevant parameter dimensions. It is distinct from diagnosing numerical warnings, assessing model fit, or interpreting estimated effects. Those checks answer different questions: whether estimation succeeded, whether the model describes the data adequately, and what its estimates mean.
The audit starts from a written analysis specification, not from the fitted object’s output. The earlier material on longitudinal formulas, event submodels, and association structures supplies the modeling vocabulary; here the task is to compare that intended structure with what the software actually fitted.
Write Down the Intended Specification
For subject \(i\), let \(Y_{ij}\) denote a longitudinal measurement at time \(t_{ij}\). A common longitudinal submodel is
Here \(x_i(t)\) is the fixed-effects design vector, \(\beta\) its coefficient vector, \(z_i(t)\) is the random-effects design vector, \(b_i\) is the subject-specific random-effects vector, \(D\) is its covariance matrix, and \(\epsilon_{ij}\) is the measurement error. An event submodel may be written
where \(h_0(t)\) is the baseline hazard, \(w_i\) contains event-submodel covariates, \(\gamma\) their coefficients, and \(m_i(t)\) the longitudinal marker trajectory linked to the event process. Other specifications may link the event hazard to the marker’s slope, a cumulative marker history, or multiple association quantities. The audit must record which of these was intended, rather than treating the word “association” as a complete specification.
Before fitting, record the response and time origin; longitudinal fixed-effects terms and their coding; random-effects terms and covariance structure; event time, event indicator, and covariates; baseline-hazard representation; and the association form. Also note any transformations, interactions, or restrictions. The intended formula should be explicit enough that another analyst could identify a mismatch without guessing what “adjusted for time” meant.
For instance, if the longitudinal model has \(p\) fixed-effect coefficients and \(q\) random effects per subject, then its fixed-effect vector has dimension \(p\), and its random-effects covariance matrix \(D\) is \(q\times q\). If \(D\) is unrestricted and symmetric, it has \(q(q+1)/2\) distinct covariance parameters. These counts are useful checks, but they do not uniquely identify a model: different formulas can have the same number of coefficients.
A Practical Audit Sequence
Write the formulas and structural choices in a compact checklist before examining the output. Include time scales, coding, and the exact association form.
Use the software’s documented methods to inspect the stored call, formulas, design terms, random-effects structure, event-response information, and association settings. A printed summary may omit important structural details.
Match each planned term to the fitted representation. Check coefficient and covariance dimensions as independent consistency checks, not as substitutes for formula inspection.
Determine whether a difference is an intentional software encoding or an unintended model change. If unintended, correct the input and refit; do not relabel estimates from the wrong model as if they came from the planned one.
Software packages do not all store formulas or parameter blocks in the same way. A formula may be expanded into a design matrix, a baseline hazard may be represented through package-specific parameters, and association options may be stored separately from the displayed formula. Therefore, use the package’s documented object-inspection tools and verify the meaning of each field. Do not assume that a particular component name or printed label is universal.
Worked Audits
Worked Example: A Missing Longitudinal Time Interaction
Suppose a hypothetical study plans to model a biomarker in 80 participants at three scheduled visits. The intended fixed-effects model includes treatment, time, and a treatment-by-time interaction; the random-effects model includes a subject-specific intercept and time slope. The fitted object reports the fixed terms as treatment and time only, while retaining the planned random intercept and slope.
Check the fixed-effects design. With treatment coded as a two-level indicator and time treated as a numeric variable, the planned fixed-effects terms are an intercept, treatment, time, and treatment-by-time. Thus \(p=4\). The reported object has an intercept, treatment, and time, so \(p=3\). The missing interaction is a structural discrepancy, not merely a difference in coefficient labels.
Check the random-effects dimensions. The intended random-effects vector is \(b_i=(b_{0i},b_{1i})^\top\), so \(q=2\). An unrestricted \(D\) has \(2(2+1)/2=3\) distinct covariance parameters: two variances and one covariance. If the object reports two random-effect coefficients per participant and a \(2\times2\) covariance structure, those dimensions agree with the plan, but they do not repair the missing fixed interaction.
Conclusion. The fitted object is not the specified model. The analyst should verify whether the interaction was omitted in the fitting call or removed by a software option, then refit the intended model before interpreting treatment-specific trajectories or event associations. The three-versus-four fixed-effect count supports the diagnosis, while inspection of the actual terms identifies the exact omission.
Worked Example: A Random Intercept Was Fitted Instead of a Random Slope
In a hypothetical cohort of 60 participants, measurements are planned at times 0, 1, and 2 years. The intended longitudinal model has a random intercept and a random linear time slope, with an unrestricted covariance matrix. The object’s stored random-effects structure contains only an intercept.
For the intended structure, \(b_i=(b_{0i},b_{1i})^\top\), so \(q=2\), and the unrestricted covariance matrix has \(2(3)/2=3\) distinct parameters. The fitted structure instead has \(b_i=b_{0i}\), so \(q=1\), and its random-effects variance block has \(1(2)/2=1\) parameter. The change from three covariance parameters to one is consistent with the missing random slope.
The longitudinal fixed-effects formula may still include time. That does not make the random-slope specification present: a fixed time effect describes the population-average time trend, whereas a random time slope allows individuals to have varying time trends. The formula and random-effects structure must be checked separately.
Conclusion. The object does not encode the planned between-subject variation in linear change. Confirm the random-effects term and its covariance option in the fit call and refit if the omission was unintended. A small estimated slope variance in a correctly specified fit would be a different issue; it is not evidence that a random slope was never included.
Worked Example: The Event Link Uses the Wrong Association Quantity
Consider a hypothetical analysis whose plan links the event hazard to the biomarker’s current value and slope:
The fitted object’s association settings show only a current-value link, with one association coefficient. The plan contains two association quantities, \(m_i(t)\) and \(m_i'(t)\), and therefore two corresponding coefficients, \(\alpha_1\) and \(\alpha_2\). The object’s single association term does not match the planned two-term structure.
A coefficient count is a useful clue, but the decisive check is the association definition itself. Some software uses internal parameterizations or labels that do not map one-to-one to the analyst’s notation. Confirm from the documented specification or stored model structure whether the fitted link includes a derivative of the longitudinal trajectory. Do not infer a slope link merely because time appears in the longitudinal model.
Conclusion. The fitted object encodes a current-value association only, not the intended current-value-plus-slope association. The estimated current-value coefficient cannot be treated as an estimate from the planned model. Correct the association settings and refit before comparing or interpreting the resulting parameters.
Why Dimension Checks Help—and Where They Fail
Dimension checks are a fast way to catch gross mismatches. If a planned random intercept and slope have been reduced to an intercept alone, the random-effects dimension and covariance-parameter count change. If a planned fixed-effect interaction is missing, the coefficient dimension may decrease. The logic is direct: the software cannot estimate a coefficient for a design term that is absent from its fitted design.
However, dimensions are not a complete audit. Two different fixed-effects formulas can have equal numbers of terms; for example, replacing one covariate with another preserves the coefficient count. Contrasts, reference categories, factor levels, aliased columns, and constraints can also make the number of printed coefficients differ from a simple count of named terms. Likewise, a covariance structure may be diagonal rather than unrestricted while retaining the same random-effects dimension but using fewer covariance parameters.
For these reasons, compare both the identity of the terms and the dimensions of the parameter blocks. If a design matrix is available, verify its columns against the intended coding, including time transformations and interactions. For random effects, check the random-effects design and covariance restrictions separately. For the event component, verify the event-time and event-indicator variables, covariates, baseline-hazard representation, and association definitions.
Diagnostics, Alternatives, and Limitations
Several warning signs should prompt closer inspection: a stored call that differs from the analysis script; unexpected coefficient names or counts; a random-effects block with the wrong dimension; an absent interaction; an event response built from a different time or status variable; or an association parameter block with the wrong terms. A successful convergence message does not eliminate any of these concerns. Nor does agreement of parameter counts prove that the right variables were used.
The main ways to check a fitted model have complementary roles:
| Audit approach | What it can reveal | What it cannot establish alone |
|---|---|---|
| Inspect the stored call and formulas | Whether named variables and terms appear as intended | Whether hidden coding, transformations, or restrictions match the plan |
| Inspect design and random-effects structures | Actual columns, dimensions, and covariance layout | Whether the scientific choices were appropriate |
| Check parameter counts and labels | Many omissions or unexpected parameter blocks | Which terms differ when alternative models have equal dimensions |
| Reconstruct and rerun from a documented script | Whether the specified input reproduces the fitted structure | Whether the model assumptions are true or the fit is adequate |
A reconstruction from the analysis script is especially useful when the object does not retain all inputs. Compare the script’s intended formulas with the fitted object’s stored representation, then record the software version and relevant options so the audit can be repeated. This is a reproducibility check, not a substitute for inspecting the actual object.
An audit also has a boundary. It can establish that the object represents a specified model, but not that the longitudinal error assumptions, event-process assumptions, missing-data assumptions, or substantive causal interpretation are justified. Those require separate scientific and statistical evaluation. If a term was intentionally changed after examining the data, document that change rather than silently treating the revised model as the original plan.
Common Pitfall
The practical rule is simple: audit structure before interpreting estimates. If a discrepancy changes the model, rerun the fit. If it is only a different software representation of the same model, document the mapping and confirm that the underlying design and likelihood components agree.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A planned longitudinal model has an intercept, treatment, time, and treatment-by-time interaction. The fitted object has three fixed-effect coefficients. Is the dimension check enough to identify the discrepancy? What should you inspect?
- A planned random intercept and slope use an unrestricted covariance matrix. How many distinct covariance parameters are expected, and what does an object with only one random-effect dimension suggest?
- The longitudinal formula includes time, but the intended event association is current value plus slope. The object reports a current-value association only. Does the presence of time in the longitudinal formula satisfy the plan?
- Why is a successful convergence message not evidence that the fitted object matches the intended specification?
Solutions. (1) No. Three coefficients suggest that one planned term may be absent, but the count alone cannot show which term is missing; inspect the stored fixed-effects terms and design columns for the treatment-by-time interaction. (2) With \(q=2\), the unrestricted covariance matrix has \(q(q+1)/2=2(3)/2=3\) distinct parameters. One random-effect dimension suggests that the random slope is absent, although the stored structure should be inspected to confirm. (3) No. Time as a longitudinal predictor does not itself add a derivative to the event association. Verify the event association settings and refit if the slope link was omitted. (4) Convergence concerns the numerical optimization for the model that was supplied. The optimizer can converge successfully even when that model has the wrong formula, random-effects structure, event terms, or association form.