table2pdf: Export Table to PDF Format

In summata: Publication-Ready Summary Tables and Forest Plots

Export Table to PDF Format

Description

Converts a data frame, data.table, or matrix to a professionally formatted PDF document using LaTeX as an intermediate format. Provides extensive control over page layout, typography, and formatting for publication-ready output. Particularly well-suited for tables from regression analyses, descriptive statistics, and model comparisons. Requires xtable for export.

Usage

table2pdf(
  table,
  file,
  orientation = "portrait",
  paper = "letter",
  margins = NULL,
  fit_to_page = TRUE,
  font_size = 8,
  caption = NULL,
  caption_size = NULL,
  format_headers = TRUE,
  variable_padding = FALSE,
  cell_padding = "normal",
  bold_significant = TRUE,
  bold_variables = FALSE,
  p_threshold = 0.05,
  align = NULL,
  indent_groups = FALSE,
  condense_table = FALSE,
  condense_quantitative = FALSE,
  zebra_stripes = FALSE,
  stripe_color = "gray!20",
  dark_header = FALSE,
  show_logs = FALSE,
  ...
)

Arguments

table	Data frame, data.table, or matrix to export. Can be output from desctable(), survtable(), fit(), uniscreen(), fullfit(), compfit(), or any tabular data structure.
file	Character string specifying the output PDF filename. Must have .pdf extension. Example: "results.pdf", "Table1.pdf".
orientation	Character string specifying page orientation: "portrait" - Vertical orientation [default] "landscape" - Horizontal orientation (recommended for wide tables)
paper	Character string specifying paper size: "letter" - US Letter (8.5" x 11") [default] "a4" - A4 (210 mm x 297 mm) "auto" - Auto-size to content (no margins, crops to fit)
margins	Numeric vector of length 4 specifying margins in inches as c(top, right, bottom, left). Default is c(1, 1, 1, 1). Ignored when paper = "auto".
fit_to_page	Logical. If TRUE, scales table to fit within the text width (respects margins). Useful for wide tables that would otherwise overflow. Default is TRUE.
font_size	Numeric. Base font size in points. Default is 8. Smaller values accommodate more content; larger values improve readability. Typical range: 6-12 points.
caption	Character string. Optional caption displayed below the table. Supports LaTeX formatting for multi-line captions, superscripts, italics, etc. See Details for formatting guidance. Default is NULL.
caption_size	Numeric. Caption font size in points. If NULL (default), uses the base font_size. Set to a specific value (e.g., 6, 7, 8) to control caption size independently of table font size. Useful for fitting captions on constrained page sizes. Typical range: 6-10 points.
format_headers	Logical. If TRUE, applies automatic formatting to column headers: converts underscores to spaces, italicizes statistical notation ("n", "p"), and improves readability. Default is TRUE.
variable_padding	Logical. If TRUE, adds vertical spacing between different variables in the table, creating visual grouping. Particularly useful for regression tables with multiple predictors. Default is FALSE.
cell_padding	Character string or numeric specifying vertical padding within table cells: "none" - No extra padding (most compact) "normal" - Standard padding [default] "relaxed" - Increased padding "loose" - Maximum padding Numeric value - Custom multiplier (e.g., 1.5) Adjusts \arraystretch in LaTeX.
bold_significant	Logical. If TRUE, applies bold formatting to p-values below the significance threshold, making significant results stand out visually. Default is TRUE.
bold_variables	Logical. If TRUE, variable names are displayed in bold. Default is FALSE.
p_threshold	Numeric. Threshold for bold p-value formatting. Only used when bold_significant = TRUE. Default is 0.05.
align	Character string or vector specifying column alignment. Options: "l" - Left aligned "c" - Center aligned "r" - Right aligned If NULL (default), automatically determines alignment based on content (text left, numbers right). Can specify per-column: c("l", "l", "r", "r").
indent_groups	Logical. If TRUE, indents factor levels/groups under their parent variable using horizontal space, creating a hierarchical display. Useful for factor variables in regression tables. Default is FALSE.
condense_table	Logical. If TRUE, condenses the table by: Showing only one row per continuous variable (estimate + CI) Showing only non-reference categories for binary factors Automatically setting indent_groups = TRUE Significantly reduces table height. Default is FALSE.
condense_quantitative	Logical. If TRUE, condenses continuous and survival variables into single rows while preserving all categorical variable rows (including binary). Only applies to descriptive tables from desctable(). Automatically sets indent_groups = TRUE. Unlike condense_table, this does not collapse binary categorical variables. Default is FALSE.
zebra_stripes	Logical. If TRUE, applies alternating gray background shading to different variables (not individual rows) for improved visual grouping and readability. Default is FALSE.
stripe_color	Character string. LaTeX color specification for zebra stripes. Default is "gray!20" (20% gray). Can use other colors like "blue!10", "red!15". Requires zebra_stripes = TRUE.
dark_header	Logical. If TRUE, creates a dark (black) background with white text for the header row. Provides strong visual contrast. Default is FALSE.
show_logs	Logical. If TRUE, retains LaTeX log and auxiliary files after PDF compilation for troubleshooting. If FALSE, deletes these files. Default is FALSE.
...	Additional arguments passed to xtable for advanced LaTeX table customization.

Details

LaTeX Requirements:

This function requires a working LaTeX installation. The function checks for LaTeX availability and provides installation guidance if missing.

Recommended LaTeX distributions:

• TinyTeX (lightweight, R-integrated): Install via tinytex::install_tinytex()

• TeX Live (comprehensive, cross-platform)

• MiKTeX (Windows)

• MacTeX (macOS)

Required LaTeX packages (auto-installed with most distributions):

• fontenc, inputenc - Character encoding

• array, booktabs, longtable - Table formatting

• graphicx - Scaling tables

• geometry - Page layout

• pdflscape, lscape - Landscape orientation

• helvet - Sans-serif fonts

• standalone, varwidth - Auto-sizing (for paper = "auto")

• float, caption - Floats and captions

• xcolor, colortable - Colors (for zebra_stripes or dark_header)

Caption Formatting:

Captions support LaTeX commands for rich formatting:

# Multi-line caption with line breaks
caption = "Table 1: Multivariable Analysis\\
          OR = odds ratio; CI = confidence interval"

# With superscripts (using LaTeX syntax)
caption = "Table 1: Results\\
          Adjusted for age and sex\\
          p-values from Wald tests"

# With special characters (must escape percent signs)
caption = "Results for income (in thousands)"

Auto-Sizing (paper = "auto"):

When paper = "auto", the function attempts to create a minimal PDF sized exactly to the table content:

1. Using the standalone LaTeX class (cleanest output)

2. Fallback to pdfcrop utility if standalone unavailable

3. Fallback to minimal margins if neither available

Table Width Management:

For wide tables that don't fit on the page:

1. Use orientation = "landscape"

2. Use fit_to_page = TRUE (default) to auto-scale

3. Reduce font_size (e.g., 7 or 6)

4. Consider paper = "auto" for maximum flexibility

Troubleshooting:

If PDF compilation fails:

1. Check that LaTeX is installed: Run Sys.which("pdflatex")

2. Set show_logs = TRUE and examine the .log file

3. Common issues:

   • Missing LaTeX packages: Install via package manager

   • Special characters in text: Escape properly

   • Very wide tables: Use landscape or reduce font size

   • Caption formatting: Check LaTeX syntax

Value

Invisibly returns NULL. Creates a PDF file at the specified location. If compilation fails, check the .log file (if show_logs = TRUE) for error details.

See Also

autotable for automatic format detection, table2tex for LaTeX source files, table2html for HTML output, table2docx for Microsoft Word, table2pptx for PowerPoint, table2rtf for Rich Text Format, desctable for descriptive tables, fit for regression tables

Other export functions: autotable(), table2docx(), table2html(), table2pptx(), table2rtf(), table2tex()

Examples

data(clintrial)
data(clintrial_labels)

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

# Test that LaTeX can compile (needed for all PDF examples)
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)
  tryCatch(
    system2("pdflatex", c("-interaction=nonstopmode",
            paste0("-output-directory=", tempdir()), test_tex),
            stdout = FALSE, stderr = FALSE),
    error = function(e) 1L) == 0L
})

# Example 1: Basic PDF export
if(has_latex){
  table2pdf(results, file.path(tempdir(), "basic_results.pdf"))
}



if(has_latex){

# Example 2: Landscape orientation for wide tables
table2pdf(results, file.path(tempdir(), "wide_results.pdf"),
         orientation = "landscape")

# Example 3: With caption
table2pdf(results, file.path(tempdir(), "captioned.pdf"),
         caption = "Table 1: Multivariable logistic regression results")

# Example 4: Multi-line caption with formatting
table2pdf(results, file.path(tempdir(), "formatted_caption.pdf"),
         caption = "Table 1: Risk Factors for Mortality\\\\
                   aOR = adjusted odds ratio; CI = confidence interval")

# Example 5: Auto-sized PDF (no fixed page dimensions)
table2pdf(results, file.path(tempdir(), "autosize.pdf"),
         paper = "auto")

# Example 6: A4 paper with custom margins
table2pdf(results, file.path(tempdir(), "a4_custom.pdf"),
         paper = "a4",
         margins = c(0.75, 0.75, 0.75, 0.75))

# Example 7: Larger font for readability
table2pdf(results, file.path(tempdir(), "large_font.pdf"),
         font_size = 11)

# Example 8: Indented hierarchical display
table2pdf(results, file.path(tempdir(), "indented.pdf"),
         indent_groups = TRUE)

# Example 9: Condensed table (reduced height)
table2pdf(results, file.path(tempdir(), "condensed.pdf"),
         condense_table = TRUE)

# Example 10: With zebra stripes
table2pdf(results, file.path(tempdir(), "striped.pdf"),
         zebra_stripes = TRUE,
         stripe_color = "gray!15")

# Example 11: Dark header style
table2pdf(results, file.path(tempdir(), "dark_header.pdf"),
         dark_header = TRUE)

# Example 12: Combination of formatting options
table2pdf(results, file.path(tempdir(), "publication_ready.pdf"),
         orientation = "portrait",
         paper = "letter",
         font_size = 9,
         caption = "Table 2: Multivariable Analysis\\\\
                   Model adjusted for age, sex, and clinical factors",
         indent_groups = TRUE,
         zebra_stripes = TRUE,
         bold_significant = TRUE,
         p_threshold = 0.05)

# Example 13: Adjust cell padding
table2pdf(results, file.path(tempdir(), "relaxed_padding.pdf"),
         cell_padding = "relaxed")  # More spacious

# Example 14: No scaling (natural table width)
table2pdf(results, file.path(tempdir(), "no_scale.pdf"),
         fit_to_page = FALSE,
         font_size = 10)

# Example 15: Hide significance bolding
table2pdf(results, file.path(tempdir(), "no_bold.pdf"),
         bold_significant = FALSE)

# Example 16: Custom column alignment
table2pdf(results, file.path(tempdir(), "custom_align.pdf"),
         align = c("c", "c", "c", "c", "c", "c", "c"))

# Example 17: Descriptive statistics table
desc_table <- desctable(clintrial, by = "treatment",
     variables = c("age", "sex", "bmi", "stage"), labels = clintrial_labels)

table2pdf(desc_table, file.path(tempdir(), "descriptive.pdf"),
         caption = "Table 1: Baseline Characteristics by Treatment Group",
         orientation = "landscape")

# Example 18: Model comparison table
models <- list(
     base = c("age", "sex"),
     full = c("age", "sex", "bmi", "treatment")
)

comparison <- compfit(
     data = clintrial,
     outcome = "os_status",
     model_list = models
)

table2pdf(comparison, file.path(tempdir(), "model_comparison.pdf"),
         caption = "Table 3: Model Comparison Statistics")

# Example 19: Very wide table with aggressive fitting
wide_model <- fit(
     data = clintrial,
     outcome = "os_status",
     predictors = c("age", "sex", "race", "bmi", "smoking", 
                   "hypertension", "diabetes", "treatment", "stage")
)

table2pdf(wide_model, file.path(tempdir(), "very_wide.pdf"),
         orientation = "landscape",
         font_size = 7,
         fit_to_page = TRUE,
         condense_table = TRUE)

# Example 20: With caption size control
table2pdf(results, file.path(tempdir(), "caption_size.pdf"),
         font_size = 8,
         caption_size = 6,
         caption = "Table 4: Results with Compact Caption\\\\
                   Smaller caption fits better on constrained pages")

# Example 21: Troubleshooting - keep logs
table2pdf(results, file.path(tempdir(), "debug.pdf"),
         show_logs = TRUE)
# If it fails, check debug.log for error messages

}

summata documentation built on May 7, 2026, 5:07 p.m.