formatTable_Simcyp: Format tables according to Simcyp Consultancy Team...

In shirewoman2/Consultancy: Standardized tools for using R within the Simcyp Consultancy Team

Format tables according to Simcyp Consultancy Team specifications

Description

formatTable_Simcyp makes a nicely formatted table from a data.frame or tibble. It was primarily designed to work with output from pk_table and pk_table, so, by default, it formats tables so that the column headings and the first column are bold, and the second through the last columns are centered. Column headings with, e.g., "AUCinf" or "Cmax" will have the "inf" or the "max" subscripted, and the table will automatically expand to fit the contents. You can save the output to a Word file with the argument save_table.

Usage

formatTable_Simcyp(
  DF,
  shading_column,
  merge_shaded_cells = TRUE,
  merge_columns = NA,
  sort_column,
  bold_cells = list(c(0, NA), c(NA, 1)),
  center_1st_column = FALSE,
  column_widths = NA,
  include_header = TRUE,
  add_header_for_DDI = TRUE,
  perpetrator_name = "perpetrator",
  prettify_columns = FALSE,
  highlight_gmr_colors = NA,
  highlight_so_cutoffs = NA,
  highlight_so_colors = "yellow to red",
  highlight_cells = NA,
  highlight_color = "yellow",
  font = "Arial",
  fontsize = 11,
  borders = TRUE,
  save_table = NA,
  page_orientation = "portrait",
  title_document = NA,
  table_caption = NA
)

Arguments

DF	a data.frame or a flextable, usually output from pk_table or pk_table
shading_column	If you would like to alternate the shading of the rows in the output table, supply here the unquoted name of the column to check for when to change the shading; every time that column's value changes, the shading will alternate between white and light gray. For example, if you have a table with PK values for multiple files and you have more than one row per file (an example of this would be the output from the function pk_table), setting shading_column = File will cause the shading of the rows to alternate between white and light gray whenever the file changes. Please see the examples at the bottom of this help file.
merge_shaded_cells	TRUE (default) or FALSE for whether to merge the cells that have the same shade. This only applies when one of the columns in the input data.frame is used for deciding when to alternate shading, that is, shading_column has a value.
merge_columns	a vector of quoted column names or of numeric column positions that should be merged vertically whenever the values are the same. For example, merge_columns = c("File", "Tissue") will cause the cells in the columns "File" and "Tissue" to merge vertically whenever the same value shows up in consecutive rows. Similarly, merge_columns = c(1, 3, 5) will merge vertically the 1st, 3rd, and 5th columns whenever the values are the same. Note: This is different from most other functions in the SimcypConsultancy package, which require unquoted column names. Honestly, we just don't know how code things for you to supply a variable number of unquoted column names for a single argument; we've just hit a coding knowledge limitation here!
sort_column	optionally specify a column to sort by. If none are supplied, the table will not be sorted. If you would like to sort by more than one column, we recommend sorting before using this function, e.g., MyPKTable <- MyPKTable %>% arrange(Study, Dose) to sort by the column "Study" and then by the column "Dose" and then supply "MyPKTable" to formatTable_Simcyp. (This is just an example; your table must include those two columns for that to work.)
bold_cells	optionally specify cells in the table to be in bold-face text with a numeric vector where the 1st number is the row number and the 2nd number is the column number (just like regular row and column specifications in R). For example, bold_cells = c(1, 2) will make the cell in row 1 and column 2 bold face. Use "0" for the row number if you want to use bold face for something in the header row, and use NA in place of a row or column number to make everything in that row or column bold face. If you want to specify multiple places to use bold face, use a list of numeric vectors. By default, the header row and the 1st column will be bold. Set bold_cells = NA to make nothing bold. Please see the examples at the bottom of the help file.
center_1st_column	TRUE or FALSE (default) for whether to make the alignment of the first column centered
column_widths	optionally specify what the widths of the columns should be with a numeric vector of the widths in inches, e.g., column_widths = c(1.5, 2, 0.5, 3)
include_header	TRUE (default) or FALSE for whether to include the header row
add_header_for_DDI	TRUE (default) or FALSE for whether to add an extra header row to the top of your table denoting when the PK are for baseline, with a perpetrator, or are the geometric mean ratios.
perpetrator_name	the name of any perpetrator that is included in a PK table. This is only used when add_header_for_DDI is TRUE. It looks for the name of the perpetrator you specify and uses that in the top, extra row where the table is labeled as being the PK at baseline, with your perpetrator, or GMRs. If we don't know what the perpetrator drug name is, it's really hard to do that just right.
prettify_columns	TRUE (default) or FALSE for whether to make easily human-readable column names for any columns with PK parameters. TRUE makes pretty column names such as "Dose 1 AUCinf (h*ng/mL)" whereas FALSE leaves the column with the R-friendly name from extractPK, e.g., "AUCinf_dose1".
highlight_gmr_colors	optionally specify a set of colors to use for highlighting geometric mean ratios for DDIs. Options are "yellow to red", "green to red", "traffic" (a more vivid version of "green to red"), or a vector of 4 colors of your choosing. If left as NA, no highlighting for GMR level will be done.
highlight_so_cutoffs	optionally specify cutoffs for highlighting any simulated-to-observed ratios. Anything that is above those values or below the inverse of those values will be highlighted. To figure out what cells to highlight, this looks for a column titled "Statistic" or "Stat", then looks for what row contains "S/O" or "simulated (something something) observed" (as in, we'll use some wildcards to try to match your specific text). Next, it looks for any values in that same row that are above those cutoffs. This overrides anything else you specified for highlighting. The default is NA, for not highlighting based on S/O value. Acceptable input for, say, highlighting values that are > 125% or < 80% of the observed and also, with a second color, values that are > 150% or < 66% would be: highlight_so_cutoffs = c(1.25, 1.5). If you would like the middle range of values to be highlighted, include 1 in your cutoffs. For example, say you would like everything that's < 80% or > 125% to be highlighted red but you'd like the "good" values from 80% to 125% to be green, you can get that by specifying highlight_so_cutoffs = c(1, 1.25) and highlight_so_colors = c("green", "red")
highlight_so_colors	optionally specify a set of colors to use for highlighting S/O values outside the limits you specified with highlight_so_cutoffs. Options: "yellow to red" (default) A range of light yellow to light orange to light red. If you have included 1 in your cutoffs, values in the middle, the "good" range of S/O values around 1 will be highlighted a light green. "traffic" light green, yellow, and red designed to display values outside 1.25, 1.5, and 2 fold of unity, respectively. If you include 1 in highlight_so_cutoffs, you'll get a darker green for "good" S/O values. This color scheme was borrowed from Lisa, so if you've seen her slides, these will look familiar. a character vector of specific colors Any R-acceptable colors, will work here, e.g., highlight_so_colors = c("yellow", "orange", "red") . If you do specify your own bespoke colors, you'll need to make sure that you supply one color for every value in highlight_so_cutoffs.
highlight_cells	optionally specify cells in the table to be highlighted with a numeric vector where the 1st number is the row number and the 2nd number is the column number (just like regular row and column specifications in R). For example, highlight_cells = c(1, 2) will make the cell in row 1 and column 2 highlighted. Use "0" for the row number if you want to highlight something in the header row, and use NA in place of a row or column number to highlight everything in that row or column. If you want to specify multiple places to highlight, use a list of numeric vectors. Please see the examples at the bottom of the help file.
highlight_color	color to use for highlighting; default is yellow. Color can be specified using any R-friendly color name or hex code, e.g., "red" or "#D8212D".
font	font to use. Default is "Arial" and any fonts available on your machine in either Word or PowerPoint should be acceptable. If you get Times New Roman in your table when you asked for something else, it means that that font isn't available or maybe wasn't spelled the way R is expecting it. For example, "Calibri" works but "Calibri (Body)" doesn't even though the latter is listed in PowerPoint and Word.
fontsize	the numeric font size for the output table. Default is 11 point.
borders	TRUE (default) or FALSE for whether to include borders around cells
save_table	optionally save the output table by supplying a file name in quotes here, e.g., "My nicely formatted table.docx". Do not include any slashes, dollar signs, or periods in the file name. If you leave off the file extension, we'll assume you want it to be ".docx". If there is a column titled "File" in your table, we'll add a caption listing which files were included.
page_orientation	set the page orientation for the Word file output to "portrait" (default) or "landscape"
title_document	optionally specify a title for the Word document output. If you don't save the table, this will be ignored. This sometimes struggles if you include special characters, e.g., "-" is fine but ":" is not and the file won't save.
table_caption	optionally add some text for a table caption. If the table you supply contains a column titled "File", there will already be a caption listing the source files; this would add some additional text before that. This doesn't allow you to include carriage returns in this caption because your friendly R coders haven't figured out how to make that work yet.

Value

a formatted table

Examples

MyPKTable <- tibble(Statistic = c("Simulated", "CV%", "Observed", "S/O"),
                        AUCinf = c(2756, 32.5, 1801, 1.53),
                        Cmax = c(852, 45.8, 775, 1.1),
                        `Half life` = c(7.75, 5.7, 6.05, 1.28))
formatTable_Simcyp(MyPKTable)
formatTable_Simcyp(MyPKTable, center_1st_column = TRUE)
formatTable_Simcyp(MyPKTable, fontsize = 18)
formatTable_Simcyp(MyPKTable, shading_column = Statistic)

# Highlighting examples
## Highlighting S/O values outside bioequivalence of 125%.
formatTable_Simcyp(MyPKTable,
                   highlight_so_cutoffs = 1.25)

## Highlighting S/O values with a few more colors based on the S/O.
formatTable_Simcyp(MyPKTable,
                   highlight_so_cutoffs = c(1.25, 1.5))

## Highlighting S/O values and shading the "good" values green.
formatTable_Simcyp(MyPKTable,
                   highlight_so_cutoffs = c(1, 1.25, 1.5))

## Highlight exactly the cells you want, e.g., row 1, column 2
formatTable_Simcyp(MyPKTable, highlight_cells = c(1, 2))

## Highlight all of column 2
formatTable_Simcyp(MyPKTable, highlight_cells = c(NA, 2))

## Highlight all of row 1
formatTable_Simcyp(MyPKTable, highlight_cells = c(1, NA))

## Highlight the 2nd column in the header
formatTable_Simcyp(MyPKTable, highlight_cells = c(0, 2))

## Set the highlight color to light blue instead of yellow
formatTable_Simcyp(MyPKTable, highlight_cells = c(1, NA),
                   highlight_color = "lightblue")

## Highlighting multiple cells
formatTable_Simcyp(MyPKTable, highlight_cells = list(c(1, 2), c(3,3), c(4, 2)),
                   highlight_color = "lightblue")

# Bold-face examples
## Make only the cell in row 4 and column 2 be bold face. This will
## override the default of having the header row and the 1st column in bold.
formatTable_Simcyp(MyPKTable, bold_cells = c(4, 2))

## Make the cell in row 4 and column 2 be bold face AND include the original
## defaults of having the header row and the 1st column be in bold.
formatTable_Simcyp(MyPKTable, bold_cells = list(c(0, NA), c(NA, 1), c(4, 2)))

# Saving
## Adding a column called "File" so that there will be a caption in the Word
## document listing which files were included in the table. Also setting
## the document title.
MyPKTable$File <- "abc-1a.xlsx"
formatTable_Simcyp(MyPKTable,
                   highlight_so_cutoffs = c(1, 1.25, 1.5),
                   save_table = "My data.docx",
                   title_document = "PK data")

shirewoman2/Consultancy documentation built on Feb. 18, 2025, 10 p.m.