# Table Export

Publication requires tables in specific formats: PDF for static outputs, Word documents for collaborative drafting, LaTeX for manuscript preparation, HTML for web supplements, PowerPoint for presentations, and RTF for broad compatability. The `summata` package provides export functions for each format, with consistent parameters across formats and format-specific options where needed.

Function | Format | Dependencies
--- | --- | ---
`tablesave()` | Any of the below, based on file extension | Varies
`data.table::fwrite()` | CSV / TSV | `data.table`
`table2pdf()` | PDF | `xtable`, LaTeX distribution
`table2docx()` | Microsoft Word (.docx) | `flextable`, `officer`
`table2html()` | HTML | `xtable`
`table2pptx()` | PowerPoint (.pptx) | `flextable`, `officer`
`table2tex()` | LaTeX source (.tex) | `xtable`
`table2rtf()` | Rich Text Format (.rtf) | `flextable`

`tablesave()` writes any of these formats, choosing one from the file extension. The format-specific functions may also be called directly if preferred. The syntax for all functions follows the same paradigm:

    result <- tablesave(data, "output.pdf", ...)

where `data` is the dataset, and `"output.pdf"` is the name of the destination file. This vignette demonstrates the various capabilities of these functions using the included sample dataset.

# Preliminaries

The examples in this vignette create sample tables using `summata` functions:

    library(summata)

    data(clintrial)
    data(clintrial_labels)

    # Create sample tables for export
    table1 <- desctable(
      data = clintrial,
      by = "treatment",
      variables = c("age", "sex", "bmi", "smoking", "stage", "ecog"),
      labels = clintrial_labels
    )

    table2 <- fullfit(
      data = clintrial,
      outcome = "surgery",
      predictors = c("age", "sex", "stage", "treatment", "ecog"),
      model_type = "glm",
      labels = clintrial_labels
    )

    table3 <- fullfit(
      data = clintrial,
      outcome = "Surv(os_months, os_status)",
      predictors = c("age", "sex", "stage", "treatment", "ecog"),
      model_type = "coxph",
      labels = clintrial_labels
    )

    table4 <- compfit(
      data = clintrial,
      outcome = "surgery",
      model_list = list(
        "Demographics" = c("age", "sex"),
        "Clinical" = c("age", "sex", "stage", "ecog"),
        "Full" = c("age", "sex", "stage", "ecog", "treatment")
      ),
      model_type = "glm"
    )

# CSV / TSV Export

Delimited text is the simplest export path and requires no dependencies beyond `data.table`, which `summata` already imports. Since all `summata` output tables are `data.table` objects, `data.table::fwrite()` may be used directly.

## Example 1: CSV Export

Standard CSV export can be performed using `data.table::fwrite()`:

    data.table::fwrite(table1, "table1.csv")

## Example 2: TSV Export

TSV export can be performed by using `data.table::fwrite()` with a specified tab delimiter:

    data.table::fwrite(table1, "table1.tsv", sep = "\t")

## Example 3: Semicolon-Delimited (European Locale)

Like `data.table::fwrite()`, `tablesave()` also accepts a custom delimiter:

    data.table::fwrite(table1, "table1_semicolon.csv", sep = ";")

CSV and TSV files are useful for archiving raw table output, importing into spreadsheet software, or downstream processing in other statistical environments. For formatted, publication-ready output, use the export functions described in the sections that follow.

# PDF Export

The `table2pdf()` function creates PDF documents using LaTeX typesetting via the `xtable` package. A LaTeX distribution (TinyTeX, TeX Live, MiKTeX, or MacTeX) is required.

## Example 4: Basic Export

The simplest usage requires only a table and filename:

    table2pdf(
      table = table1,
      file = "table1.pdf"
    )

## Example 5: With Caption

Add a caption using the `caption` parameter:

    table2pdf(
      table = table1,
      file = "table1_caption.pdf",
      caption = "Table 1. Baseline Characteristics by Group"
    )

## Example 6: With Formatting Options

Multiple formatting options can be combined:

    table2pdf(
      table = table2,
      file = "table2.pdf",
      caption = "Table 2. Regression Analysis",
      font_size = 8,
      bold_significant = TRUE,
      p_threshold = 0.05,
      indent_groups = TRUE,
      variable_padding = TRUE,
      zebra_stripes = TRUE
    )

## Example 7: Page Layout

Control page size and orientation:

    table2pdf(
      table = table2,
      file = "table2_landscape.pdf",
      caption = "Table 2. Regression Results",
      paper = "letter",
      orientation = "landscape"
    )

## Example 8: Custom Margins

Adjust page margins (in inches):

    table2pdf(
      table = table2,
      file = "table2_margins.pdf",
      margins = c(0.5, 0.5, 0.5, 0.5)  # top, right, bottom, left
    )

## Example 9: Fit to Page Width

Scale tables to fit the page width:

    table2pdf(
      table = table2,
      file = "table2_fitted.pdf",
      fit_to_page = TRUE
    )

## Example 10: Standalone Table

Standalone settings are useful for embedding tables in larger documents:

    table2pdf(
      table = table2,
      file = "table2_auto.pdf",
      paper = "auto"
    )

# Microsoft Word Export

The `table2docx()` function creates editable Word documents using the `flextable` and `officer` packages.

## Example 11: Basic Export

The simplest usage requires only a table and filename:

    table2docx(
      table = table1,
      file = "table1.docx"
    )

## Example 12: With Caption

Add a caption using the `caption` parameter:

    table2docx(
      table = table1,
      file = "table1_caption.docx",
      caption = "Table 1. Baseline Characteristics by Group"
    )

## Example 13: With Formatting Options

Multiple formatting options can be combined:

    table2docx(
      table = table2,
      file = "table2.docx",
      caption = "Table 2. Regression Analysis",
      font_size = 9,
      font_family = "Times New Roman",
      bold_significant = TRUE,
      p_threshold = 0.05,
      indent_groups = TRUE,
      zebra_stripes = TRUE
    )

## Example 14: Page Layout

Control page size and orientation for wide tables:

    table2docx(
      table = table2,
      file = "table2_landscape.docx",
      caption = "Table 2. Regression Results",
      paper = "letter",
      orientation = "landscape"
    )

## Example 15: Dark Header Style

Use a dark header background for visual emphasis:

    table2docx(
      table = table1,
      file = "table1_darkheader.docx",
      caption = "Table 1. Baseline Characteristics",
      dark_header = TRUE,
      zebra_stripes = TRUE
    )

# HTML Export

The `table2html()` function exports tables to HTML file output for web use via the `xtable` package.

## Example 16: Basic Export

The simplest usage requires only a table and filename:

    table2html(
      table = table1,
      file = "table1.html"
    )

## Example 17: With Caption

Add a caption using the `caption` parameter:

    table2html(
      table = table1,
      file = "table1_caption.html",
      caption = "Table 1. Baseline Characteristics"
    )

## Example 18: With Formatting Options

Multiple formatting options can be combined:

    table2html(
      table = table2,
      file = "table2.html",
      caption = "Table 2. Regression Analysis",
      bold_significant = TRUE,
      indent_groups = TRUE,
      zebra_stripes = TRUE,
      stripe_color = "#f5f5f5"
    )

# PowerPoint Export

The `table2pptx()` function creates PowerPoint presentations with tables using the `flextable` and `officer` packages.

## Example 19: Basic Export

The simplest usage creates a single-slide presentation:

    table2pptx(
      table = table1,
      file = "table1.pptx"
    )

## Example 20: With Slide Title

Add a slide title using the `slide_title` parameter:

    table2pptx(
      table = table1,
      file = "table1_slidetitle.pptx",
      slide_title = "Baseline Characteristics"
    )

## Example 21: With Formatting Options

Multiple formatting options can be combined:

    table2pptx(
      table = table2,
      file = "table2.pptx",
      slide_title = "Regression Analysis",
      font_size = 10,
      font_family = "Arial",
      bold_significant = TRUE,
      indent_groups = TRUE,
      zebra_stripes = TRUE
    )

## Example 22: Custom Template

Use an existing PowerPoint template:

    table2pptx(
      table = table1,
      file = "table1_custom.pptx",
      template = "my_template.pptx",
      layout = "Title and Content",
      master = "Office Theme"
    )

# LaTeX Export

The `table2tex()` function creates LaTeX source files for inclusion in manuscripts via the `xtable` package.

## Example 23: Basic Export

The simplest usage requires only a table and filename:

    table2tex(
      table = table1,
      file = "table1.tex"
    )

## Example 24: With Caption and Label

Add caption and cross-reference label:

    table2tex(
      table = table1,
      file = "table1_caption.tex",
      caption = "Baseline Characteristics by Group",
      label = "tab:demographics"
    )

## Example 25: With Booktabs Styling

Use the booktabs package for professional formatting:

    table2tex(
      table = table2,
      file = "table2.tex",
      caption = "Regression Analysis",
      label = "tab:regression",
      booktabs = TRUE,
      bold_significant = TRUE,
      indent_groups = TRUE
    )

# RTF Export

The `table2rtf()` function creates Rich Text Format files using the `flextable` and `officer` packages.

## Example 26: Basic Export

The simplest usage requires only a table and filename:

    table2rtf(
      table = table1,
      file = "table1.rtf"
    )

## Example 27: With Formatting Options

Multiple formatting options can be combined:

    table2rtf(
      table = table2,
      file = "table2.rtf",
      caption = "Table 2. Regression Analysis",
      font_size = 9,
      font_family = "Times New Roman",
      bold_significant = TRUE,
      indent_groups = TRUE,
      zebra_stripes = TRUE
    )

## Example 28: Page Layout

Control page size and orientation:

    table2rtf(
      table = table2,
      file = "table2_landscape.rtf",
      paper = "letter",
      orientation = "landscape"
    )

# Saving to Any Format

The `tablesave()` function writes a table in the format indicated by the file extension, simplifying the export workflow:

    tablesave(table1, "table1.csv")             # CSV output
    tablesave(table1, "table1.tsv")             # TSV output
    tablesave(table1, "table1.ssv", sep = " ")  # SSV output
    tablesave(table1, "table1.pdf")             # PDF output
    tablesave(table1, "table1.docx")            # DOCX output
    tablesave(table1, "table1.html")            # HTML output
    tablesave(table1, "table1.pptx")            # PPTX output
    tablesave(table1, "table1.tex")             # TeX output
    tablesave(table1, "table1.rtf")             # RTF output

Format-specific parameters pass through to the underlying function:

    tablesave(
      table = table2,
      file = "table2.pdf",
      caption = "Table 2. Regression Analysis",
      orientation = "landscape",
      font_size = 8,
      bold_significant = TRUE,
      indent_groups = TRUE,
      zebra_stripes = TRUE
    )

# Common Formatting Parameters

All export functions share common parameters for consistent results:

Parameter | Description | Default
--- | --- | ---
`caption` | Table caption/title | `NULL`
`font_size` | Base font size (points) | 8–10
`format_headers` | Auto-format column headers | `TRUE`
`bold_significant` | Bold significant p-values | `TRUE`
`p_threshold` | Significance threshold | 0.05
`indent_groups` | Indent factor levels | `FALSE`
`condense_table` | Show essential rows only | `FALSE`
`condense_quantitative` | Condense continuous/survival only (`desctable()` only) | `FALSE`
`zebra_stripes` | Alternating row shading | `FALSE`
`dark_header` | Dark header background | `FALSE`

## Condensing Options

The `condense_table` and `condense_quantitative` parameters reduce table height:

- `condense_table = TRUE`: Condenses continuous, survival, and binary categorical variables
- `condense_quantitative = TRUE`: Condenses only continuous and survival variables (`desctable()` outputs only)

    # Full display
    table2docx(table1, "table1_full.docx")

    # Condense all variable types
    table2docx(
      table = table1,
      file = "table1_condensed.docx",
      condense_table = TRUE,
      zebra_stripes = TRUE
    )

    # Condense only continuous/survival (descriptive tables only)
    table2docx(
      table = table1,
      file = "table1_condensequant.docx",
      condense_quantitative = TRUE,
      zebra_stripes = TRUE
    )

# Format-Specific Parameters

## PDF

Parameter | Description | Default
--- | --- | ---
`margins` | Page margins `c(top, right, bottom, left)` | `c(1, 1, 1, 1)`
`fit_to_page` | Scale table to fit page width | `TRUE`
`cell_padding` | Vertical padding (“none”, “normal”, “relaxed”, “loose”) | `"normal"`
`variable_padding` | Add spacing between variables | `FALSE`
`show_logs` | Keep LaTeX log files | `FALSE`

## Word/RTF/PowerPoint

Parameter | Description | Default
--- | --- | ---
`font_family` | Font name | `Arial`
`width` | Table width (inches) | `NULL`
`align` | Column alignment vector | `NULL`
`return_ft` | Return flextable object | `FALSE`

## HTML

Parameter | Description | Default
--- | --- | ---
`include_css` | Include embedded CSS styling | `FALSE`
`stripe_color` | Zebra stripe color (hex or name) | `"#EEEEEE"`

## LaTeX

Parameter | Description | Default
--- | --- | ---
`booktabs` | Use booktabs package styling | `FALSE`
`label` | LaTeX cross-reference label | `NULL`
`cell_padding` | Arraystretch value | `"normal"`

## PowerPoint (additional)

Parameter | Description | Default
--- | --- | ---
`template` | Custom PPTX template file | `NULL`
`layout` | Slide layout name | `"Title and Content"`
`master` | Slide master name | `"Office Theme"`
`left`, `top` | Table position (inches) | `0.5`, `1.5`

# Best Practices

## Format Selection

Use-Case | Recommended Format
--- | ---
Data archival, further processing | CSV (`.csv`) or TSV (`.tsv`)
Journal submission | PDF (`.pdf`) or LaTeX (`.tex`)
Manuscript drafts, collaboration | Word (`.docx`)
Web/R Markdown | HTML (`.html`)
Presentations | PowerPoint (`.pptx`)
Maximum compatibility | RTF (`.rtf`)

## Page Layout Guidelines

1. Portrait: Tables with ≤ 6 columns
2. Landscape: Tables with > 6 columns
3. Auto-sizing: Use `paper = "auto"` for embedding

## Consistent Multi-Format Export

Export to multiple formats with consistent formatting:

    common_opts <- list(
      caption = "Table 2. Regression Analysis",
      bold_significant = TRUE,
      indent_groups = TRUE,
      zebra_stripes = TRUE
    )

    formats <- c("csv", "pdf", "docx", "html", "pptx", "rtf", "tex")

    for (fmt in formats) {
      tablesave(
        table = table2,
        file = paste0("Table2.", fmt),
        caption = common_opts$caption,
        bold_significant = common_opts$bold_significant,
        indent_groups = common_opts$indent_groups,
        zebra_stripes = common_opts$zebra_stripes
      )
    }

# Troubleshooting

## PDF Compilation Fails

Verify LaTeX installation and consider keeping log files for debugging:

    # Check LaTeX installation
    Sys.which("pdflatex")

    # Install TinyTeX if needed
    # tinytex::install_tinytex()

    # Keep log files for debugging
    table2pdf(table, "debug.pdf", show_logs = TRUE)

See Installation and Setup for LaTeX configuration details.

## Table Too Wide

Several options address wide tables:

    # Use landscape orientation
    table2pdf(table, "wide.pdf", orientation = "landscape")

    # Enable fit-to-page scaling
    table2pdf(table, "wide.pdf", fit_to_page = TRUE)

    # Reduce font size
    table2pdf(table, "wide.pdf", font_size = 7)

## Customizing flextable Output

Get the flextable object for further customization:

    ft <- table2docx(table1, "table1.docx", return_ft = TRUE)

    library(flextable)
    ft <- ft %>%
      bold(i = 1, part = "header") %>%
      color(i = 1, color = "navy", part = "header")

    save_as_docx(ft, path = "table1_custom.docx")

# Further Reading

- Descriptive Tables: `desctable()` for baseline characteristics
- Regression Modeling: `uniscreen()`, `fit()`, and `fullfit()`
- Model Comparison: `compfit()` for comparing models
- Forest Plots: Visualization of regression results
- Multivariate Regression: `multifit()` for multi-outcome analysis
- Advanced Workflows: Interactions and mixed-effects models