Package 'rtables'

Description

Add the data derived column counts.

Usage

add_colcounts(lyt, format = "(N=xx)")

Arguments

Details

It is often the case that the the column counts derived from the input data to build_table() is not representative of the population counts. For example, if events are counted in the table and the header should display the number of subjects and not the total number of events.

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Author(s)

Gabriel Becker

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  split_rows_by("RACE", split_fun = drop_split_levels) %>%
  analyze("AGE", afun = function(x) list(min = min(x), max = max(x)))
lyt

tbl <- build_table(lyt, DM)
tbl

Description

Add a combination facet during the post-processing stage in a custom split fun.

Usage

add_combo_facet(name, label = name, levels, extra = list())

add_overall_facet(name, label, extra = list())

Arguments

Details

For add_combo_facet, the data associated with the resulting facet will be the data associated with the facets for each level in levels, row-bound together. In particular, this means that if those levels are overlapping, data that appears in both will be duplicated.

Value

A function which can be used within the post argument in make_split_fun().

See Also

make_split_fun()

Other make_custom_split: drop_facet_levels(), make_split_fun(), make_split_result(), trim_levels_in_facets()

Examples

mysplfun <- make_split_fun(post = list(
  add_combo_facet("A_B",
    label = "Arms A+B",
    levels = c("A: Drug X", "B: Placebo")
  ),
  add_overall_facet("ALL", label = "All Arms")
))

lyt <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM", split_fun = mysplfun) %>%
  analyze("AGE")

tbl <- build_table(lyt, DM)

Description

Add an already calculated table to the layout

Usage

add_existing_table(lyt, tt, indent_mod = 0)

Arguments

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Author(s)

Gabriel Becker

Examples

lyt1 <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = mean, format = "xx.xx")

tbl1 <- build_table(lyt1, DM)
tbl1

lyt2 <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = sd, format = "xx.xx") %>%
  add_existing_table(tbl1)

tbl2 <- build_table(lyt2, DM)
tbl2

table_structure(tbl2)
row_paths_summary(tbl2)

Description

This function will only add an overall column at the top level of splitting, NOT within existing column splits. See add_overall_level() for the recommended way to add overall columns more generally within existing splits.

Usage

add_overall_col(lyt, label)

Arguments

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

See Also

add_overall_level()

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_overall_col("All Patients") %>%
  analyze("AGE")
lyt

tbl <- build_table(lyt, DM)
tbl

Description

add_overall_level is a split function that adds a global level to the current levels in the split. Similarly, add_combo_df uses a user-provided data.frame to define the combine the levels to be added. If you need a single overall column, after all splits, please check add_overall_col(). Consider also defining your custom split function if you need more flexibility (see custom_split_funs).

Usage

add_overall_level(
  valname = "Overall",
  label = valname,
  extra_args = list(),
  first = TRUE,
  trim = FALSE
)

select_all_levels

add_combo_levels(combosdf, trim = FALSE, first = FALSE, keep_levels = NULL)

Arguments

Format

An object of class AllLevelsSentinel of length 0.

Value

A splitting function (splfun) that adds or changes the levels of a split.

Note

Analysis or summary functions for which the order matters should never be used within the tabulation framework.

See Also

custom_split_funs and split_funcs.

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM", split_fun = add_overall_level("All Patients",
    first = FALSE
  )) %>%
  analyze("AGE")

tbl <- build_table(lyt, DM)
tbl

lyt2 <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_rows_by("RACE",
    split_fun = add_overall_level("All Ethnicities")
  ) %>%
  summarize_row_groups(label_fstr = "%s (n)") %>%
  analyze("AGE")
lyt2

tbl2 <- build_table(lyt2, DM)
tbl2



library(tibble)
combodf <- tribble(
  ~valname, ~label, ~levelcombo, ~exargs,
  "A_B", "Arms A+B", c("A: Drug X", "B: Placebo"), list(),
  "A_C", "Arms A+C", c("A: Drug X", "C: Combination"), list()
)

lyt <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM", split_fun = add_combo_levels(combodf)) %>%
  analyze("AGE")

tbl <- build_table(lyt, DM)
tbl

lyt1 <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM",
    split_fun = add_combo_levels(combodf,
      keep_levels = c(
        "A_B",
        "A_C"
      )
    )
  ) %>%
  analyze("AGE")

tbl1 <- build_table(lyt1, DM)
tbl1

smallerDM <- droplevels(subset(DM, SEX %in% c("M", "F") &
  grepl("^(A|B)", ARM)))
lyt2 <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM", split_fun = add_combo_levels(combodf[1, ])) %>%
  split_cols_by("SEX",
    split_fun = add_overall_level("SEX_ALL", "All Genders")
  ) %>%
  analyze("AGE")

lyt3 <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM", split_fun = add_combo_levels(combodf)) %>%
  split_rows_by("SEX",
    split_fun = add_overall_level("SEX_ALL", "All Genders")
  ) %>%
  summarize_row_groups() %>%
  analyze("AGE")

tbl3 <- build_table(lyt3, smallerDM)
tbl3

Description

It is possible to add specific parameters to afun and cfun, in analyze() and summarize_row_groups(), respectively. These parameters grant access to relevant information like the row split structure (see spl_context) and the predefined baseline (.ref_group).

Details

We list and describe all the parameters that can be added to a custom analysis function below:

.N_col

Column-wise N (column count) for the full column being tabulated within.

.N_total

Overall N (all observation count, defined as sum of column counts) for the tabulation.

.N_row

Row-wise N (row group count) for the group of observations being analyzed (i.e. with no column-based subsetting).

.df_row

data.frame for observations in the row group being analyzed (i.e. with no column-based subsetting).

.var

Variable being analyzed.

.ref_group

data.frame or vector of subset corresponding to the ref_group column including subsetting defined by row-splitting. Only required/meaningful if a ref_group column has been defined.

.ref_full

data.frame or vector of subset corresponding to the ref_group column without subsetting defined by row-splitting. Only required/meaningful if a ref_group column has been defined.

.in_ref_col

Boolean indicating if calculation is done for cells within the reference column.

.spl_context

data.frame where each row gives information about a previous 'ancestor' split state. See spl_context.

.alt_df_row

data.frame, i.e. the alt_count_df after row splitting. It can be used with .all_col_exprs and .spl_context information to retrieve current faceting, but for alt_count_df. It can be an empty table if all the entries are filtered out.

.alt_df

data.frame, .alt_df_row but filtered by columns expression. This data present the same faceting of main data df. This also filters NAs out if related parameters are set to do so (e.g. inclNAs in analyze()). Similarly to .alt_df_row, it can be an empty table if all the entries are filtered out.

.all_col_exprs

List of expressions. Each of them represents a different column splitting.

.all_col_counts

Vector of integers. Each of them represents the global count for each column. It differs if alt_counts_df is used (see build_table()).

Note

If any of these formals is specified incorrectly or not present in the tabulation machinery, it will be treated as if missing. For example, .ref_group will be missing if no baseline is previously defined during data splitting (via ref_group parameters in, e.g., split_rows_by()). Similarly, if no alt_counts_df is provided to build_table(), .alt_df_row and .alt_df will not be present.

Description

Criteria functions (and constructors thereof) for trimming and pruning tables.

Usage

all_zero_or_na(tr)

all_zero(tr)

content_all_zeros_nas(tt, criteria = all_zero_or_na)

prune_empty_level(tt)

prune_zeros_only(tt)

low_obs_pruner(min, type = c("sum", "mean"))

Arguments

Details

all_zero_or_na returns TRUE (and thus indicates trimming/pruning) for any non-LabelRow TableRow which contain only any mix of NA (including NaN), 0, Inf and -Inf values.

all_zero returns TRUE for any non-LabelRow which contains only (non-missing) zero values.

content_all_zeros_nas prunes a subtable if both of the following are true:

• It has a content table with exactly one row in it.

• all_zero_or_na returns TRUE for that single content row. In practice, when the default summary/content function is used, this represents pruning any subtable which corresponds to an empty set of the input data (e.g. because a factor variable was used in split_rows_by() but not all levels were present in the data).

prune_empty_level combines all_zero_or_na behavior for TableRow objects, content_all_zeros_nas on content_table(tt) for TableTree objects, and an additional check that returns TRUE if the tt has no children.

prune_zeros_only behaves as prune_empty_level does, except that like all_zero it prunes only in the case of all non-missing zero values.

low_obs_pruner is a constructor function which, when called, returns a pruning criteria function which will prune on content rows by comparing sum or mean (dictated by type) of the count portions of the cell values (defined as the first value per cell regardless of how many values per cell there are) against min.

Value

A logical value indicating whether tr should be included (TRUE) or pruned (FALSE) during pruning.

See Also

prune_table(), trim_rows()

Examples

adsl <- ex_adsl
levels(adsl$SEX) <- c(levels(ex_adsl$SEX), "OTHER")
adsl$AGE[adsl$SEX == "UNDIFFERENTIATED"] <- 0
adsl$BMRKR1 <- 0

tbl_to_prune <- basic_table() %>%
  analyze("BMRKR1") %>%
  split_cols_by("ARM") %>%
  split_rows_by("SEX") %>%
  summarize_row_groups() %>%
  split_rows_by("STRATA1") %>%
  summarize_row_groups() %>%
  analyze("AGE") %>%
  build_table(adsl)

tbl_to_prune %>% prune_table(all_zero_or_na)

tbl_to_prune %>% prune_table(all_zero)

tbl_to_prune %>% prune_table(content_all_zeros_nas)

tbl_to_prune %>% prune_table(prune_empty_level)

tbl_to_prune %>% prune_table(prune_zeros_only)

min_prune <- low_obs_pruner(70, "sum")
tbl_to_prune %>% prune_table(min_prune)

Description

Adding analyzed variables to our table layout defines the primary tabulation to be performed. We do this by adding calls to analyze and/or analyze_colvars() into our layout pipeline. As with adding further splitting, the tabulation will occur at the current/next level of nesting by default.

Usage

analyze(
  lyt,
  vars,
  afun = simple_analysis,
  var_labels = vars,
  table_names = vars,
  format = NULL,
  na_str = NA_character_,
  nested = TRUE,
  inclNAs = FALSE,
  extra_args = list(),
  show_labels = c("default", "visible", "hidden"),
  indent_mod = 0L,
  section_div = NA_character_
)

Arguments

Details

When non-NULL, format is used to specify formats for all generated rows, and can be a character vector, a function, or a list of functions. It will be repped out to the number of rows once this is calculated during the tabulation process, but will be overridden by formats specified within rcell calls in afun.

The analysis function (afun) should take as its first parameter either x or df. Whichever of these the function accepts will change the behavior when tabulation is performed as follows:

• If afun's first parameter is x, it will receive the corresponding subset vector of data from the relevant column (from var here) of the raw data being used to build the table.

• If afun's first parameter is df, it will receive the corresponding subset data frame (i.e. all columns) of the raw data being tabulated.

In addition to differentiation on the first argument, the analysis function can optionally accept a number of other parameters which, if and only if present in the formals, will be passed to the function by the tabulation machinery. These are listed and described in additional_fun_params.

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Note

None of the arguments described in the Details section can be overridden via extra_args or when calling make_afun(). .N_col and .N_total can be overridden via the col_counts argument to build_table(). Alternative values for the others must be calculated within afun based on a combination of extra arguments and the unmodified values provided by the tabulation framework.

Author(s)

Gabriel Becker

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = list_wrap_x(summary), format = "xx.xx")
lyt

tbl <- build_table(lyt, DM)
tbl

lyt2 <- basic_table() %>%
  split_cols_by("Species") %>%
  analyze(head(names(iris), -1), afun = function(x) {
    list(
      "mean / sd" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"),
      "range" = rcell(diff(range(x)), format = "xx.xx")
    )
  })
lyt2

tbl2 <- build_table(lyt2, iris)
tbl2

Description

Generate rows analyzing different variables across columns

Usage

analyze_colvars(
  lyt,
  afun,
  format = NULL,
  na_str = NA_character_,
  nested = TRUE,
  extra_args = list(),
  indent_mod = 0L,
  inclNAs = FALSE
)

Arguments

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Author(s)

Gabriel Becker

See Also

split_cols_by_multivar()

Examples

library(dplyr)

ANL <- DM %>% mutate(value = rnorm(n()), pctdiff = runif(n()))

## toy example where we take the mean of the first variable and the
## count of >.5 for the second.
colfuns <- list(
  function(x) rcell(mean(x), format = "xx.x"),
  function(x) rcell(sum(x > .5), format = "xx")
)

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by_multivar(c("value", "pctdiff")) %>%
  split_rows_by("RACE",
    split_label = "ethnicity",
    split_fun = drop_split_levels
  ) %>%
  summarize_row_groups() %>%
  analyze_colvars(afun = colfuns)
lyt

tbl <- build_table(lyt, ANL)
tbl

lyt2 <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by_multivar(c("value", "pctdiff"),
    varlabels = c("Measurement", "Pct Diff")
  ) %>%
  split_rows_by("RACE",
    split_label = "ethnicity",
    split_fun = drop_split_levels
  ) %>%
  summarize_row_groups() %>%
  analyze_colvars(afun = mean, format = "xx.xx")

tbl2 <- build_table(lyt2, ANL)
tbl2

Description

Define a subset tabulation/analysis

Define a subset tabulation/analysis

Usage

AnalyzeVarSplit(
  var,
  split_label = var,
  afun,
  defrowlab = "",
  cfun = NULL,
  cformat = NULL,
  split_format = NULL,
  split_na_str = NA_character_,
  inclNAs = FALSE,
  split_name = var,
  extra_args = list(),
  indent_mod = 0L,
  label_pos = "default",
  cvar = "",
  section_div = NA_character_
)

AnalyzeColVarSplit(
  afun,
  defrowlab = "",
  cfun = NULL,
  cformat = NULL,
  split_format = NULL,
  split_na_str = NA_character_,
  inclNAs = FALSE,
  split_name = "",
  extra_args = list(),
  indent_mod = 0L,
  label_pos = "default",
  cvar = "",
  section_div = NA_character_
)

AnalyzeMultiVars(
  var,
  split_label = "",
  afun,
  defrowlab = "",
  cfun = NULL,
  cformat = NULL,
  split_format = NULL,
  split_na_str = NA_character_,
  inclNAs = FALSE,
  .payload = NULL,
  split_name = NULL,
  extra_args = list(),
  indent_mod = 0L,
  child_labels = c("default", "topleft", "visible", "hidden"),
  child_names = var,
  cvar = "",
  section_div = NA_character_
)

Arguments

Value

An AnalyzeVarSplit object.

An AnalyzeMultiVars split object.

Author(s)

Gabriel Becker

Description

This function adds newlines to the current set of "top-left materials".

Usage

append_topleft(lyt, newlines)

Arguments

Details

Adds newlines to the set of strings representing the 'top-left' materials declared in the layout (the content displayed to the left of the column labels when the resulting tables are printed).

Top-left material strings are stored and then displayed exactly as is, no structure or indenting is applied to them either when they are added or when they are displayed.

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Note

Currently, where in the construction of the layout this is called makes no difference, as it is independent of the actual splitting keywords. This may change in the future.

This function is experimental, its name and the details of its behavior are subject to change in future versions.

See Also

top_left()

Examples

library(dplyr)

DM2 <- DM %>% mutate(RACE = factor(RACE), SEX = factor(SEX))

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("SEX") %>%
  split_rows_by("RACE") %>%
  append_topleft("Ethnicity") %>%
  analyze("AGE") %>%
  append_topleft("  Age")

tbl <- build_table(lyt, DM2)
tbl

Description

The returned HTML object can be immediately used in shiny and rmarkdown.

Usage

as_html(
  x,
  width = NULL,
  class_table = "table table-condensed table-hover",
  class_tr = NULL,
  class_th = NULL,
  link_label = NULL,
  bold = c("header"),
  header_sep_line = TRUE,
  no_spaces_between_cells = FALSE,
  expand_newlines = FALSE
)

Arguments

Value

A shiny.tag object representing x in HTML.

Examples

tbl <- rtable(
  header = LETTERS[1:3],
  format = "xx",
  rrow("r1", 1, 2, 3),
  rrow("r2", 4, 3, 2, indent = 1),
  rrow("r3", indent = 2)
)

as_html(tbl)

as_html(tbl, class_table = "table", class_tr = "row")

as_html(tbl, bold = c("header", "row_names"))

## Not run: 
Viewer(tbl)

## End(Not run)

Description

Convert an rtables framework object into a vector, if possible. This is unlikely to be useful in realistic scenarios.

Usage

## S4 method for signature 'VTableTree'
as.vector(x, mode = "any")

Arguments

Value

A vector of the chosen mode (or an error is raised if more than one row was present).

Note

This only works for a table with a single row or a row object.

Description

Every layout must start with a basic table.

Usage

basic_table(
  title = "",
  subtitles = character(),
  main_footer = character(),
  prov_footer = character(),
  show_colcounts = NA,
  colcount_format = "(N=xx)",
  header_section_div = NA_character_,
  top_level_section_div = NA_character_,
  inset = 0L
)

Arguments

Details

colcount_format is ignored if show_colcounts is FALSE (the default). When show_colcounts is TRUE, and colcount_format is 2-dimensional with a percent component, the value component for the percent is always populated with 1 (i.e. 100%). 1d formats are used to render the counts exactly as they normally would be, while 2d formats which don't include a percent, and all 3d formats result in an error. Formats in the form of functions are not supported for colcount format. See formatters::list_valid_format_labels() for the list of valid format labels to select from.

Value

A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().

Note

• Because percent components in colcount_format are always populated with the value 1, we can get arguably strange results, such as that individual arm columns and a combined "all patients" column all list "100%" as their percentage, even though the individual arm columns represent strict subsets of the "all patients" column.

• Note that subtitles (formatters::subtitles()) and footers (formatters::main_footer() and formatters::prov_footer()) that span more than one line can be supplied as a character vector to maintain indentation on multiple lines.

Examples

lyt <- basic_table() %>%
  analyze("AGE", afun = mean)

tbl <- build_table(lyt, DM)
tbl

lyt2 <- basic_table(
  title = "Title of table",
  subtitles = c("a number", "of subtitles"),
  main_footer = "test footer",
  prov_footer = paste(
    "test.R program, executed at",
    Sys.time()
  )
) %>%
  split_cols_by("ARM") %>%
  analyze("AGE", mean)

tbl2 <- build_table(lyt2, DM)
tbl2

lyt3 <- basic_table(
  show_colcounts = TRUE,
  colcount_format = "xx. (xx.%)"
) %>%
  split_cols_by("ARM")

Description

Retrieve and assign elements of a TableTree

Usage

## S4 replacement method for signature 'VTableTree,ANY,ANY,list'
x[i, j, ...] <- value

## S4 method for signature 'VTableTree,logical,logical'
x[i, j, ..., drop = FALSE]

Arguments

Details

By default, subsetting drops the information about title, subtitle, main footer, provenance footer, and topleft. If only a column is selected and all rows are kept, the topleft information remains as default. Any referential footnote is kept whenever the subset table contains the referenced element.

Value

A TableTree (or ElementaryTable) object, unless a single cell was selected with drop = TRUE, in which case the (possibly multi-valued) fully stripped raw value of the selected cell.

Note

Subsetting always preserve the original order, even if provided indexes do not preserve it. If sorting is needed, please consider using sort_at_path(). Also note that character indices are treated as paths, not vectors of names in both [ and ⁠[<-⁠.

See Also

• sort_at_path() to understand sorting.

• summarize_row_groups() to understand path structure.

Examples

lyt <- basic_table(
  title = "Title",
  subtitles = c("Sub", "titles"),
  prov_footer = "prov footer",
  main_footer = "main footer"
) %>%
  split_cols_by("ARM") %>%
  split_rows_by("SEX") %>%
  analyze(c("AGE"))

tbl <- build_table(lyt, DM)
top_left(tbl) <- "Info"
tbl

# As default header, footer, and topleft information is lost
tbl[1, ]
tbl[1:2, 2]

# Also boolean filters can work
tbl[, c(FALSE, TRUE, FALSE)]

# If drop = TRUE, the content values are directly retrieved
tbl[2, 1]
tbl[2, 1, drop = TRUE]

# Drop works also if vectors are selected, but not matrices
tbl[, 1, drop = TRUE]
tbl[2, , drop = TRUE]
tbl[1, 1, drop = TRUE] # NULL because it is a label row
tbl[2, 1:2, drop = TRUE] # vectors can be returned only with cell_values()
tbl[1:2, 1:2, drop = TRUE] # no dropping because it is a matrix

# If all rows are selected, topleft is kept by default
tbl[, 2]
tbl[, 1]

# It is possible to deselect values
tbl[-2, ]
tbl[, -1]

# Values can be reassigned
tbl[2, 1] <- rcell(999)
tbl[2, ] <- list(rrow("FFF", 888, 666, 777))
tbl[6, ] <- list(-111, -222, -333)
tbl

# We can keep some information from the original table if we need
tbl[1, 2, keep_titles = TRUE]
tbl[1, 2, keep_footers = TRUE, keep_titles = FALSE]
tbl[1, 2, keep_footers = FALSE, keep_titles = TRUE]
tbl[1, 2, keep_footers = TRUE]
tbl[1, 2, keep_topleft = TRUE]

# Keeps the referential footnotes when subset contains them
fnotes_at_path(tbl, rowpath = c("SEX", "M", "AGE", "Mean")) <- "important"
tbl[4, 1]
tbl[2, 1] # None present

# We can reindex referential footnotes, so that the new table does not depend
#  on the original one
fnotes_at_path(tbl, rowpath = c("SEX", "U", "AGE", "Mean")) <- "important"
tbl[, 1] # both present
tbl[5:6, 1] # {1} because it has been indexed again
tbl[5:6, 1, reindex_refs = FALSE] # {2} -> not reindexed

# Note that order can not be changed with subsetting
tbl[c(4, 3, 1), c(3, 1)] # It preserves order and wanted selection

Description

Layouts are used to describe a table pre-data. build_table is used to create a table using a layout and a dataset.

Usage

build_table(
  lyt,
  df,
  alt_counts_df = NULL,
  col_counts = NULL,
  col_total = if (is.null(alt_counts_df)) nrow(df) else nrow(alt_counts_df),
  topleft = NULL,
  hsep = default_hsep(),
  ...
)

Arguments

Details

When alt_counts_df is specified, column counts are calculated by applying the exact column subsetting expressions determined when applying column splitting to the main data (df) to alt_counts_df and counting the observations in each resulting subset.

In particular, this means that in the case of splitting based on cuts of the data, any dynamic cuts will have been calculated based on df and simply re-used for the count calculation.

Value

A TableTree or ElementaryTable object representing the table created by performing the tabulations declared in lyt to the data df.

Note

When overriding the column counts or totals care must be taken that, e.g., length() or nrow() are not called within tabulation functions, because those will NOT give the overridden counts. Writing/using tabulation functions which accept .N_col and .N_total or do not rely on column counts at all (even implicitly) is the only way to ensure overridden counts are fully respected.

Author(s)

Gabriel Becker

Examples

lyt <- basic_table() %>%
  split_cols_by("Species") %>%
  analyze("Sepal.Length", afun = function(x) {
    list(
      "mean (sd)" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"),
      "range" = diff(range(x))
    )
  })
lyt

tbl <- build_table(lyt, iris)
tbl

# analyze multiple variables
lyt2 <- basic_table() %>%
  split_cols_by("Species") %>%
  analyze(c("Sepal.Length", "Petal.Width"), afun = function(x) {
    list(
      "mean (sd)" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"),
      "range" = diff(range(x))
    )
  })

tbl2 <- build_table(lyt2, iris)
tbl2

# an example more relevant for clinical trials with column counts
lyt3 <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = function(x) {
    setNames(as.list(fivenum(x)), c(
      "minimum", "lower-hinge", "median",
      "upper-hinge", "maximum"
    ))
  })

tbl3 <- build_table(lyt3, DM)
tbl3

tbl4 <- build_table(lyt3, subset(DM, AGE > 40))
tbl4

# with column counts calculated based on different data
miniDM <- DM[sample(1:NROW(DM), 100), ]
tbl5 <- build_table(lyt3, DM, alt_counts_df = miniDM)
tbl5

tbl6 <- build_table(lyt3, DM, col_counts = 1:3)
tbl6

Description

Column-bind two TableTree objects

Usage

cbind_rtables(x, ..., sync_count_vis = TRUE)

Arguments

Value

A formal table object.

Examples

x <- rtable(c("A", "B"), rrow("row 1", 1, 2), rrow("row 2", 3, 4))
y <- rtable("C", rrow("row 1", 5), rrow("row 2", 6))
z <- rtable("D", rrow("row 1", 9), rrow("row 2", 10))

t1 <- cbind_rtables(x, y)
t1

t2 <- cbind_rtables(x, y, z)
t2

col_paths_summary(t1)
col_paths_summary(t2)

Description

Retrieve cell values by row and column path

Usage

cell_values(tt, rowpath = NULL, colpath = NULL, omit_labrows = TRUE)

value_at(tt, rowpath = NULL, colpath = NULL)

## S4 method for signature 'VTableTree'
value_at(tt, rowpath = NULL, colpath = NULL)

Arguments

Value

• cell_values returns a list (regardless of the type of value the cells hold). If rowpath defines a path to a single row, cell_values returns the list of cell values for that row, otherwise a list of such lists, one for each row captured underneath rowpath. This occurs after subsetting to colpath has occurred.

• value_at returns the "unwrapped" value of a single cell, or an error, if the combination of rowpath and colpath do not define the location of a single cell in tt.

Note

cell_values will return a single cell's value wrapped in a list. Use value_at to receive the "bare" cell value.

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("SEX") %>%
  split_rows_by("RACE") %>%
  summarize_row_groups() %>%
  split_rows_by("STRATA1") %>%
  analyze("AGE")


library(dplyr) ## for mutate
tbl <- build_table(lyt, DM %>%
  mutate(SEX = droplevels(SEX), RACE = droplevels(RACE)))

row_paths_summary(tbl)
col_paths_summary(tbl)

cell_values(
  tbl, c("RACE", "ASIAN", "STRATA1", "B"),
  c("ARM", "A: Drug X", "SEX", "F")
)

# it's also possible to access multiple values by being less specific
cell_values(
  tbl, c("RACE", "ASIAN", "STRATA1"),
  c("ARM", "A: Drug X", "SEX", "F")
)
cell_values(tbl, c("RACE", "ASIAN"), c("ARM", "A: Drug X", "SEX", "M"))

## any arm, male columns from the ASIAN content (i.e. summary) row
cell_values(
  tbl, c("RACE", "ASIAN", "@content"),
  c("ARM", "B: Placebo", "SEX", "M")
)
cell_values(
  tbl, c("RACE", "ASIAN", "@content"),
  c("ARM", "*", "SEX", "M")
)

## all columns
cell_values(tbl, c("RACE", "ASIAN", "STRATA1", "B"))

## all columns for the Combination arm
cell_values(
  tbl, c("RACE", "ASIAN", "STRATA1", "B"),
  c("ARM", "C: Combination")
)

cvlist <- cell_values(
  tbl, c("RACE", "ASIAN", "STRATA1", "B", "AGE", "Mean"),
  c("ARM", "B: Placebo", "SEX", "M")
)
cvnolist <- value_at(
  tbl, c("RACE", "ASIAN", "STRATA1", "B", "AGE", "Mean"),
  c("ARM", "B: Placebo", "SEX", "M")
)
stopifnot(identical(cvlist[[1]], cvnolist))

Description

Constructor for Cell Value

Usage

CellValue(
  val,
  format = NULL,
  colspan = 1L,
  label = NULL,
  indent_mod = NULL,
  footnotes = NULL,
  align = NULL,
  format_na_str = NULL
)

Arguments

Value

An object representing the value within a single cell within a populated table. The underlying structure of this object is an implementation detail and should not be relied upon beyond calling accessors for the class.

Description

Column information/structure accessors

Usage

clayout(obj)

## S4 method for signature 'VTableNodeInfo'
clayout(obj)

## S4 method for signature 'PreDataTableLayouts'
clayout(obj)

## S4 method for signature 'ANY'
clayout(obj)

clayout(object) <- value

## S4 replacement method for signature 'PreDataTableLayouts'
clayout(object) <- value

col_info(obj)

## S4 method for signature 'VTableNodeInfo'
col_info(obj)

col_info(obj) <- value

## S4 replacement method for signature 'TableRow'
col_info(obj) <- value

## S4 replacement method for signature 'ElementaryTable'
col_info(obj) <- value

## S4 replacement method for signature 'TableTree'
col_info(obj) <- value

coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'InstantiatedColumnInfo'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'PreDataTableLayouts'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'PreDataColLayout'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'LayoutColTree'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'VTableTree'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

## S4 method for signature 'TableRow'
coltree(
  obj,
  df = NULL,
  rtpos = TreePos(),
  alt_counts_df = df,
  ccount_format = "(N=xx)"
)

col_exprs(obj, df = NULL)

## S4 method for signature 'PreDataTableLayouts'
col_exprs(obj, df = NULL)

## S4 method for signature 'PreDataColLayout'
col_exprs(obj, df = NULL)

## S4 method for signature 'InstantiatedColumnInfo'
col_exprs(obj, df = NULL)

col_counts(obj, path = NULL)

## S4 method for signature 'InstantiatedColumnInfo'
col_counts(obj, path = NULL)

## S4 method for signature 'VTableNodeInfo'
col_counts(obj, path = NULL)

col_counts(obj, path = NULL) <- value

## S4 replacement method for signature 'InstantiatedColumnInfo'
col_counts(obj, path = NULL) <- value

## S4 replacement method for signature 'VTableNodeInfo'
col_counts(obj, path = NULL) <- value

col_total(obj)

## S4 method for signature 'InstantiatedColumnInfo'
col_total(obj)

## S4 method for signature 'VTableNodeInfo'
col_total(obj)

col_total(obj) <- value

## S4 replacement method for signature 'InstantiatedColumnInfo'
col_total(obj) <- value

## S4 replacement method for signature 'VTableNodeInfo'
col_total(obj) <- value

Arguments

Value

A LayoutColTree object.

Returns various information about columns, depending on the accessor used.

See Also

facet_colcount()

Description

Clear all indent modifiers from a table

Usage

clear_indent_mods(tt)

## S4 method for signature 'VTableTree'
clear_indent_mods(tt)

## S4 method for signature 'TableRow'
clear_indent_mods(tt)

Arguments

Value

The same class as tt, with all indent modifiers set to zero.

Examples

lyt1 <- basic_table() %>%
  summarize_row_groups("STUDYID", label_fstr = "overall summary") %>%
  split_rows_by("AEBODSYS", child_labels = "visible") %>%
  summarize_row_groups("STUDYID", label_fstr = "subgroup summary") %>%
  analyze("AGE", indent_mod = -1L)

tbl1 <- build_table(lyt1, ex_adae)
tbl1
clear_indent_mods(tbl1)

Description

Value and Visibility of specific column counts by path

Usage

colcount_visible(obj, path)

## S4 method for signature 'VTableTree'
colcount_visible(obj, path)

## S4 method for signature 'InstantiatedColumnInfo'
colcount_visible(obj, path)

## S4 method for signature 'LayoutColTree'
colcount_visible(obj, path)

colcount_visible(obj, path) <- value

## S4 replacement method for signature 'VTableTree'
colcount_visible(obj, path) <- value

## S4 replacement method for signature 'InstantiatedColumnInfo'
colcount_visible(obj, path) <- value

## S4 replacement method for signature 'LayoutColTree'
colcount_visible(obj, path) <- value

Arguments

Value

for colcount_visible a logical scalar indicating whether the specified position in the column hierarchy is set to display its column count; for ⁠colcount_visible<-⁠, obj updated with the specified count displaying behavior set.

Note

Users generally should not call colcount_visible directly, as setting sibling facets to have differing column count visibility will result in an error when printing or paginating the table.

Description

Collect leaves of a TableTree

Usage

collect_leaves(tt, incl.cont = TRUE, add.labrows = FALSE)

Arguments

Value

A list of TableRow objects for all rows in the table.

Description

Displays the tree structure of the columns of a table or column structure object.

Usage

coltree_structure(obj)

Arguments

Value

Nothing, called for its side effect of displaying a summary to the terminal.

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("STRATA1") %>%
  split_cols_by("SEX", nested = FALSE) %>%
  analyze("AGE")

tbl <- build_table(lyt, ex_adsl)
coltree_structure(tbl)

Description

Prints a matrix where . means cell matches, X means cell does not match, + cell (row) is missing, and - cell (row) should not be there. If structure is set to TRUE, C indicates column-structure mismatch, R indicates row-structure mismatch, and S indicates mismatch in both row and column structure.

Usage

compare_rtables(
  object,
  expected,
  tol = 0.1,
  comp.attr = TRUE,
  structure = FALSE
)

Arguments

Value

A matrix of class rtables_diff representing the differences between object and expected as described above.

Note

In its current form, compare_rtables does not take structure into account, only row and cell position.

Examples

t1 <- rtable(header = c("A", "B"), format = "xx", rrow("row 1", 1, 2))
t2 <- rtable(header = c("A", "B", "C"), format = "xx", rrow("row 1", 1, 2, 3))

compare_rtables(object = t1, expected = t2)

if (interactive()) {
  Viewer(t1, t2)
}

expected <- rtable(
  header = c("ARM A\nN=100", "ARM B\nN=200"),
  format = "xx",
  rrow("row 1", 10, 15),
  rrow(),
  rrow("section title"),
  rrow("row colspan", rcell(c(.345543, .4432423), colspan = 2, format = "(xx.xx, xx.xx)"))
)

expected

object <- rtable(
  header = c("ARM A\nN=100", "ARM B\nN=200"),
  format = "xx",
  rrow("row 1", 10, 15),
  rrow("section title"),
  rrow("row colspan", rcell(c(.345543, .4432423), colspan = 2, format = "(xx.xx, xx.xx)"))
)

compare_rtables(object, expected, comp.attr = FALSE)

object <- rtable(
  header = c("ARM A\nN=100", "ARM B\nN=200"),
  format = "xx",
  rrow("row 1", 10, 15),
  rrow(),
  rrow("section title")
)

compare_rtables(object, expected)

object <- rtable(
  header = c("ARM A\nN=100", "ARM B\nN=200"),
  format = "xx",
  rrow("row 1", 14, 15.03),
  rrow(),
  rrow("section title"),
  rrow("row colspan", rcell(c(.345543, .4432423), colspan = 2, format = "(xx.xx, xx.xx)"))
)

compare_rtables(object, expected)

object <- rtable(
  header = c("ARM A\nN=100", "ARM B\nN=200"),
  format = "xx",
  rrow("row 1", 10, 15),
  rrow(),
  rrow("section title"),
  rrow("row colspan", rcell(c(.345543, .4432423), colspan = 2, format = "(xx.x, xx.x)"))
)

compare_rtables(object, expected)

Description

Compatibility argument conventions

Usage

compat_args(.lst, row.name, format, indent, label, inset)

Arguments

Value

No return value.

See Also

Other conventions: constr_args(), gen_args(), lyt_args(), sf_args()

Description

Score functions for sorting TableTrees

Usage

cont_n_allcols(tt)

cont_n_onecol(j)

Arguments

Value

A single numeric value indicating score according to the relevant metric for tt, to be used when sorting.

See Also

For examples and details, please read the documentation for sort_at_path() and the Sorting and Pruning vignette.

Description

Returns the content table of obj if it is a TableTree object, or NULL otherwise.

Usage

content_table(obj)

content_table(obj) <- value

Arguments

Value

the ElementaryTable containing the (top level) content rows of obj (or NULL if obj is not a formal table object).

Description

Analysis function to count levels of a factor with percentage of the column total

Usage

counts_wpcts(x, .N_col)

Arguments

Value

A RowsVerticalSection object with counts (and percents) for each level of the factor.

Examples

counts_wpcts(DM$SEX, 400)

Description

Split functions provide the work-horse for rtables's generalized partitioning. These functions accept a (sub)set of incoming data and a split object, and return "splits" of that data.

Custom Splitting Function Details

User-defined custom split functions can perform any type of computation on the incoming data provided that they meet the requirements for generating "splits" of the incoming data based on the split object.

Split functions are functions that accept:

df

a data.frame of incoming data to be split.

spl

a Split object. This is largely an internal detail custom functions will not need to worry about, but obj_name(spl), for example, will give the name of the split as it will appear in paths in the resulting table.

vals

any pre-calculated values. If given non-NULL values, the values returned should match these. Should be NULL in most cases and can usually be ignored.

labels

any pre-calculated value labels. Same as above for values.

trim

if TRUE, resulting splits that are empty are removed.

(optional) .spl_context

a data.frame describing previously performed splits which collectively arrived at df.

The function must then output a named list with the following elements:

values

the vector of all values corresponding to the splits of df.

datasplit

a list of data.frames representing the groupings of the actual observations from df.

labels

a character vector giving a string label for each value listed in the values element above.

(optional) extras

if present, extra arguments are to be passed to summary and analysis functions whenever they are executed on the corresponding element of datasplit or a subset thereof.

One way to generate custom splitting functions is to wrap existing split functions and modify either the incoming data before they are called or their outputs.

See Also

make_split_fun() for the API for creating custom split functions, and split_funcs for a variety of pre-defined split functions.

Examples

# Example of a picky split function. The number of values in the column variable
# var decrees if we are going to print also the column with all observation
# or not.

picky_splitter <- function(var) {
  # Main layout function
  function(df, spl, vals, labels, trim) {
    orig_vals <- vals

    # Check for number of levels if all are selected
    if (is.null(vals)) {
      vec <- df[[var]]
      vals <- unique(vec)
    }

    # Do a split with or without All obs
    if (length(vals) == 1) {
      do_base_split(spl = spl, df = df, vals = vals, labels = labels, trim = trim)
    } else {
      fnc_tmp <- add_overall_level("Overall", label = "All Obs", first = FALSE)
      fnc_tmp(df = df, spl = spl, vals = orig_vals, trim = trim)
    }
  }
}

# Data sub-set
d1 <- subset(ex_adsl, ARM == "A: Drug X" | (ARM == "B: Placebo" & SEX == "F"))
d1 <- subset(d1, SEX %in% c("M", "F"))
d1$SEX <- factor(d1$SEX)

# This table uses the number of values in the SEX column to add the overall col or not
lyt <- basic_table() %>%
  split_cols_by("ARM", split_fun = drop_split_levels) %>%
  split_cols_by("SEX", split_fun = picky_splitter("SEX")) %>%
  analyze("AGE", show_labels = "visible")
tbl <- build_table(lyt, d1)
tbl

Description

Collection of utilities to extract data.frame objects from TableTree objects.

Usage

as_result_df(tt, spec = "v0_experimental", simplify = FALSE, ...)

result_df_specs()

path_enriched_df(tt, path_fun = collapse_path, value_fun = collapse_values)

Arguments

Details

as_result_df(): Result data frame specifications may differ in the exact information they include and the form in which they represent it. Specifications whose names end in "_experimental" are subject to change without notice, but specifications without the "_experimental" suffix will remain available including any bugs in their construction indefinitely.

Value

• as_result_df returns a result data.frame.

• result_df_specs() returns a named list of result data frame extraction functions by "specification".

• path_enriched_df() returns a data.frame of tt's cell values (processed by value_fun, with columns named by the full column paths (processed by path_fun and an additional row_path column with the row paths (processed by path_fun).

Functions

• result_df_specs(): A list of functions that extract result data frames from TableTrees.

• path_enriched_df(): Transform a TableTree object to a path-enriched data.frame.

See Also

df_to_tt() when using as_is = TRUE and formatters::make_row_df() to have a comprehensive view of the hierarchical structure of the rows.

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_rows_by("STRATA1") %>%
  analyze(c("AGE", "BMRKR2"))

tbl <- build_table(lyt, ex_adsl)
as_result_df(tbl)

result_df_specs()

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze(c("AGE", "BMRKR2"))

tbl <- build_table(lyt, ex_adsl)
path_enriched_df(tbl)

Description

Create an ElementaryTable from a data.frame

Usage

df_to_tt(df)

Arguments

Details

If row names are not defined in df (or they are simple numbers), then the row names are taken from the column label_name, if it exists. If label_name exists, then it is also removed from the original data. This behavior is compatible with as_result_df(), when as_is = TRUE and the row names are not unique.

See Also

as_result_df() for the inverse operation.

Examples

df_to_tt(mtcars)

Description

This function is intended for use inside custom split functions. It applies the current split as if it had no custom splitting function so that those default splits can be further manipulated.

Usage

do_base_split(spl, df, vals = NULL, labels = NULL, trim = FALSE)

Arguments

Value

The result of the split being applied as if it had no custom split function. See custom_split_funs.

Examples

uneven_splfun <- function(df, spl, vals = NULL, labels = NULL, trim = FALSE) {
  ret <- do_base_split(spl, df, vals, labels, trim)
  if (NROW(df) == 0) {
    ret <- lapply(ret, function(x) x[1])
  }
  ret
}

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by_multivar(c("USUBJID", "AESEQ", "BMRKR1"),
    varlabels = c("N", "E", "BMR1"),
    split_fun = uneven_splfun
  ) %>%
  analyze_colvars(list(
    USUBJID = function(x, ...) length(unique(x)),
    AESEQ = max,
    BMRKR1 = mean
  ))

tbl <- build_table(lyt, subset(ex_adae, as.numeric(ARM) <= 2))
tbl

Description

This function is intended for use as a pre-processing component in make_split_fun, and should not be called directly by end users.

Usage

drop_facet_levels(df, spl, ...)

Arguments

See Also

make_split_fun()

Other make_custom_split: add_combo_facet(), make_split_fun(), make_split_result(), trim_levels_in_facets()

Description

TableTree classes

Table constructors and classes

Usage

ElementaryTable(
  kids = list(),
  name = "",
  lev = 1L,
  label = "",
  labelrow = LabelRow(lev = lev, label = label, vis = !isTRUE(iscontent) && !is.na(label)
    && nzchar(label)),
  rspans = data.frame(),
  cinfo = NULL,
  iscontent = NA,
  var = NA_character_,
  format = NULL,
  na_str = NA_character_,
  indent_mod = 0L,
  title = "",
  subtitles = character(),
  main_footer = character(),
  prov_footer = character(),
  header_section_div = NA_character_,
  hsep = default_hsep(),
  trailing_section_div = NA_character_,
  inset = 0L
)

TableTree(
  kids = list(),
  name = if (!is.na(var)) var else "",
  cont = EmptyElTable,
  lev = 1L,
  label = name,
  labelrow = LabelRow(lev = lev, label = label, vis = nrow(cont) == 0 && !is.na(label) &&
    nzchar(label)),
  rspans = data.frame(),
  iscontent = NA,
  var = NA_character_,
  cinfo = NULL,
  format = NULL,
  na_str = NA_character_,
  indent_mod = 0L,
  title = "",
  subtitles = character(),
  main_footer = character(),
  prov_footer = character(),
  page_title = NA_character_,
  hsep = default_hsep(),
  header_section_div = NA_character_,
  trailing_section_div = NA_character_,
  inset = 0L
)

Arguments

Value

A formal object representing a populated table.

Author(s)

Gabriel Becker

Description

Empty objects of various types to compare against efficiently.

Description

From a table, produce a self-contained word document or attach it to a template word file (template_file). This function is based on the tt_to_flextable() transformer and the officer package.

Usage

export_as_docx(
  tt,
  file,
  doc_metadata = NULL,
  titles_as_header = FALSE,
  footers_as_text = TRUE,
  template_file = NULL,
  section_properties = section_properties_default(),
  ...
)

section_properties_default(
  page_size = c("letter", "A4"),
  orientation = c("portrait", "landscape")
)

margins_potrait()

margins_landscape()

Arguments

Functions

• section_properties_default(): Helper function that defines standard portrait properties for tables.

• margins_potrait(): Helper function that defines standard portrait margins for tables.

• margins_landscape(): Helper function that defines standard landscape margins for tables.

Note

export_as_docx() has few customization options available. If you require specific formats and details, we suggest that you use tt_to_flextable() prior to export_as_docx. Only the titles_as_header and footer_as_text parameters must be re-specified if the table is changed first using tt_to_flextable().

See Also

tt_to_flextable()

Examples

library(flextable)
lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze(c("AGE", "BMRKR2", "COUNTRY"))

tbl <- build_table(lyt, ex_adsl)

# See how section_properties_portrait function is built for custom
tf <- tempfile(fileext = ".docx")
export_as_docx(tbl,
  file = tf,
  section_properties = section_properties_default(orientation = "landscape")
)

Description

This function creates a flat tabular file of cell values and corresponding paths via path_enriched_df(). It then writes that data frame out as a tsv file.

Usage

export_as_tsv(
  tt,
  file = NULL,
  path_fun = collapse_path,
  value_fun = collapse_values,
  sep = "\t",
  ...
)

import_from_tsv(file)

Arguments

Details

By default (i.e. when value_func is not specified, list columns where at least one value has length > 1 are collapsed to character vectors by collapsing the list element with "|".

Value

• export_as_tsv returns NULL silently.

• import_from_tsv returns a data.frame with re-constituted list values.

Note

There is currently no round-trip capability for this type of export. You can read values exported this way back in via import_from_tsv but you will receive only the data.frame version back, NOT a TableTree.

See Also

path_enriched_df() for the underlying function that does the work.

Description

Get or set column count for a facet in column space

Usage

facet_colcount(obj, path)

## S4 method for signature 'LayoutColTree'
facet_colcount(obj, path = NULL)

## S4 method for signature 'LayoutColLeaf'
facet_colcount(obj, path = NULL)

## S4 method for signature 'VTableTree'
facet_colcount(obj, path)

## S4 method for signature 'InstantiatedColumnInfo'
facet_colcount(obj, path)

facet_colcount(obj, path) <- value

## S4 replacement method for signature 'LayoutColTree'
facet_colcount(obj, path) <- value

## S4 replacement method for signature 'LayoutColLeaf'
facet_colcount(obj, path) <- value

## S4 replacement method for signature 'VTableTree'
facet_colcount(obj, path) <- value

## S4 replacement method for signature 'InstantiatedColumnInfo'
facet_colcount(obj, path) <- value

Arguments

Value

for facet_colcount the current count associated with that facet in column space, for ⁠facet_colcount<-⁠, obj modified with the new column count for the specified facet.

Note

Updating a lower-level (more specific) column count manually will not update the counts for its parent facets. This cannot be made automatic because the rtables framework does not require sibling facets to be mutually exclusive (e.g., total "arm", faceting into cumulative quantiles, etc) and thus the count of a parent facet will not always be simply the sum of the counts for all of its children.

See Also

col_counts()

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM", show_colcounts = TRUE) %>%
  split_cols_by("SEX",
    split_fun = keep_split_levels(c("F", "M")),
    show_colcounts = TRUE
  ) %>%
  split_cols_by("STRATA1", show_colcounts = TRUE) %>%
  analyze("AGE")

tbl <- build_table(lyt, ex_adsl)

facet_colcount(tbl, c("ARM", "A: Drug X"))
facet_colcount(tbl, c("ARM", "A: Drug X", "SEX", "F"))
facet_colcount(tbl, c("ARM", "A: Drug X", "SEX", "F", "STRATA1", "A"))

## modify specific count after table creation
facet_colcount(tbl, c("ARM", "A: Drug X", "SEX", "F", "STRATA1", "A")) <- 25

## show black space for certain counts by assign NA

facet_colcount(tbl, c("ARM", "A: Drug X", "SEX", "F", "STRATA1", "C")) <- NA

Description

Set visibility of column counts for a group of sibling facets

Usage

facet_colcounts_visible(obj, path) <- value

Arguments

Value

obj, modified with the desired column count. display behavior

See Also

colcount_visible()

Description

This function returns a list with the row-paths to all structural subtables which contain no data rows (even if they have associated content rows).

Usage

find_degen_struct(tt)

Arguments

Value

A list of character vectors representing the row paths, if any, to degenerate substructures within the table.

See Also

Other table structure validation functions: sanitize_table_struct(), validate_table_struct()

Examples

find_degen_struct(rtable("hi"))

Description

This is a wrapper for formatters::format_value() for use with CellValue objects

Usage

format_rcell(
  x,
  format,
  output = c("ascii", "html"),
  na_str = obj_na_str(x) %||% "NA",
  pr_row_format = NULL,
  pr_row_na_str = NULL,
  shell = FALSE
)

Arguments

Value

Formatted text.

Examples

cll <- CellValue(pi, format = "xx.xxx")
format_rcell(cll)

# Cell values precedes the row values
cll <- CellValue(pi, format = "xx.xxx")
format_rcell(cll, pr_row_format = "xx.x")

# Similarly for NA values
cll <- CellValue(NA, format = "xx.xxx", format_na_str = "This is THE NA")
format_rcell(cll, pr_row_na_str = "This is NA")

Description

Get formatted cells

Usage

get_formatted_cells(obj, shell = FALSE)

## S4 method for signature 'TableTree'
get_formatted_cells(obj, shell = FALSE)

## S4 method for signature 'ElementaryTable'
get_formatted_cells(obj, shell = FALSE)

## S4 method for signature 'TableRow'
get_formatted_cells(obj, shell = FALSE)

## S4 method for signature 'LabelRow'
get_formatted_cells(obj, shell = FALSE)

get_cell_aligns(obj)

## S4 method for signature 'TableTree'
get_cell_aligns(obj)

## S4 method for signature 'ElementaryTable'
get_cell_aligns(obj)

## S4 method for signature 'TableRow'
get_cell_aligns(obj)

## S4 method for signature 'LabelRow'
get_cell_aligns(obj)

Arguments

Value

The formatted print-strings for all (body) cells in obj.

Examples

library(dplyr)

iris2 <- iris %>%
  group_by(Species) %>%
  mutate(group = as.factor(rep_len(c("a", "b"), length.out = n()))) %>%
  ungroup()

tbl <- basic_table() %>%
  split_cols_by("Species") %>%
  split_cols_by("group") %>%
  analyze(c("Sepal.Length", "Petal.Width"), afun = list_wrap_x(summary), format = "xx.xx") %>%
  build_table(iris2)

get_formatted_cells(tbl)

Description

Head and tail methods

Usage

head(x, ...)

## S4 method for signature 'VTableTree'
head(
  x,
  n = 6,
  ...,
  keep_topleft = TRUE,
  keep_titles = TRUE,
  keep_footers = keep_titles,
  reindex_refs = FALSE
)

tail(x, ...)

## S4 method for signature 'VTableTree'
tail(
  x,
  n = 6,
  ...,
  keep_topleft = TRUE,
  keep_titles = TRUE,
  keep_footers = keep_titles,
  reindex_refs = FALSE
)

Arguments

Description

Access or recursively set header-body separator for tables

Usage

horizontal_sep(obj)

## S4 method for signature 'VTableTree'
horizontal_sep(obj)

horizontal_sep(obj) <- value

## S4 replacement method for signature 'VTableTree'
horizontal_sep(obj) <- value

## S4 replacement method for signature 'TableRow'
horizontal_sep(obj) <- value

Arguments

Value

• horizontal_sep returns the string acting as the header separator.

• ⁠horizontal_sep<-⁠ returns obj, with the new header separator applied recursively to it and all its subtables.

Description

Define the cells that get placed into multiple rows in afun.

Usage

in_rows(
  ...,
  .list = NULL,
  .names = NULL,
  .labels = NULL,
  .formats = NULL,
  .indent_mods = NULL,
  .cell_footnotes = list(NULL),
  .row_footnotes = list(NULL),
  .aligns = NULL,
  .format_na_strs = NULL
)

Arguments

Value

A RowsVerticalSection object (or NULL). The details of this object should be considered an internal implementation detail.

Note

In post-processing, referential footnotes can also be added using row and column paths with fnotes_at_path<-.

See Also

analyze()

Examples

in_rows(1, 2, 3, .names = c("a", "b", "c"))
in_rows(1, 2, 3, .labels = c("a", "b", "c"))
in_rows(1, 2, 3, .names = c("a", "b", "c"), .labels = c("AAA", "BBB", "CCC"))

in_rows(.list = list(a = 1, b = 2, c = 3))
in_rows(1, 2, .list = list(3), .names = c("a", "b", "c"))

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = function(x) {
    in_rows(
      "Mean (sd)" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"),
      "Range" = rcell(range(x), format = "xx.xx - xx.xx")
    )
  })

tbl <- build_table(lyt, ex_adsl)
tbl

Description

Change indentation of all rrows in an rtable

Usage

indent(x, by = 1)

Arguments

Value

x with its indent modifier incremented by by.

Examples

is_setosa <- iris$Species == "setosa"
m_tbl <- rtable(
  header = rheader(
    rrow(row.name = NULL, rcell("Sepal.Length", colspan = 2), rcell("Petal.Length", colspan = 2)),
    rrow(NULL, "mean", "median", "mean", "median")
  ),
  rrow(
    row.name = "All Species",
    mean(iris$Sepal.Length), median(iris$Sepal.Length),
    mean(iris$Petal.Length), median(iris$Petal.Length),
    format = "xx.xx"
  ),
  rrow(
    row.name = "Setosa",
    mean(iris$Sepal.Length[is_setosa]), median(iris$Sepal.Length[is_setosa]),
    mean(iris$Petal.Length[is_setosa]), median(iris$Petal.Length[is_setosa]),
    format = "xx.xx"
  )
)
indent(m_tbl)
indent(m_tbl, 2)

Description

Used in rtables to indent row names for the ASCII output.

Usage

indent_string(x, indent = 0, incr = 2, including_newline = TRUE)

Arguments

Value

x, indented with left-padding with indent * incr white-spaces.

Examples

indent_string("a", 0)
indent_string("a", 1)
indent_string(letters[1:3], 0:2)
indent_string(paste0(letters[1:3], "\n", LETTERS[1:3]), 0:2)

Description

Insert a row into an existing table directly before or directly after an existing data (i.e., non-content and non-label) row, specified by its path.

Usage

insert_row_at_path(tt, path, value, after = FALSE)

## S4 method for signature 'VTableTree,DataRow'
insert_row_at_path(tt, path, value, after = FALSE)

## S4 method for signature 'VTableTree,ANY'
insert_row_at_path(tt, path, value)

Arguments