Introduction

The modelsummary_rms function is designed to process output from models fitted using the rms package and generate a summarised dataframe of the results. The goal is to produce publication-ready summaries of the models.

This vignette will guide you through the basic usage of the function and then move on to more advanced examples.

# Install the package if you haven't already
# install.packages("rmsMD")

library(rms)
library(rmsMD)
library(MASS)

Basic Usage

Here is a simple example using a linear regression model (“ordinary least squares”; OLS). The example data being used here is the built-in survey dataset from the MASS package. The models are for demonstration purposes only.

The output dataframe contains the estimated coefficients, their 95% confidence intervals, and the associated p-values. These are in a publication ready format.

# Loading the built-in dataset from the MASS package:
data("survey", package = "MASS")

# Fit a linear regression model using the rms package:
fit_ols <- ols(Wr.Hnd ~ Age + Exer + Sex, data = survey)

# Generate a model summary, and assign it to rmsMD_summary
rmsMD_summary <- modelsummary_rms(fit_ols)

# displaying rmsMD dataframe output
rmsMD_summary

##    variable                coef_95CI Pvalue
## 1       Age  0.011 (-0.020 to 0.042)  0.474
## 2 Exer=None -0.112 (-0.798 to 0.574)  0.749
## 3 Exer=Some -0.021 (-0.447 to 0.406)  0.924
## 4  Sex=Male   2.146 (1.743 to 2.550) <0.001

# rmsMD dataframe as a table
knitr::kable(rmsMD_summary)

# Generate a model summary with custom styling options
summary_custom <- modelsummary_rms(fit_ols, 
                                   combine_ci = FALSE, 
                                   round_dp_coef = 2, 
                                   round_dp_p = 5)

# to display the dataframe as a table
knitr::kable(summary_custom)

# Generate a model summary with custom styling options
summary_fullmodel <- modelsummary_rms(fit_ols, 
                                   combine_ci = FALSE, 
                                   round_dp_coef = 2, 
                                   round_dp_p = 5,
                                   fullmodel = TRUE)
knitr::kable(summary_fullmodel)

# Note: For demonstration, we create a binary outcome using the survey dataset.
survey$BinaryOutcome <- ifelse(survey$Wr.Hnd > median(survey$Wr.Hnd, na.rm = TRUE), 1, 0)

# fitting the model
fit_lrm <- lrm(BinaryOutcome ~ Age + Exer + Sex, data = survey)

# rmsMD summary
summary_lrm <- modelsummary_rms(fit_lrm)

# displaying as a table
knitr::kable(summary_lrm)

# Fit a simple linear model using lm() from base R (an example model fit without using rms package)
fit_lm <- lm(Wr.Hnd ~ Age + Exer + Sex, data = survey)

# Generate a model summary for the non-RMS model by explicitly setting exp_coef = FALSE
summary_lm <- modelsummary_rms(fit_lm, 
                               exp_coef = FALSE)

# display rmsMD results as a table
knitr::kable(summary_lm)

Restricted Cubic Splines

Restricted Cubic Splines (RCS) are a flexible modelling tool used to capture non-linear relationships between predictors and outcomes. In medicine, for the majority of continuous variables (e.g. age, blood pressure, or biomarker levels) the assumption of linearity may not hold. A key highlight of the rms package is the ability to analyse variables using RCS.

The rmsMD package is designed to report and summarise models that include RCS terms. Individual coefficients for RCS terms are difficult to interpret in isolation. Instead, an overall p-value can be generated to assess whether the overall relationship between the RCS variable and outcome is significant. By default modelsummary_rms removes the individual RCS coefficients, replacing them with the overall p-value for that variable.

• Display an overall p-value for the spline terms using the rcs_overallp option.
  When this option is set to TRUE (which is the default), the function computes a single p-value that tests the overall significance of the spline terms for each variable. This overall p-value provides insight into whether the relationship between the predictor and the dependent variable is significant.

• Hide the individual spline coefficients using the hide_rcs_coef option.
  Hiding the individual spline coefficients can be advantageous because these lack straightforward clinical interpretation. Instead, the focus is on the overall association captured by all RCS terms for that specific variable. This helps simplify the output. If the variable has a signficant association with outcome, we recommend plotting this relationship.

Example of a model with RCS terms for the continuous outcome Age. The default settings are applied, which hides the individual RCS terms, and provides an overall p-value for the association of Age with outcome.

# Using the built-in dataset from the MASS package
data("survey", package = "MASS")

# Fit an OLS model including a restricted cubic spline for Age (with 4 knots)
fit_spline <- ols(Wr.Hnd ~ rcs(Age, 4) + Exer + Sex, data = survey)

# Generate an rmsMD model summary using default settings
summary_spline <- modelsummary_rms(fit_spline)

# Outputting this as a table
knitr::kable(summary_spline)

# Fit an OLS model including a restricted cubic spline for Age (with 4 knots)
fit_spline_hide <- ols(Wr.Hnd ~ rcs(Age, 4) + Exer + Sex, data = survey)

# Generate a model summary with rcs_overallp set to TRUE and hide_rcs_coef set to TRUE
summary_spline_hide <- modelsummary_rms(fit_spline_hide, 
                                        hide_rcs_coef = FALSE)

# Outputting this as a table
knitr::kable(summary_spline_hide)

# Fit an OLS model including a restricted cubic spline for Age (with 4 knots)
fit_spline_hide <- ols(Wr.Hnd ~ rcs(Age, 4) + Exer + Sex, data = survey)

# Generate a model summary with rcs_overallp set to TRUE and hide_rcs_coef set to TRUE
summary_spline_hide <- modelsummary_rms(fit_spline_hide, 
                                        rcs_overallp = FALSE, 
                                        hide_rcs_coef = FALSE)
knitr::kable(summary_spline_hide)

Models with Interactions

In medical research, interactions can be critical, as the impact of a treatment or risk factor might differ across subgroups (for example, by age or sex). These interaction terms are handled by modelsummary_rms.

Here is a simple example:

# Using the built-in dataset from the MASS package
data("survey", package = "MASS")

# Fit an OLS model using the rms package with an interaction between Age and Exer.
fit_interact <- ols(Wr.Hnd ~ Age * Exer + Sex, data = survey)

# Generate a model summary that includes the interaction term
summary_interact <- modelsummary_rms(fit_interact)
knitr::kable(summary_interact)

# Using the built-in dataset from the MASS package
data("survey", package = "MASS")

# Fit an OLS model with a restricted cubic spline for Age and an interaction between Age and Exer.
fit_spline_interact <- ols(Wr.Hnd ~ rcs(Age, 4) * Exer + Sex, data = survey)

# Generate a model summary with default RCS output
summary_spline_interact <- modelsummary_rms(fit_spline_interact)

# Format the output as a nice table
knitr::kable(summary_spline_interact)

Exporting to Microsoft Word

The output of modelsummary_rms is a dataframe, as this is easy to work with and further process if required. This dataframe output can easily be exported to a word document using flextable and officer packages.

library(officer)
library(flextable)
library(dplyr)

# converting modelsummary_rms dataframe generated above into a flextable
rmsMD_as_table <- flextable(rmsMD_summary)

# use officer to create a 
doc <- read_docx() %>% 
  body_add_flextable(rmsMD_as_table) %>%
  body_add_par("Model summary from rmsMD", style = "heading 2")

# generating a temporary output path for demonstration. This would be replaced by the file path where the word document will be generated
output_path <- file.path(tempdir(), "example_output.docx")

# generating the word document
print(doc, target = output_path)

print(doc, target = "temp.docx")