StatsTFLValR (version 1.0.0)

ATCbyDrug: Fully Nested ATC2 → ATC4 → Drug (CMDECOD) Table by Treatment (wide)

Description

Builds a three-level nested summary table of concomitant medications (or similar data), grouped as ATC2 → ATC4 → Drug (CMDECOD), with counts and percentages by treatment arm. Outputs a wide data frame where each treatment column contains n (pct).

Two indent modes are supported for the display label column stat:

• RTF mode (default): If atc4_spaces and cmdecod_spaces are both NULL, and rtf_safe = TRUE, stat will include the provided RTF indent strings (atc4_rtf, cmdecod_rtf) before the label text.

• SAS blanks mode: If atc4_spaces or cmdecod_spaces is provided (non-NULL), stat will use only blank spaces (no RTF codes) as visual indents (SAS-style), regardless of rtf_safe.

Sorting can be controlled by sort_by:

• "count" (default): within each level, sort descending by counts for the column n__<trtan_coln> (e.g., n__21), then alphabetically.

• "alpha": alphabetical ascending order at each level.

Rows where all three levels are "UNCODED" (case-insensitive) are pushed to the very end of the table (after all other rows), preserving the nested order.

Usage

ATCbyDrug(
  indata,
  dmdata,
  group_vars,
  trtan_coln,
  rtf_safe = TRUE,
  sort_by = c("count", "alpha"),
  atc4_spaces = NULL,
  cmdecod_spaces = NULL,
  atc4_rtf = "(*ESC*)R/RTF\"\\li180 \"",
  cmdecod_rtf = "(*ESC*)R/RTF\"\\li360 \""
)

Value

A tibble with nested rows containing:

• stat (indented label),

• treatment columns trt* (string "n (pct)"),

• raw-count columns n__*,

• helper ordering columns (sec_ord, psec_ord, sort_ord).

Arguments

indata

A data frame containing medication/event records. Must include: USUBJID and the variables named in group_vars.

dmdata

A data frame with one row per subject (for denominators). Must include USUBJID and the main treatment grouping variable (first element of group_vars).

group_vars

Character vector of length 4 specifying, in order: c(main_group, atc2, atc4, meddecod).

• main_group = treatment/grouping variable used for columns (e.g., "TRTAN").

• atc2, atc4, meddecod = the three nested display levels.

trtan_coln

Character scalar giving the column-level of interest used for count-based sorting, i.e., the suffix in n__<trtan_coln>. Example: "21" makes the function look for n__21 to drive "count" sorting.

rtf_safe

Logical; if TRUE, RTF strings will be used in stat when both atc4_spaces and cmdecod_spaces are NULL. If either spaces argument is provided, stat will not include RTF strings.

sort_by

One of c("count","alpha"). See Details.

atc4_spaces, cmdecod_spaces

NULL or non-negative integer specifying the number of blank spaces to prepend for ATC4 and Drug (CMDECOD) labels in stat. If either is non-NULL, the function uses SAS blanks mode (no RTF codes).

atc4_rtf, cmdecod_rtf

Character RTF indent strings used only when both atc4_spaces and cmdecod_spaces are NULL and rtf_safe = TRUE. Defaults: (*ESC*)R/RTF"\\li180 " for ATC4, (*ESC*)R/RTF"\\li360 " for Drug (CMDECOD).

Details

Denominator (N) is computed from dmdata as distinct USUBJID per main_group. For each level (ATC2, ATC4 within ATC2, Drug/CMDECOD within ATC4), the function computes distinct-subject counts by main_group, the percentage w.r.t. N, and forms "n (pct)". The wide result has:

• stat = display label with indent (RTF or blanks, depending on mode).

• trt<value> columns (e.g., trt21, trt22, …): "n (pct)" per treatment value.

• n__<value> columns mirroring raw counts (useful for custom sorting or QC).

• Ordering columns: sec_ord, psec_ord, sort_ord (help keep nested order).

Indent modes:

• RTF mode: Use when you want RTF control words in the output for direct RTF rendering. Do not set atc4_spaces/cmdecod_spaces; keep rtf_safe = TRUE.

• SAS blanks mode: Provide atc4_spaces and/or cmdecod_spaces to indent using blanks only (friendly for plain-text outputs or RTF pipelines that inject formatting later).

UNCODED handling: Rows are considered UNCODED only if all three of ATC2, ATC4, and Drug (CMDECOD) equal "UNCODED" (case-insensitive, leading/trailing space ignored). Such rows are assigned to the end of the table after sorting.

Examples

library(dplyr)

cm <- tibble::tribble(
  ~USUBJID, ~TRTAN, ~ATC2,      ~ATC4,         ~CMDECOD,
  "01",       21,   "A - Alim.", "A01A",        "CHLORHEXIDINE",
  "01",       21,   "A - Alim.", "A01A",        "CHLORHEXIDINE",
  "02",       21,   "A - Alim.", "A01A",        "NYSTATIN",
  "03",       22,   "A - Alim.", "A01A",        "NYSTATIN",
  "04",       22,   "J - Anti.", "J01C",        "AMOXICILLIN",
  "05",       21,   "J - Anti.", "J01C",        "AMOXICILLIN",
  "06",       22,   "UNCODED",   "UNCODED",     "UNCODED"
)



dm <- tibble::tribble(
  ~USUBJID, ~TRTAN,
  "01",       21,
  "02",       21,
  "05",       21,
  "03",       22,
  "04",       22,
  "06",       22
)

out_rtf <- ATCbyDrug(
  indata      = cm,
  dmdata      = dm,
  group_vars  = c("TRTAN", "ATC2", "ATC4", "CMDECOD"),
  trtan_coln  = "21",
  rtf_safe    = TRUE,
  sort_by     = "count"
)

out_rtf



out_spaces <- ATCbyDrug(
  indata          = cm,
  dmdata          = dm,
  group_vars      = c("TRTAN", "ATC2", "ATC4", "CMDECOD"),
  trtan_coln      = "21",
  sort_by         = "count",
  atc4_spaces     = 2,
  cmdecod_spaces  = 4
)

out_spaces



out_alpha <- ATCbyDrug(
  indata      = cm,
  dmdata      = dm,
  group_vars  = c("TRTAN", "ATC2", "ATC4", "CMDECOD"),
  trtan_coln  = "21",
  sort_by     = "alpha",
  rtf_safe    = FALSE
)

out_alpha