Add a subgroup count to the dtrackr history graph

A frequent use case for more detailed description is to have a subgroup count within a flowchart. This works best for factor subgroup columns but other data will be converted to a factor automatically. The count of the items in each subgroup is added as a new stage in the flowchart.

Usage

count_subgroup(
  .data,
  .subgroup,
  ...,
  .messages = .defaultCountSubgroup(),
  .headline = .defaultHeadline(),
  .type = "info",
  .asOffshoot = FALSE,
  .tag = NULL,
  .maxsubgroups = .defaultMaxSupportedGroupings()
)

Arguments

.data

a dataframe which may be grouped

.subgroup

a column with a small number of levels (e.g. a factor)

...

passed to base::factor(subgroup values, ...) to allow reordering of levels etc.

.messages

a character vector of glue specifications. A glue specification can refer to anything from the calling environment, {.subgroup} for the subgroup column name and {.name} for the subgroup column value, {.count} for the subgroup column count, {.subtotal} for the current stratification grouping count and {.total} for the whole dataset count

.headline

a glue specification which can refer to grouping variables of .data, {.subtotal} for the current grouping count, or any variables defined in the calling environment

.type

one of "info","exclusion": used to define formatting

.asOffshoot

do you want this comment to be an offshoot of the main flow (default = FALSE).

.tag

if you want to use the summary data from this step in the future then give it a name with .tag.

.maxsubgroups

the maximum number of discrete values allowed in .subgroup is configurable with options("dtrackr.max_supported_groupings"=XX). The default is 16. Large values produce unwieldy flow charts.

Value

the same .data dataframe with the history graph updated with a subgroup count as a new stage

Examples

library(dplyr)
library(dtrackr)
survival::cgd %>% track() %>% group_by(treat) %>%
  count_subgroup(center) %>% history()
#> dtrackr history:
#> number of flowchart steps: 3 (approx)
#> tags defined: <none>
#> items excluded so far: <not capturing exclusions>
#> last entry / entries:
#> ├ [treat:placebo]: "treat:placebo", "Harvard Medical Sch: 3 items", "Scripps Institute: 22 items", "Copenhagen: 4 items", "NIH: 20 items", "L.A. Children's Hosp: 8 items", "Mott Children's Hosp: 13 items", "Univ. of Utah: 2 items", "Univ. of Washington: 2 items", "Univ. of Minnesota: 7 items", "Univ. of Zurich: 13 items", "Texas Children's Hosp: 7 items", "Amsterdam: 16 items", "Mt. Sinai Medical Ctr: 3 items"
#> └ [treat:rIFN-g]: "treat:rIFN-g", "Harvard Medical Sch: 1 items", "Scripps Institute: 14 items", "Copenhagen: 1 items", "NIH: 21 items", "L.A. Children's Hosp: 5 items", "Mott Children's Hosp: 7 items", "Univ. of Utah: 3 items", "Univ. of Washington: 2 items", "Univ. of Minnesota: 3 items", "Univ. of Zurich: 8 items", "Texas Children's Hosp: 4 items", "Amsterdam: 12 items", "Mt. Sinai Medical Ctr: 2 items"