Skip to contents

Listings & Figures

Source: vignettes/listings-and-figures.Rmd
listings-and-figures.Rmd

Listings

fr_listing() creates a spec optimised for record-level patient listings. It uses the same pipeline verbs as fr_table() but with different defaults:

Feature fr_table() fr_listing()
Font size 9pt 8pt
Alignment Auto-detect Left
Text wrapping Off On
Column splitting Off On
H-lines None "header"

AE Listing (16.2.7.1) 

ae_list <- adae[1:40, c("USUBJID", "AEBODSYS", "AEDECOD",
                         "AESEV", "AESER", "AEREL", "AEACN")]
ae_listing_spec <- ae_list |>
  fr_listing() |>
  fr_titles(
    "Listing 16.2.7.1",
    list("Adverse Events", bold = TRUE),
    "Safety Population"
  ) |>
  fr_cols(
    USUBJID  = fr_col("Subject ID", width = 1.3),
    AEBODSYS = fr_col("System Organ Class", width = 1.8),
    AEDECOD  = fr_col("Preferred Term", width = 1.5),
    AESEV    = fr_col("Severity", width = 0.8),
    AESER    = fr_col("Serious", width = 0.7),
    AEREL    = fr_col("Related", width = 0.8),
    AEACN    = fr_col("Action", width = 1.2)
  ) |>
  fr_rows(sort_by = c("USUBJID", "AEBODSYS", "AEDECOD"),
          suppress = "USUBJID") |>
  fr_footnotes(
    "Related = Probable or Possible.",
    "Action = Action taken with study drug."
  )
fr_validate(ae_listing_spec)
ae_listing_spec |> fr_render("output/Listing_16_2_7_1.rtf")
Listing 16.2.7.1
Adverse Events
Safety Population
Subject ID System Organ Class Preferred Term Severity Serious Related Action
TFR-001-0001 Infections and infestations Nasopharyngitis MILD N NONE DOSE NOT CHANGED
Respiratory, thoracic and mediastinal disorders Rhinorrhoea MILD N NONE DOSE NOT CHANGED
TFR-001-0003 Gastrointestinal disorders Flatulence MODERATE N NONE DOSE NOT CHANGED
Infections and infestations Nasopharyngitis MILD N NONE DOSE NOT CHANGED
Renal and urinary disorders Incontinence MILD N NONE DOSE NOT CHANGED
TFR-001-0015 Gastrointestinal disorders Nausea MILD N NONE DOSE NOT CHANGED
TFR-001-0016 Cardiac disorders Palpitations MILD N NONE DOSE NOT CHANGED
Gastrointestinal disorders Abdominal pain upper MILD N NONE DOSE NOT CHANGED
General disorders and administration site conditions Fatigue MILD N NONE DOSE NOT CHANGED
Musculoskeletal and connective tissue disorders Back pain MODERATE N NONE DRUG INTERRUPTED
Nervous system disorders Headache MILD N NONE DOSE NOT CHANGED
TFR-001-0021 Metabolism and nutrition disorders Weight decreased MILD N NONE DOSE NOT CHANGED
Musculoskeletal and connective tissue disorders Arthralgia MILD N REMOTE DOSE NOT CHANGED
Respiratory, thoracic and mediastinal disorders Epistaxis MILD N REMOTE DOSE NOT CHANGED
Respiratory, thoracic and mediastinal disorders Oropharyngeal pain MILD N POSSIBLE DOSE NOT CHANGED
Vascular disorders Hypotension MODERATE N PROBABLE DOSE NOT CHANGED
TFR-001-0024 Gastrointestinal disorders Diarrhoea MILD N NONE DOSE NOT CHANGED
General disorders and administration site conditions Fatigue MILD N NONE DOSE NOT CHANGED
Metabolism and nutrition disorders Dehydration MILD N PROBABLE DOSE NOT CHANGED
Musculoskeletal and connective tissue disorders Back pain MODERATE N NONE DRUG INTERRUPTED
Psychiatric disorders Hallucination SEVERE N POSSIBLE DOSE REDUCED
TFR-001-0025 General disorders and administration site conditions Fatigue SEVERE N REMOTE DRUG INTERRUPTED
Vascular disorders Flushing MILD N PROBABLE NOT APPLICABLE
TFR-001-0040 Cardiac disorders Palpitations MILD N NONE DOSE NOT CHANGED
Eye disorders Conjunctivitis MODERATE N NONE DOSE REDUCED
Gastrointestinal disorders Diarrhoea MILD N POSSIBLE DOSE NOT CHANGED
General disorders and administration site conditions Fatigue MILD N NONE NOT APPLICABLE
Musculoskeletal and connective tissue disorders Pain in extremity MILD N NONE DOSE NOT CHANGED
Nervous system disorders Dizziness MILD N NONE DOSE NOT CHANGED
Renal and urinary disorders Incontinence MILD N NONE NOT APPLICABLE
TFR-001-0042 Eye disorders Conjunctivitis MODERATE N PROBABLE DOSE NOT CHANGED
Infections and infestations Urinary tract infection SEVERE N PROBABLE DOSE REDUCED
Metabolism and nutrition disorders Decreased appetite MODERATE N POSSIBLE DOSE NOT CHANGED
Metabolism and nutrition disorders Weight decreased MODERATE N NONE DRUG INTERRUPTED
Musculoskeletal and connective tissue disorders Back pain MILD N PROBABLE DOSE NOT CHANGED
Musculoskeletal and connective tissue disorders Myalgia MODERATE N NONE DOSE NOT CHANGED
Nervous system disorders Insomnia MILD N NONE DOSE NOT CHANGED
Psychiatric disorders Anxiety SEVERE Y POSSIBLE DRUG WITHDRAWN
Reproductive system and breast disorders Erectile dysfunction MILD N NONE DOSE NOT CHANGED
Skin and subcutaneous tissue disorders Rash MODERATE N PROBABLE DOSE NOT CHANGED
Related = Probable or Possible.
Action = Action taken with study drug.
/tmp/RtmpKCCmfM/callr-scr-6801c6112d3c3 01APR2026 11:29:21

Key listing features

sort_by orders rows by the named columns:

spec <- adae[1:10, c("USUBJID", "AEDECOD", "AESEV")] |>
  fr_listing() |>
  fr_rows(sort_by = c("USUBJID", "AEDECOD"))

suppress suppresses repeated values (like SAS NOREPEAT):

spec <- adae[1:10, c("ARM", "USUBJID", "AEDECOD")] |>
  fr_listing() |>
  fr_rows(sort_by = c("ARM", "USUBJID"),
          suppress = c("ARM", "USUBJID"))

wrap = TRUE enables automatic text wrapping (on by default in listings):

spec <- adae[1:5, c("USUBJID", "AEBODSYS")] |>
  fr_listing() |>
  fr_rows(wrap = TRUE)

Figures

fr_figure() wraps a ggplot2 or base R plot into the same pipeline, giving it titles, footnotes, page headers, and footers:

# fr_figure() wraps a ggplot2 or base R plot
# pagehead/pagefoot are inherited from fr_theme() --- no need to repeat
my_plot |>
  fr_figure(width = 8, height = 5) |>
  fr_titles(
    "Figure 14.2.1",
    "Kaplan-Meier Plot of Time to Study Withdrawal"
  )

With ggplot2 

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  km_plot <- ggplot(adtte, aes(x = AVAL, colour = ARM)) +
    stat_ecdf(geom = "step") +
    labs(x = "Days", y = "Proportion Event-Free") +
    theme_minimal()

  fig_spec <- km_plot |>
    fr_figure(width = 8, height = 5) |>
    fr_titles(
      "Figure 14.2.1",
      "Kaplan-Meier Plot of Time to Study Withdrawal",
      "Intent-to-Treat Population"
    ) |>
    fr_footnotes("Tick marks indicate censored observations.")
}
fig_spec |> fr_render("output/Figure_14_2_1.pdf")
Figure 14.2.1
Kaplan-Meier Plot of Time to Study Withdrawal
Intent-to-Treat Population
figure
Tick marks indicate censored observations.
/tmp/RtmpKCCmfM/callr-scr-6801c6112d3c3 01APR2026 11:29:22

Multi-page figures

Pass a list of plots to create a multi-page figure. Add a meta data frame to inject per-page tokens into titles and footnotes:

# Three KM plots --- one per subgroup
km_plots <- list(p_adults, p_pediatrics, p_geriatrics)
page_meta <- data.frame(
  subgroup = c("Adults", "Pediatrics", "Geriatrics"),
  n        = c(80, 55, 30)
)

km_plots |>
  fr_figure(meta = page_meta) |>
  fr_titles(
    "Figure 14.1.1 Kaplan-Meier Curve",
    "Subgroup: {subgroup} (N = {n})"
  ) |>
  fr_footnotes("Source: ADTTE") |>
  fr_render("km_by_subgroup.rtf")

Each meta column name becomes a {token} resolved dynamically per page. The second title line renders as “Subgroup: Adults (N = 80)” on page 1, “Subgroup: Pediatrics (N = 55)” on page 2, and so on.

Figure parameters

Parameter Default Description
plot (required) ggplot2 object, recorded base R plot, or a list of either
width NULL Plot width in inches (auto-sized from page if NULL)
height NULL Plot height in inches (70% of printable height if NULL)
meta NULL Data frame with one row per plot; columns become {token} names in titles/footnotes