Attach an auto-numbered footnote to a table location

Anchor a footnote to a cell, column header, title line, or any other cells_*() location. The engine assigns the marker, places a superscript at every matching anchor, and emits the marked-footnote line at the foot of the table. Markers are assigned once, in reading order, deduped by id, and are byte-identical across every backend (RTF / LaTeX / PDF / HTML / DOCX) and every page, so the marker at the anchor can never desynchronise from its note.

Usage

footnote(.spec, text, .at = cells_body(), id = NULL, symbol = NULL)

Arguments

.spec

The tabular_spec to annotate. <tabular_spec>: required.

text

The footnote text. <character(1)> | md() | html(). Wrap in md() / html() for inline markup; plain strings are shown verbatim. A plain string supports glue-style {expr} interpolation, evaluated as R code in the calling environment at build time (double a brace for a literal one); an md() / html() value is passed through without interpolation.

.at

Where the marker is placed. <tabular_location>: default [cells_body()]. Any cells_*() location: a body-cell predicate (cells_body(where = ...)), a column header (cells_headers()), a title line (cells_title()), and so on.

# data-driven body anchor: mark every high-frequency preferred term
footnote(spec, "Includes events of any severity.",
         .at = cells_body(where = n_total >= 50, j = "label"))

# column-header anchor: mark the analysis-population denominator
footnote(spec, "Safety population.",
         .at = cells_headers(j = "Total"))

Note: the styling argument is .at, never at.

id

Stable identifier for sharing one marker across anchors. <character(1)> | NULL. Two footnote() calls with the same id share a single marker and a single note line. NULL (default) makes each call its own note.

symbol

Pin an explicit marker glyph. <character(1)> | NULL. Overrides the auto-allocated marker for this note (e.g. "*"). A pinned symbol is reserved and skipped by the auto-allocator, so it never collides. NULL (default) auto-allocates from the preset scheme.

Value

A tabular_spec. Pipe it onward to more verbs or to emit().

Details

Engine-assigned, never hand-typed. Unlike a literal ^a^ typed into both a cell and the footnotes argument, a footnote() marker is allocated by the resolve engine after decimal alignment, so it never disturbs column alignment and never drifts out of sync. The scheme (letters / numbers / symbols) and the block-line format come from the active preset (footnote_markers, footnote_label).

Dedup by id. Give two anchors the same id to share one marker and one note line. Without an id, each footnote() call is its own note.

Coexists with footnotes. Manual footnotes lines render first; the auto-numbered block follows. The two systems do not cross-dedup, so do not mix a hand-typed marker with an engine one for the same note.

See also

Manual footnote lines: the footnotes argument to tabular().

Location helpers: cells_body(), cells_headers(), cells_title().

Inline markup: md(), html().

Examples

# ---- Example 1: a denominator note on a column header ----
#
# AE-by-SOC/PT table whose Total column header carries the analysis-
# population note. The engine drops a superscript "a" on the header
# and prints "a <text>" beneath the table.
n <- stats::setNames(cdisc_saf_n$n, cdisc_saf_n$arm_short)
tabular(cdisc_saf_aesocpt) |>
  cols(
    label    = col_spec(label = "SOC / PT", indent = "indent_level"),
    soc      = col_spec(visible = FALSE),
    row_type = col_spec(visible = FALSE),
    soc_n    = col_spec(visible = FALSE),
    n_total  = col_spec(visible = FALSE),
    placebo  = col_spec(label = "Placebo\nN={n['placebo']}"),
    drug_50  = col_spec(label = "Drug 50\nN={n['drug_50']}"),
    drug_100 = col_spec(label = "Drug 100\nN={n['drug_100']}"),
    Total    = col_spec(label = "Total\nN={n['Total']}")
  ) |>
  footnote(
    "Safety population: all randomised subjects who took study drug.",
    .at = cells_headers(j = "Total")
  )

SOC / PT
Placebo
N=86
Drug 50
N=96
Drug 100
N=72
Total
N=254a
TOTAL SUBJECTS WITH AN EVENT
52 (60.5)
81 (84.4)
66 (91.7)
199 (78.3)
SKIN AND SUBCUTANEOUS TISSUE DISORDERS
19 (22.1)
36 (37.5)
35 (48.6)
90 (35.4)
PRURITUS
8 (9.3)
21 (21.9)
25 (34.7)
54 (21.3)
ERYTHEMA
8 (9.3)
14 (14.6)
14 (19.4)
36 (14.2)
RASH
5 (5.8)
13 (13.5)
8 (11.1)
26 (10.2)
HYPERHIDROSIS
2 (2.3)
4 (4.2)
8 (11.1)
14 (5.5)
SKIN IRRITATION
3 (3.5)
6 (6.2)
5 (6.9)
14 (5.5)
GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS
15 (17.4)
36 (37.5)
30 (41.7)
81 (31.9)
APPLICATION SITE PRURITUS
6 (7.0)
23 (24.0)
21 (29.2)
50 (19.7)
APPLICATION SITE ERYTHEMA
3 (3.5)
13 (13.5)
14 (19.4)
30 (11.8)
APPLICATION SITE DERMATITIS
5 (5.8)
9 (9.4)
7 (9.7)
21 (8.3)
APPLICATION SITE IRRITATION
3 (3.5)
9 (9.4)
9 (12.5)
21 (8.3)
APPLICATION SITE VESICLES
1 (1.2)
5 (5.2)
5 (6.9)
11 (4.3)
GASTROINTESTINAL DISORDERS
13 (15.1)
12 (12.5)
17 (23.6)
42 (16.5)
DIARRHOEA
9 (10.5)
5 (5.2)
3 (4.2)
17 (6.7)
VOMITING
3 (3.5)
4 (4.2)
6 (8.3)
13 (5.1)
NAUSEA
3 (3.5)
3 (3.1)
6 (8.3)
12 (4.7)
ABDOMINAL PAIN
1 (1.2)
3 (3.1)
1 (1.4)
5 (2.0)
SALIVARY HYPERSECRETION
0 (0.0)
0 (0.0)
4 (5.6)
4 (1.6)
NERVOUS SYSTEM DISORDERS
6 (7.0)
18 (18.8)
17 (23.6)
41 (16.1)
DIZZINESS
2 (2.3)
9 (9.4)
10 (13.9)
21 (8.3)
HEADACHE
3 (3.5)
3 (3.1)
5 (6.9)
11 (4.3)
SYNCOPE
0 (0.0)
5 (5.2)
2 (2.8)
7 (2.8)
SOMNOLENCE
2 (2.3)
3 (3.1)
1 (1.4)
6 (2.4)
TRANSIENT ISCHAEMIC ATTACK
0 (0.0)
2 (2.1)
1 (1.4)
3 (1.2)
CARDIAC DISORDERS
7 (8.1)
12 (12.5)
14 (19.4)
33 (13.0)
SINUS BRADYCARDIA
2 (2.3)
7 (7.3)
8 (11.1)
17 (6.7)
MYOCARDIAL INFARCTION
4 (4.7)
2 (2.1)
4 (5.6)
10 (3.9)
ATRIAL FIBRILLATION
1 (1.2)
2 (2.1)
2 (2.8)
5 (2.0)
SUPRAVENTRICULAR EXTRASYSTOLES
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
VENTRICULAR EXTRASYSTOLES
0 (0.0)
2 (2.1)
1 (1.4)
3 (1.2)
INFECTIONS AND INFESTATIONS
12 (14.0)
6 (6.2)
11 (15.3)
29 (11.4)
NASOPHARYNGITIS
2 (2.3)
4 (4.2)
6 (8.3)
12 (4.7)
UPPER RESPIRATORY TRACT INFECTION
6 (7.0)
1 (1.0)
3 (4.2)
10 (3.9)
INFLUENZA
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
URINARY TRACT INFECTION
2 (2.3)
0 (0.0)
1 (1.4)
3 (1.2)
CYSTITIS
1 (1.2)
0 (0.0)
1 (1.4)
2 (0.8)
RESPIRATORY, THORACIC AND MEDIASTINAL DISORDERS
5 (5.8)
8 (8.3)
9 (12.5)
22 (8.7)
COUGH
1 (1.2)
5 (5.2)
5 (6.9)
11 (4.3)
NASAL CONGESTION
3 (3.5)
1 (1.0)
3 (4.2)
7 (2.8)
DYSPNOEA
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
EPISTAXIS
0 (0.0)
1 (1.0)
2 (2.8)
3 (1.2)
PHARYNGOLARYNGEAL PAIN
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
PSYCHIATRIC DISORDERS
7 (8.1)
9 (9.4)
3 (4.2)
19 (7.5)
CONFUSIONAL STATE
2 (2.3)
3 (3.1)
1 (1.4)
6 (2.4)
AGITATION
2 (2.3)
3 (3.1)
0 (0.0)
5 (2.0)
INSOMNIA
2 (2.3)
0 (0.0)
2 (2.8)
4 (1.6)
ANXIETY
0 (0.0)
3 (3.1)
0 (0.0)
3 (1.2)
DELUSION
1 (1.2)
0 (0.0)
1 (1.4)
2 (0.8)
MUSCULOSKELETAL AND CONNECTIVE TISSUE DISORDERS
3 (3.5)
6 (6.2)
5 (6.9)
14 (5.5)
BACK PAIN
1 (1.2)
1 (1.0)
3 (4.2)
5 (2.0)
ARTHRALGIA
1 (1.2)
2 (2.1)
1 (1.4)
4 (1.6)
SHOULDER PAIN
1 (1.2)
2 (2.1)
0 (0.0)
3 (1.2)
MUSCLE SPASMS
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
ARTHRITIS
0 (0.0)
0 (0.0)
1 (1.4)
1 (0.4)
INVESTIGATIONS
5 (5.8)
4 (4.2)
3 (4.2)
12 (4.7)
ELECTROCARDIOGRAM ST SEGMENT DEPRESSION
4 (4.7)
1 (1.0)
0 (0.0)
5 (2.0)
ELECTROCARDIOGRAM T WAVE INVERSION
2 (2.3)
1 (1.0)
1 (1.4)
4 (1.6)
BLOOD GLUCOSE INCREASED
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
ELECTROCARDIOGRAM T WAVE AMPLITUDE DECREASED
1 (1.2)
1 (1.0)
0 (0.0)
2 (0.8)
BIOPSY
0 (0.0)
0 (0.0)
1 (1.4)
1 (0.4)
a Safety population: all randomised subjects who took study drug.

# ---- Example 2: a data-driven note shared across cells ----
#
# A single note marks every high-frequency preferred term (n >= 50 in
# the Total column) in the SOC/PT stub. Sharing one `id` keeps it to
# one marker and one line; the marker lands on each matching cell.
tabular(cdisc_saf_aesocpt) |>
  cols(
    label    = col_spec(label = "SOC / PT", indent = "indent_level"),
    soc      = col_spec(visible = FALSE),
    row_type = col_spec(visible = FALSE),
    soc_n    = col_spec(visible = FALSE),
    n_total  = col_spec(visible = FALSE),
    placebo  = col_spec(label = "Placebo"),
    drug_50  = col_spec(label = "Drug 50"),
    drug_100 = col_spec(label = "Drug 100"),
    Total    = col_spec(label = "Total")
  ) |>
  footnote(
    md("Includes events of *any* severity."),
    .at = cells_body(where = n_total >= 50, j = "label"),
    id = "anysev"
  )

SOC / PT
Placebo
Drug 50
Drug 100
Total
TOTAL SUBJECTS WITH AN EVENTa
52 (60.5)
81 (84.4)
66 (91.7)
199 (78.3)
SKIN AND SUBCUTANEOUS TISSUE DISORDERSa
19 (22.1)
36 (37.5)
35 (48.6)
90 (35.4)
PRURITUSa
8 (9.3)
21 (21.9)
25 (34.7)
54 (21.3)
ERYTHEMA
8 (9.3)
14 (14.6)
14 (19.4)
36 (14.2)
RASH
5 (5.8)
13 (13.5)
8 (11.1)
26 (10.2)
HYPERHIDROSIS
2 (2.3)
4 (4.2)
8 (11.1)
14 (5.5)
SKIN IRRITATION
3 (3.5)
6 (6.2)
5 (6.9)
14 (5.5)
GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONSa
15 (17.4)
36 (37.5)
30 (41.7)
81 (31.9)
APPLICATION SITE PRURITUSa
6 (7.0)
23 (24.0)
21 (29.2)
50 (19.7)
APPLICATION SITE ERYTHEMA
3 (3.5)
13 (13.5)
14 (19.4)
30 (11.8)
APPLICATION SITE DERMATITIS
5 (5.8)
9 (9.4)
7 (9.7)
21 (8.3)
APPLICATION SITE IRRITATION
3 (3.5)
9 (9.4)
9 (12.5)
21 (8.3)
APPLICATION SITE VESICLES
1 (1.2)
5 (5.2)
5 (6.9)
11 (4.3)
GASTROINTESTINAL DISORDERS
13 (15.1)
12 (12.5)
17 (23.6)
42 (16.5)
DIARRHOEA
9 (10.5)
5 (5.2)
3 (4.2)
17 (6.7)
VOMITING
3 (3.5)
4 (4.2)
6 (8.3)
13 (5.1)
NAUSEA
3 (3.5)
3 (3.1)
6 (8.3)
12 (4.7)
ABDOMINAL PAIN
1 (1.2)
3 (3.1)
1 (1.4)
5 (2.0)
SALIVARY HYPERSECRETION
0 (0.0)
0 (0.0)
4 (5.6)
4 (1.6)
NERVOUS SYSTEM DISORDERS
6 (7.0)
18 (18.8)
17 (23.6)
41 (16.1)
DIZZINESS
2 (2.3)
9 (9.4)
10 (13.9)
21 (8.3)
HEADACHE
3 (3.5)
3 (3.1)
5 (6.9)
11 (4.3)
SYNCOPE
0 (0.0)
5 (5.2)
2 (2.8)
7 (2.8)
SOMNOLENCE
2 (2.3)
3 (3.1)
1 (1.4)
6 (2.4)
TRANSIENT ISCHAEMIC ATTACK
0 (0.0)
2 (2.1)
1 (1.4)
3 (1.2)
CARDIAC DISORDERS
7 (8.1)
12 (12.5)
14 (19.4)
33 (13.0)
SINUS BRADYCARDIA
2 (2.3)
7 (7.3)
8 (11.1)
17 (6.7)
MYOCARDIAL INFARCTION
4 (4.7)
2 (2.1)
4 (5.6)
10 (3.9)
ATRIAL FIBRILLATION
1 (1.2)
2 (2.1)
2 (2.8)
5 (2.0)
SUPRAVENTRICULAR EXTRASYSTOLES
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
VENTRICULAR EXTRASYSTOLES
0 (0.0)
2 (2.1)
1 (1.4)
3 (1.2)
INFECTIONS AND INFESTATIONS
12 (14.0)
6 (6.2)
11 (15.3)
29 (11.4)
NASOPHARYNGITIS
2 (2.3)
4 (4.2)
6 (8.3)
12 (4.7)
UPPER RESPIRATORY TRACT INFECTION
6 (7.0)
1 (1.0)
3 (4.2)
10 (3.9)
INFLUENZA
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
URINARY TRACT INFECTION
2 (2.3)
0 (0.0)
1 (1.4)
3 (1.2)
CYSTITIS
1 (1.2)
0 (0.0)
1 (1.4)
2 (0.8)
RESPIRATORY, THORACIC AND MEDIASTINAL DISORDERS
5 (5.8)
8 (8.3)
9 (12.5)
22 (8.7)
COUGH
1 (1.2)
5 (5.2)
5 (6.9)
11 (4.3)
NASAL CONGESTION
3 (3.5)
1 (1.0)
3 (4.2)
7 (2.8)
DYSPNOEA
1 (1.2)
1 (1.0)
1 (1.4)
3 (1.2)
EPISTAXIS
0 (0.0)
1 (1.0)
2 (2.8)
3 (1.2)
PHARYNGOLARYNGEAL PAIN
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
PSYCHIATRIC DISORDERS
7 (8.1)
9 (9.4)
3 (4.2)
19 (7.5)
CONFUSIONAL STATE
2 (2.3)
3 (3.1)
1 (1.4)
6 (2.4)
AGITATION
2 (2.3)
3 (3.1)
0 (0.0)
5 (2.0)
INSOMNIA
2 (2.3)
0 (0.0)
2 (2.8)
4 (1.6)
ANXIETY
0 (0.0)
3 (3.1)
0 (0.0)
3 (1.2)
DELUSION
1 (1.2)
0 (0.0)
1 (1.4)
2 (0.8)
MUSCULOSKELETAL AND CONNECTIVE TISSUE DISORDERS
3 (3.5)
6 (6.2)
5 (6.9)
14 (5.5)
BACK PAIN
1 (1.2)
1 (1.0)
3 (4.2)
5 (2.0)
ARTHRALGIA
1 (1.2)
2 (2.1)
1 (1.4)
4 (1.6)
SHOULDER PAIN
1 (1.2)
2 (2.1)
0 (0.0)
3 (1.2)
MUSCLE SPASMS
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
ARTHRITIS
0 (0.0)
0 (0.0)
1 (1.4)
1 (0.4)
INVESTIGATIONS
5 (5.8)
4 (4.2)
3 (4.2)
12 (4.7)
ELECTROCARDIOGRAM ST SEGMENT DEPRESSION
4 (4.7)
1 (1.0)
0 (0.0)
5 (2.0)
ELECTROCARDIOGRAM T WAVE INVERSION
2 (2.3)
1 (1.0)
1 (1.4)
4 (1.6)
BLOOD GLUCOSE INCREASED
0 (0.0)
1 (1.0)
1 (1.4)
2 (0.8)
ELECTROCARDIOGRAM T WAVE AMPLITUDE DECREASED
1 (1.2)
1 (1.0)
0 (0.0)
2 (0.8)
BIOPSY
0 (0.0)
0 (0.0)
1 (1.4)
1 (0.4)
a Includes events of any severity.