Get and display MMRM Results in a Formatted Table

Source: R/tbl_mmrm.R

These functions take a fitted MMRM model object and creates a formatted table, following the style of the MMRM template. It combines baseline summary statistics (if available) with the MMRM results, presenting them in a clear and organized manner.

get_mmrm_results(
  fit_mmrm,
  arm,
  visit,
  conf_level = 0.95,
  weights = c("equal", "proportional", "outer", "cells", "flat")
)

tbl_mmrm(
  mmrm_df,
  base_df = NULL,
  arm,
  visit,
  baseline_aval = NULL,
  digits = c(2, 3, 4),
  baseline_args = list(),
  postbaseline_args = list()
)

Arguments

fit_mmrm

(mmrm model object)
A fitted MMRM model object, typically created using the mmrm function from the mmrm package. This object should contain the necessary information to extract adjusted means, differences, confidence intervals, and p-values for the specified visits and arms.

arm

(string)
The column in mmrm_df and base_df that identifies the treatment arms. This will be used to divide the results in columns. First value is reference.

visit

(string)
The column in mmrm_df and base_df that identifies the visits. This will be used to stratify the results in rows.

conf_level

(numeric)
The confidence level to use when calculating confidence intervals for the adjusted means and differences. Default is 0.95 for 95% confidence intervals.

weights

(string)
The weighting scheme passed to emmeans::emmeans() when averaging the adjusted means over the levels of the model factors. Default is "equal". Use "proportional" to weight by the observed group sizes.

mmrm_df

(data.frame)
A tidy data frame containing the MMRM results. This should include columns for the visit, arm, adjusted means, differences, confidence intervals, and p-values. The data frame should be structured in a way that allows for stratification by visit and arm. Usually the output of get_mmrm_results().

base_df

(data.frame)
A data frame containing baseline measurements. This should include columns for the visit, arm, and baseline values. The function will summarize this data to provide baseline statistics in the final table. If base_df is not provided or does not contain any rows, the function will simply omit the baseline summary section from the final table.

baseline_aval

(tidy-select)
The column in base_df that contains the baseline values to be summarized. Unused if base_df is not provided or does not contain any rows.

digits

(numeric)
A numeric vector of length 3 specifying the number of decimal places for: 1) Estimates/CIs, 2) Standard Errors, and 3) P-values. Default is c(2, 3, 4).

baseline_args

(named list)
Arguments forwarded to the baseline tbl_roche_summary() call, letting you configure the baseline section (statistic, digits, type, sort, ...). Defaults to n and Mean (SE); only the elements you supply are overridden. For example, baseline_args = list(statistic = ~ c("{N_nonmiss}", "{mean} ({sd})", "{median}", "{min} - {max}")) shows n, Mean (SD), Median and Min - Max.

postbaseline_args

(named list)
Configures the post-baseline (MMRM) section. Supported elements:

  • stats (character) - which statistics to show and in which order. Defaults to c("n", "estimate_est", "lower_cl_est", "estimate_contr", "lower_cl_contr", "p_value"). The log-scale statistics "geom_mean_ratio" and "geom_mean_ratio_ci" are also available (meaningful only for a log-transformed response); add them to stats to show them.

  • label (named list) - row-label overrides, keyed by statistic id, e.g. label = list(p_value = "p").

  • stat_fns (named list) - formatting-function overrides, keyed by statistic id. Each function receives the row-group data and returns list(my_stat = <string>). Only the elements you supply are overridden; the rest keep their defaults. For example, postbaseline_args = list(stats = c("n", "estimate_est", "geom_mean_ratio", "geom_mean_ratio_ci")) appends the geometric mean ratio and its CI.

Value

A data.frame containing the estimated marginal means (adjusted means) and contrasts (differences in adjusted means) for each visit and arm, along with their standard errors, confidence intervals, degrees of freedom, and sample sizes. This data frame is structured to facilitate the creation of a formatted table using tbl_mmrm().

tbl_mmrm returns a 'gtsummary' table object.

See also

gg_mmrm_lineplot() for visualizing MMRM results.

Examples

if (FALSE) { # identical(Sys.getenv("NOT_CRAN"), "true") && requireNamespace("mmrm", quietly = TRUE)
library(mmrm)
fv_dt <- mmrm::fev_data |>
  dplyr::mutate(
    ARMCD = sprintf(
      "%s\n(N = %d)", ARMCD,
      table(mmrm::fev_data$ARMCD)[ARMCD]
    ),
    ARMCD = factor(ARMCD)
  )
}
if (FALSE) { # identical(Sys.getenv("NOT_CRAN"), "true") && requireNamespace("mmrm", quietly = TRUE)
# Fit an MMRM model using the FEV data
fit_mmrm <- mmrm::mmrm(
  # us -> unstructured cov structure
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fv_dt
)
mmrm_results <- get_mmrm_results(fit_mmrm, arm = "ARMCD", visit = "AVISIT", conf_level = 0.95)
}
if (FALSE) { # identical(Sys.getenv("NOT_CRAN"), "true") && requireNamespace("mmrm", quietly = TRUE)
tbl_mmrm(
  mmrm_results,
  fv_dt |> dplyr::mutate(AVISIT = "Baseline"),
  arm = "ARMCD", visit = "AVISIT", baseline_aval = "FEV1"
)

# Append the geometric mean ratio and its CI (for a log-transformed response)
tbl_mmrm(
  mmrm_results,
  arm = "ARMCD", visit = "AVISIT",
  postbaseline_args = list(
    stats = c("n", "estimate_est", "geom_mean_ratio", "geom_mean_ratio_ci")
  )
)
}