Skip to contents

A deferred, last-wins plan for a table

Source: R/table_plan.R
table_plan.Rd

table_plan() starts a plan, and takes the roles: which column goes across the table, which go down it, which carries the row identity. This is ggplot(data, aes(x, y)) — the names must be columns of the data you hand it, so you can check them by looking. Every plan_*() verb after it adds a declaration, and nothing runs until plan_apply().

Usage

table_plan(
  x = NULL,
  cols = NULL,
  rows = NULL,
  label = NULL,
  stat = NULL,
  show_keys = NULL
)

Arguments

x

What the table is built from. A plan does not flatten: cols / rows / label name columns of what you hand it, so flatten first and look at the result.

  • a frame through normalize_ard() — the ordinary case;

  • any long frame of statistics: keys, a stat_name and a stat, built with dplyr and no cards anywhere. plan_cells() does the work;

  • a frame that is already the table, for the display half on its own;

  • a frame of subject records, with plan_listing().

A raw cards ARD is refused, with the line to write.

cols

The key that goes across the table, as widen_ard(cols = ) takes it: one or more columns, optionally renamed c(new = old). The order of its values across the table is the ARD's (a factor's levels) unless plan_levels(<key> = c(...)) says otherwise. Left out when the ARD has no group to spread (one arm): one column, All (see widen_ard()).

rows

The keys that go down it, likewise. Left out, the analysis variable is used (as group). Each name is the column the finished table gets, and later verbs refer to it by that name (plan_stub(), plan_paginate_group(col = ), plan_hide()); left unnamed, the first key is called group. "variable" is the column that holds the analysis variable's name, so c(group = "variable") makes one block of rows per analysis variable (AGE, SEX, ...). Subgroups from different variables laid one under another come from normalize_ard(stack = ); see the article Tables from an ARD, step by step (Subgroups).

label

The column carrying the row identity — the text in the label column. ".label" by default (what normalize_ard() builds), NA for a table that has none, or a guarded template. .label holds, per row: the category (variable_level) for a categorical variable; the deepest level's value in a hierarchy; and NA for a continuous variable, whose rows are named by the plan_cells() template names ("Mean (SD)").

stat

Which of your columns play the three parts widen_ard() reads by name, as a named vector: variable (the analysis variable, what plan_cells() and plan_digits() key on), name (which statistic a row is) and value (what it is worth) — stat = c(variable = "PARAMCD", name = "STAT", value = "AVAL"). A frame from cards already calls them variable, stat_name and stat and needs none of this; a summary somebody built with dplyr says so here, once, instead of being asked again by every verb. Name only the parts your frame calls something else.

show_keys

Row keys this table also shows as variables: their own counts (cards::ard_tabulate(adsl, by = TRT, variables = SEX)), which normalize_ard() marks as a key's own tabulation once SEX is a key anywhere in the ARD (a subgroup layer of another analysis), go to the body instead of only to the header's {n}. With rows = c(block = "variable", grp = "subgroup", lvl = "subgroup_level") SEX's n (%) is a block of its own beside the ORR's SEX subgroups. A column key is refused (its counts are the columns' populations). NULL (default): none, as before.

Value

An object of class table_plan.

Details

The rule is last wins — a later layer overwrites what an earlier one said about the same key — so "set everything, then fix one variable" is a two-line edit:

plan_digits(2) |> plan_digits(AGE = 0)

This is tfrmt's frmt_structure rule. Within one layer the keys are picked by specificity, as widen_ard()'s cells are: an analysis variable before a kind, a kind before the default.

Where the other settings went

table_plan() takes the roles and nothing else. Every other setting belongs to the verb whose job it is:

  • a template per cell or a row per statistic, stat / stat_fmt, the empty-cell text: plan_cells() (stats =, value =, na =)

  • the statistic a frequency order totals: plan_sort() (stat =)

  • reporting what the templates did not use: plan_cells() (notes =)

  • the separator several cols keys are joined with in the column names: plan_columns() (sep =)

See also

plan_apply(), normalize_ard(), widen_ard()

Examples

if (requireNamespace("cards", quietly = TRUE)) {
  ard <- cards::ard_stack(
    cards::ADSL, .by = ARM,
    cards::ard_summary(variables = c(AGE, BMIBL)),
    cards::ard_tabulate(variables = SEX))

  ard |>
    normalize_ard() |>
    table_plan(cols = "ARM", rows = c(group = "variable")) |>
    plan_cells(continuous  = c("Mean (SD)" = "{mean} ({sd})"),
               categorical = "{n} ({p:%})") |>
    plan_digits(2) |>
    plan_digits(AGE = 0, SEX = 1) |>
    plan_apply()
}
#> widen_ard(): 51 ARD rows were not used.
#>   summary        N                6  no template named it
#>   summary        max              6  no template named it
#>   summary        median           6  no template named it
#>   summary        min              6  no template named it
#>   summary        p25              6  no template named it
#>   summary        p75              6  no template named it
#>   tabulate       N                6  no template named it
#>   tabulate       N                3  a key variable's own tabulation
#>   ... and 2 more; see attr(, "ard_ignored")
#>   (notes = FALSE to silence; attr(, "ard_ignored") has the detail)
#>   group     label      Placebo Xanomeline High Dose Xanomeline Low Dose
#> 1   AGE Mean (SD)       75 (9)               74 (8)              76 (8)
#> 2 BMIBL Mean (SD) 23.64 (3.67)         25.35 (4.16)        25.06 (4.27)
#> 3   SEX         F  53.0 (61.6)          40.0 (47.6)         50.0 (59.5)
#> 4   SEX         M  33.0 (38.4)          44.0 (52.4)         34.0 (40.5)