Package {otter}

otter: Ott's Utility Functions

Description

A growing collection of personal utility functions. Currently provides tools to parse Rich Text Format (RTF) files and extract their tables into data frames, automatically detecting header rows, merging multi-page tables, and resolving merged cells. Particularly useful for tables produced by SAS or by the 'r2rtf' package, which are commonly used for clinical trial and regulatory reporting.

Author(s)

Maintainer: Ott Vahtrik ott.vahtrik@gmail.com

See Also

Useful links:

• https://github.com/ottvahtrik/otter

• https://ottvahtrik.github.io/otter/

• Report bugs at https://github.com/ottvahtrik/otter/issues

Extract table rows from a tokenized RTF stream

Description

State machine over the token vector produced by rtf_tokenize().

Usage

rtf_extract_tables(tokens, hex_encoding = "CP1252")

Arguments

Value

A list with three elements:

• header_rows / body_rows: lists of character vectors (one per row; one element per cell) with all tables merged – the existing single-table interface.

• all_tables: list of per-table list(header_rows, body_rows) for files that contain multiple logically distinct tables.

Parse an RTF file and extract table body cells into a data frame

Description

Reads an RTF file and returns a data.frame of the body cell values.

Usage

rtf_to_df(
  path,
  include_header = FALSE,
  header_row = NULL,
  encoding = "UTF-8",
  table_index = NULL
)

Arguments

Details

Header rows are detected automatically via ⁠\trhdr⁠ (explicit; Word/SAS) or via cell vertical-alignment hints (⁠\clvertalb⁠ / ⁠\clvertalt⁠) used by {r2rtf}.

When include_header = TRUE and no header rows are auto-detected, the first body row is promoted to column names and removed from the data (analogous to read.csv(header = TRUE)). Footnote and source rows are excluded by their cell count (they span the full table width as a single cell).

When an RTF file contains multiple logically distinct tables (separated by paragraph text), use table_index to select a specific one. The default (NULL) merges all tables into a single data frame, which is the correct behaviour for paginated single-table outputs.

Value

A data.frame with one row per body row and one column per cell. All values are character strings. Column names are V1, V2, ... unless include_header = TRUE.

Examples

path <- system.file("extdata", "example.rtf", package = "otter")
rtf_to_df(path)
rtf_to_df(path, include_header = TRUE)

multi_path <- system.file("extdata", "multi_table_example.rtf", package = "otter")
rtf_to_df(multi_path, include_header = TRUE, table_index = 2L)

Tokenize raw RTF text into a flat character vector

Description

Splits an RTF string into control words, control symbols, group braces, and plain-text runs. Newlines are not tokenized (they are insignificant whitespace in RTF between tokens).

Usage

rtf_tokenize(rtf_text)

Arguments

Value

A character vector; each element is one RTF token.