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().
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,FALSEor"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:2merges the top two rows only,merge = -3merges 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 callsflextable::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.
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")
)
Flowers
Sepal
Petal
Length
Width
Length
Width
5.1
3.5
1.4
0.2
setosa
4.9
3.0
1.4
0.2
setosa
4.7
3.2
1.3
0.2
setosa
4.6
3.1
1.5
0.2
setosa
5.0
3.6
1.4
0.2
setosa
5.4
3.9
1.7
0.4
setosa
4.6
3.4
1.4
0.3
setosa
5.0
3.4
1.5
0.2
setosa
4.4
2.9
1.4
0.2
setosa
4.9
3.1
1.5
0.1
setosa
5.4
3.7
1.5
0.2
setosa
4.8
3.4
1.6
0.2
setosa
4.8
3.0
1.4
0.1
setosa
4.3
3.0
1.1
0.1
setosa
5.8
4.0
1.2
0.2
setosa
# 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"
)
Flowers
Sepal
Petal
Value
Value
Value
Value
5.1
3.5
1.4
0.2
setosa
4.9
3.0
1.4
0.2
setosa
4.7
3.2
1.3
0.2
setosa
4.6
3.1
1.5
0.2
setosa
5.0
3.6
1.4
0.2
setosa
5.4
3.9
1.7
0.4
setosa
4.6
3.4
1.4
0.3
setosa
5.0
3.4
1.5
0.2
setosa
4.4
2.9
1.4
0.2
setosa
4.9
3.1
1.5
0.1
setosa
5.4
3.7
1.5
0.2
setosa
4.8
3.4
1.6
0.2
setosa
4.8
3.0
1.4
0.1
setosa
4.3
3.0
1.1
0.1
setosa
5.8
4.0
1.2
0.2
setosa
# 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)
Flowers
Value
Value
5.1
3.5
1.4
0.2
setosa
4.9
3.0
1.4
0.2
setosa
4.7
3.2
1.3
0.2
setosa
4.6
3.1
1.5
0.2
setosa
5.0
3.6
1.4
0.2
setosa
5.4
3.9
1.7
0.4
setosa
4.6
3.4
1.4
0.3
setosa
5.0
3.4
1.5
0.2
setosa
4.4
2.9
1.4
0.2
setosa
4.9
3.1
1.5
0.1
setosa
5.4
3.7
1.5
0.2
setosa
4.8
3.4
1.6
0.2
setosa
4.8
3.0
1.4
0.1
setosa
4.3
3.0
1.1
0.1
setosa
5.8
4.0
1.2
0.2
setosa