Package 'docorator'

Title: Docorate (Decorate + Output) Displays
Description: A framework for creating production outputs. Users can frame a table, listing, or figure with headers and footers and save to an output file. Stores an intermediate 'docorator' object for reproducibility and rendering to multiple output types.
Authors: Becca Krouse [aut, cre], Shannon Haughton [aut], Seongbin Hong [aut], Dragoș Moldovan-Grünfeld [aut], GlaxoSmithKline Research & Development Limited [cph, fnd]
Maintainer: Becca Krouse <[email protected]>
License: Apache License 2.0
Version: 0.6.0.9000
Built: 2026-06-02 18:49:20 UTC
Source: https://github.com/gsk-biostatistics/docorator

Help Index

apply a gt function to a gt_group

Description

apply a gt function to a gt_group

Usage

apply_to_gt_group(x, func, args, call = rlang::caller_env())

Arguments

x

gt group object
func

string with function name
args

named list of function arguments with gt_tbl or gt_group as first arg
call

caller env

Examples

gt_tbl <- gt::exibble|> gt::gt()
gt_group <- gt::gt_group(gt_tbl, gt_tbl)

func <- gt::tab_options
arg_list_group <- list(page.header.use_tbl_headings = c(TRUE))

apply_to_gt_group(gt_group, func,arg_list_group)

Create docorator object

Description

Create docorator object

Usage

as_docorator(
  x,
  display_name,
  display_loc = NULL,
  header = fancyhead(fancyrow(right = doc_pagenum())),
  footer = NULL,
  save_object = TRUE,
  object_loc = display_loc,
  ...,
  fontsize = 10,
  geometry = geom_set(),
  fig_dim = c(5, 8),
  tbl_scale = TRUE,
  tbl_stub_pct = 0.3
)

Arguments

x

object containing the display. See @details for more information.
display_name

required name of file (excluding extension)
display_loc

optional path to save the output file to
header

Document header. Accepts a fancyhead object. If NULL, no header will be displayed.
footer

Document footer Accepts a fancyfoot object. If NULL, no footer will be displayed.
save_object

Boolean indicating if a docorator object should be saved.
object_loc

path for the docorator object - defaults to display_loc argument.
...

These dots are for future extensions and must be empty.
fontsize

Font size (pt). Defaults to 10. Accepted values: 10, 11, 12.
geometry

Document sizing options based on the geometry latex package. Accepts a named list. Default is geom_set().
fig_dim

vector containing figure height and width in inches. Defaults to c(5,8)
tbl_scale

Boolean for whether or not to automatically scale table columns to fit display area. Defaults to TRUE. Note that this will overwrite scaling set in the table directly unless set to FALSE.
tbl_stub_pct

percent of total width that should be dedicated to stub column(s). If more than 1 stub column then this is the total for both.

Details

While the x argument flexibly accepts many different R objects, the following classes/types are recommended:

  • gt

  • gt_group (list of gt objects)

  • ggplot

  • list of ggplots

  • path to PNG file created via png_path()

  • list of paths to PNG files created via png_path()

Value

docorator object

Examples

## Not run: 
gt::gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt::gt(groupname_col = "mfr",
         row_group_as_column = TRUE) |>
  as_docorator(
   header = fancyhead(fancyrow("Header 1"), fancyrow("Header 2")),
   display_name = "mytbl",
   footer = NULL)

## End(Not run)

Date and time of program run

Description

Date and time of program run

Usage

doc_datetime()

Value

character string

Examples

doc_datetime()

Automatic page numbering

Description

Automatic page numbering

Usage

doc_pagenum()

Value

character string containing latex code

Examples

doc_pagenum()

Path of program

Description

Path of program

Usage

doc_path(filename = NULL, path = NULL)

Arguments

filename

Name of output file
path

program path

Value

character string

Examples

## Not run: 
 doc_path(filename = "my_tbl.pdf", path = NULL)

## End(Not run)

Decorate and output a table, listing, or figure to a file

Description

[Deprecated]

This function was deprecated and replaced with as_docorator and a corresponding render function i.e render_pdf

Usage

docorate(
  x,
  filename,
  path = NULL,
  header = fancyhead(fancyrow(right = doc_pagenum())),
  footer = fancyfoot(fancyrow(left = doc_path(filename, path), right = doc_datetime())),
  ...,
  fontsize = 10,
  geometry = geom_set(),
  fig_dim = c(5, 8),
  tbl_scale = TRUE,
  tbl_stub_pct = 0.3
)

Arguments

x

object containing the display. See @details for more information.
filename

required name of file including extension (note: only PDF supported currently)
path

optional path to save the output pdf to
header

Document header. Accepts a fancyhead object. If NULL, no header will be displayed.
footer

Document footer Accepts a fancyfoot object. If NULL, no footer will be displayed.
...

These dots are for future extensions and must be empty.
fontsize

Font size (pt). Defaults to 10. Accepted values: 10, 11, 12.
geometry

Document sizing options based on the geometry latex package. Accepts a named list. Default is geom_set().
fig_dim

vector containing figure height and width in inches. Defaults to c(5,8)
tbl_scale

Boolean for whether or not to automatically scale table columns to fit display area. Defaults to TRUE. Note that this will overwrite scaling set in the table directly unless set to FALSE.
tbl_stub_pct

percent of total width that should be dedicated to stub column(s). If more than 1 stub column then this is the total for both.

Details

While the x argument flexibly accepts many different R objects, the following classes/types are recommended:

  • gt

  • gt_group (list of gt objects)

  • ggplot

  • list of ggplots

  • path to PNG file created via png_path()

  • list of paths to PNG files created via png_path()

Value

This function is called for its side effects

Examples

## Not run: 
gt::gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt::gt(groupname_col = "mfr",
         row_group_as_column = TRUE) |>
  docorate(
   header = fancyhead(fancyrow("Header 1"), fancyrow("Header 2")),
   filename = "mytbl.pdf")
 
## End(Not run)

Construct document footer

Description

Define document footer through a series of fancyrows. Each row represents a new line in the footer with options for positioning text at left, center, and/or right positions.

Usage

fancyfoot(...)

Arguments

...

Series of objects of class fancyrow. Each entry represents a new row in the document footer.

Value

Character string containing latex code for the fancyfoot entries as part of the fancyhdr latex framework

Examples

fancyfoot(
 fancyrow(left = "My first footnote", right = doc_datetime())
)

Construct document header

Description

Define document header through a series of fancyrows. Each row represents a new line in the header with options for positioning text at left, center, and/or right positions.

Usage

fancyhead(...)

Arguments

...

Series of objects of class fancyrow. Each entry represents a new row in the document header.

Value

Character string containing latex code for the fancyhead entries as part of the fancyhdr latex framework

Examples

fancyhead(
 fancyrow(left = "Protocol: 12345", right = doc_pagenum()),
 fancyrow(center = "Demographic Summary")
)

Construct document header row

Description

Define a single row in the document header/footer. Each row represents a single line of text, with options for positioning text at left, center, and/or right.

Usage

fancyrow(left = NA, center = NA, right = NA)

Arguments

left

Character string to be aligned to the left side of the row.
center

Character string to be aligned to the center of the row.
right

Character string to be aligned to the right side of the row.

Value

Object of class fancyrow

Examples

fancyrow(left = "Left most text", right = "Right most text")

fancyrow(center = "Just text in the center")

fancyrow(left = "All", center = "Three", right = "Positions filled")

Set document geometry defaults

Description

Set document geometry defaults

Usage

geom_set(...)

Arguments

...

Series of named value pairs for latex geometry options

Details

Type geom_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 NULL, such as for headheight and footskip, the values will be calculated automatically based on the number of header and/or footer lines. For all geometry settings, reference the documentation here: https://texdoc.org/serve/geometry.pdf/0

Value

Named list

Examples

# view defaults
geom_set()

# Update the defaults
geom_set(left="0.5in", right="0.5in")

# add new defaults
geom_set(paper = "legalpaper")

Path of png file

Description

Path of png file

Usage

png_path(path = NULL)

Arguments

path

path to png

Value

object with png attribute

Examples

## Not run: 
png_path <- png_path(path = "path_to_my_png.png")

## End(Not run)

Render to pdf

Description

Render to pdf

Usage

render_pdf(
  x,
  display_loc = NULL,
  transform = NULL,
  header_latex = NULL,
  keep_tex = FALSE,
  escape_latex = TRUE,
  quarto = FALSE,
  version_check = TRUE,
  fancywrap = TRUE
)

Arguments

x

docorator object
display_loc

optional path to save the output pdf to
transform

optional latex transformation function to apply to a gt latex string
header_latex

optional .tex file of header latex
keep_tex

Boolean indicating if to keep resulting .tex file from latex conversion. Defaults to FALSE.
escape_latex

Boolean indicating if headers and footers of a gt table should be escaped with gt::escape_latex
quarto

Boolean indicating whether to use Quarto as the rendering engine. Defaults to FALSE, which uses Rmarkdown to render. [Experimental]
version_check

Boolean indicating whether to print a note if gt or ggplot versions dont match between the original docorator object and the one being used for rendering
fancywrap

Boolean indicating if headers and footers should be split to fit the page. Defaults to TRUE. Note that only fancyrows with one left, right OR center element will be wrapped. [Experimental]

Value

This function saves a pdf to a specified location

Examples

gt::gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt::gt(groupname_col = "mfr",
         row_group_as_column = TRUE) |>
  as_docorator(
   header = fancyhead(fancyrow("Header 1"), fancyrow("Header 2")),
   display_name = "mytbl") |>
 render_pdf()

Render to rtf

Description

[Experimental]

Usage

render_rtf(
  x,
  display_loc = NULL,
  remove_unicode_ws = TRUE,
  use_page_header = FALSE,
  version_check = TRUE
)

Arguments

x

docorator object
display_loc

path to save the output rtf to
remove_unicode_ws

Option to remove unicode white space from text.
use_page_header

If TRUE then all table headings will be migrated to the page header. See https://gt.rstudio.com/reference/tab_options.html#arg-page-header-use-tbl-headings
version_check

Boolean indicating whether to print a note if gt or ggplot versions dont match between the original docorator object and the one being used for rendering

Details

Option remove_unicode_ws serves as a workaround for this issue in gt

Value

This function saves an rtf to a specified location

Examples

gt::gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp) |>
  gt::gt(groupname_col = "mfr",
         row_group_as_column = TRUE) |>
  as_docorator(
   header = fancyhead(fancyrow("Header 1"), fancyrow("Header 2")),
   display_name = "mytbl") |>
 render_rtf()

Scale gt table contents for document

Description

Scale gt table contents for document

Usage

scale_gt(x, tbl_stub_pct = 0.3)

Arguments

x

table of class gt_tbl
tbl_stub_pct

percent of total width that should be dedicated to stub column(s). If more than 1 stub column then this is the total for both.

Value

Table with col_widths settings applied

Examples

gt::gtcars |>
  dplyr::slice_head(n = 10) |>
  dplyr::select(mfr, model, year, msrp, ctry_origin) |>
  gt::gt(
      groupname_col = "ctry_origin",
      rowname_col = "mfr",
      row_group_as_column = TRUE) |>
  scale_gt(tbl_stub_pct = 0.4)