Skip to contents

Pathing

Source: R/tt_pos_and_access.R
tt_row_path_exists.Rd

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.

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").

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.

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
#> [1] TRUE
tt_row_path_exists(tbl, c("ARM", "*", "*", "*", "SEX")) # TRUE
#> [1] TRUE
tt_row_path_exists(tbl, c("ARM", "*", "*", "SEX")) # FALSE
#> [1] FALSE
tt_row_path_exists(tbl, "FAKE") # FALSE
#> [1] FALSE
tt_row_path_exists(tbl, c("ARM", "*", "STRATA1", "*", "SEX")) # TRUE
#> [1] TRUE
tt_row_path_exists(tbl, c("ARM", "*", "STRATA", "*", "SEX")) # FALSE
#> [1] FALSE
tt_row_path_exists(tbl, "SEX") # TRUE
#> [1] TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "table") # TRUE
#> [1] TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "elemtable") # TRUE
#> [1] TRUE
tt_row_path_exists(tbl, "SEX", tt_type = "row") # FALSE
#> [1] FALSE
tt_row_path_exists(tbl, c("SEX", "*")) # TRUE
#> [1] TRUE
tt_normalize_row_path(tbl, c("root", "ARM", "*", "*", "*", "SEX"))
#> $`A: Drug X.STRATA1.A`
#> [1] "root"      "ARM"       "A: Drug X" "STRATA1"   "A"         "SEX"      
#> 
#> $`A: Drug X.STRATA1.B`
#> [1] "root"      "ARM"       "A: Drug X" "STRATA1"   "B"         "SEX"      
#> 
#> $`A: Drug X.STRATA1.C`
#> [1] "root"      "ARM"       "A: Drug X" "STRATA1"   "C"         "SEX"      
#> 
#> $`B: Placebo.STRATA1.A`
#> [1] "root"       "ARM"        "B: Placebo" "STRATA1"    "A"         
#> [6] "SEX"       
#> 
#> $`B: Placebo.STRATA1.B`
#> [1] "root"       "ARM"        "B: Placebo" "STRATA1"    "B"         
#> [6] "SEX"       
#> 
#> $`B: Placebo.STRATA1.C`
#> [1] "root"       "ARM"        "B: Placebo" "STRATA1"    "C"         
#> [6] "SEX"       
#> 
#> $`C: Combination.STRATA1.A`
#> [1] "root"           "ARM"            "C: Combination" "STRATA1"       
#> [5] "A"              "SEX"           
#> 
#> $`C: Combination.STRATA1.B`
#> [1] "root"           "ARM"            "C: Combination" "STRATA1"       
#> [5] "B"              "SEX"           
#> 
#> $`C: Combination.STRATA1.C`
#> [1] "root"           "ARM"            "C: Combination" "STRATA1"       
#> [5] "C"              "SEX"           
#> 
tt_normalize_row_path(tbl, "SEX", tt_type = "row") # empty list
#> list()