# 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
--- | --- | ---
`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`
`autotable()` | Auto-detect from extension | Varies

For delimited text formats (CSV, TSV), tables can be written directly with `data.table::fwrite()` since all `summata` output tables are `data.table` objects. For formatted document output, these functions follow a standard syntax when called:

    result <- autotable(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

All `summata` output tables are `data.table` objects, so they can be written to delimited text files directly with `data.table::fwrite()`. This is the simplest export path and requires no additional dependencies beyond `data.table`, which `summata` already imports.

## Example 1: CSV Export

    data.table::fwrite(table1, file.path(tempdir(), "Table1.csv"))

## Example 2: TSV Export

Specify a tab delimiter for TSV output:

    data.table::fwrite(table1, file.path(tempdir(), "Table1.tsv"), sep = "\t")

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

Use a semicolon delimiter for compatibility with locales where the comma is the decimal separator:

    data.table::fwrite(table1, file.path(tempdir(), "Table1.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 = file.path(tempdir(), "Table1.pdf")
    )

## Example 5: With Caption

Add a caption using the `caption` parameter:

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

## Example 6: With Formatting Options

Multiple formatting options can be combined:

    table2pdf(
      table = table2,
      file = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "Table1.docx")
    )

## Example 12: With Caption

Add a caption using the `caption` parameter:

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

## Example 13: With Formatting Options

Multiple formatting options can be combined:

    table2docx(
      table = table2,
      file = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "Table1.html")
    )

## Example 17: With Caption

Add a caption using the `caption` parameter:

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

## Example 18: With Formatting Options

Multiple formatting options can be combined:

    table2html(
      table = table2,
      file = file.path(tempdir(), "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 = file.path(tempdir(), "Table1.pptx")
    )

## Example 20: With Slide Title

Add a slide title using the `slide_title` parameter:

    table2pptx(
      table = table1,
      file = file.path(tempdir(), "Table1.pptx"),
      slide_title = "Baseline Characteristics"
    )

## Example 21: With Formatting Options

Multiple formatting options can be combined:

    table2pptx(
      table = table2,
      file = file.path(tempdir(), "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 = file.path(tempdir(), "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 = file.path(tempdir(), "Table1.tex")
    )

## Example 24: With Caption and Label

Add caption and cross-reference label:

    table2tex(
      table = table1,
      file = file.path(tempdir(), "Table1.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 = file.path(tempdir(), "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 = file.path(tempdir(), "Table1.rtf")
    )

## Example 27: With Formatting Options

Multiple formatting options can be combined:

    table2rtf(
      table = table2,
      file = file.path(tempdir(), "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 = file.path(tempdir(), "Table2_Landscape.rtf"),
      paper = "letter",
      orientation = "landscape"
    )

# Automatic Format Detection

The `autotable()` function detects the output format from the file extension, simplifying the export workflow:

    autotable(table1, file.path(tempdir(), "Table1.csv"))   # CSV output
    autotable(table1, file.path(tempdir(), "Table1.tsv"))   # TSV output
    autotable(table1, file.path(tempdir(), "Table1.pdf"))   # PDF output
    autotable(table1, file.path(tempdir(), "Table1.docx"))  # DOCX output
    autotable(table1, file.path(tempdir(), "Table1.html"))  # HTML output
    autotable(table1, file.path(tempdir(), "Table1.pptx"))  # PPTX output
    autotable(table1, file.path(tempdir(), "Table1.tex"))   # TeX output
    autotable(table1, file.path(tempdir(), "Table1.rtf"))   # RTF output

Format-specific parameters pass through to the underlying function:

    autotable(
      table = table2,
      file = file.path(tempdir(), "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, file.path(tempdir(), "Table1_Full.docx"))

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

    # Condense only continuous/survival (descriptive tables only)
    table2docx(
      table = table1,
      file = file.path(tempdir(), "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) {
      autotable(
        table = table2,
        file = file.path(tempdir(), 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, file.path(tempdir(), "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, file.path(tempdir(), "wide.pdf"), orientation = "landscape")

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

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

## Customizing flextable Output

Get the flextable object for further customization:

    ft <- table2docx(table1, file.path(tempdir(), "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 = file.path(tempdir(), "Table1_Custom.docx"))

# Further Reading

- Descriptive Tables: `desctable()` for baseline characteristics
- Regression Modeling: `fit()`, `uniscreen()`, 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