Write an hv_man_table() table to a compliant .docx

Stage 3 of the %summarytable split: writes the document. Replaces the macro's RTFFILE=/PDFFILE= output block.

Usage

hv_man_table_save(
  ft,
  file,
  footnotes = NULL,
  abbreviations = NULL,
  caption = NULL,
  ...
)

Arguments

ft: A flextable object, typically from hv_man_table().
file: Output .docx path. The output directory (dirname(file)) must already exist; this function does not create it. (%summarytable RTFFILE=/PDFFILE= equivalent; output here is always .docx).
footnotes: Optional named list, symbol -> footnote text. When omitted, uses the hv_footnotes attribute carried from hv_tbl_summary() through hv_man_table(), so the dagger follows that table's continuous_stat and percentiles. Other flextables fall back to hv_man_footnotes()'s median/15th-85th house defaults. Pass NULL to suppress both, or compose with hv_man_footnotes() to override or extend. A note's text may carry ^2^ or ~2~ markup, as a label does. Symbols must be drawn from c("*", "†", "‡", "§", "¶", "||"). † describes the statistic, so it is appended as a superscript reference mark to every statistic-column header (stat_<k>), and to the count column only when the table has no such column. On a table that compares its groups, † also marks the p-value and standardized-difference headers, because the note names the tests behind the p-values and says what the difference is. Every other symbol goes on the table's count-column header cell (a column named n, else the first n_stat_<k> column hv_man_table() creates when it splits an hv_tbl_summary() table, else the first column). In a manuscript table the dagger goes on the grouping's spanning cell and * on its n column. In the describe layout * goes on every group's n and the dagger on every statistic. Each text is rendered as its own paragraph below the table, in the order given. Every element must be named (unnamed or blank-named entries raise an error) and every text must be a single non-empty string (NULL, NA, a number, or a multi-element vector raise an error, since each writes a dangling marker); an empty list is a no-op, same as NULL. (%summarytable ADDFN= equivalent; PRINTFN=1's house block is hv_man_footnotes()).
abbreviations: Optional named character vector, c(ABBR = "expansion", ...). A table with a confidence-interval column (compare = "both") adds CI unless you define it yourself. Rendered as one Key: paragraph below any footnotes, sorted alphabetically by abbreviation, abbreviation italicized, pairs separated by "; " (house rule 14). Every element must be named (unnamed or blank-named entries raise an error); an empty or NULL vector is a no-op. A name or definition may carry ^2^ or ~2~ markup, as a label does.
caption: The table's caption, written in bold on its own line above the table. A manuscript table requires one, so it is written with the table and not typed in later; a report table takes one when given and writes none otherwise. It may carry ^2^ or ~2~ markup, as a label does.
...: Not used. Present so that %summarytable parameter names produce an error naming the argument to use instead.

Value

Invisibly, the file path.

Details

You hand this a flextable (typically from hv_man_table()), and it writes a Word document with footnotes and an abbreviation key rendered as text below the table rather than embedded within it (house rules 13-14). flextable::footnote() cannot do this for you: it renders footnote text as an extra row inside the table's own <w:tbl> block (a "footer" table part), which is exactly the compliance violation this function exists to avoid. Instead, a superscript reference symbol is appended to the target header cell (a normal, compliant reference mark), and the footnote text itself is written as a genuine document paragraph after the table via officer::body_add_fpar(). The table itself is inserted directly (no leading blank paragraph), which keeps vertical cell alignment controllable if you later reformat the surrounding document to 1.5- or double-spacing. House rule 2 concerns the insertion point in the destination document, not this function's output; see the package README for the paste-in workflow.

Every style is written on a US Letter page. A report table with three or more statistic columns, such as an Overall column and two groups, is written on a landscape page: with a No. column beside each, it does not fit a portrait one. A manuscript table turns only on width, since it has one overall n column: Overall, two groups and a P value come to 6.5 inches and stay portrait. Any table wider than a portrait page's text block (6.53 inches on US Letter) is written landscape. A table wider than landscape's (9.0 inches), as a continuous_stat = "both" table with an Overall column can be, has its columns narrowed in proportion to fit; the font size is not changed.

In every style the saver drops the "Variable" column hv_tbl_summary()'s show_variable adds for the report view before the page is fitted, so it never reaches Word and never widens the page. hv_man_table_display() keeps it, for the report.

Common mistakes

"A manuscript table needs caption ..." The table is in the manuscript style, which requires a caption so the title is written with the table. Pass caption = "Table 1. ..."; a report table takes one optionally.

"footnotes must be a named list (symbol -> footnote text) ..." You passed the deprecated JTCVS shape. The two savers' footnotes arguments are unrelated types: this one is keyed by symbol, list(`*` = "text"), and hv_man_table_save_jtcvs()'s is keyed by position, list(list(row =, col =, text =)). So hv_test_footnotes_jtcvs()'s output does not belong here; hv_man_footnotes()'s does.

"Invalid footnote symbol(s): ..." Symbols are drawn from the house set * † ‡ § ¶ ||. A letter or a digit is not one of them; lettered markers are the JTCVS renderer's convention.

"Output directory does not exist: ..." The dirname() of file is not created for you. Run dir.create(dirname(file), recursive = TRUE) first.

A hand-built footnote that misstates the table. The automatic hv_tbl_summary() -> hv_man_table() path keeps the default dagger in sync. When supplying footnotes yourself, make its wording match the statistic and percentile pair used to build the table.

Examples

library(gtsummary)
tbl <- tbl_summary(trial, by = trt, include = c(age, grade))
ft <- hv_man_table(tbl)
out <- tempfile(fileext = ".docx")
hv_man_table_save(ft, out, abbreviations = c(N = "sample size"))
unlink(out)