Write the plan for you

The counterpart of plan_template(form = "widen") for the deferred form: reads an ARD and prints a runnable table_plan() pipeline, filled in with the keys, hierarchy, contexts and statistics it actually found.

Usage

plan_template(
  x,
  cols = NULL,
  hierarchy = character(),
  form = c("plan", "widen"),
  file = NULL,
  pipe = NULL
)

Arguments

x

A cards / cardx ARD (or anything normalize_ard() takes).

cols

The column keys, as table_plan()'s cols; NULL takes the first key the ARD has.

hierarchy

The hierarchy columns, as normalize_ard()'s.

form

"plan" (default) writes the deferred form, a table_plan() pipeline; "widen" writes the immediate form, normalize_ard() into widen_ard() with the seam left open for a dplyr::mutate().

file

When given, the code is also written there.

pipe

"|>" or "%>%"; NULL follows getOption("rtfreporter.ard_pipe"), then RStudio's own preference, then %>%.

Value

The generated code, as a character vector, invisibly.

Details

It writes both halves — the ARD to the table, and the table to the RTF pages — because a plan that stops at the table is a plan that made you look up stub_vars and the header somewhere else. The display half is a starting point and is meant to be edited: only plan_stub() is derivable from the ARD, and the rest are display decisions nothing can guess.

See also

table_plan(), plan_apply()

Examples

if (requireNamespace("cards", quietly = TRUE)) {
  ard <- cards::ard_stack(
    cards::ADSL, .by = ARM,
    cards::ard_summary(variables = AGE),
    cards::ard_tabulate(variables = SEX))
  plan_template(ard, cols = "ARM")
}
#> # ====================================================================
#> #  generated by rtfreporter::plan_template()
#> #
#> #  keys       : ARM
#> #  variables  : AGE, SEX
#> #  kinds      : continuous, categorical
#> #
#> #  normalize_ard() runs; the plan does not, until it is asked.
#> #  print(p) says how far it will go, and what its columns are called.
#> #  A later layer wins, so tune one variable by ADDING a line.
#> # ====================================================================
#> 
#> library(magrittr)   # for %>% ; dplyr re-exports it too
#> 
#> # -- 1. the ARD half --------------------------------------------------
#> p <- ard %>%
#>   rtfreporter::normalize_ard() %>%
#>   rtfreporter::table_plan(
#>     cols = "ARM",
#>     rows = c(group = "variable")
#>   ) %>%
#>   rtfreporter::plan_cells(
#>     continuous = c(
#>       "n"         = "{N:.0f}",
#>       "Mean (SD)" = "{mean:.1f} ({sd:.1f})",
#>       "Median"    = "{median:.1f}",
#>       "Q1, Q3"    = "{p25:.1f}, {p75:.1f}",
#>       "Min, Max"  = "{min:.1f}, {max:.1f}"
#>     ),
#>     categorical = "{n:.0f} ({p:.1f%})"
#>   ) %>%
#> 
#> # -- 2. the display half -- edit this ---------------------------------
#>   rtfreporter::plan_stub(
#>     name = "row_label"
#>   ) %>%
#>   rtfreporter::plan_row_group(mode = "indent") %>%
#>   rtfreporter::plan_blanks("between_groups") %>%
#>   rtfreporter::plan_paginate_rows(max_rows = 22, split = "group_safe") %>%
#>   rtfreporter::plan_style(border = "tfl") %>%
#>   rtfreporter::plan_col_header(
#>     values = list(n = TRUE),
#>     header = function(n) c("Characteristic", paste0(names(n), "\nN = ", as.integer(n)))
#>   )
#> 
#> # rtf_tables() takes the plan directly -- plan_apply() is only for
#> # looking inside:
#> #
#> #   doc <- rtf_document() |>
#> #     rtf_section(page = 1, secinfo = <your header / footer>) |>
#> #     rtf_tables(p)
#> #
#> #   print(p)        what it declares, and how far it goes
#> #   plan_apply(p)   the object itself