ggswim

The ggswim package provides a convenient set of commands to easily create swimmer plots. It integrates with the familiar ggplot2 framework and streamlines the process of generating legends that effectively communicate events of interest along individual subject trajectories.

ggswim solves some of the headaches associated with layer management in ggplot2 by leveraging the ggnewscale package and presenting an optimized workflow to get a swimmer plot.

Installation

You can install the development version of ggswim like so:

devtools::install_github("CHOP-CGTInformatics/ggswim")

Usage

To help you get started, ggswim includes three sample datasets: patient_data, infusion_events, and end_study_events. These de-identified datasets simulate real world data related to infusions, disease assessments, and study statuses for a clinical trial.

By first calling the ggswim() function, we can set up the horizontal survival bars of our swimmer plot, i.e. the “lanes:”

library(ggswim)
library(ggplot2)

p <- patient_data |>
  ggswim(
    mapping = aes(
      x = start_time, xend = end_time, y = pt_id,
      color = disease_assessment
    ),
    linewidth = 5
  ) +
  add_arrows(
    data = arrow_data,
    mapping = aes(x = start_time, xend = end_time, y = pt_id),
    arrow = "status"
  ) +
  scale_color_brewer(
    name = "Overall Disease Assessment",
    palette = "Set1"
  )

p

Next we’ll add on events of interest: end of study updates, and infusions. We’ll refer to these as “markers”:

p <- p +
  new_scale_color() +
  add_marker(
    data = end_study_events,
    aes(x = time_from_initial_infusion, y = pt_id, label_vals = end_study_label, label_names = end_study_name),
    label.size = NA, fill = NA, size = 5
  ) +
  add_marker(
    data = infusion_events,
    aes(x = time_from_initial_infusion, y = pt_id, color = infusion_type),
    size = 5
  )

p

Finally, we’ll beautify the plot with familiar ggplot2 techniques and a last finishing touch with theme_ggswim():

p +
  scale_color_brewer(name = "Markers", palette = "Set2") +
  labs(title = "My Swimmer Plot") +
  xlab("Time Since Infusion (Months)") + ylab("Patient ID") +
  theme_ggswim()

Collaboration

We invite you to give feedback and collaborate with us! If you are familiar with GitHub and R packages, please feel free to submit a pull request. Please do let us know if ggswim fails for whatever reason with your database and submit a bug report by creating a GitHub issue.

Please note that this project is released with a Contributor Code of Conduct. By participating you agree to abide by its terms.