Descriptive Statistic Layers

Built-in Summaries

We’ve built a number of default summaries into ‘Tplyr’, which allows you to perform these summaries without having to specify the functions to calculate them yourself. The summaries built in to ‘Tplyr’ are listed below. In the second column are the names that you would use within an f_str() call to use them. In the third column, we have the syntax used to make the function call.

tplyr_table(adsl, TRT01P) %>% 
  add_layer(
    group_desc(CUMDOSE) %>% 
      set_format_strings("Q1, Q3" = f_str('xxxxx, xxxxx', q1, q3))
  ) %>% 
  build() %>%
  select(-starts_with("ord")) %>% 
  kable()

options(tplyr.quantile_type = 3)
tplyr_table(adsl, TRT01P) %>% 
  add_layer(
    group_desc(CUMDOSE) %>% 
      set_format_strings("Q1, Q3" = f_str('xxxxx, xxxxx', q1, q3))
  ) %>% 
  build() %>% 
    select(-starts_with("ord")) %>% 
  kable()

Custom Summaries

We understand that our defaults may not cover every descriptive statistic that you’d like to see. That’s why we’ve opened to door to creating custom summaries. Custom summaries allow you to provide any function you’d like into a desc layer. You can focus on the derivation and how to calculate the number you want to see. ‘Tplyr’ can consume this function, and use all the existing tools within ‘Tplyr’ to produce the string formatted result alongside any of the default summaries we provide as well.

Custom summaries may be provided in two ways:

• Through the tplyr.custom_summaries option set at your session level
• Through the function set_custom_summaries() at the layer level

As with any other setting in ‘Tplyr’, the layer setting will always take precedence over any other setting.

Let’s look at an example.

tplyr_table(adsl, TRT01P) %>%
  add_layer(
    group_desc(vars(AGE, HEIGHTBL), by = "Sepal Length") %>%
      set_custom_summaries(
        geometric_mean = exp(sum(log(.var[.var > 0]), na.rm=TRUE) / length(.var))
      ) %>%
      set_format_strings(
        'Geometric Mean (SD)' = f_str('xx.xx (xx.xxx)', geometric_mean, sd)
      )
  ) %>% 
  build() %>% 
  select(-starts_with("ord")) %>% 
  kable()

Here, a few important things are demonstrated:

• This is a multi-variable descriptive statistics layer. Both AGE and HEIGHTBL are being summarized in the same layer. AGE results go to the var1_ variables and HEIGHTBL results go to the var2_ variables.
• The parameter names in set_custom_summaries(), or names on the left side of the equals, flow into set_format_strings() in the f_str() calls. Just like the default summaries, geometric_mean becomes the name that you refer to in order to use the geometric mean derivation in a summary.
• In geometric mean, the target variable that you’re summarizing is referred to as .var. This may not seem intuitive. The reason we have to use .var is so that, like in this example, the custom function can be applied to each of the separate target variables.

Another note about custom summaries is that you’re able to overwrite the default summaries built into ‘Tplyr’ as well. Don’t like the default summary functions that we provide? Use the tplyr.custom_summaries option to overwrite them in your session, and add any new ones that you would like to include.

For example, here we use the ‘Tplyr’ default mean.

tplyr_table(adsl, TRT01P) %>% 
  add_layer(
    group_desc(AGE) %>% 
      set_format_strings("Mean" = f_str('xx.xx', mean))
  ) %>% 
  build() %>% 
  kable()

But now, let’s overwrite mean using a custom summary. Let’s use a trimmed mean instead, taking 20% of observations off of both ends.

options(tplyr.custom_summaries = 
          rlang::quos(
            mean = mean(.var, na.rm=TRUE, trim=0.4)
          )
        )

tplyr_table(adsl, TRT01P) %>% 
  add_layer(
    group_desc(AGE) %>% 
      set_format_strings("Mean" = f_str('xx.xx', mean))
  ) %>% 
  build() %>% 
  kable()

Note that the table code used to produce the output is the same. Now ‘Tplyr’ used the custom summary function for mean as specified in the tplyr.custom_summaries option. Also note the use of rlang::quos(). We’ve done our best to mask this from the user everywhere possible and make the interfaces clean and intuitive, but a great deal of ‘Tplyr’ is built using ‘rlang’ and non-standard evaluation. Within this option is one of the very few instances where a user needs to concern themselves with the use of quosures. If you’d like to learn more about non-standard evaluation and quosures, we recommend Section IV in Advanced R.

Formatting

A lot of the nuance to formatting descriptive statistics layers has already been covered above, but there are a couple more tricks to getting the most out of ‘Tplyr’. One of these tricks is filling empty values.

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

adlb_2 <- adlb %>% 
  filter(TRTA != "Placebo")

tplyr_table(adlb_2, TRTA) %>% 
  set_pop_data(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

adlb_2 <- adlb %>% 
  filter(TRTA != "Placebo")

tplyr_table(adlb_2, TRTA) %>% 
  set_pop_data(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.

adlb_2 <- adlb %>% 
  filter(TRTA != "Placebo")

tplyr_table(adlb_2, TRTA) %>% 
  set_pop_data(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.

tplyr_table(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) %>% 
  kable()

tplyr_table(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) %>% 
  kable()

tplyr_table(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() %>% 
  kable()