Package index • rtfreporter

Tables from an ARD — reading the ARD

The recommended start: an analysis results dataset (cards / cardx) made ready for a table. Acts on: an ARD data frame. normalize_ard() flattens it – groups and hierarchy become ordinary key columns, and stack = puts subgroups from different variables one under another – and widen_ard() does the whole ARD half in one call, giving a table data frame now. list_ard_keys(), pull_ard(), overall_row() and cell_rows() look inside an ARD and shape its rows. Start with the Get started article.

ard-tables: Tables from a cards/cardx ARD
normalize_ard(): Flatten an ARD into an explicitly keyed long table
widen_ard(): Turn a normalized ARD into a wide table data.frame
list_ard_keys(): What is actually inside an ARD
pull_ard(): Pull a statistic out of an ARD, keyed like the spread columns
overall_row(): Where the table's overall row comes from
cell_rows(): Several rows in one cell recipe, each with its own fallback chain

Tables from an ARD — the plan

table_plan() names the roles (what goes across, what goes down; show_keys = also shows a subgroup key’s own counts as rows) and each plan_*() verb adds one declaration. Nothing runs until the plan is handed to rtf_tables() or plan_apply(); a later layer wins. The verbs share one help page, plan_verbs; by job:

cells: plan_cells(), plan_digits(), plan_stat_groups()
rows: plan_filter(), plan_sort() (-n@SOC, -n[Total]), plan_levels(), plan_labels(), plan_nest()
more columns: plan_total(), plan_compare()
layout: plan_stub(), plan_row_group(), plan_blanks(), plan_hide(), plan_columns(), plan_cell_style(), plan_style()
pages: plan_paginate_group(), plan_paginate_rows(), plan_paginate_cols()
header and text: plan_col_header(), plan_titles(), plan_footnotes()
the rest: plan_listing(), plan_after()

The plan verbs article has an at-a-glance table. The Excel definition of a table lives in tflspec (tflspec::tfl_table_plan()).

table_plan(): A deferred, last-wins plan for a table
plan_levels() plan_labels() plan_cells() plan_digits() plan_stub() plan_cell_style() plan_paginate_group() plan_row_group() plan_nest() plan_total() plan_filter() plan_compare() plan_stat_groups() plan_hide() plan_sort() plan_empty() plan_blanks() plan_paginate_rows() plan_style() plan_col_header() plan_columns() plan_listing() plan_titles() plan_footnotes() plan_after() plan_paginate_cols(): Declare the table, one layer at a time
plan_apply(): Run a plan, or look inside it
plan_template(): Write the plan for you

Looking inside a plan

plan_layers(): What a plan declares, and what it resolved to
plan_header_tokens(): The tokens a plan's column header may carry, with their values
plan_n_candidates(): The populations a column header's {n} can say

Bring your own table — as_rtftables()

The second path: a table already built elsewhere – a gt::gt() table, a gtsummary table, an rtables/tern VTableTree, a tfrmt, flextable or huxtable table, an rlistings listing_df, or a plain data.frame – turned into rtftable objects, reading the source’s metadata and paginating in one call. Acts on: the source object. Produces: rtftable objects. as_rtftables() returns one per page (a list); as_rtftable() returns a single object. stub_cols() prepares a tidy data.frame beforehand by merging hierarchy columns into one indented stub column; stub_spec() carries the same settings into as_rtftables(stub = ).

as_rtftables(): Convert a table object into rtfreporter table pages
as_rtftable(): Convert one table object to a single rtftable
combine_sections(): Combine table page lists into one auto-sectioned list
stub_cols(): Merge hierarchy columns into one indented stub column
stub_spec(): Bundle the row-stub settings for as_rtftables()

Document, rendering & tokens

rtf_document() creates the document – with the program, the program_fallback and tokens of your own (tokens =) for its headers and footers; the section and content calls below add to it; generate_rtfreport() writes the file. Acts on: the rtf_document object. rtf_page() and rtf_default_format() are the only settings that are document-only – everything else in this reference acts on a table. rtf_config() edits an already-composed document; rtf_document() starts a new one. rtf_text_tokens() lists every {TOKEN} a header, footer, title or footnote can carry ({PAGE}, {PROGRAM}, {PROGRAM_FULL}, {DATETIME}, your own).

rtf_document(): Create an RTF document for pipe composition
rtf_config(): Configure document-level settings
rtf_page(): Page geometry for an RTF document
rtf_default_format(): Document-wide default formatting for an RTF document
rtf_watermark(): Build a page watermark
generate_rtfreport(): Generate an RTF file from a report object
rtf_text_tokens(): The tokens a page's text may carry
print(<rtf_document>): Print an rtf_document object
print(<rtfreport>): Print an rtfreport object

Sections — headers & footers

A section applies a running header / footer to a range of pages. Acts on: the rtf_document object. Headers and footers are themselves small tables: build their rows with rtf_header() / rtf_footer() (a list of rows – to change one, make it again).

rtf_section(): Define sections for pages
rtf_header() rtf_footer(): Create a header or footer object for a section

Page content — tables, titles & footnotes

Place a table on the page, with its titles and footnotes. Acts on: the rtf_document object – rtf_tables() takes the rtftable objects the sections below produce. Note the two levels: rtftable() sets how a table looks; passing the same setting to rtf_tables() overrides it for that placement only, leaving the table object untouched.

rtf_tables(): Add content pages to document
rtf_titles(): Assign content titles to pages
rtf_footnotes(): Assign content footnotes to pages
rtftable(): Create an RTF table object
print(<rtftable>): Print an rtftable object
format(<rtftable>): Render an rtftable body as console text
summary(<rtftable>): Summarise an rtftable object

Package defaults

Inspect and reset the rtfreporter.* option defaults (paper size, orientation, margins, font, font size). Acts on: nothing – these set the fallbacks every other function uses when you do not pass a value. A site can set its own in Rprofile.site; see the page-setup article.

rtfreporter_options(): Inspect the active rtfreporter defaults
rtfreporter_reset_defaults(): Restore the factory default options

Recipes — four complete tables from data frames

Copy-and-run examples for the four table shapes a clinical report is mostly made of: demographics, adverse events, PK concentrations and a laboratory shift table. Each runs end to end, data in and RTF out, and they are shown together because their arguments barely overlap – what a demographics table needs, an adverse-events table does not.

rtfreporter-recipes: Four complete recipes: DM, AE, PK and LB

Column headers

Build and edit the column-header block. Acts on: an rtftable – there is no header setting at document level. col_cell() describes one header cell and is accepted by rtf_col_header(), rtftable(col_header = ) and rtf_tables(col_header = ). A whole header built with rtf_col_header() goes to the same places plus set_col_header(). Coordinates are those of the finished table, so a merged stub counts as one column. col_key() lets a cell name the columns it covers by a column-name segment instead of by position.

col_cell(): Column-header cell specification
col_key(): Select header columns by a column-name segment
rtf_col_header(): Build a multi-row column-header specification
set_col_header(): Set the whole column header of a finished table (final-table coordinates)
header_map(): Show the column header of every page, cell by cell
rtf_columns(): Column names of a finished table's body
rtf_header_source(): Deparse a table's column header back to editable rtf_col_header() source

Post-hoc styling verbs

Restyle a table you have already built, without rebuilding it. Acts on: an rtftable, or a list of them – every verb here has a list method, so one call styles every page. These are the last word: they override whatever rtftable() or the source adapter set. set_decimal_split() is the exception in kind – it does not change the data, only how a numeric column is rendered.

style_header() style_cols() style_body() style_zone() add_header_row(): Restyle an existing rtftable (post-hoc styling verbs)
collapse_repeats(): Blank out consecutive repeated values in a finished table
set_decimal_split(): Line up the decimal points of a numeric column

Built-in cell-format functions

Re-shape the TEXT of cells so counts and percentages line up. Acts on: a data.frame or a character vector, before it becomes a table. Pass one to rtftable(cell_format = ) / as_rtftables(cell_format = ) to apply it during the build instead.

fmt_count_pct(): Format count + percent cells to a uniform display width
fmt_count_paren(): Align "count (parenthetical)" cells
fmt_value_paren(): Align "value (parenthetical)" cells, text values included
fmt_right_align(): Right-align the cells of a column to a common width

Numeric display formatters & rounding

Turn numbers into the strings a clinical table prints – significant digits, rounding, alignment. Acts on: a data.frame or a numeric vector, before it becomes a table. Numbers reaching rtftable() unformatted are converted with as.character(), which is rarely what a report wants, so format first. round_num() is the rounding rule every formatter (and a plan’s templates) uses – R’s half-to-even, or SAS’s half-away-from-zero with options(rtfreporter.rounding = "sas").

fmt_signif(): Format numbers to a number of significant digits
fmt_round(): Format numbers to a fixed number of decimal places
fmt_numeric(): Format the numeric columns of a table for display
round_num(): Round the way R rounds, or the way SAS rounds

Blank rows

Insert blank separator rows by position, by value change, or by rule.

set_blank_rows(): Attach blank-row positions to a data.frame
blank_rows_by_change(): Blank-row specification: insert when a variable's value changes
blank_rows_by_rule(): Blank-row specification: insert before/after rows matching a pattern

Pagination strategies & helpers

Split a table across pages. Acts on: the body of a table being built. Vertical splitting is chosen with as_rtftables(split = ) – a strategy name ("group_safe", "group_force", "by_value", "rows", "none") with its settings given as ordinary arguments alongside it, or a function of your own for a bespoke rule. paginate_cols() is the horizontal counterpart: it acts on a FINISHED rtftable, splitting a too-wide table by column and repeating the row headings on every page.

paginate_cols(): Paginate a table horizontally, by columns
add_cont_label(): Prepend a continuation label row to a paginated chunk

Column-width utilities

Measure text and size columns to their content. Acts on: a data.frame; returns widths in twips for rtftable(column_widths_twips = ). Use auto_col_widths() when long labels wrap; as_rtftables(auto_width = TRUE) does the same during the build, clamped to the writable page width.

text_width_in(): Estimate the display width of a text string
auto_col_widths(): Automatically calculate column widths for a data.frame

Listings (source data → listing body)

Reshape source data into what a listing prints, before any of it is rendered: source variables joined into one printed column, a long cell wrapped over several physical rows, narrow gutter columns, and a blank row after each record. Acts on: a data.frame / tibble. Produces: a data.frame, which as_rtftables() renders. listing_col() describes one printed column and listing_spec() the listing as a whole; build_listing() applies the spec, and as_rtftables(listing = ) runs the same work inside the pipeline and derives the header, the widths and the alignment from it. An rlistings listing_df needs none of this – it is already laid out, and goes straight to as_rtftables(). fit_listing_widths() proposes every column’s width from the page and the data, and listing_code() prints the spec as source to paste and tune. listing_wrap() is the rule that breaks a cell into lines, and listing_wrap_code() writes that rule out as source when a listing needs a different one – calling listing_disp_width(), listing_take() and listing_split_after(), the measurements a rule is built on, rather than copying them. catx() is the join a listing column makes, exported for the columns you build yourself.

listing_col(): One printed column of a listing
listing_spec(): Bundle the settings for one listing
build_listing(): Reshape a data.frame into a listing body
fit_listing_widths(): Propose the listing's column widths from the page and the data
listing_code(): Print a listing spec as the code that would build it
listing_wrap(): Break a listing cell or header into the lines it occupies
listing_wrap_code(): The default wrapping rule, as source to edit
listing_disp_width() listing_take() listing_split_after(): The measurements a listing's wrapping rule is built on
catx(): Join values with a separator, skipping the missing ones

Figures

Place a plot or an image file on a page. rtfplot() wraps a PNG / JPEG (or a plot object, saved for you); rtf_figures() adds figures to the document, with titles and footnotes, as rtf_tables() does for tables. Acts on: the rtf_document object.

rtf_figures(): Add figure content to document
rtfplot(): Create an RTF figure object
print(<rtfplot>): Print an rtfplot object

Assembling a deliverable & post-processing

Join finished RTF FILES into one, with a table of contents and continuous page numbering. Acts on: files on disk, not R objects – this is the step after generate_rtfreport(). The table of contents is a table (file, label, heading, level) – assemble_folder() makes it from a folder – or the path of one (.xlsx / .csv). rtf_replace_text() edits a rendered file in place – text a report needs only at delivery time.

assemble_rtf(): Assemble multiple RTF files into one
assemble_folder(): Assemble every RTF in a folder into one TOC deliverable
rtf_replace_text(): Replace text inside a generated RTF file

Borders

Two constructors, and only two: rtf_border_line() describes one edge – its line style, width and colour – and rtf_border() collects edges into the border of a cell, a row or a zone, including the rules inside a selection (inside_h, inside_v). Where usable: both are accepted by rtftable(border = ), rtf_tables(border = ) and the style_*() verbs; rtf_border() is also accepted by col_cell(border = ). There is no border setting at document level. Later wins, per edge – a style_*() call overrides rtftable(), which overrides the adapter. The constructors these two replaced are listed under Deprecated at the bottom of this page; ?rtf_border pairs the old and the new spelling for every case.

rtf_border_line() rtf_border_side(): Single-edge border specification
rtf_border() rtf_border_none() rtf_border_top() rtf_border_bottom() rtf_border_box(): Four-edge border specification for a cell or row

Shared table styles (S3, snapshot)

One object carrying borders, alignment, padding and row height, so a set of tables can share a look. Where usable: rtftable(style = ) and rtf_tables(style = ). rtf_table_style_with() derives a variant from an existing style, changing only the fields you name.

rtf_table_style(): Shared table style
rtf_table_style_with(): Return a copy of an rtf_table_style with selected fields replaced
rtf_table_style_tfl(): Clinical TFL preset (table style)

Visual preview (S3 plot methods)

Look at a table, a border or a document without writing a file. Acts on: whichever object you pass; nothing is modified. These are for checking work in progress, not for producing output.

plot(<rtf_border>): Visualise an rtf_border
plot(<rtf_border_line>): Visualise an rtf_border_line
plot(<rtf_table_border>): Visualise an rtf_table_border
plot(<rtftable>): Visualise an rtftable
plot(<rtf_document>): Visualise an rtf_document

Working with an AI assistant

The package is too new to be in a chat model’s training data, so an assistant has to be told the API before it writes any. Two briefings ship inside the package for that – one for using rtfreporter, one for working on it – and this returns the copy installed alongside your version, which is the one that matches what you actually have.

rtfreporter_ai_manual(): The AI assistant manuals that ship with this package

Deprecated – scheduled for removal

The border constructors that rtf_border_line() and rtf_border() replaced at 0.5.0 / 0.6.0. They still work and each warns once per session, naming its replacement, and are removed in 0.9.0 – do not write new code against them. ?rtf_border pairs the old and the new spelling for every case. rtf_border_none(), rtf_border_top(), rtf_border_bottom() and rtf_border_box() are documented on the rtf_border() page itself. Deprecated in 0.8.x by the pre-CRAN API review, and removed in 0.9.0 too: rtf_border_side() (now rtf_border_line(), documented on its page), the header editors below (write the header in rtf_col_header() / rtf_header() instead), paginate() (use as_rtftables()), and the arguments rtftable(spanning_header = ) and as_rtftable(gt_obj = ) (now x), the as_rtftables() arguments stub_vars / stub_label / stub_indent / stub_group_summary (now stub =), and the assembly helpers below (assemble_folder() and assemble_rtf(toc = <a table>)). Deprecated by the review’s iteration 0 (#594), removed in 0.9.0 too: the 26 table-format arguments of rtf_tables() and read_gt (write them on rtftable() / as_rtftables() / plan_style()), and the cell formatters below – fmt_count_paren_bare() (now fmt_count_paren(bare = TRUE)), realign_count_pct() (now as_rtftables(align_count_pct = TRUE)) and format_count_pct() (now fmt_count_pct()).

rtf_border_with(): Return a copy of an rtf_border with selected sides replaced
rtf_table_border(): Per-zone border specification for a table
rtf_border_tfl(): Clinical TFL-style table border preset
add_col_header_row(): Append (or prepend) a row to an rtf_col_header (deprecated)
col_header_from_names(): Build a spanning column header from delimited column names (deprecated)
set_header_cell(): Set or merge individual column-header cells (deprecated)
update_header_row() update_footer_row(): Update a specific row in an rtf_header() object (deprecated)
paginate(): Split a table object into per-page data.frames (deprecated)
assemble_files(): Collect the RTF files in a folder (deprecated)
assemble_spec(): Build an assembly spec (one editable row per RTF) (deprecated)
assemble_toc(): Build a TOC definition from a set of RTF files (deprecated)
assemble_from_spec(): Assemble RTF files from an assembly spec (deprecated)
toc_heading(): Build a structured TOC heading (deprecated)
toc_entry(): Build a structured TOC entry (deprecated)
fmt_count_paren_bare(): Align "count (parenthetical)" cells, including bare counts
realign_count_pct(): Re-align existing "n (xx.x)" strings to a uniform display width
format_count_pct(): Format count + percent cells (old name)