col_counts.R
Many tables call for column counts to be displayed in the header material of a table (i.e., interspersed with the column labels).
Historically, rtables supported this only for so-called
leaf or individual columns.
Display of column counts (off by default) was primarily achieved via
passing show_colcounts = TRUE to basic_table ,
e.g.
library(dplyr)
library(rtables)
lyt <- basic_table(show_colcounts = TRUE) %>%
split_cols_by("ARM") %>%
split_cols_by("SEX", split_fun = keep_split_levels(c("F", "M"))) %>%
analyze("AGE")
tbl <- build_table(lyt, ex_adsl)
tbl
# A: Drug X B: Placebo C: Combination
# F M F M F M
# (N=79) (N=51) (N=77) (N=55) (N=66) (N=60)
# ————————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
The format of the counts could also be controlled by the
colcount_format argument to basic_table.
We had no way of displaying (or, in fact, even easily calculating)
the ARM facet counts.
(Leaf-)column counts could be altered after the fact via the
col_counts<- getter:
col_counts(tbl) <- c(17, 18, 19, 17, 18, 19)
tbl
# A: Drug X B: Placebo C: Combination
# F M F M F M
# (N=17) (N=18) (N=19) (N=17) (N=18) (N=19)
# ————————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R NB doing this has never updated percentages that appear within the table as they are calculated at table-creation time, so this can lead to misleading results when not used with care.
We did not provide a user-visible way to toggle column count display
after table creation, though we did support showing a blank space for
particular counts by setting them to NA:
col_counts(tbl) <- c(17, 18, NA, 17, 18, 19)
tbl
# A: Drug X B: Placebo C: Combination
# F M F M F M
# (N=17) (N=18) (N=17) (N=18) (N=19)
# ———————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
These mechanisms will all continue to work for the forseeable future, though new code is advised use the new API discussed below.
Starting in rtables version 6.8.0, the
concept of column counts is modeled and handled with much more
granularity than previously. Each facet in column space now has a column
count (whether or not it is displayed), which will appear directly under
the corresponding column label (spanning the same number of rows) when
set to be visible.
The primary way for users to create tables which displays these “high-level” column counts is to create a layout that specifies they should be visible.
We do this with the new show_colcounts argument now
accepted by all split_cols_by* layout functions.
lyt2 <- basic_table() %>%
split_cols_by("ARM") %>%
split_cols_by("SEX",
split_fun = keep_split_levels(c("F", "M")),
show_colcounts = TRUE
) %>%
analyze("AGE")
tbl2 <- build_table(lyt2, ex_adsl)
tbl2
# A: Drug X B: Placebo C: Combination
# F M F M F M
# (N=79) (N=51) (N=77) (N=55) (N=66) (N=60)
# ————————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
lyt3 <- basic_table() %>%
split_cols_by("ARM", show_colcounts = TRUE) %>%
split_cols_by("SEX", split_fun = keep_split_levels(c("F", "M"))) %>%
analyze("AGE")
tbl3 <- build_table(lyt3, ex_adsl)
tbl3
# A: Drug X B: Placebo C: Combination
# (N=134) (N=134) (N=132)
# F M F M F M
# ————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
As before, these column counts are calculated at table creation time,
using alt_counts_df if it is provided (or simply
df otherwise).
Column formats are set at layout time via the
colcount_format argument of the specific
split_cols_by call.
Manipulation of column counts (beyond the old setters provided for backwards compatibility) is path based. In other words, when we set a column count (e.g., to NA so it displays as a blank) or set the visibilty of a set of column counts, we do so by indicating them via column paths. The ability to alter column count formats on an existing table is currently not offered by any exported functions.
Column paths can be obtained via col_paths for the leaf
columns, or via make_col_df(tbl, visible_only = FALSE)$path
for all addressable facets.
The facet_colcount getter and setter queries and sets
the column count for a facet in column space (note it needs not be a
leaf facet). E.g.,
col_counts.R
facet_colcount(tbl3, c("ARM", "C: Combination")) <- 75
tbl3
# A: Drug X B: Placebo C: Combination
# (N=134) (N=134) (N=75)
# F M F M F M
# ————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
For convenience (primarily because it was needed internally), we also
provide rm_all_colcounts which sets all column
counts for a particular table to NA at all levels of
nesting. We do not expect this to be particularly useful to
end-users.
Typically we do not set column count visibility individually. *This is due to a constraint where direct leaf siblings (e.g. F and M under one of the arms in our layout) must have the same visibility for their column counts in order for the rendering machinery to work.
Instead, we can reset the column count visibility of groups of
siblings via the facet_colcounts_visible (note the ‘s’)
setter. This function accepts a path which ends in the name associated
with a splitting instruction in the layout (e.g., c("ARM"),
c("ARM", "B: Placebo", "SEX"), etc) and resets the
visibility of all direct children of that path.
facet_colcounts_visible(tbl3, c("ARM", "A: Drug X", "SEX")) <- TRUE
tbl3
# A: Drug X
# (N=134) B: Placebo C: Combination
# F M (N=134) (N=75)
# (N=79) (N=51) F M F M
# ——————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R
NOTE as we can see here, the visibility of column
counts can have an “unbalanced design”, provided the direct-siblings
agreeing constraint is met. This leads to things not lining up directly
as one might expect (it does not generate any blank spaces the way
setting a visible column count to NA does).
Currently paths with "*" in them do not work within
facet_colcounts_visible, but that capability is likely to
be added in future releases.
colcount_visible getters and setters do also exist which
retrieve and set individual column counts’ visiblities, but these are
largely an internal detail and in virtually all cases end users should
avoid calling them directly.
## BEWARE, the following is expected to show error
tbl4 <- tbl3
colcount_visible(tbl4, c("ARM", "A: Drug X", "SEX", "F")) <- FALSE
tbl4
# Expected Error message
# Error in h(simpleError(msg, call)) :
# error in evaluating the argument 'x' in selecting a method for function 'toString':
# Detected different colcount visibility among sibling facets (those arising from the
# same split_cols_by* layout instruction). This is not supported.
# Set count values to NA if you want a blank space to appear as the displayed count for particular facets.
# First disagreement occured at paths:
# ARM[A: Drug X]->SEX[F]
# ARM[A: Drug X]->SEX[M]col_counts.R
Note currently this restriction is currently only enforced for leaf columns due to technical implementation details but how a table renders should be considered undefined behavior when it contains a group of sibling column facets arising from the same layout instruction whose column count visiblities disagree. That may become an error in future versions without warning.
By using make_col_df() we can see the full path to any
column count. One example application is to add a NA value
that would print to the default value is "", that will show
nothing. To change (for now uniformly only) the output string in case of
missing values in the column counts you can use
colcount_na_str:
coldf <- make_col_df(tbl3)
facet_colcount(tbl3, coldf$path[[1]][c(1, 2)]) <- NA_integer_
print(tbl3) # Keeps the missing space
# A: Drug X
# B: Placebo C: Combination
# F M (N=134) (N=75)
# (N=79) (N=51) F M F M
# ——————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38
colcount_na_str(tbl3) <- "NaN"
tbl3 # Shows NaN
# A: Drug X
# NaN B: Placebo C: Combination
# F M (N=134) (N=75)
# (N=79) (N=51) F M F M
# ——————————————————————————————————————————————————————————
# Mean 32.76 35.57 34.12 37.44 35.20 35.38col_counts.R