Skip to content

Add modify_split_caption() to label paginated splits and hide the split column #282

Description

@Melkiades

When paginating a listing with gtsummary::tbl_split_by_rows(variable_level = <col>) (e.g. splitting a lab listing by PARAM, or a demographics listing by treatment), two manual post-processing steps are always needed:

  1. The split value is stored in attr(tbl, "variable_level") as a bare level (e.g. "WEIGHT"). Decorators (citril) inject it as the page subtitle, but it usually needs a prefix, e.g. "Parameter: WEIGHT".
  2. The split column is redundant on each single-value page and should be hidden.

Currently this is repeated inline in every paginated template:

gts |>
  purrr::map(\(tbl) {
    lvl <- attr(tbl, "variable_level")
    tbl <- gtsummary::modify_column_hide(tbl, columns = "PARAM")
    attr(tbl, "variable_level") <- paste0("Parameter: ", lvl)
    tbl
  }) |>
  structure(class = class(gts))

Proposal

Add modify_split_caption() to R/tbl_listing.R (sibling of remove_duplicate_keys() / add_blank_rows(), shared @rdname tbl_listing):

modify_split_caption(
  x,
  spl_col,
  pattern = "Parameter: {spl_level}",  # glue; {spl_level} is the split value
  hide_spl_col = TRUE                   # hidden silently; no-op if col absent/already hidden
)
  • Rewrites each split page's variable_level label via the glue pattern (default suits BDS/lab tables split by PARAM).
  • Hides spl_col on every page by default; silent when the column is absent or already hidden.
  • Works on a single tbl_split element or the whole list.
  • No citril/internal references — operates only on the gtsummary-native variable_level attribute, so crane stays open-source clean.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions