clin_column_headers: Set the column headers of the output clintable

In clinify: Clinical Table Styling Tools and Utilities

Set the column headers of the output clintable

Description

This function allows you to apply column headers named arguments and character vectors. Separate elements of the character vector are converted to separate levels of the output table header. The in which the headers are applied goes from top to bottom, so if you provide 3 elements for a column header, the first element is applied to the top and the second to the bottom. If one variable has three levels and other variable only have one or two, the columns with less levels to the header will bind to the bottom. So a column with two levels will apply to the second and third row, and a column with one level with apply the bottom row. Spanners are determined using cells of the same text value, where horizontally adjacent cells holding the same text are merged. Use the merge argument when a header row legitimately repeats a label across adjacent columns and those cells should be left alone - merged, they render as one label centred over the whole run, so the repeats are not there to read any more. That is most often wanted for the bottom row, which holds each column's own label: six columns each labelled "Baseline" come out as a single Baseline spanning all six unless merge = "spanners" keeps that row out of it. merge works a row at a time, so if a single row needs some of its repeated cells merged but not others, leave that row out of merge and span the intended cells with flextable::merge_at().

Usage

clin_column_headers(x, ..., merge = TRUE)

Arguments

x	A clintable object
...	Named arguments providing the column header text. Separate levels of the header are determined using separate elements of a character vector.
merge	Controls the automatic merging of identical, adjacent header cells, which is what forms spanners. TRUE (the default) or "all" merges every header row, FALSE or "none" merges none of them, and "spanners" merges every row except the bottom one - the row holding the individual column labels. Merging can also be limited to specific header rows, numbered from the top down, using ordinary R subscripts: merge = 1:2 merges the top two rows only, merge = -3 merges every row except the third, and a logical vector as long as the header is deep toggles each row individually. Only the header is ever merged - the table body is left alone. One thing to know: a custom clinify_table_default() that calls flextable::merge_h() on the header will merge it again when the table renders, overriding whatever is set here.

Details

The same result can be achieved using column labels on the input dataframe to the clintable. If labels are present, header levels will be separated using the delimitter "||" within the label string. Headers built that way can have their merging adjusted by calling clin_column_headers() with no header text and only the merge argument, which leaves the header text as it is. Called that way, any merging already on the header is cleared first - including merges applied by hand with flextable::merge_at() or flextable::merge_v() - so the rows named in merge end up being the only merged rows.

Value

A clintable object

Examples

clintable(iris) |>
  clin_column_headers(
    Sepal.Length = c("Flowers", "Sepal", "Length"),
    Sepal.Width = c("Flowers", "Sepal", "Width"),
    Petal.Length = c("Petal", "Length"),
    Petal.Width = c("Petal", "Width")
  )

# Keep the repeated bottom row cells separate, but still span
# "Flowers" and "Petal" across the columns above them
clintable(iris) |>
  clin_column_headers(
    Sepal.Length = c("Flowers", "Sepal", "Value"),
    Sepal.Width = c("Flowers", "Sepal", "Value"),
    Petal.Length = c("Petal", "Value"),
    Petal.Width = c("Petal", "Value"),
    merge = "spanners"
  )

# Headers coming from column labels can have their merging adjusted
# without restating the header text
iris2 <- iris
attr(iris2$Sepal.Length, "label") <- "Flowers||Value"
attr(iris2$Sepal.Width, "label") <- "Flowers||Value"

clintable(iris2) |>
  clin_column_headers(merge = 1)

clinify documentation built on Aug. 2, 2026, 1:06 a.m.