tt_row_path_exists: Pathing

In rtables: Reporting Tables

Pathing

Description

for tt_row_path_exists, tests whether a single path (potentially including "*" wildcards) resolves to at least one element satisfying tt_type (if specified).

Given a path with at least one wildcard ("*") in it, tt_normalize_path walks the tree and generates the complete set of fully specified (ie no wildcards) paths which exist in the row structure of obj

Usage

tt_row_path_exists(obj, path, tt_type = c("any", "row", "table", "elemtable"))

tt_normalize_row_path(
  obj,
  path,
  .prev_path = character(),
  tt_type = c("any", "row", "table", "elemtable")
)

Arguments

obj	(ANY) the object for the accessor to access or modify.
path	(character) a vector path for a position within the structure of a TableTree. Each element represents a subsequent choice amongst the children of the previous choice.
tt_type	(character(1)) One of "any", "row", "table", "elemtable"; when testing existence or resolving a path with "*" wildcards, this indicates a restriction on the final element the path resolves to. E.g., for "table", possible paths which match the structure of the wild-card path but resolve to an individual row will not be considered matching. The value "elemtable" indicates an Elementary table, i.e., one representing a single variable within an analyze call.
.prev_path	(character) Internal implementation detail. Do not set manually.

Details

Pathing is a method of using known structure within a table to specify elements within it in a self-describing, semantically meaningful way.

A Path consists of a character vector of one or more elements which will be used to descend the tree structure of a table's row or column space.

Existing paths will match the layout used to make the table in the form of split, split-value pairs corresponding to facets generated by ⁠split_rows_by*⁠ and, elementary subtables generated by analyze, and rows generated by the afun used. Groups summaries generated by summarize_row_groups are represented by the 'content table' attached to a subtable representing a facet generated by a split_rows_by instruction, and are addressed via ⁠@content⁠ instead of their name.

For example, given the code

lyt <- basic_table() |>
  split_rows_by("ARM") |>
  split_rows_by("RACE") |>
  summarize_row_groups() |>
  analyze("SEX") |>
  analyze("AGE", nested = FALSE)

tbl <- build_table(lyt, DM)

We know that there will be two top-level subtables, one representing (and generated via) the split on the ARM variable, and one generated from the non-nested analyze on AGE. These can be be 'pathed to' at "ARM" and "AGE", respectively. Furthermore each value for ARM can be pathed to via, e.g., c("ARM", "A: Drug X") or more generally using the pathing wildcard "*" at c("ARM", "*").

A particular SEX analysis subtable, then, would be pathed to via the (row) path c("ARM", "*", "RACE", "*", "SEX"), e.g. c("ARM", "B: Placebo", "RACE", "ASIAN", "SEX"). The group-summary for Asians within the placebo group would be pathed to via c("ARM", "B: Placebo", "RACE", "ASIAN", "@content") for the table, and c("ARM", "B: Placebo", "RACE", "ASIAN", "@content", "ASIAN") for the row.

Value

For tt_row_path_exists: TRUE if the path resolves to at least one substructure (subtable or row) that satisfies tt_type, or if the path is length 0; FALSE otherwise

for tt_normalize_row_path: a list of 0 or more fully specified paths which exist in the row structure of obj that match the original wildcard path, and which lead to an element of type tt_type (if specified other than ⁠"any")⁠.

Note

some pathing-based functionality supports the "*" wildcard (typically 'setters'/functionality which alters a table and returns it) while some does not (typically 'getters' which retrieve a subtable/row from a table or some attribute of that subtable/row).

The "*" wildcard will never act as "@content" to step into a subtable's content table; that must be specified in the path, via e.g., c("*", "*", "@content") instead of c("*", "*", "*").

Examples

lyt <- basic_table() |>
  split_rows_by("ARM") |>
  split_rows_by("STRATA1") |>
  analyze("SEX") |>
  analyze("SEX", nested = FALSE)
tbl <- build_table(lyt, DM)
tt_row_path_exists(tbl, c("root", "ARM", "*", "*", "*", "SEX")) # TRUE
tt_row_path_exists(tbl, c("ARM", "*", "*", "*", "SEX")) # TRUE
tt_row_path_exists(tbl, c("ARM", "*", "*", "SEX")) # FALSE
tt_row_path_exists(tbl, "FAKE") # FALSE
tt_row_path_exists(tbl, c("ARM", "*", "STRATA1", "*", "SEX")) # TRUE
tt_row_path_exists(tbl, c("ARM", "*", "STRATA", "*", "SEX")) # FALSE
tt_row_path_exists(tbl, "SEX") # TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "table") # TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "elemtable") # TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "row") # FALSE
tt_row_path_exists(tbl, c("SEX", "*")) # TRUE
tt_normalize_row_path(tbl, c("root", "ARM", "*", "*", "*", "SEX"))
tt_normalize_row_path(tbl, "SEX", tt_type = "row") # empty list

rtables documentation built on June 20, 2025, 1:09 a.m.