mmrm: Mixed Models for Repeated Measures in R

Scope

• Continuous responses: Assumes normal (but potentially heteroscedastic) residuals.
• Marginal linear models: Implements models without individual-level random effects.

Key Features

• Flexible Covariance Structures: Supports unstructured, Toeplitz, AR1, compound symmetry, ante-dependence, and spatial exponential. You can specify shared covariance for all subjects or group-specific estimates, and homogeneous or heterogeneous variances across time points.
• Inference: Supports both REML and ML, and allows for weighted observations.
• Hypothesis Testing:
  • Supports Satterthwaite and Kenward-Roger adjusted degrees of freedom.
  • Supports one- and multi-dimensional linear contrasts.
  • Integration with emmeans for obtaining least square means.
• Performance: Uses a C++ backend with automatic differentiation for fast and robust model fitting.
• Ecosystem Integration:
  • tidymodels: Includes a dedicated parsnip engine for linear regression and integration with recipes.
  • tern: Integration via tern.mmrm for automated tabulation, plots of least square means, and model diagnostics.

The mmrm package implements Mixed Models for Repeated Measures (MMRM) based on the marginal linear model without random effects. It uses the Template Model Builder (TMB) backend for fast and robust model fitting via C++ and automatic differentiation.

Core Scope:

• Continuous responses with normal (potentially heteroscedastic) residuals.
• Marginal linear models (no individual-level random effects).

Key Capabilities:

• Flexible Covariance Structures: Supports unstructured, Toeplitz, AR1, compound symmetry, ante-dependence, and spatial exponential structures. It allows for shared or group-specific covariance and homogeneous or heterogeneous variances across time points.
• Inference & Testing: Supports Restricted Maximum Likelihood (REML) and Maximum Likelihood (ML). Provides Satterthwaite or Kenward-Roger adjustments for degrees of freedom and coefficient covariance matrices.
• Integration: Works with emmeans for least square means, tidymodels (via a parsnip engine), and tern (via tern.mmrm for automated tabulation and plotting).

To assess the correctness of mmrm(), you can compare its results against established software like SAS's PROC MIXED. When using the sasr R package to facilitate this comparison, you must be careful with the repeated measures variable (e.g., time).

If the repeated measures variable is a factor, its alphanumeric ordering must match the expected temporal ordering. Because sasr converts R data.frame objects into pandas DataFrames (via SASPy) before transforming them into SAS datasets, factor levels like c("1", "2", ..., "10") may be reordered as "1", "10", "2", ..., "9" in SAS due to string sorting.

To avoid incorrect parameter estimation (such as swapped variances), you should:

1. Use explicit factor levels for the time variable.
2. Pad zeroes in the time variable (e.g., "01", "02"...).
3. Or, pass the time variable as a numeric type to avoid string-based reordering entirely.

This example demonstrates how to generate data and use a wrapper function to run SAS PROC MIXED via sasr. It highlights the importance of how the time variable is formatted to prevent alphanumeric reordering in SAS.

#' PROC MIXED Wrapper Function
#'
#' @description This function takes as input the ouput of a data-generating
#'   process function, and fits PROC MIXED repeated measures model on this data.
#'
#' @param participant A factor vector of participant IDs.
#' @param time A factor vector of time points.
#' @param y A numeric vector of outcomes.
#' @param trt A binary vector of treatment group indicators.
#'
#' @return Estimated parameters of the repeated measures' covariance matrix.
#'   These parameters are stored in a data.frame object.
proc_mixed_fun <- function(
    participant,
    time,
    y,
    trt) {
  ## assemble the vectors into a data.frame
  df <- data.frame(
    "participant" = participant,
    "time" = time,
    "y" = y,
    "trt" = trt
  )
  rownames(df) <- NULL

## create SAS dataset
  sasr::df2sd(df, "sas_df")

## specify the SAS code: only return covariance matrix estimates for
  ## repeated measures
  sas_code <- "ods output CovParms = cov_parms;
    PROC MIXED DATA = sas_df;
      CLASS trt time participant;
      MODEL y = trt;
      REPEATED time / subject=participant type=CSH;
    RUN;"

## run the SAS code, and capture the output
  sas_result <- sasr::run_sas(sas_code)
  cov_mat_df <- sasr::sd2df("cov_parms")

## prepare the fit object
  return(list(fit = cov_mat_df))
}