rtables (version 0.6.12)

add_overall_level: Add overall or combination levels to split groups

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)

Value

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

Format

An object of class AllLevelsSentinel of length 0.

Arguments

valname

(string)
value to be assigned to the implicit all-observations split level. Defaults to "Overall".

label

(string)
a label (not to be confused with the name) for the object/structure.

extra_args

(list)
extra arguments to be passed to the tabulation function. Element position in the list corresponds to the children of this split. Named elements in the child-specific lists are ignored if they do not match a formal argument of the tabulation function.

first

(flag)
whether the implicit level should appear first (TRUE) or last (FALSE). Defaults to TRUE.

trim

(flag)
whether splits corresponding with 0 observations should be kept when tabulating.

combosdf

(data.frame or tbl_df)
a data frame with columns valname, label, levelcombo, and exargs. levelcombo and exargs should be list columns. Passing the select_all_levels object as a value in comblevels column indicates that an overall/all-observations level should be created.

keep_levels

(character or NULL)
if non-NULL, the levels to retain across both combination and individual levels.

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