Empty Value Formatting

By default, if there is no available value for a summary in a particular observation, the result being presented will be blanked out.

Note: Tplyr generally respects factor levels - so in instances of a missing row or column group, if the factor level is present, then the variable or row will still generate)

tplyr_adsl$TRT01P <- as.factor(tplyr_adsl$TRT01P)
tplyr_adlb$TRTA <- as.factor(tplyr_adlb$TRTA)

tplyr_adlb_2 <- tplyr_adlb %>% 
  filter(TRTA != "Placebo")

tplyr_table(tplyr_adlb_2, TRTA) %>% 
  set_pop_data(tplyr_adsl) %>% 
  set_pop_treat_var(TRT01P) %>% 
  add_layer(
    group_desc(AVAL, by=PARAMCD) %>% 
      set_format_strings('Mean (SD)' = f_str('xxx (xxx)', mean, sd))
  ) %>% 
  build() %>% 
  head() %>% 
  select(-starts_with("ord")) %>% 
  kable()

Note how the entire example above has all records in var1_Placebo missing. Tplyr gives you control over how you fill this space. Let’s say that we wanted instead to make that space say “Missing”. You can control this with the f_str() object using the empty parameter.

tplyr_table(tplyr_adlb_2, TRTA) %>% 
  set_pop_data(tplyr_adsl) %>% 
  set_pop_treat_var(TRT01P) %>% 
  add_layer(
    group_desc(AVAL, by=PARAMCD) %>% 
      set_format_strings('Mean (SD)' = f_str('xxx.xx (xxx.xxx)', mean, sd, empty=c(.overall="MISSING")))
  ) %>% 
  build() %>% 
  head() %>% 
  select(-starts_with("ord")) %>% 
  kable()

Look at the empty parameter above. Here, we use a named character vector, where the name is .overall. When this name is used, if all elements within the cell are missing, they will be filled with the specified text. Otherwise, the provided string will fill just the missing parameter. In some cases, this may not be what you’d like to see. Perhaps we want a string that fills each missing space.

tplyr_table(tplyr_adlb_2, TRTA) %>% 
  set_pop_data(tplyr_adsl) %>% 
  set_pop_treat_var(TRT01P) %>% 
  add_layer(
    group_desc(AVAL, by=PARAMCD) %>% 
      set_format_strings('Mean (SD)' = f_str('xxx.xx (xxx.xxx)', mean, sd, empty=c("NA")))
  ) %>% 
  build() %>% 
  head() %>%
  select(-starts_with("ord")) %>%
  kable()

In the example above, instead of filling the whole space, the empty text of “NA” replaces the empty value for each element. So for ‘Mean (SD)’, we now have ‘NA ( NA)’. Note that the proper padding was still used for ‘NA’ to make sure the parentheses still align with populated records.

Auto Precision

You may have noticed that the approach to formatting covered so far leaves a lot to be desired. Consider analyzing lab results, where you may want precision to vary based on the collected precision of the tests. Furthermore, depending on the summary being presented, you may wish to increase the precision further. For example, you may want the mean to be at collected precision +1 decimal place, and for standard deviation +2.

Tplyr has this covered using auto-precision. Auto-precision allows you to format your numeric summaries based on the precision of the data collected. This has all been built into the format strings, because a natural place to specify your desired format is where you specify how you want your data presented. If you wish to use auto-precision, use a instead of x when creating your summaries. Note that only one a is needed on each side of a decimal. To use increased precision, use a+n where n is the number of additional spaces you wish to add.

tplyr_table(tplyr_adlb, TRTA) %>% 
  add_layer(
    group_desc(AVAL, by = PARAMCD) %>% 
      set_format_strings(
        'Mean (SD)' = f_str('a.a+1 (a.a+2)', mean, sd)
      )
  ) %>% 
  build() %>% 
  head(20) %>% 
  select(-starts_with("ord")) %>% 
  kable()

As you can see, the decimal precision is now varying depending on the test being performed. Notice that both the integer and the decimal side of each number fluctuate as well. Tplyr collects both the integer and decimal precision, and you can specify both separately. For example, you could use x’s to specify a default number of spaces for your integers that are used consistently across by variables, but vary the decimal precision based on collected data. You can also increment the number of spaces for both integer and decimal separately.

But - this is kind of ugly, isn’t it? Do we really need all 6 decimal places collected for CA? For this reason, you’re able to set a cap on the precision that’s displayed:

tplyr_table(tplyr_adlb, TRTA) %>% 
  add_layer(
    group_desc(AVAL, by = PARAMCD) %>% 
      set_format_strings(
        'Mean (SD)' = f_str('a.a+1 (a.a+2)', mean, sd),
        cap = c(int=3, dec=2)
      )
  ) %>% 
  build() %>% 
  head(20) %>% 
  select(-starts_with("ord")) %>%
  kable()

Now that looks better. The cap argument is part of set_format_strings(). You need to specify the integer and decimal caps separately. Note that integer precision works slightly differently than decimal precision. Integer precision relates to the length allotted for the left side of a decimal, but integers will not truncate. When using ‘x’ formatting, if an integer exceeds the set length, it will push the number over. If the integer side of auto-precision is not capped, the necessary length for an integer in the associated by group will be as long as necessary. Decimals, on the other hand, round to the specified length. These caps apply to the length allotted for the “a” on either the integer or the decimal. So for example, if the decimal length is capped at 2 and the selected precision is “a+1”, then 3 decimal places will be allotted.

This was a basic situation, but if you’re paying close attention, you may have some questions. What if you have more by variables, like by visit AND test. Do we then calculate precision by visit and test? What if collected precision is different per visit and we don’t want that? What about multiple summary variables? How do we determine precision then? We have modifier functions for this:

tplyr_table(tplyr_adlb, TRTA) %>% 
  add_layer(
    group_desc(vars(AVAL, CHG, BASE), by = PARAMCD) %>% 
      set_format_strings(
        'Mean (SD)' = f_str('a.a+1 (a.a+2)', mean, sd, empty="NA"),
        cap = c(int=3, dec=2)
      ) %>% 
      set_precision_on(AVAL) %>% 
      set_precision_by(PARAMCD)
  ) %>%
  build() %>% 
  head() %>% 
  select(-starts_with("ord")) %>%
  kable()

Three variables are being summarized here - AVAL, CHG, and BASE. So which should be used for precision? set_precision_on() allows you to specify this, where the precision_on() variable must be one of the variables within target_var. Similarly, set_precision_by() changes the by variables used to determine collected precision. If no precision_on() variable is specified, the first variable in target_var is used. If no precision_by variables are specified, then the default by variables are used.

External Precision

Lastly, while dynamic precision might be what you’re looking for, you may not want precision driven by the data. Perhaps there’s a company standard that dictates what decimal precision should be used for each separate lab test. Maybe even deeper down to the lab test and category. New in Tplyr 1.0.0 we’ve added the ability to take decimal precision from an external source.

The principal of external precision is exactly the same as auto-precision. The only difference is that you - the user - provide the precision table that Tplyr was automatically calculating in the background. This is done using the new function set_precision_data(). In the output below, Notice how the precision by PARAMCD varies depending on what was specified in the data frame prec_data.

prec_data <- tibble::tribble(
  ~PARAMCD, ~max_int, ~max_dec,
  "BUN",   1, 0,
  "CA",    2, 4,
  "CK",    3, 1,
  "GGT",   3, 0,
  "URATE", 3, 1,
)
  
tplyr_table(tplyr_adlb, TRTA) %>% 
  add_layer(
    group_desc(AVAL, by = PARAMCD) %>% 
      set_format_strings(
        'Mean (SD)' = f_str('a.a+1 (a.a+2)', mean, sd, empty="NA")
      ) %>% 
      set_precision_on(AVAL) %>% 
      set_precision_by(PARAMCD) %>%
      set_precision_data(prec_data)
  ) %>%
  build() %>% 
  head() %>% 
  select(-starts_with("ord")) %>%
  kable()

If one of your by variable groups are missing in the precision data, Tplyr can default back to using auto-precision by using the option default=auto.

prec_data <- tibble::tribble(
  ~PARAMCD, ~max_int, ~max_dec,
  "BUN", 1, 0,
  "CA",  2, 4,
  "CK",  3, 1,
  "GGT", 3, 0,
)
  
tplyr_table(tplyr_adlb, TRTA) %>% 
  add_layer(
    group_desc(AVAL, by = PARAMCD) %>% 
      set_format_strings(
        'Mean (SD)' = f_str('a.a+1 (a.a+2)', mean, sd, empty="NA")
      ) %>% 
      set_precision_on(AVAL) %>% 
      set_precision_by(PARAMCD) %>%
      set_precision_data(prec_data, default="auto")
  ) %>%
  build() %>% 
  head() %>% 
  select(-starts_with("ord")) %>%
  kable()
#> Unhandled precision cases were found - calculating precision based on source data

Parenthesis Hugging

By default, when using ‘x’ or ‘a’, any other character within a format string will stay stationary. Consider the standard example from the descriptive statistic layer vignette.

tplyr_table(tplyr_adsl, TRT01P) %>% 
  add_layer(
    group_desc(AGE, by = "Age (years)", where= SAFFL=="Y") %>% 
      set_format_strings(
        "n"        = f_str("xx", n),
        "Mean (SD)"= f_str("xx.x (xx.xx)", mean, sd),
        "Median"   = f_str("xx.x", median),
        "Q1, Q3"   = f_str("xx, xx", q1, q3),
        "Min, Max" = f_str("xx, xx", min, max),
        "Missing"  = f_str("xx", missing)
      )
  ) %>% 
  build() %>% 
  select(-starts_with('ord'))
#> # A tibble: 6 × 5
#>   row_label1  row_label2 var1_Placebo   `var1_Xanomeline High Dose`
#>   <chr>       <chr>      <chr>          <chr>                      
#> 1 Age (years) n          "86"           "84"                       
#> 2 Age (years) Mean (SD)  "76.3 ( 8.59)" "75.9 ( 7.89)"             
#> 3 Age (years) Median     "76.0"         "76.0"                     
#> 4 Age (years) Q1, Q3     "69, 82"       "71, 80"                   
#> 5 Age (years) Min, Max   "52, 89"       "56, 88"                   
#> 6 Age (years) Missing    " 0"           " 0"                       
#> # ℹ 1 more variable: `var1_Xanomeline Low Dose` <chr>

Note that if a certain number of integers are alotted, space will be left for the numbers that fill that space, but the position of the parenthesis stays fixed. In some displays, you may want the parenthesis to ‘hug’ your number - the “format group” width should stay fixed, the parenthesis should move to the right along with the numbers consuming less integer space. Within your f_str(), you can achieve this by using a capital ‘X’. For example, focusing on the mean and standard deviation line:

tplyr_table(tplyr_adlb, TRTA, PARAMCD == "CK") %>% 
  add_layer(
    group_desc(AVAL, by=vars(PARAMCD, AVISIT)) %>% 
      set_format_strings(
        TEST = f_str("xxx.x (XXX.x)", mean, sd, empty="NA")
      ) %>% 
      set_precision_by(PARAMCD)
  ) %>% 
  build() %>% 
  head() %>% 
  select(-starts_with('ord'))
#> # A tibble: 3 × 6
#>   row_label1 row_label2 row_label3 var1_Placebo    `var1_Xanomeline High Dose`
#>   <chr>      <chr>      <chr>      <chr>           <chr>                      
#> 1 CK         Week 12    TEST       " 67.5 (148.6)" "122.0 (115.5)"            
#> 2 CK         Week 24    TEST       " 73.2 (438.5)" " 55.5   (3.5)"            
#> 3 CK         Week 8     TEST       " 82.0  (78.9)" " 67.5  (80.6)"            
#> # ℹ 1 more variable: `var1_Xanomeline Low Dose` <chr>

Similarly, the same functionality works with auto precision by using a capital A.

tplyr_table(tplyr_adlb, TRTA, PARAMCD == "CK") %>% 
  add_layer(
    group_desc(AVAL, by=vars(PARAMCD, AVISIT)) %>% 
      set_format_strings(
        TEST = f_str("a.a (A.a)", mean, sd, empty="NA")
      ) %>% 
      set_precision_by(PARAMCD)
  ) %>% 
  build() %>% 
  head() %>% 
  select(-starts_with('ord'))
#> # A tibble: 3 × 6
#>   row_label1 row_label2 row_label3 var1_Placebo `var1_Xanomeline High Dose`
#>   <chr>      <chr>      <chr>      <chr>        <chr>                      
#> 1 CK         Week 12    TEST       "  68 (149)" " 122 (115)"               
#> 2 CK         Week 24    TEST       "  73 (438)" "  56   (4)"               
#> 3 CK         Week 8     TEST       "  82  (79)" "  68  (81)"               
#> # ℹ 1 more variable: `var1_Xanomeline Low Dose` <chr>

There are a two rules when using ‘parenthesis hugging’:

• Capital letters should only be used on the integer side of a number
• A character must precede the capital letter, otherwise there’s no character to ‘hug’

Aside from these rules, parenthesis hugging can be combined with all other valid format string capabilities.