Basic Templates

The functions new_layer_template() and use_template() allow a user to create and use layer templates. Layer templates allow a user to pre-build and reuse an entire layer configuration, from the layer constructor down to all modifying functions. Furthermore, users can specify parameters they may want to be interchangeable. Additionally, layer templates are extensible, so a template can be use and then further extended with additional layer modifying functions.

Consider the following example:

new_layer_template(
  "example_template", 
  group_count(...) %>% 
    set_format_strings(f_str("xx (xx%)", n, pct))
)

In this example, we’ve created a basic layer template. The template is named “example_template”, and this is the name we’ll use to reference the template when we want to use it. When the template is created, we start with the function group_count(...). Note the use of the ellipsis (i.e. ...). This is a required part of a layer template. Templates must start with a Tplyr layer constructor, which is one of the function group_count(), group_desc(), or group_shift(). The ellipsis is necessary because when the template is used, we are able to pass arguments directly into the layer constructor. For example:

tplyr_table(tplyr_adsl, TRT01P) %>% 
  add_layer(
    use_template("example_template", RACE, by=ETHNIC)
  ) %>% 
  build() %>% 
  kable()

Within use_template(), the first parameter is the template name. After that, we supply arguments as we normally would into group_count(), group_desc(), or group_shift(). Additionally, note that our formats have been applied just as they would be if we used set_format_strings() as specified in the template. Our template was applied, the table built with all of the settings appropriately.

An additional feature of layer templates is that they act just as any other function would in a Tplyr layer. This means that they’re also extensible and can be expanded on directly within a Tplyr table. For example:

tplyr_table(tplyr_adsl, TRT01P) %>% 
  add_layer(
    use_template("example_template", RACE) %>% 
      add_total_row()
  ) %>% 
  build() %>% 
  kable()

Here we show two things - first, that the we called the template without the by variable argument from the previous example. This allows a template to have some flexibility depending on the context of its usage. Furthermore, we added the additional modifier function add_total_row(). In this example, we took the layer as constructed by the template and then modified that layer further. This may be useful if most but not all of a layer is reusable. The reusable portions can be put in a template, and the rest added using normal Tplyr syntax.

new_layer_template("example_params",
  group_count(...) %>% 
    set_format_strings(f_str("xx (xx.x%)", n, pct)) %>% 
    set_order_count_method({sort_meth}) %>% 
    set_ordering_cols({sort_col})
 )

tplyr_table(tplyr_adsl, TRT01P) %>% 
  add_layer(
    use_template('example_params', RACE, add_params = 
                   list(
                     sort_meth = "bycount",
                     sort_col = Placebo
                   ))
  ) %>% 
  build() %>% 
  kable()

Viewing and Removing Templates

If you want to view any available templates in your session, use the function get_layer_templates().

get_layer_templates()
#> $example_template
#> Template name: example_template
#> Template parameters: None
#> Template code:
#> {
#> group_count(...) %>% set_format_strings(f_str("xx (xx%)", n, pct))
#> } 
#> 
#> $example_params
#> Template name: example_params
#> Template parameters: sort_meth, sort_col
#> Template code:
#> {
#> group_count(...) %>% set_format_strings(f_str("xx (xx.x%)", n, pct)) %>% set_order_count_method({
#>     sort_meth
#> }) %>% set_ordering_cols({
#>     sort_col
#> })
#> }

You can view a specific template using get_layer_template().

get_layer_template("example_params")
#> Template name: example_params
#> Template parameters: sort_meth, sort_col
#> Template code:
#> {
#> group_count(...) %>% set_format_strings(f_str("xx (xx.x%)", n, pct)) %>% set_order_count_method({
#>     sort_meth
#> }) %>% set_ordering_cols({
#>     sort_col
#> })
#> }

Note that layer templates are of class tplyr_layer_template. They additionally carry the attribute params that specifies which parameters are available in the template, which can be seen in the output above.

Finally, if you want to remove a layer from your session, use the function remove_layer_template()

remove_layer_template("example_params")
get_layer_templates()
#> $example_template
#> Template name: example_template
#> Template parameters: None
#> Template code:
#> {
#> group_count(...) %>% set_format_strings(f_str("xx (xx%)", n, pct))
#> }