Package 'clinify'

Convert a flextable into a clintable object

Description

Convert a flextable into a clintable object

Usage

as_clintable(x, page_by = NULL, group_by = NULL)

Arguments

x	A flextable object
page_by	A variable in the input dataframe to use for pagination
group_by	A variable which will be used for grouping and attached as a label above the table headers

Value

A clintable object

Examples

ft <- flextable::flextable(mtcars)
as_clintable(ft)

---

Add titles, footnotes, or a footnote page to a clintable or clindoc

Description

This function allows you to attach specified titles, footnotes, or a footnote page into clintable or clindoc object. The input can be provided either as a list of character vectors, or pre-built flextable.

Usage

clin_add_titles(x, ls = NULL, ft = NULL)

clin_add_footnotes(x, ls = NULL, ft = NULL)

clin_add_footnote_page(x, ls = NULL, ft = NULL)

Arguments

x	a clintable object
ls	a list of character vectors, no more than 2 elements to a vector
ft	A flextable object to use as the header

Details

When using the ls parameter, each element of the list can contain no more than two elements within each character vector. In a title, a single element will align center. In a footnote, a single element will align to the left. For both titles and footnotes, two elements will align split down the middle, with the left side element aligning left and the right side element aligning right. In a title, a single left aligned element, provide a 2 element character vector with duplicate values.

Value

A clintable object

Examples

clintable(mtcars) |>
  clin_add_titles(
    list(
      c("Left", "Right"),
      c("Just the middle")
    )
  ) |>
  clin_add_footnotes(
    list(
      c(
        "Here's a footnote.",
        format(Sys.time(), "%H:%M %A, %B %d, %Y")
      )
    )
  ) |>
  clin_add_footnote_page(
    list(
      c(
        "Use when you have a lot of footnotes",
        "And you don't want to put them on every page"
      )
    )
  )

---

Configure alternating pages during pagination of a clintable

Description

This function configures alternating pages on a clintable object.

Usage

clin_alt_pages(x, key_cols, col_groups)

Arguments

x	A clintable object
key_cols	A character vector of variable names
col_groups	A list of character vectors of variable names

Value

A clintable object

Examples

ct <- clintable(mtcars)

clin_alt_pages(
  ct,
  key_cols = c("mpg", "cyl", "hp"),
  col_groups = list(
    c("disp", "drat", "wt"),
    c("qsec", "vs", "am"),
    c("gear", "carb")
  )
)

---

Enable Word Auto-Pagination Using Group Variable

Description

This function uses the applies the functionality flextable::keep_with_next() by automatically building the row indices using some grouping variable. Each group identified by the variable (i.e. when the value of the variable changes) will be set as a "keep_with_next" group in Word. Using this functionality, Word will attempt not to break that group across pages, enabling smoother pagination without having to do specific calculations of page breaks.

Usage

clin_auto_page(x, group_var, when = c("change", "notempty"), drop = FALSE)

Arguments

x	A clintable object
group_var	A string containing a variable name of the input dataset used to calculate groups
when	Character string indicating when to apply padding: "notempty": Find allowable break points when the value in group_var is not empty. "change": Find allowable break points when the value in group_var changes from the previous row.
drop	Keep or drop the 'group_var“ variable

Value

A clintable object

Examples

clintable(mtcars) |>
  clin_auto_page("gear")

---

Set column widths using percent

Description

Extraction of flextable print method with special handling of clintable pages and

Usage

clin_col_widths(x, ...)

Arguments

x	A clintable object
...	Named parameters where the names are columns in the flextable and the values are decimals representing the percent of total width of the table

Value

A clintable object

Examples

ct <- clintable(mtcars)

ct <- clin_alt_pages(
  ct,
  key_cols = c("mpg", "cyl", "hp"),
  col_groups = list(
    c("disp", "drat", "wt"),
    c("qsec", "vs", "am"),
    c("gear", "carb")
  )
) |>
  clin_col_widths(mpg = .2, cyl = .2, disp = .15, vs = .15)

print(ct)

---

Set the column headers of the output clintable

Description

This function allows you to apply column headers named arguments and character vectors. Separate elements of the character vector are converted to separate levels of the output table header. The in which the headers are applied goes from top to bottom, so if you provide 3 elements for a column header, the first element is applied to the top and the second to the bottom. If one variable has three levels and other variable only have one or two, the columns with less levels to the header will bind to the bottom. So a column with two levels will apply to the second and third row, and a column with one level with apply the bottom row. Spanners are determined using cells of the same text value, where horizontal and vertical merging is performed.

Usage

clin_column_headers(x, ...)

Arguments

x	A clintable object
...	Named arguments providing the column header text. Separate levels of the header are determined using separate elements of a character vector.

Details

The same result can be achieved using column labels on the input dataframe to the clintable. If labels are present, header levels will be separated using the delimitter "||" within the label string.

Value

A clintable object

Examples

clintable(iris) |>
  clin_column_headers(
    Sepal.Length = c("Flowers", "Sepal", "Length"),
    Sepal.Width = c("Flowers", "Sepal", "Width"),
    Petal.Length = c("Petal", "Length"),
    Petal.Width = c("Petal", "Width")
  )

---

Get the Default Table Width for Clinical Documents

Description

This function calculates the default table width based on the page width and margins specified in the clinify_docx_default option.

Usage

clin_default_table_width()

Value

An rdocx object from the officer package

Examples

clin_default_table_width()

---

Configure a clintable to table by a grouping variable, which will be used as a label

Description

Configure a clintable to table by a grouping variable, which will be used as a label

Usage

clin_group_by(x, group_by, caption_by = NULL, when = c("change", "notempty"))

Arguments

x	A clintable object
group_by	A character vector of variable names which will be used for grouping and attached as a label above the table headers
caption_by	A single element string of a variable name which will be used as a caption attached below the table body and above in the footer. Defaults to NULL.
when	Character string indicating how to identify groups and captions: "change": Add padding when the value in group_by or caption_by changes from the previous row. "notempty": Add padding when the value in group_by or caption_by is not empty.

Value

A clintable object

Examples

clintable(iris) |>
  clin_group_by("Species")

---

Add Padding Between Groups in a Clinical Flextable

Description

Adds top padding to rows in a 'clintable“ based on changes in a grouping variable or non-empty values. Useful for visually separating groups in a table

Usage

clin_group_pad(
  x,
  pad_by,
  size = 9,
  when = c("change", "notempty"),
  drop = FALSE
)

Arguments

x	A clintable
pad_by	A string indicating the column name used to detect group changes.
size	Numeric value for the base padding size (default is 9).
when	Character string indicating when to apply padding: "notempty": Add padding when the value in pad_by is not empty. "change": Add padding when the value in pad_by changes from the previous row.
drop	Keep or drop the padding variable used to identify padding locations

Value

A clintable object with modified padding.

Examples

ct <- clintable(mtcars) |>
  clin_group_pad('gear')

ct <- clintable(mtcars) |>
  clin_group_pad('gear', size = 15)

---

Configure pagination using a page variable

Description

Configure pagination using a page variable

Usage

clin_page_by(x, page_by, max_rows = 10)

Arguments

x	A clintable object
page_by	A variable in the input dataframe to use for pagination
max_rows	If no page_by, the maximum rows allowed per page

Value

A clintable object

Examples

dat <- mtcars
dat["page"] <- c(
  rep(1, 10),
  rep(2, 10),
  rep(3, 10),
  c(4, 4)
)

clintable(dat) |>
  clin_page_by("page")

clintable(mtcars) |>
  clin_page_by(max_rows = 10)

---

Replace Table Cells with Word Page Number Fields

Description

This helper function will find placeholder text and replace the fields of the flextable object with the appropriate page number fields. The function will search for the text {PAGE} and replace with the word field for current pages, and {NUMPAGES} for total pages. This allows you to current and total page fields within Word documents. Note that this is intended to be used in the defaults for clinify_titles_default or clinify_footnotes_default.

Usage

clin_replace_pagenums(x)

Arguments

x	A clintable object

Value

A clintable object

Examples

title <- new_title_footnote(
  list(
    # We'll add tools to automate paging
    c("Protocol: CDISCPILOT01", "Page {PAGE} of {NUMPAGES}"),
    c("Table 14-2.01"),
    c("Summary of Demographic and Baseline Characteristics")
  ),
  "titles"
)

title <- clin_replace_pagenums(title)

footnote <- new_title_footnote(
  list(
    # We'll add tools to automate paging
    c("Page {PAGE}", "Total Pages: {NUMPAGES}")
  ),
  "footnotes"
)

footnote <- clin_replace_pagenums(footnote)

---

Create a clindoc object

Description

These functions handle the conversion of a clintable object into a clindoc object.

Usage

clindoc(...)

as_clindoc(x)

Arguments

...	clintable objects to be converted. Or separately, a list of clintable objects
x	A clintable object to be converted.

Details

• as_clindoc() is intended for a single clintable object and extracts all necessary title and footnote information to apply to the document

• clindoc() can accept clintable objects as separate parameters or as a list of clintable objects. If a single clintable is passed, this function simply calls as_clindoc() internally.

When a multiple clintable objects are passed to clindoc(), titles and footnotes should be applied directly to the clindoc object using clin_add_title(), clin_add_footnote(), or clin_add_footnote_page(). Title and footnote information on the individual clintable objects will be ignored.

Value

a clindoc object, inherited from an officer::rdocx object

Examples

ct <- clintable(mtcars)

clindoc(ct)

---

Apply Default Clinical Styling to Clintables

Description

These functions apply default styling to clintable objects used for clinical tables, including titles and footnotes. The styling includes removing borders, setting font properties, and adjusting table width, line spacing, and padding.

Usage

clinify_titles_default(x, ...)

clinify_footnotes_default(x, ...)

clinify_table_default(x, ...)

clinify_caption_default(x, ...)

clinify_grouplabel_default(x, ...)

clinify_docx_default()

Arguments

x	A clintable object representing the table (title or footnote).
...	Additional arguments (currently unused).

Value

A clintable object with the applied styling.

Examples

op <- options()

sect <- clinify_docx_default()

# Save out options to grab defaults
options(
  clinify_docx_default = sect,
  clinify_titles_default = clinify_titles_default,
  clinify_footnotes_default = clinify_footnotes_default,
  clinify_table_default = clinify_table_default,
  clinify_caption_default = clinify_caption_default,
  clinify_grouplabel_default = clinify_grouplabel_default
)

options(op)

---

Create a new clintable object

Description

A clintable object directly inherits from a flextable object. This function will pass all necessary parameters flextable::flextable() and conver the object to a clintable

Usage

clintable(x, page_by = NULL, group_by = NULL, use_labels = TRUE, ...)

Arguments

x	A data frame
page_by	A variable in the input dataframe to use for pagination
group_by	A character vector of variable names which will be used for grouping and attached as a label above the table headers
use_labels	Use variable labels as column headers. Nested levels can be achieved using the string "||" as a delimitter. Horizontal and vertical levels using identical words will be merged.
...	Parameters to pass to flextable::flextable()

Value

A clintable object

Examples

clintable(mtcars)

---

Assign Page Numbers to Presorted Grouped Data

Description

Assigns sequential page numbers to elements of a vector, grouping by unique values and allocating a specified number of rows per page. The input vector must be presorted by group.

Usage

make_grouped_pagenums(var, rows)

Arguments

var	A vector of group labels, presorted so that identical values are contiguous.
rows	Integer. The maximum number of rows per page.

Details

The function splits the input vector into groups, then assigns page numbers within each group so that each page contains up to 'rows“ items. Page numbers increment sequentially across groups. If the input is not presorted by group, the function will throw an error.

Value

An integer vector of the same length as 'var“, indicating the assigned page number for each element.

Examples

library(dplyr)
iris |>
  mutate(
    page = make_grouped_pagenums(Species, 5)
  )

---

Create a new title or footnote flextable

Description

Create a new title or footnote flextable

Usage

new_title_footnote(x, sect = c("titles", "footnotes", "footnote_page"))

Arguments

x	a list of character vectors, no more than 3 elements to a vector.
sect	Either "titles" or "footnotes"

Value

A flextable object

Examples

title <- new_title_footnote(
  list(
    # We'll add tools to automate paging
    c("Protocol: CDISCPILOT01", "Page {PAGE} of {NUMPAGES}"),
    c("Table 14-2.01"),
    c("Summary of Demographic and Baseline Characteristics")
  ),
  "titles"
)

footnote <- new_title_footnote(
  list(
    # We'll add tools to automate paging
    c("Page {PAGE}", "Total Pages: {NUMPAGES}")
  ),
  "footnotes"
)

---

Clintable print method

Description

Extraction of flextable print method with special handling of clintable pages and

Usage

## S3 method for class 'clintable'
print(x, n = 3, nrows = 15, apply_defaults = TRUE, ...)

## S3 method for class 'clintable'
knit_print(x, n = 3, nrows = 15, apply_defaults = TRUE, ...)

Arguments

x	A clintable object
n	Number of pages within the clintable to print. Only used when pagination is configured
nrows	Number of rows to print. Only used when rows aren't configured within the pagination method
apply_defaults	Apply default styles. These styles are stored in the options clinify_header_default, clinify_footer_default, and clinify_table_default respectively. Defaults to true.
...	Additional parameters passed to flextable print method

Value

Invisible

Examples

ct <- clintable(mtcars)

print(ct)

ct <- clin_alt_pages(
  ct,
  key_cols = c("mpg", "cyl", "hp"),
  col_groups = list(
    c("disp", "drat", "wt"),
    c("qsec", "vs", "am"),
    c("gear", "carb")
  )
)

print(ct)

---

Clintable write method

Description

Write a clinify table out to a docx file

Usage

write_clindoc(x, file)

Arguments

x	a clintable object
file	The file path to which the file should be written

Value

Invisible

Examples

ct <- clintable(mtcars)

ct <- clin_alt_pages(
  ct,
  key_cols = c("mpg", "cyl", "hp"),
  col_groups = list(
    c("disp", "drat", "wt"),
    c("qsec", "vs", "am"),
    c("gear", "carb")
  )
)

# Get document object directly
doc <- clindoc(ct)

# Write out docx file
write_clindoc(ct, file.path(tempdir(), "demo.docx"))

---