Save a Table to File

Writes a table to file in the format indicated by the file extension, dispatching to the appropriate specialized export function. Provides a unified interface for table export across all supported formats, and is the counterpart to forestsave() for forest plots.

Usage

tablesave(table, file, quiet = FALSE, ...)

autotable(table, file, quiet = FALSE, ...)

Arguments

table

A table produced by desctable(), survtable(), fit(), uniscreen(), fullfit(), compfit(), or multifit(). Any data frame, data.table, or matrix is accepted.

file

Character string specifying the output filename. The file extension determines the export format:

.csv - Comma-separated values (uses data.table::fwrite())
.tsv - Tab-separated values (uses data.table::fwrite())
.pdf - PDF via LaTeX (uses table2pdf())
.docx - Microsoft Word (uses table2docx())
.html or .htm - HTML (uses table2html())
.pptx - Microsoft PowerPoint (uses table2pptx())
.tex - LaTeX source (uses table2tex())
.rtf - Rich Text Format (uses table2rtf())

quiet

Logical. Suppress progress and confirmation messages. The setting is forwarded to the format-specific export function, so the LaTeX compilation notices from table2pdf() are suppressed with it. Default is FALSE.

...

Additional arguments passed to the format-specific function. See the documentation for individual functions for available parameters:

PDF: table2pdf() - orientation, paper, margins, fit_to_page, etc.
DOCX: table2docx() - font_size, font_family, caption, etc.
HTML: table2html() - format_headers, zebra_stripes, etc.
PPTX: table2pptx() - font_size, font_family, caption, etc.
TEX: table2tex() - caption, format_headers, align, etc.
RTF: table2rtf() - font_size, font_family, caption, etc.
CSV, TSV: data.table::fwrite() - sep, quote, na, etc.

Common parameters across formats include:

caption: Table caption (supported by most formats)
font_size: Base font size in points (PDF, DOCX, PPTX, RTF)
format_headers: Format column headers (all formats)
bold_significant: Bold significant p-values (all formats)
p_threshold: Threshold for p-value bolding (all formats)
indent_groups: Indent factor levels (all formats)
condense_table: Condense to essential rows (all formats)
zebra_stripes: Alternating background colors (most formats)

Value

Invisibly returns file.

Details

This function provides a convenient wrapper around format-specific export functions, automatically routing to the appropriate function based on the file extension. All parameters are passed through to the underlying function, so the full range of format-specific options remains available.

For format-specific advanced features, individual export functions may be called directly:

PDF exports support orientation, paper size, margins, and auto-sizing
DOCX/PPTX/RTF support font customization and flextable formatting
HTML supports CSS styling, responsive design, and custom themes
TeX generates standalone LaTeX source with booktabs styling

Examples

# Create example data
data(clintrial)
data(clintrial_labels)
tbl <- desctable(clintrial, by = "treatment",
    variables = c("age", "sex"), labels = clintrial_labels)

# Example 1: The format follows the file extension
if (requireNamespace("xtable", quietly = TRUE)) {
  tablesave(tbl, file.path(tempdir(), "example.html"))
}
#> Table saved to /tmp/RtmpVRC0ab/example.html

# Example 2: Delimited output needs no additional packages
tablesave(tbl, file.path(tempdir(), "example.csv"))
#> Table saved to /tmp/RtmpVRC0ab/example.csv

# Example 3: Suppress the message reporting the file written
tablesave(tbl, file.path(tempdir(), "example.tsv"), quiet = TRUE)

# \donttest{
# Load example data
data(clintrial)
data(clintrial_labels)

# Create a regression table
results <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment"),
    labels = clintrial_labels
)

# Test that LaTeX can actually compile (needed for PDF export)
has_latex <- local({
  if (!nzchar(Sys.which("pdflatex"))) return(FALSE)
  test_tex <- file.path(tempdir(), "summata_latex_test.tex")
  writeLines(c("\\documentclass{article}",
               "\\usepackage{booktabs}",
               "\\begin{document}", "test",
               "\\end{document}"), test_tex)
  result <- tryCatch(
    system2("pdflatex", c("-interaction=nonstopmode",
            paste0("-output-directory=", tempdir()), test_tex),
            stdout = FALSE, stderr = FALSE),
    error = function(e) 1L)
  result == 0L
})

# Example 4: The format is taken from the file extension
tablesave(results, file.path(tempdir(), "results.html"))  # Creates HTML file
#> Table saved to /tmp/RtmpVRC0ab/results.html
tablesave(results, file.path(tempdir(), "results.docx"))  # Creates Word document
#> Table saved to /tmp/RtmpVRC0ab/results.docx
tablesave(results, file.path(tempdir(), "results.pptx"))  # Creates PowerPoint slide
#> Table saved to /tmp/RtmpVRC0ab/results.pptx
tablesave(results, file.path(tempdir(), "results.tex"))   # Creates LaTeX source
#> Table saved to /tmp/RtmpVRC0ab/results.tex
tablesave(results, file.path(tempdir(), "results.rtf"))   # Creates RTF document
#> Table saved to /tmp/RtmpVRC0ab/results.rtf
if (has_latex) {
  tablesave(results, file.path(tempdir(), "results.pdf")) # Creates PDF
}
#> Compiling PDF...
#> Table saved to /tmp/RtmpVRC0ab/results.pdf

# Example 5: Format-specific parameters are passed through
if (has_latex) {
  tablesave(results, file.path(tempdir(), "results.pdf"), 
             orientation = "landscape",
             paper = "a4",
             font_size = 10)
}
#> Compiling PDF...
#> Table saved to /tmp/RtmpVRC0ab/results.pdf

tablesave(results, file.path(tempdir(), "results.docx"),
           caption = "Table 1: Logistic Regression Results",
           font_family = "Times New Roman",
           condense_table = TRUE)
#> Table saved to /tmp/RtmpVRC0ab/results.docx

tablesave(results, file.path(tempdir(), "results.html"),
           zebra_stripes = TRUE,
           dark_header = TRUE,
           bold_significant = TRUE)
#> Table saved to /tmp/RtmpVRC0ab/results.html

# Example 6: Any summata table may be saved
desc <- desctable(clintrial,
                  by = "treatment",
                  variables = c("age", "sex", "bmi"))
if (has_latex) {
  tablesave(desc, file.path(tempdir(), "demographics.pdf"))
}
#> Compiling PDF...
#> Table saved to /tmp/RtmpVRC0ab/demographics.pdf

# Example 7: Model comparison table
# Information criteria assume a common sample, so the candidate
# predictors are restricted to complete cases before comparison
comparison_data <- na.omit(
    clintrial[, c("os_status", "age", "sex", "treatment", "stage")]
)
comparison <- compfit(
    data = comparison_data,
    outcome = "os_status",
    model_list = list(
        base = c("age", "sex"),
        full = c("age", "sex", "treatment", "stage")
    )
)
#> Auto-detected binary outcome, using logistic regression
#> Fitting base with 2 predictors...
#> Fitting full with 4 predictors...
tablesave(comparison, file.path(tempdir(), "model_comparison.docx"))
#> Table saved to /tmp/RtmpVRC0ab/model_comparison.docx

# }

Usage

Arguments

Value

Details

See also

Examples