Code Documentation with explain • mrgda

This is a vignette to help you become familiar with using explain(). Check out the function documentation for additional background and examples.

explain() prints a formatted message containing the result of a provided expression. This function is intended to be run interactively in the R console to aid in code understanding, transfer and debugging.

Below, we will go through a few examples cases using explain().

library(mrgda)
library(dplyr)

Setup

We will use explain() to document data manipulations and checks on the derived PK data set from mrgda.

pk_data <- readr::read_csv(system.file("derived/pk.csv", package = "mrgda"))

Using explain()

Before performing a data manipulation, we can use explain() to document why it is needed. This will help transfer knowledge of assumptions/decisions made to future authors or reviewers.

For instance, if we’re planning to exclude a record we believe is an outlier, we can first use explain() to show where in the data the issue exists.

mrgda::explain("ID = 1 has outlier in PK data, will remove", {
  pk_data %>% 
    filter(ID == 1, DVID == 2, TIME < 24) %>% 
    select(ID, TIME, TAD, DV, DVID, EVID)
})

 [36m── [39m  [1mExplanation: ID = 1 has outlier in PK data, will remove [22m  [36m───────────────────── [39m

 [38;5;246m# A tibble: 5 × 6 [39m
     ID  TIME   TAD DV     DVID  EVID
   [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<chr> [39m [23m  [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<dbl> [39m [23m
 [38;5;250m1 [39m     1 - [31m0 [39m [31m. [39m [31m17 [39m - [31m0 [39m [31m. [39m [31m17 [39m .         2     2
 [38;5;250m2 [39m     1  0.68  0.68 15000     2     0
 [38;5;250m3 [39m     1  2.68  2.68 10.4      2     0
 [38;5;250m4 [39m     1  4.68  4.68 9.51      2     0
 [38;5;250m5 [39m     1 23.6  23.6  2.02      2     0

 [36m──────────────────────────────────────────────────────────────────────────────── [39m

This not only explains the issue, but shows where in the data it occurs. Additionally, the formatting of the message separates itself from the rest of the console outputs, helping it be more easily seen.

Arguments

Users need to provide two arguments to explain(). The first is a message to display in the header and the second is an expression to display the result of.

As shown previously, this expression could be in the form of a data.frame.

mrgda::explain("Show the first few records of ID = 2 from the pk_data data.frame", {
  pk_data %>% 
    filter(ID == 2) %>% 
    select(ID, TIME, DV, EVID) %>% 
    head()
})

 [36m── [39m  [1mExplanation: Show the first few records of ID = 2 from the pk_data data.frame [22m

 [38;5;246m# A tibble: 6 × 4 [39m
     ID  TIME DV     EVID
   [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<dbl> [39m [23m  [3m [38;5;246m<chr> [39m [23m  [3m [38;5;246m<dbl> [39m [23m
 [38;5;250m1 [39m     2 - [31m0 [39m [31m. [39m [31m22 [39m .         2
 [38;5;250m2 [39m     2  0    .         1
 [38;5;250m3 [39m     2  0.62 67.7      0
 [38;5;250m4 [39m     2  2.58 33.9      0
 [38;5;250m5 [39m     2  4.62 32.7      0
 [38;5;250m6 [39m     2 22.8  14.4      0

 [36m──────────────────────────────────────────────────────────────────────────────── [39m

A vector can also be provided, such as one containing all the unique studies from the data set.

mrgda::explain("Show a vector of all studies in the data set", {
  pk_data %>% 
    distinct(STUDYID) %>% 
    pull(STUDYID)
})

 [36m── [39m  [1mExplanation: Show a vector of all studies in the data set [22m  [36m─────────────────── [39m

[1] "STUDY-X" "STUDY-Y"

 [36m──────────────────────────────────────────────────────────────────────────────── [39m

Calculations can even be performed.

mrgda::explain("Total number of PK records that are not BLQ and doses", {
  nrow(pk_data %>% filter(DVID == 2, BLQ == 1)) +
    nrow(pk_data %>% filter(DVID ==1))
})

 [36m── [39m  [1mExplanation: Total number of PK records that are not BLQ and doses [22m  [36m────────── [39m

[1] 1034

 [36m──────────────────────────────────────────────────────────────────────────────── [39m

Essentially, anything that can be evaluated in the console can be provided as the .expr argument.