Skip to contents

Add titles, footnotes, or a footnote page to a clintable or clindoc

Source: R/add_titles_footnotes.R
add_titles_footnotes.Rd

This function allows you to attach specified titles, footnotes, or a footnote page into clintable or clindoc object. The input can be provided either as a list of character vectors, or pre-built flextable.

Usage

clin_add_titles(x, ls = NULL, ft = NULL, align = NULL, tokens = NULL)

clin_add_footnotes(x, ls = NULL, ft = NULL, align = NULL, tokens = NULL)

clin_add_footnote_page(x, ls = NULL, ft = NULL, align = NULL, tokens = NULL)

Arguments

x

a clintable object

ls

a list of character vectors, no more than 2 elements to a vector, or a data frame spec as described above

ft

A flextable object to use as the header

align

Where to place each line, as a character vector holding one value per element of ls (or a single value for all of them). Values are "left", "center", "right", "split", or NA to keep the default for that line. Cannot be used together with ft, or with a spec that already has an align column.

tokens

Replacements for {NAME} placeholders in the text, as a named list or character vector - tokens = list(FILE = "programs/t14-1-01.R") turns {FILE} into that path. Cannot be used together with ft.

Value

A clintable object

Details

When using the ls parameter, each element of the list can contain no more than two elements within each character vector. In a title, a single element will align center. In a footnote, a single element will align to the left. For both titles and footnotes, two elements will align split down the middle, with the left side element aligning left and the right side element aligning right.

Use align to place a line somewhere other than its default. A line holding a single element can go "left", "center", or "right"; a line holding two elements is split down the middle by construction, which align spells "split". NA leaves a line where it would have landed anyway.

Instead of a list, ls can be a data frame holding every line for a table at once, so one object feeds the titles, the footnotes and a footnote page together. Each of the three functions takes the rows that belong to it and ignores the rest, and a surface with no rows is left alone. Rows are used in the order they are given.

columnholds
type"title", "footnote", or "footnote_page" (plurals accepted)
text1the line, or its left hand side
text2the right hand side of a split line, blank or NA if there is none
alignas the align argument below, blank or NA for the default

Only type and text1 are required. Reading the spec in is left to you - it is an ordinary data frame, so it can come from a spreadsheet, a CSV, a database, or be written out by hand.

tokens fills in {NAME} placeholders, which is how a program path or a run date gets into text that was written somewhere else. {PAGE} and {NUMPAGES} are left alone - those become real Word page number fields when the table renders, so do not pass them as tokens.

Examples

clintable(mtcars) |>
  clin_add_titles(
    list(
      c("Left", "Right"),
      c("Just the middle")
    )
  ) |>
  clin_add_titles(
    list(
      c("Protocol: ABC", "Page {PAGE} of {NUMPAGES}"),
      "Table 14-2.01",
      "Summary of Demographic and Baseline Characteristics"
    ),
    # the title line stays centered, the one below it goes left
    align = c(NA, NA, "left")
  ) |>
  clin_add_footnotes(
    list(
      c(
        "Here's a footnote.",
        format(Sys.time(), "%H:%M %A, %B %d, %Y")
      )
    )
  ) |>
  clin_add_footnote_page(
    list(
      c(
        "Use when you have a lot of footnotes",
        "And you don't want to put them on every page"
      )
    )
  )


  
Protocol: ABC
Page  of 
Table 14-2.01
Summary of Demographic and Baseline Characteristics
Use when you have a lot of footnotes
And you don't want to put them on every page
Here's a footnote.
01:20 Sunday, August 02, 2026






  
  



# Or keep every line for the table in one place and let each function take
# the rows that belong to it
spec <- data.frame(
  type = c("title", "title", "footnote"),
  text1 = c("Protocol: ABC", "Table 14-2.01", "Source: {FILE}"),
  text2 = c("Page {PAGE} of {NUMPAGES}", NA, NA),
  align = c("split", "center", "left")
)

clintable(mtcars) |>
  clin_add_titles(spec, tokens = list(FILE = "programs/t14-2-01.R")) |>
  clin_add_footnotes(spec, tokens = list(FILE = "programs/t14-2-01.R"))

Protocol: ABC
Page  of 
Table 14-2.01
mpg
cyl
disp
hp
drat
wt
qsec
vs
am
gear
carb
21.0
6
160.0
110
3.90
2.620
16.46
0
1
4
4
21.0
6
160.0
110
3.90
2.875
17.02
0
1
4
4
22.8
4
108.0
93
3.85
2.320
18.61
1
1
4
1
21.4
6
258.0
110
3.08
3.215
19.44
1
0
3
1
18.7
8
360.0
175
3.15
3.440
17.02
0
0
3
2
18.1
6
225.0
105
2.76
3.460
20.22
1
0
3
1
14.3
8
360.0
245
3.21
3.570
15.84
0
0
3
4
24.4
4
146.7
62
3.69
3.190
20.00
1
0
4
2
22.8
4
140.8
95
3.92
3.150
22.90
1
0
4
2
19.2
6
167.6
123
3.92
3.440
18.30
1
0
4
4
17.8
6
167.6
123
3.92
3.440
18.90
1
0
4
4
16.4
8
275.8
180
3.07
4.070
17.40
0
0
3
3
17.3
8
275.8
180
3.07
3.730
17.60
0
0
3
3
15.2
8
275.8
180
3.07
3.780
18.00
0
0
3
3
10.4
8
472.0
205
2.93
5.250
17.98
0
0
3
4
Source: programs/t14-2-01.R