library(mmrm)
fit <- mmrm(
formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
data = fev_data
)MMRM in R
Fitting the MMRM in R
Mixed models for repeated measures (MMRM) are a popular choice for analyzing longitudinal continuous outcomes in randomized clinical trials and beyond; see Cnaan, Laird and Slasor (1997) for a tutorial and Mallinckrodt, Lane and Schnell (2008) for a review.
This vignette shows examples from the mmrm package.
The mmrm package implements MMRM based on the marginal linear model without random effects using Template Model Builder (TMB) which enables fast and robust model fitting. Users can specify a variety of covariance matrices, weight observations, fit models with restricted or standard maximum likelihood inference, perform hypothesis testing with Satterthwaite or Kenward-Roger adjustment, and extract least square means estimates by using emmeans.
Main Features
- Flexible covariance specification:
- Structures: unstructured, Toeplitz, AR1, compound symmetry, ante-dependence, and spatial exponential.
- Groups: shared covariance structure for all subjects or group-specific covariance estimates.
- Variances: homogeneous or heterogeneous across time points.
- Inference:
- Supports REML and ML.
- Supports weights.
- Hypothesis testing:
- Least square means: can be obtained with the
emmeanspackage - One- and multi-dimensional linear contrasts of model parameters can be tested.
- Satterthwaite adjusted degrees of freedom.
- Kenward-Roger adjusted degrees of freedom and coefficients covariance matrix.
- Coefficient Covariance
- Least square means: can be obtained with the
C++backend:- Fast implementation using
C++and automatic differentiation to obtain precise gradient information for model fitting. - Model fitting algorithm details used in
mmrm.
- Fast implementation using
- Package ecosystems integration:
- Integration with tidymodels package ecosystem
- Integration with tern package ecosystems
- The tern.mmrm package can be used to run the
mmrmfit and generate tabulation and plots of least square means per visit and treatment arm, tabulation of model diagnostics, diagnostic graphs, and other standard model outputs.
- The tern.mmrm package can be used to run the
Using the mmrm::mmrm function
See also the introductory vignette
The code below implements an MMRM fit in R with the mmrm::mmrm function.
The code specifies an MMRM with the given covariates and an unstructured covariance matrix for the timepoints (also called visits in the clinical trial context, here given by AVISIT) within the subjects (here USUBJID). While by default this uses restricted maximum likelihood (REML), it is also possible to use ML, see ?mmrm.
Printing the object will show you output which should be familiar to anyone who has used any popular modeling functions such as stats::lm(), stats::glm(), glmmTMB::glmmTMB(), and lme4::nlmer(). From this print out we see the function call, the data used, the covariance structure with number of variance parameters, as well as the likelihood method, and model deviance achieved. Additionally the user is provided a printout of the estimated coefficients and the model convergence information:
fitmmrm fit
Formula: FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID)
Data: fev_data (used 537 observations from 197 subjects with maximum 4
timepoints)
Covariance: unstructured (10 variance parameters)
Inference: REML
Deviance: 3386.45
Coefficients:
(Intercept) RACEBlack or African American
30.77747548 1.53049977
RACEWhite SEXFemale
5.64356535 0.32606192
ARMCDTRT AVISITVIS2
3.77423004 4.83958845
AVISITVIS3 AVISITVIS4
10.34211288 15.05389826
ARMCDTRT:AVISITVIS2 ARMCDTRT:AVISITVIS3
-0.04192625 -0.69368537
ARMCDTRT:AVISITVIS4
0.62422703
Model Inference Optimization:
Converged with code 0 and message: convergence: rel_reduction_of_f <= factr*epsmchThe summary() method then provides the coefficients table with Satterthwaite degrees of freedom as well as the covariance matrix estimate:
fit |>
summary()mmrm fit
Formula: FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID)
Data: fev_data (used 537 observations from 197 subjects with maximum 4
timepoints)
Covariance: unstructured (10 variance parameters)
Method: Satterthwaite
Vcov Method: Asymptotic
Inference: REML
Model selection criteria:
AIC BIC logLik deviance
3406.4 3439.3 -1693.2 3386.4
Coefficients:
Estimate Std. Error df t value Pr(>|t|)
(Intercept) 30.77748 0.88656 218.80000 34.715 < 2e-16
RACEBlack or African American 1.53050 0.62448 168.67000 2.451 0.015272
RACEWhite 5.64357 0.66561 157.14000 8.479 1.56e-14
SEXFemale 0.32606 0.53195 166.13000 0.613 0.540744
ARMCDTRT 3.77423 1.07415 145.55000 3.514 0.000589
AVISITVIS2 4.83959 0.80172 143.88000 6.037 1.27e-08
AVISITVIS3 10.34211 0.82269 155.56000 12.571 < 2e-16
AVISITVIS4 15.05390 1.31281 138.47000 11.467 < 2e-16
ARMCDTRT:AVISITVIS2 -0.04193 1.12932 138.56000 -0.037 0.970439
ARMCDTRT:AVISITVIS3 -0.69369 1.18765 158.17000 -0.584 0.559996
ARMCDTRT:AVISITVIS4 0.62423 1.85085 129.72000 0.337 0.736463
(Intercept) ***
RACEBlack or African American *
RACEWhite ***
SEXFemale
ARMCDTRT ***
AVISITVIS2 ***
AVISITVIS3 ***
AVISITVIS4 ***
ARMCDTRT:AVISITVIS2
ARMCDTRT:AVISITVIS3
ARMCDTRT:AVISITVIS4
---
Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
Covariance estimate:
VIS1 VIS2 VIS3 VIS4
VIS1 40.5537 14.3960 4.9747 13.3867
VIS2 14.3960 26.5715 2.7855 7.4745
VIS3 4.9747 2.7855 14.8979 0.9082
VIS4 13.3867 7.4745 0.9082 95.5568Extracting effect estimates using emmeans
In order to extract relevant marginal means (LSmeans) and contrasts we can use the emmeans package. This package includes methods that allow mmrm objects to be used with the emmeans package. emmeans computes estimated marginal means (also called least-square means) for the coefficients of the MMRM.
if (require(emmeans)) {
emmeans(fit, ~ ARMCD | AVISIT)
}Loading required package: emmeansmmrm() registered as emmeans extensionWelcome to emmeans.
Caution: You lose important information if you filter this package's results.
See '? untidy'AVISIT = VIS1:
ARMCD emmean SE df lower.CL upper.CL
PBO 33.3 0.755 148 31.8 34.8
TRT 37.1 0.763 143 35.6 38.6
AVISIT = VIS2:
ARMCD emmean SE df lower.CL upper.CL
PBO 38.2 0.612 147 37.0 39.4
TRT 41.9 0.602 143 40.7 43.1
AVISIT = VIS3:
ARMCD emmean SE df lower.CL upper.CL
PBO 43.7 0.462 130 42.8 44.6
TRT 46.8 0.509 130 45.7 47.8
AVISIT = VIS4:
ARMCD emmean SE df lower.CL upper.CL
PBO 48.4 1.189 134 46.0 50.7
TRT 52.8 1.188 133 50.4 55.1
Results are averaged over the levels of: RACE, SEX
Confidence level used: 0.95 Note that the degrees of freedom choice is inherited here from the initial mmrm fit.