rtables (version 0.5.1)

build_table: Create a table from a layout and data

Description

Layouts are used to describe a table pre-data. build_rable 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(),
  ...
)

Value

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

Arguments

lyt

layout object pre-data used for tabulation

df

dataset (data.frame or tibble)

alt_counts_df

dataset (data.frame or tibble). Alternative full data the rtables framework will use (only) when calculating column counts.

col_counts

numeric (or NULL). Deprecated. If non-null, column counts which override those calculated automatically during tabulation. Must specify "counts" for all resulting columns if non-NULL. NA elements will be replaced with the automatically calculated counts.

col_total

integer(1). The total observations across all columns. Defaults to nrow(df).

topleft

character. Override values for the "top left" material to be displayed during printing.

hsep

character(1). Set of character(s) to be repeated as the separator between the header and body of the table when rendered as text. Defaults to a connected horrizontal line (unicode 2014) in locals that use a UTF charset, and to - elsewhere (with a once per session warning).

...

currently ignored.

Author

Gabriel Becker

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.

Examples

l <- 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))
  )
})

l

build_table(l, iris)

# analyze multiple variables
l <- 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))
  )
})

build_table(l, iris)

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

build_table(l, DM)

build_table(l, subset(DM, AGE > 40))

# with column counts
l2 <- l %>%
  add_colcounts()
build_table(l2, DM)


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

build_table(l, DM, col_counts = 1:3)