Study Summary

Summarize the study data sources with text summary or table.

yspec
pmtables
reporting

1 Introduction

Our modeling and simulation reports include a summary of the study data included in the anaylsis. Given that MetrumRGs reports are written in Latex, it can often be a time-consuming process to appropriately write and format these text-heavy data summary tables. We now make these tables, and the corresponding text summaries, in R using a YAML file to hold all the study-specific information. The yaml and pmtables packages to convert the YAML contents to a text section or table.

2 Tools used

2.1 MetrumRG packages

yspec Data specification, wrangling, and documentation for pharmacometrics.

pmtables Create summary tables commonly used in pharmacometrics and turn any R table into a highly customized tex table.

2.2 CRAN packages

dplyr A grammar of data manipulation.

yaml Methods to convert R data to YAML and back.

3 Outline

Here we walk through how to summarize the studies in your analysis in a YAML file and how to convert it to a table tex file for Latex (shown below) using R.

Figure 1: An example study summary table generated from a YAML file

We also show how to use the information in the YAML file to create a bulletted list for each study and save it out to a tex file for Latex

Figure 2: An example of the study summary text generated from a YAML file

4 Set up

4.1 Required packages

library(tidyverse)
library(pmtables)
library(yaml)
library(here)
library(glue)
library(magrittr)

4.2 Other set up

# Grab some helper functions ----------------------------
source(here("script", 'functions-study-summary.R'))

# Set options for saving out table ----------------------------
options(mrg.script = "study-summary.R", pmtables.dir = tempdir())

5 Description of studies in the YML

The study-summary.yaml includes a description of each study. The important information extracted about each study will obviously vary from project-to-project.

Here is an example of the YAML code for one study:

A:
  Study: 101-DEMO-001
  fileEx: met01
  Title: |
    A randomized, single ascending dose, Phase I trial to assess the safety, 
    tolerability, and \gls{PK} of once daily oral doses of \drugx\ in healthy adults.
  Phase: '1'
  Short: Randomized, single ascending dose study
  Patients: Healthy
  nSub: 30 \linebreak (5 per DG)
  nDose: Single dose
  D_levels: 5, 10, 25, 100, 150, 200 mg 
  obTime: 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 12, 20, 24, 48, 72, and 96 hours post-dose
  nTime: '15'
  Conc: |
    Single doses of \drugx\ were safe and well tolerated when administered orally.
  Source: |
    IB, p20 (nSub + doses), p35 (times)
  • Study: study name
  • fileEx: file extension for the study tex file
  • Title: full study title
  • Phase: phase of this study
  • Short: short description of the study
  • Patients: description of patients or healthy subjects included in the study
  • nSub: number of subjects
  • nDose: number of doses
  • D_levels: dose levels
  • obTime: observation times
  • nTime: number of observation time points
  • Conc: main take home conclusion from the study
  • Source: where was the information in the above categories extracted from

These categories should be adapted to suit each project.

6 Study descriptions from YML to R dataframe

The description in the YML are read into R as a dataframe using the pmtables yaml_as_df function. The resulting data frame includes one row per study and one column per category.

sdf <- yaml_as_df(here("script", "study-summary.yaml"))
head(sdf, 5)
# A tibble: 4 × 14
  .row  Study      fileEx Title Phase Short Patients nSub  nDose D_levels obTime
  <chr> <chr>      <chr>  <chr> <chr> <chr> <chr>    <chr> <chr> <chr>    <chr> 
1 A     101-DEMO-… met01  "A r… 1     Rand… "Health… "30 … Sing… 5, 10, … "0.5,…
2 B     101-DEMO-… met02  "A r… 1     Rand… "Health… "50 … Mult… 10, 25,… "\\em…
3 C     201-DEMO-… met03  "A r… 1     Rand… "Normal… "40 … Mult… 25 mg    "\\em…
4 D     201-DEMO-… met04  "A r… 1     Rand… "Normal… "40 … Sing… 25 mg    "1, 1…
# ℹ 3 more variables: nTime <chr>, Conc <chr>, Source <chr>

7 Creating a study summary table

The study summary table was created by selecting the appropriate columns from the summary data frame and then using functions from the pmtables package to format it for Latex and save it out as a tex file.

df = sdf %>% 
  mutate(ob_n_time = paste0(obTime, " (N = ", nTime, ")")) %>% 
  select(Study, Short, Phase, nSub, nDose, D_levels, ob_n_time) %>% 
  st_new() %>%
  st_rename("Design" = "Short",
            "Number of ... subjects" = "nSub", 
            "Dose ...regimen" = "nDose", 
            "Dose levels" = "D_levels", 
            "Planned observations" = "ob_n_time") %>% 
  st_align(c(Study = col_ragged(2.5),
              Short = col_ragged(3),
              Phase = 'c',
              nSub = col_fixed(2.5, center=TRUE),
              nDose = col_ragged(2),
              D_levels = col_ragged(2),
              ob_n_time = col_ragged(6))) %>% 
  st_hline(from = "Study") %>% 
  st_notes("Abbreviations: BID = twice daily; 
              DG = Dose Group; 
              Obs = Observations") %>% 
  st_noteconf(type="minipage", width = 1) %>% 
  st_files(output = "study-summary-table.tex") %>% 
  st_sizes(font="small", row = 2, header_row = -1) %>% 
  st_bold("Study", pattern = "DEMO") %>% 
  stable(cols_bold = TRUE) %>%
  as_lscape() %T>% 
  stable_save()

Figure 3: An example study summary table generated from a YAML file

While this table fits comfortably on a single landscape page that will not always be the case, so the study-summary.R script includes examples (commented out at the end) showing how to create a long table version of the study summary table using either the pmtable::stable_long function.

8 Creating text descriptions of the studies

We often include text summaries of each study in our reports to accompany the study summary tables. These can also be generated from the YAML file and R data frame. The advantage here is that the full study description can be contained within a single YAML file and all text for the study summaries can be created from a single function. In this Expo, there is a function called perStudy located in the functions-table.R script that creates a single tex file per study. The function is designed to accept a dataframe where the first column includes the file extension, the second column defines the upper level of the bullet list (in most cases the study name) and subsequent columns form the sub-bullet items. In this example, the upper bullet point is the study name and the sub-bullets include the title, study design and main conclusions from each study as shown in the screenshot below.

sdf %>% 
  select(fileEx, Study, Title, Short, Conc) %>% 
  rename(Design = Short, 
         Conclusion = Conc) %>% 
  pwalk(perStudy, out_dir = tempdir())

Figure 4: The study summary text generated from a YAML file

9 Other resources

9.1 Full script

The following files from the Github repository are discussed on this page. If you’re interested running this code, visit the About the Github Repo page first.