tern Formatting Functions Overview

The tern R package provides functions to create common analyses from clinical trials in R and these functions have default formatting arguments for displaying the values in the output a specific way.

tern formatting differs compared to the formatting available in the formatters package as tern formats are capable of handling logical statements, allowing for more fine-tuning of the output displayed. Depending on what type of value is being displayed, and what that value is, the format of the output will change. Whereas when using the formatters package, the specified format is applied regardless of the value.

To see the available formatting functions available in tern see ?formatting_functions. To see the available format strings available in formatters see formatters::list_valid_format_labels().

Comparing tern & formatters Formats

The packages used in this vignette are:

library(rtables)
library(formatters)
library(tern)
library(dplyr)

tern_formats.R

The example below demonstrates the use of tern formatting in the count_abnormal() function. The example “low” category has a non-zero numerator value so both a fraction and a percentage value are displayed, while the “high” value has a numerator value of zero and so the fraction value is displayed without also displaying the redundant zero percentage value.

df2 <- data.frame(
  ID = as.character(c(1, 1, 2, 2)),
  RANGE = factor(c("NORMAL", "LOW", "HIGH", "LOW")),
  BL_RANGE = factor(c("NORMAL", "NORMAL", "HIGH", "HIGH")),
  ONTRTFL = c("", "Y", "", "Y"),
  stringsAsFactors = FALSE
)

df2 <- df2 %>%
  filter(ONTRTFL == "Y")

basic_table() %>%
  count_abnormal(
    var = "RANGE",
    abnormal = list(low = "LOW", high = "HIGH"),
    variables = list(id = "ID", baseline = "BL_RANGE"),
    exclude_base_abn = FALSE,
    .formats = list(fraction = format_fraction)
  ) %>%
  build_table(df2)
#>         all obs  
#> —————————————————
#> low    2/2 (100%)
#> high      0/2

tern_formats.R

In the following example the count_abnormal() function is utilized again. This time both “low” values and “high” values have a non-zero numerator and so both show a percentage.

df2 <- data.frame(
  ID = as.character(c(1, 1, 2, 2)),
  RANGE = factor(c("NORMAL", "LOW", "HIGH", "HIGH")),
  BL_RANGE = factor(c("NORMAL", "NORMAL", "HIGH", "HIGH")),
  ONTRTFL = c("", "Y", "", "Y"),
  stringsAsFactors = FALSE
)

df2 <- df2 %>%
  filter(ONTRTFL == "Y")

basic_table() %>%
  count_abnormal(
    var = "RANGE",
    abnormal = list(low = "LOW", high = "HIGH"),
    variables = list(id = "ID", baseline = "BL_RANGE"),
    exclude_base_abn = FALSE,
    .formats = list(fraction = format_fraction)
  ) %>%
  build_table(df2)
#>         all obs 
#> ————————————————
#> low    1/2 (50%)
#> high   1/2 (50%)

tern_formats.R

The following example demonstrates the difference when formatters is used instead to format the output. Here we choose to use "xx / xx" as our value format. The “high” value has a zero numerator value and the “low” value has a non-zero numerator, yet both are displayed in the same format.

df2 <- data.frame(
  ID = as.character(c(1, 1, 2, 2)),
  RANGE = factor(c("NORMAL", "LOW", "HIGH", "LOW")),
  BL_RANGE = factor(c("NORMAL", "NORMAL", "HIGH", "HIGH")),
  ONTRTFL = c("", "Y", "", "Y"),
  stringsAsFactors = FALSE
)
df2 <- df2 %>%
  filter(ONTRTFL == "Y")

basic_table() %>%