Referential Footnotes
In rlistings: Clinical Trial Style Data Readout Listings

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

There is currently no formal method for adding referential footnotes to a listing object. This vignette demonstrates how referential footnotes can be added to a listing_df object via a workaround applied during pre-processing.

To learn more about how listings are constructed using the rlistings package, see the Getting Started vignette.

Referential Footnotes Workaround

When creating a listing with the rlistings package, you may want to add referential footnotes, similar to how referential footnotes can be added to rtable objects. Since there is no formal method in rlistings for applying referential footnotes to a listing_df object, we will demonstrate how a workaround can be applied to add a set of pseudo-referential footnotes to your listing.

To demonstrate, we will create a basic listing below.

We begin by loading in the rlistings package.

library(rlistings)

For this example, we will use the dummy ADAE dataset provided within the formatters package as our data frame, which consists of 48 columns of adverse event patient data, and one or more rows per patient. For the purpose of this example, we will subset the data and only use the first 30 records of the dataset.

adae <- ex_adae[1:30, ]

Now we will create a basic listing.

lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASEQ", "ASTDY"),
  disp_cols = c("BMRKR1", "AESEV"),
)

lsting

For this example, we will add 4 referential footnotes.

In the ARM column, for all records with ARM = "A: Drug X" and ASEQ equal to 1 or 2.
In the ASTDY column, for imputed dates, where imputed dates are indicated by the ASTDTF variable.
In the AESEV column, for all records with AETOXGR equal to 5.
In the USUBJID column header.

Footnote text can be supplied either as a vector, where each element is a new footnote, or as a single string with footnotes separated by the new line (\n) character. For example, see the following list of referential footnotes:

ref_fns <- "*   ASEQ 1 or 2\n**  Analysis start date is imputed\n***  Records with ATOXGR = 5\n**** ID column"

We start with our first footnote in the ARM column for records with arm "A: Drug X" which also have analysis sequence number 1 or 2. Referential footnotes can be added to any variable by converting the variable to a factor, editing the variable values, and adding a corresponding footnote below the listing. We will add our first referential footnote in the ARM column. To ensure that levels are correctly ordered, be sure to specify the new level order when mutating your variable.

# Save variable labels for your data to add back in after mutating dataset
df_lbls <- var_labels(adae)

# Mutate variable where referential footnotes are to be added according to your conditions
# Specify order of levels with new referential footnotes added
adae <- adae %>% dplyr::mutate(
  ARM = factor(
    ifelse(ARM == "A: Drug X" & ASEQ %in% 1:2, paste0(ARM, "*"), as.character(ARM)),
    levels = c(sapply(levels(adae$ARM), paste0, c("", "*")))
  )
)

# Add data variable labels back in
var_labels(adae) <- df_lbls

# Generate listing
lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASEQ", "ASTDY"),
  disp_cols = c("BMRKR1", "AESEV"),
)

lsting

Additional referential footnotes can be added to the data be repeating the above steps.

For example, we can add the second referential footnote to the ASTDY column for imputed analysis start days. We use dummy variable ASTDTF to indicate imputed analysis start dates. When adding referential footnotes to numeric variables, the variables must be converted to factors.

set.seed(1)

# Save variable labels for your data to add back in after mutating dataset
df_lbls <- var_labels(adae)

# Mutate variable where referential footnotes are to be added according to your conditions
# Specify order of levels with new referential footnotes added
adae <- adae %>%
  dplyr::mutate(ASTDTF = sample(c("Y", NA), nrow(.), replace = TRUE, prob = c(0.25, 0.75))) %>%
  dplyr::mutate(ASTDY = factor(
    ifelse(!is.na(ASTDTF), paste0(as.character(ASTDY), "**"), as.character(ASTDY)),
    levels = c(sapply(sort(unique(adae$ASTDY)), paste0, c("", "**")))
  )) %>%
  dplyr::select(-ASTDTF)

# Add data variable labels back in
var_labels(adae) <- df_lbls

# Generate listing
lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASEQ", "ASTDY"),
  disp_cols = c("BMRKR1", "AESEV"),
)

lsting

Next we can add our third referential footnote to the AESEV column for records with analysis toxicity grade 5.

# Save variable labels for your data to add back in after mutating dataset
df_lbls <- var_labels(adae)

# Mutate variable where referential footnotes are to be added according to your conditions
# Specify order of levels with new referential footnotes added
adae <- adae %>% dplyr::mutate(
  AESEV = factor(
    ifelse(AETOXGR == 5, paste0(AESEV, "***"), as.character(AESEV)),
    levels = c(sapply(levels(adae$AESEV), paste0, c("", "***")))
  )
)

# Add data variable labels back in
var_labels(adae) <- df_lbls

# Generate listing
lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASEQ", "ASTDY"),
  disp_cols = c("BMRKR1", "AESEV"),
)

lsting

Referential footnotes can also be added to column header labels. Suppose we want to add our fourth referential footnote to the USUBJID column label. We can do so by editing the USUBJID variable label and adding the footnote text as follows:

# Modify data variable label
adae <- adae %>% var_relabel(
  USUBJID = paste0(var_labels(adae)[["USUBJID"]], "****")
)

# Generate listing
lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASTDY", "ASEQ"),
  disp_cols = c("BMRKR1", "AESEV")
)

lsting

Finally, we add in the referential footnote text below the listing as follows.

# Generate listing
lsting <- as_listing(
  df = adae,
  key_cols = c("ARM", "USUBJID", "ASTDY", "ASEQ"),
  disp_cols = c("BMRKR1", "AESEV")
)

main_footer(lsting) <- c(main_footer(lsting), ref_fns)

lsting