Title:	Applies Display Metadata to Analysis Results Datasets
Version:	0.1.3
Description:	Creates a framework to store and apply display metadata to Analysis Results Datasets (ARDs). The use of 'tfrmt' allows users to define table format and styling without the data, and later apply the format to the data.
Language:	en-GB
License:	Apache License (≥ 2)
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
Suggests:	covr, testthat (≥ 3.0.0), knitr, rmarkdown, patchwork, survival, ggfortify
Imports:	magrittr, dplyr, purrr, rlang, stringr, stringi, tidyr, gt (≥ 0.6.0), tidyselect, forcats, tibble, ggplot2, jsonlite, glue
Config/testthat/edition:	3
URL:	https://GSK-Biostatistics.github.io/tfrmt/, https://github.com/GSK-Biostatistics/tfrmt
BugReports:	https://github.com/GSK-Biostatistics/tfrmt/issues
Depends:	R (≥ 2.10)
NeedsCompilation:	no
Packaged:	2024-10-15 18:37:36 UTC; bkrouse
Author:	Becca Krouse [aut, cre], Christina Fillmore [aut], GlaxoSmithKline Research & Development Limited [cph, fnd], Atorus Research LLC [cph, fnd], Ellis Hughes [aut], Karima Ahmad [aut], Shannon Haughton [aut]
Maintainer:	Becca Krouse <becca.z.krouse@gsk.com>
Repository:	CRAN
Date/Publication:	2024-10-15 21:30:02 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Apply formatting

Description

Apply formatting

Usage

apply_frmt(frmt_def, .data, value, mock = FALSE, ...)

## S3 method for class 'frmt'
apply_frmt(frmt_def, .data, value, mock = FALSE, ...)

## S3 method for class 'frmt_combine'
apply_frmt(
  frmt_def,
  .data,
  value,
  mock = FALSE,
  param,
  column,
  label,
  group,
  ...
)

## S3 method for class 'frmt_when'
apply_frmt(frmt_def, .data, value, mock = FALSE, ...)

Arguments

Value

formatted dataset

Examples

library(tibble)
library(dplyr)
# Set up data
df <- tibble(x = c(20.12,34.54,12.34))

apply_frmt(
 frmt_def = frmt("XX.X"),
 .data=df,
 value=quo(x))

Convert tfrmt elements

Description

This collection of functions is used to create a json or json ready objects. While primarily intended for internal use these functions can be used externally

Usage

as_json(x)

Arguments

Value

as_json.tfrmt() will return a json object all other methods will return a list that is cleaned so it can be directly converted to a json object

Big N Structure

Description

Big N structure allows you to specify which values should become the subject totals ("big N" values) and how they should be formatted in the table's column labels. Values are specified by providing the value(s) of the param column for which the values are big N's. This will remove these from the body of the table and place them into columns matching the values in the column column(s). The default formatting is N = xx, on its own line, but that can be changed by providing a different frmt() to n_frmt

Usage

big_n_structure(param_val, n_frmt = frmt("\nN = xx"), by_page = FALSE)

Arguments

Value

big_n_structure object

See Also

Link to related article

Table Body Plan

Description

Define the formatting of the body contents of the table through a series of frmt_structures. Structures get applied in order from bottom up, so the last added structure is the first applied.

Usage

body_plan(...)

Arguments

Value

body_plan object

See Also

frmt_structure() defines which rows the formats will be applied to, and frmt(), frmt_combine(), and frmt_when() define the format semantics.

Link to related article

Examples

  tfrmt_spec<- tfrmt(
      title = "Table Title",
      body_plan = body_plan(
        frmt_structure(
          group_val = c("group1"),
          label_val = ".default",
          frmt("XXX")
        )
      )
     )

Do all the formatting for the GT

Description

Do all the formatting for the GT

Apply formatting to a list of tables

Apply formatting to a single table

Usage

cleaned_data_to_gt(.data, tfrmt, .unicode_ws)

## S3 method for class 'list'
cleaned_data_to_gt(.data, tfrmt, .unicode_ws)

## Default S3 method:
cleaned_data_to_gt(.data, tfrmt, .unicode_ws)

Arguments

Value

gt_group object

GT object

Define the Column Plan & Span Structures

Description

Using <tidy-select> expressions and a series span_structures, define the order of the columns. The selection follows "last selected" principals, meaning columns are moved to the last selection as opposed to preserving the first location.

Usage

col_plan(..., .drop = FALSE)

span_structure(...)

Arguments

Details

Column Selection

When col_plan gets applied and is used to create the output table, the underlying logic sorts out which column specifically is being selected. If a column is selected twice, the last instance in which the column is selected will be the location it gets rendered.

Avoid beginning the col_plan() column selection with a deselection (i.e. col_plan(-col1), col_plan(-starts_with("value"))). This will result in the table preserving all columns not "de-selected" in the statement, and the order of the columns not changed. It is preferred when creating the col_plan() to identify all the columns planned on preserving in the order they are wished to appear, or if <tidy-select> arguments - such as everything- are used, identify the de-selection after the positive-selection.

Alternatively, once the gt table is produced, use the cols_hide function to remove un-wanted columns.

Value

col_plan object

span_structure object

Images

Here are some example outputs:

See Also

Link to related article

Examples

library(dplyr)

## select col_1 as the first column, remove col_last, then create spanning
## structures that have multiple levels
##
## examples also assume the tfrmt has the column argument set to c(c1, c2, c3)
##
spanning_col_plan_ex <- col_plan(
 col_1,
 -col_last,
 span_structure(
   c1 = "Top Label Level 1",
   c2 = "Second Label Level 1.1",
   c3 = c(col_3, col_4)
 ),
 span_structure(
   c1 = "Top Label Level 1",
   c2 = "Second Label Level 1.2",
   c3 = starts_with("B")
   ),
 span_structure(
   c1 = "Top Label Level 1",
   c3 = col_5
 ),
 span_structure(
   c2 = "Top Label Level 2",
   c3 = c(col_6, col_7)
 )
)

## select my_col_1 as the first column, then
## rename col_2 to new_col_1 and put as the
## second column, then select the rest of the columns
renaming_col_plan_ex <- col_plan(
   my_col_1,
   new_col_1 = col_2,
   everything()
 )

renaming_col_plan_ex2 <- col_plan(
   my_col_1,
   new_col_1 = col_2,
   span_structure(
    c1 = c(`My Favorite span name` = "Top Label Level 1"),
    c3 = c(`the results column` = col_5)
   )
 )

Column Style Plan

Description

Define how the columns of the table body should be aligned, whether left, right or on a specific character(s).

Usage

col_style_plan(...)

Arguments

Value

col_style_plan object

See Also

col_style_structure() for more information on how to specify how to and which columns to align.

Link to related article

Examples

 plan <- col_style_plan(
    col_style_structure(col = "my_var", align = "left", width = 100),
    col_style_structure(col = vars(four), align = "right"),
    col_style_structure(col = vars(two, three), align = c(".", ",", " "))
   )

Column Style Structure

Description

Column Style Structure

Usage

col_style_structure(
  col,
  align = NULL,
  type = c("char", "pos"),
  width = NULL,
  ...
)

Arguments

Details

Supports alignment and width setting of data value columns (values found in the column column). Row group and label columns are left-aligned by default. Acceptable input values for align differ by type = "char" or "pos":

Character alignment (type = "char"):

• "left" for left alignment

• "right" for right alignment"

• supply a vector of character(s) to align on. If more than one character is provided, alignment will be based on the first occurrence of any of the characters. For alignment based on white space, leading white spaces will be ignored.

Positional alignment (type = "pos"):

supply a vector of strings covering all formatted cell values, with numeric values represented as x's. These values can be created manually or obtained by utilizing the helper display_val_frmts(). Alignment positions will be represented by vertical bars. For example, with starting values: c("12.3", "(5%)", "2.35 (10.23)") we can align all of the first sets of decimals and parentheses by providing align = c("xx|.x", "||(x%)", "x|.xx |")

Value

col_style_structure object

See Also

col_style_plan() for more information on how to combine col_style_structure()'s together to form a plan.

Link to related article

Examples

 plan <- col_style_plan(
    col_style_structure(col = "my_var",
                        align = c("xx| |(xx%)",
                                  "xx|.x |(xx.x - xx.x)"),
                        type = "pos", width = 100),
    col_style_structure(col = vars(four), align = "right", width = 200),
    col_style_structure(col = vars(two, three), align = c(".", ",", " ")),
    col_style_structure(col = c(two, three), width = 25),
    col_style_structure(col = two, width = 25),
    col_style_structure(col = span_structure(span = value, col = val2),
                        width = 25)
   )

Adverse Events Analysis Results Data

Description

A dataset containing the results needed for an AE table. Using the CDISC pilot data.

Usage

data_ae

Format

A data frame with 2,794 rows and 8 variables:

AEBODSYS

highest level row labels: System Organ Class

AETERM

more specific row labels: Preferred Term

col2

higher level column names (spanners)

col1

lower level column names

param

parameter to explain each value

value

values to put in a table

ord1

controls ordering

ord2

more ordering controls

Demography Analysis Results Data

Description

A dataset containing the results needed for a demography table. Using the CDISC pilot data.

Usage

data_demog

Format

A data frame with 386 rows and 7 variables:

rowlbl1

highest level row labels

rowlbl2

more specific row labels

param

parameter to explain each value

grp

grouping column used to distinguish continuous and categorical

ord1

controls ordering

ord2

more ordering controls

column

column names

value

values to put in a table

Efficacy Analysis Results Data

Description

A dataset containing the results needed for an Efficacy table. Using the CDISC pilot data for ADAS-Cog(11).

Usage

data_efficacy

Format

A data frame with 70 rows and 7 variables:

group

highest level row labels

label

more specific row labels

column

column names

param

parameter to explain each value

value

values to put in a table

ord1

controls ordering

ord2

more ordering controls

Labs Analysis Results Data

Description

A dataset containing the results needed for an labs results table. Using the CDISC pilot data.

Usage

data_labs

Format

A data frame with 4,950 rows and 7 variables:

group1

highest level row labels: Lab value class

group2

more specific row labels: Lab parameter

rowlbl

most specific row labels: Study visit

col1

higher level column names (spanners)

col2

lower level column names

param

parameter to explain each value

value

values to put in a table

ord1

controls ordering

ord2

more ordering controls

ord3

more ordering controls

Display formatting applied to each row

Description

Used when debugging formatting, it is an easy way to allow you to see which formats are applied to each row in your dataset.

Used when debugging formatting, it is an easy way to allow you to see which formats are applied to each row in your dataset.

Usage

display_row_frmts(tfrmt, .data, convert_to_txt = TRUE)

display_row_frmts(tfrmt, .data, convert_to_txt = TRUE)

Arguments

Value

formatted tibble

formatted tibble

Examples

 library(dplyr)
 library(tidyr)

 tfrmt_spec <- tfrmt(
 label = label,
 column = column,
 param = param,
 value=value,
 body_plan = body_plan(
   frmt_structure(group_val = ".default", label_val = ".default",
                  frmt_combine(
                    "{count} {percent}",
                    count = frmt("xxx"),
                    percent = frmt_when("==100"~ frmt(""),
                                        "==0"~ "",
                                        "TRUE" ~ frmt("(xx.x%)"))))
 ))

 # Create data
 df <- crossing(label = c("label 1", "label 2"),
                column = c("placebo", "trt1"),
                param = c("count", "percent")) %>%
   mutate(value=c(24,19,2400/48,1900/38,5,1,500/48,100/38))

 display_row_frmts(tfrmt_spec,df)
 library(dplyr)
 library(tidyr)

 tfrmt_spec <- tfrmt(
 label = label,
 column = column,
 param = param,
 value=value,
 body_plan = body_plan(
   frmt_structure(group_val = ".default", label_val = ".default",
                  frmt_combine(
                    "{count} {percent}",
                    count = frmt("xxx"),
                    percent = frmt_when("==100"~ frmt(""),
                                        "==0"~ "",
                                        "TRUE" ~ frmt("(xx.x%)"))))
 ))

 # Create data
 df <- crossing(label = c("label 1", "label 2"),
                column = c("placebo", "trt1"),
                param = c("count", "percent")) %>%
   mutate(value=c(24,19,2400/48,1900/38,5,1,500/48,100/38))

 display_row_frmts(tfrmt_spec,df)

Display formatted values

Description

A helper for creating positional-alignment specifications for the col_style_plan. Returns all unique formatted values to appear in the column(s) specified. Numeric values are represented by x's.

Usage

display_val_frmts(tfrmt, .data, mock = FALSE, col = NULL)

Arguments

Value

text representing character vector of formatted values to be copied and modified in the col_style_plan

Examples

 tf_spec <- tfrmt(
 group = c(rowlbl1,grp),
 label = rowlbl2,
 column = column,
 param = param,
 value = value,
 sorting_cols = c(ord1, ord2),
 body_plan = body_plan(
 frmt_structure(group_val = ".default", label_val = ".default", frmt_combine("{n} ({pct} %)",
                                                                             n = frmt("xxx"),
                                                                             pct = frmt("xx.x"))),
 frmt_structure(group_val = ".default", label_val = "n", frmt("xxx")),
 frmt_structure(group_val = ".default", label_val = c("Mean", "Median", "Min","Max"),
                             frmt("xxx.x")),
 frmt_structure(group_val = ".default", label_val = "SD", frmt("xxx.xx")),
 frmt_structure(group_val = ".default", label_val = ".default",
                            p = frmt_when(">0.99" ~ ">0.99",
                                          "<0.15" ~ "<0.15",
                                          TRUE ~ frmt("x.xxx", missing = "")))
))

 display_val_frmts(tf_spec, data_demog, col = vars(everything()))
 display_val_frmts(tf_spec, data_demog, col = "p-value")

Element block

Description

Element block

Usage

element_block(post_space = c(NULL, " ", "-"), fill = TRUE)

Arguments

Value

element block object

See Also

row_grp_plan() for more details on how to group row group structures, row_grp_structure() for more details on how to specify row group structures, element_row_grp_loc() for more details on how to specify whether row group titles span the entire table or collapse.

Examples

tfrmt_spec <- tfrmt(
  group = grp1,
  label = label,
  param = param,
  value = value,
  column = column,
  row_grp_plan = row_grp_plan(
    row_grp_structure(group_val = ".default", element_block(post_space = "   "))
  ),
  body_plan = body_plan(
    frmt_structure(group_val = ".default", label_val = ".default", frmt("xx"))
  )
)

Element Row Group Location

Description

Element Row Group Location

Usage

element_row_grp_loc(
  location = c("indented", "spanning", "column", "noprint", "gtdefault"),
  indent = "  "
)

Arguments

Value

element_row_grp_loc object

Images

Here are some example outputs:

See Also

row_grp_plan() for more details on how to group row group structures, row_grp_structure() for more details on how to specify row group structures, element_block() for more details on how to specify spacing between each group.

Link to related article

Examples

tfrmt_spec <- tfrmt(
  group = c(grp1, grp2),
  label = label,
  param = param,
  value = value,
  column = column,
  row_grp_plan = row_grp_plan(label_loc = element_row_grp_loc(location = "noprint")),
  body_plan = body_plan(
    frmt_structure(group_val = ".default", label_val = ".default", frmt("xx"))
  )
)

Footnote Plan

Description

Defining the location and content of footnotes with a series of footnote structures. Each structure is a footnote and can be applied in multiple locations.

Usage

footnote_plan(..., marks = c("numbers", "letters", "standard", "extended"))

Arguments

Value

footnote plan object

Examples

# Adds a footnote indicated by letters rather than numbers to Group 1
footnote_plan <- footnote_plan(
    footnote_structure(footnote_text = "Source Note", group_val = "Group 1"),
    marks="letters")

# Adds a footnote to the 'Placebo' column
footnote_plan <- footnote_plan(
    footnote_structure(footnote_text = "footnote", column_val = "Placebo"),
    marks="numbers")

Footnote Structure

Description

Footnote Structure

Usage

footnote_structure(
  footnote_text,
  column_val = NULL,
  group_val = NULL,
  label_val = NULL
)

Arguments

Value

footnote structure object

Examples

# Adds a source note aka a footnote without a symbol in the table
footnote_structure <- footnote_structure(footnote_text = "Source Note")

# Adds a footnote to the 'Placebo' column
footnote_structure <- footnote_structure(footnote_text = "Text",
                               column_val = "Placebo")

# Adds a footnote to either 'Placebo' or 'Treatment groups' depending on which
# which is last to appear in the column vector
footnote_structure <- footnote_structure(footnote_text = "Text",
      column_val = list(col1 = "Placebo", col2= "Treatment groups"))

# Adds a footnote to the 'Adverse Event' label
footnote_structure <- footnote_structure("Text", label_val = "Adverse Event")

Table Value Formatting

Description

These functions provide an abstracted way to approach to define formatting of table contents. By defining in this way, the formats can be layered to be more specific and general cell styling can be done first.

frmt() is the base definition of a format. This defines spacing, rounding, and missing behaviour.

frmt_combine() is used when two or more rows need to be combined into a single cell in the table. Each of the rows needs to have a defined frmt() and need to share a label.

frmt_when() is used when a rows format behaviour is dependent on the value itself and is written similarly to dplyr::case_when(). The left hand side of the equation is a "TRUE"for the default case or the right hand side of a boolean expression ">50".

Usage

frmt(expression, missing = NULL, scientific = NULL, transform = NULL, ...)

frmt_combine(expression, ..., missing = NULL)

frmt_when(..., missing = NULL)

Arguments

Details

expression

• frmt() All numbers are represented by "x". Any additional character are printed as-is. If additional X's present to the left of the decimal point than the value, they will be represented as spaces.

• frmt_combine() defines how the parameters will be combined as a glue::glue() statement. Parameters need to be equal to the values in the param column and defined in the expression as "{param1} {param2}".

missing

• frmt() Value to enter when the value is missing. When NULL, the value is "".

• frmt_combine() defines how when all values to be combined are missing. When NULL the value is "".

...

• frmt() These dots are for future extensions and must be empty.

• frmt_combine() accepts named arguments defining the frmt() to be applied to which parameters before being combined.

• frmt_when()accepts a series of equations separated by commas, similar to dplyr::case_when(). The left hand side of the equation is a "TRUE"for the default case or the right hand side of a boolean expression ">50". The right hand side of the equation is the frmt() to apply when the left side evaluates to TRUE.

Value

frmt object

See Also

body_plan() combines the frmt_structures to be applied to the table body, and frmt_structure() defines which rows the formats will be applied to.

Link to related article

Examples

frmt("XXX %")

frmt("XX.XXX")

frmt("xx.xx", scientific = "x10^xx")

frmt_combine(
 "{param1} {param2}",
 param1 = frmt("XXX %"),
 param2 = frmt("XX.XXX")
)

frmt_when(
  ">3" ~ frmt("(X.X%)"),
  "<=3" ~ frmt("Undetectable")
  )

frmt_when(
  "==100"~ frmt(""),
  "==0"~ "",
  "TRUE" ~ frmt("(XXX.X%)")
  )

Format Structure Object

Description

Function needed to create a frmt_structure object, which is a building block of body_plan(). This specifies the rows the format will be applied to.

Usage

frmt_structure(group_val = ".default", label_val = ".default", ...)

Arguments

Value

frmt_structure object

Images

Here are some example outputs:

See Also

body_plan() combines the frmt_structures to be applied to the table body, and frmt(), frmt_combine(), and frmt_when() define the format semantics.

Link to related article

Examples

sample_structure <- frmt_structure(
          group_val = c("group1"),
          label_val = ".default",
          frmt("XXX")
        )
## multiple group columns
sample_structure <- frmt_structure(
          group_val = list(grp_col1 = "group1", grp_col2 = "subgroup3"),
          label_val = ".default",
          frmt("XXX")
        )

Check if input is a frmt

Description

Check if input is a frmt

Check if input is a frmt_combine

Check if input is a frmt_when

Check if input is a frmt_structure

Check if input is a row_grp_structure

Usage

is_frmt(x)

is_frmt_combine(x)

is_frmt_when(x)

is_frmt_structure(x)

is_row_grp_structure(x)

Arguments

Value

'TRUE' if yes, 'FALSE' if no

Examples

x1 <- frmt("XXX.XX")
is_frmt(x1)

x2 <- frmt_combine("XXX %","XX,XXX")
is_frmt_combine(x2)

x2 <- frmt_when(
">3" ~ frmt("(X.X%)"),
"<=3" ~ frmt("Undetectable")
)
is_frmt_when(x2)

x3 <- frmt_structure(
 group_val = c("group1"),
 label_val = ".default",
frmt("XXX")
)
is_frmt_structure(x3)

x4 <- row_grp_structure(group_val = c("A","C"), element_block(post_space = "---"))
is_row_grp_structure(x4)

json to tfrmt

Description

Reader to read JSON files/objects into tfrmt objects

Usage

json_to_tfrmt(path = NULL, json = NULL)

Arguments

Layer tfrmt objects together

Description

Provide utility for layering tfrmt objects together. If both tfrmt's have values, it will preferentially choose the second tfrmt by default. This is an alternative to piping together tfrmt's

Usage

layer_tfrmt(x, y, ..., join_body_plans = TRUE)

Arguments

Details

join_body_plan

When combining two body_plans, the body plans will stack together, first the body plan from x tfrmt then y tfrmt. This means that frmt_structures in y will take priority over those in x.

Combining two tfrmt with large body_plans can lead to slow table evaluation. Consider setting join_body_plan to FALSE. Only the y body_plan will be preserved.

Value

tfrmt object

Examples

tfrmt_1 <- tfrmt(title = "title1")

tfrmt_2 <- tfrmt(title = "title2",subtitle = "subtitle2")

layered_table_format <- layer_tfrmt(tfrmt_1, tfrmt_2)

Make mock data for display shells

Description

Make mock data for display shells

Usage

make_mock_data(tfrmt, .default = 1:3, n_cols = NULL)

Arguments

Value

tibble containing mock data

Examples

tfrmt_spec <- tfrmt(
  label = label,
  column = column,
  param = param,
  value=value,
  body_plan = body_plan(
    frmt_structure(group_val=".default", label_val=".default", frmt("xx.x"))
    )
  )

make_mock_data(tfrmt_spec)

Page Plan

Description

Defining the location and/or frequency of page splits with a series of page_structure's and the row_every_n argument, respectively.

Usage

page_plan(
  ...,
  note_loc = c("noprint", "preheader", "subtitle", "source_note"),
  max_rows = NULL
)

Arguments

Value

page_plan object

Examples

 # use of page_struct
 page_plan(
    page_structure(group_val = "grp1", label_val = "lbl1")
 )

 # use of #  rows
 page_plan(
    max_rows = 5
 )

Page structure

Description

Page structure

Usage

page_structure(group_val = NULL, label_val = NULL)

Arguments

Value

page structure object

Examples

# split page after every unique level of the grouping variable
 page_structure(group_val = ".default", label_val = NULL)

 # split page after specific levels
 page_structure(group_val = "grp1", label_val = "lbl3")

Set custom parameter-level significant digits rounding

Description

Set custom parameter-level significant digits rounding

Usage

param_set(...)

Arguments

Details

Type param_set() in console to view package defaults. Use of the function will add to the defaults and/or override included defaults of the same name. For values that are integers, use NA so no decimal places will be added.

Value

list of default parameter-level significant digits rounding

Examples

# View included defaults
param_set()

# Update the defaults
param_set("{mean} ({sd})" = c(2,3), "pct" = 1)

# Separate mean and SD to different lines
param_set("mean" = 2, "sd" = 3)

# Add formatting using the glue syntax
param_set("{pct} %" = 1)

Print mock table to GT

Description

Print mock table to GT

Usage

print_mock_gt(
  tfrmt,
  .data = NULL,
  .default = 1:3,
  n_cols = NULL,
  .unicode_ws = TRUE
)

Arguments

Value

a stylized gt object

Examples

  # Create tfrmt specification
  tfrmt_spec <- tfrmt( label = label, column =
  column, param = param, body_plan = body_plan( frmt_structure(group_val =
  ".default", label_val = ".default", frmt_combine( "{count} {percent}",
  count = frmt("xxx"), percent = frmt_when("==100"~ frmt(""), "==0"~ "",
  "TRUE" ~ frmt("(xx.x%)")))) ))

  # Print mock table using default
  print_mock_gt(tfrmt = tfrmt_spec)

  # Create mock data
  df <- crossing(label = c("label 1", "label 2",
  "label 3"), column = c("placebo", "trt1", "trt2"), param = c("count",
  "percent"))

  # Print mock table using mock data
  print_mock_gt(tfrmt_spec, df)

Print to ggplot

Description

Print to ggplot

Usage

print_to_ggplot(tfrmt, .data, ...)

Arguments

Value

a stylized ggplot object

Examples

# Create data
risk<-tibble(time=c(rep(c(0,1000,2000,3000),3)),
            label=c(rep("Obs",4),rep("Lev",4),rep("Lev+5FU",4)),
            value=c(630,372,256,11,620,360,266,8,608,425,328,14),
            param=rep("n",12))

table<-tfrmt(
 label = label ,
 column = time,
 param = param,
 value = value) %>%
  print_to_ggplot(risk)

table

Print to gt

Description

Print to gt

Usage

print_to_gt(tfrmt, .data, .unicode_ws = TRUE)

Arguments

Value

a stylized gt object

Examples

library(dplyr)
# Create tfrmt specification
tfrmt_spec <- tfrmt(
  label = label,
  column = column,
  param = param,
  value=value,
  body_plan = body_plan(
    frmt_structure(group_val = ".default", label_val = ".default",
                   frmt_combine(
                     "{count} {percent}",
                     count = frmt("xxx"),
                     percent = frmt_when("==100"~ frmt(""),
                                         "==0"~ "",
                                         "TRUE" ~ frmt("(xx.x%)"))))
  ))

# Create data
df <- crossing(label = c("label 1", "label 2"),
               column = c("placebo", "trt1"),
               param = c("count", "percent")) %>%
      mutate(value=c(24,19,2400/48,1900/38,5,1,500/48,100/38))

print_to_gt(tfrmt_spec,df)

Row Group Plan

Description

Define the look of the table groups on the output. This function allows you to add spaces after blocks and allows you to control how the groups are viewed whether they span the entire table or are nested as a column.

Usage

row_grp_plan(..., label_loc = element_row_grp_loc(location = "indented"))

Arguments

Value

row_grp_plan object

See Also

row_grp_structure() for more details on how to specify row group structures, element_block() for more details on how to specify spacing between each group, element_row_grp_loc() for more details on how to specify whether row group titles span the entire table or collapse.

Link to related article

Examples

  ## single grouping variable example
  sample_grp_plan <- row_grp_plan(
    row_grp_structure(group_val = c("A","C"), element_block(post_space = "---")),
    row_grp_structure(group_val = c("B"), element_block(post_space = " ")),
    label_loc = element_row_grp_loc(location = "column")
  )

  ## example with multiple grouping variables
  sample_grp_plan <- row_grp_plan(
     row_grp_structure(group_val = list(grp1 = "A", grp2 = "b"), element_block(post_space = " ")),
     label_loc = element_row_grp_loc(location = "spanning")
     )

Row Group Structure Object

Description

Function needed to create a row_grp_structure object, which is a building block of row_grp_plan()

Usage

row_grp_structure(group_val = ".default", element_block)

Arguments

Value

row_grp_structure object

See Also

row_grp_plan() for more details on how to group row group structures, element_block() for more details on how to specify spacing between each group.

Link to related article

Examples

## single grouping variable example
row_grp_structure(group_val = c("A","C"), element_block(post_space = "---"))

## example with multiple grouping variables
row_grp_structure(group_val = list(grp1 = "A", grp2 = "b"), element_block(post_space = " "))

Table Format

Description

tfrmt, or "table format" is a way to pre-define the non-data components of your tables, and how the data will be handled once added: i.e. title, footers, headers, span headers, and cell formats. In addition, tfrmt's can be layered, building from one table format to the next. For cases where only one value can be used, the newly defined tfrmt accepts the latest tfrmt

Usage

tfrmt(
  tfrmt_obj,
  group = vars(),
  label = quo(),
  param = quo(),
  value = quo(),
  column = vars(),
  title,
  subtitle,
  row_grp_plan,
  body_plan,
  col_style_plan,
  col_plan,
  sorting_cols,
  big_n,
  footnote_plan,
  page_plan,
  ...
)

Arguments

Details

NSE and Argument Evaluation

• tfrmt allows users to pass vars, quo, and unquoted expressions to a variety of arguments, such as group, label, param, value, column, and sorting_cols. Users accustomed to tidyverse semantics should be familiar with this behaviour. However, there is an important behaviour difference between tfrmt and normal tidyverse functions. Because the data are not a part of tfrmt, it does not know when a value being passed to it is intended to be an unquoted expression representing a column name or an object from the environment. As such, it preferentially uses the value from the environment over preserving the entry as an expression. For example, if you have an object "my_object" in your environment with the value "Hello world", and try to create a tfrmt as tfrmt(column = my_object), it will take the value of "my_object" over assuming the column argument is an unquoted expression and view the entry to column as "Hello World". To pass "my_object" to tfrmt as a column name, use quotes around the value: tfrmt(columnn = "my_object").

• Additionally, unquoted expressions that match tfrmt's other argument names can cause unexpected results. It is recommended to put quotes around the value as such: tfrmt(label = "group"). In this case, the quoting will prevent tfrmt from assigning its group input value to the label value.

Value

tfrmt object

Images

Here are some example outputs:

See Also

Link to related article

Examples

tfrmt_spec <- tfrmt(
  label = label,
  column = column,
  param = param,
  value=value)

tfrmt_spec <- tfrmt(
  label = label,
  column = column,
  param = param,
  value=value,
# Set the formatting for values
  body_plan = body_plan(
    frmt_structure(
      group_val = ".default",
      label_val = ".default",
      frmt_combine("{n} {pct}",
           n = frmt("xxx"),
           pct = frmt_when(
                "==100" ~ "(100%)",
                "==0" ~ "",
                TRUE ~ frmt("(xx.x %)")
                )
           )
    )
  ),
# Specify column styling plan
  col_style_plan = col_style_plan(
    col_style_structure(col = vars(everything()), align = c(".",","," "))
  ))

tfrmt_spec <- tfrmt(
  group = group,
  label = label,
  column = column,
  param = param,
  value=value,
  sorting_cols = c(ord1, ord2),
  # specify value formatting
  body_plan = body_plan(
    frmt_structure(
      group_val = ".default",
      label_val = ".default",
      frmt_combine("{n} {pct}",
           n = frmt("xxx"),
           pct = frmt_when(
                "==100" ~ "(100%)",
                "==0" ~ "",
                TRUE ~ frmt("(xx.x %)")
                )
           )
    ),
    frmt_structure(
        group_val = ".default",
        label_val = "n",
        frmt("xxx")
   ),
    frmt_structure(
        group_val = ".default",
        label_val = c("Mean", "Median", "Min","Max"),
        frmt("xxx.x")
     ),
    frmt_structure(
        group_val = ".default",
        label_val = "SD",
        frmt("xxx.xx")
    ),
    frmt_structure(
        group_val = ".default",
        label_val = ".default",
        p = frmt("")
    ),
    frmt_structure(
        group_val = ".default",
        label_val = c("n","<65 yrs","<12 months","<25"),
        p = frmt_when(
            ">0.99" ~ ">0.99",
            "<0.001" ~ "<0.001",
            TRUE ~ frmt("x.xxx", missing = "")
        )
    )
  ),
  # remove extra cols
  col_plan = col_plan(-grp,
                      -starts_with("ord") ),
  # Specify column styling plan
  col_style_plan = col_style_plan(
    col_style_structure(col = vars(everything()), align = c(".",","," "))
  ),

  # Specify row group plan
  row_grp_plan = row_grp_plan(
    row_grp_structure(
         group_val = ".default",
         element_block(post_space = " ")
    ),
    label_loc = element_row_grp_loc(location = "column")
  )

)

N Percent Template

Description

This function creates an tfrmt for an n % table, so count based table. The parameter values for n and percent can be provided (by default it will assume n and pct). Additionally the frmt_when for formatting the percent can be specified. By default 100% and 0% will not appear and everything between 99% and 100% and 0% and 1% will be rounded using greater than (>) and less than (<) signs respectively.

Usage

tfrmt_n_pct(
  n = "n",
  pct = "pct",
  pct_frmt_when = frmt_when("==100" ~ frmt(""), ">99" ~ frmt("(>99%)"), "==0" ~ "", "<1"
    ~ frmt("(<1%)"), "TRUE" ~ frmt("(xx.x%)")),
  tfrmt_obj = NULL
)

Arguments

Value

tfrmt object

Examples

print_mock_gt(tfrmt_n_pct())

Create tfrmt object from significant digits spec

Description

This function creates a tfrmt based on significant digits specifications for group/label values. The input data spec provided to sigdig_df will contain group/label value specifications. tfrmt_sigdig assumes that these columns are group columns unless otherwise specified. The user may optionally choose to pass the names of the group and/or label columns as arguments to the function.

Usage

tfrmt_sigdig(
  sigdig_df,
  group = vars(),
  label = quo(),
  param_defaults = param_set(),
  missing = NULL,
  tfrmt_obj = NULL,
  ...
)

Arguments

Details

Formats covered

Currently covers specifications for frmt and frmt_combine. frmt_when not supported and must be supplied in additional tfrmt that is layered on.

Group/label variables

If the group/label variables are not provided to the arguments, the body_plan will be constructed from the input data with the following behaviour:

• If no group or label are supplied, it will be assumed that all columns in the input data are group columns.

• If a label variable is provided, but nothing is specified for group, any leftover columns (i.e. not matching sigdig or the supplied label variable name) in the input data will be assumed to be group columns.

• If any group variable is provided, any leftover columns (i.e. not matching sigdig or the supplied group/label variable) will be disregarded.

Value

tfrmt object with a body_plan constructed based on the significant digits data spec and param-level significant digits defaults.

Examples

sig_input <- tibble::tribble(
  ~group1,   ~group2, ~sigdig,
  "CHEMISTRY",   ".default", 3,
  "CHEMISTRY",   "ALBUMIN",  1,
  "CHEMISTRY",   "CALCIUM",   1,
  ".default",    ".default",  2
)

# Subset data for the example
data <- dplyr::filter(data_labs, group2 == "BASOPHILS", col1 %in% c("Placebo", "Xanomeline Low Dose"))
tfrmt_sigdig(sigdig_df = sig_input,
             group = vars(group1, group2),
             label = rowlbl,
             param_defaults = param_set("[{n}]" = NA)) %>%
  tfrmt(column = vars(col1, col2),
        param = param,
        value = value,
        sorting_cols = vars(ord1, ord2, ord3),
        col_plan = col_plan(-starts_with("ord"))) %>%
  print_to_gt(.data = data)

Print to JSON

Description

Print to JSON

Usage

tfrmt_to_json(tfrmt, path = NULL)

Arguments

Value

JSON

Examples

tfrmt(
  label = label,
  column = column,
  param = param,
  value=value) %>%
  tfrmt_to_json()

Remap group values in a tfrmt

Description

Remap group values in a tfrmt

Usage

update_group(tfrmt, ...)

Arguments

Value

A tfrmt with the group variables updated in all places

tfrmt object with updated groups#'

Examples

tfrmt_spec <- tfrmt(
    group = c(group1, group2),
    body_plan  = body_plan(
      frmt_structure(
         group_val = list(group2 = "value"),
         label_val = ".default",
         frmt("XXX")
         ),
     frmt_structure(
         group_val = list(group1 = "value", group2 = "value"),
         label_val = ".default",
         frmt("XXX")
       )
    ))

tfrmt_spec %>%
  update_group(New_Group = group1)