---
title: "Table Export"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Table Export}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE,
  eval = FALSE
)
old_opts <- options(width = 180)
```

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:

``` r
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:

```{r setup, eval = TRUE}
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

```{r}
data.table::fwrite(table1, file.path(tempdir(), "Table1.csv"))
```

## **Example 2:** TSV Export

Specify a tab delimiter for TSV output:

```{r}
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:

```{r}
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:

```{r}
table2pdf(
  table = table1,
  file = file.path(tempdir(), "Table1.pdf")
)
```

## **Example 5:** With Caption

Add a caption using the `caption` parameter:

```{r}
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:

```{r}
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:

```{r}
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):

```{r}
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:

```{r}
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:

```{r}
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:

```{r}
table2docx(
  table = table1,
  file = file.path(tempdir(), "Table1.docx")
)
```

## **Example 12:** With Caption

Add a caption using the `caption` parameter:

```{r}
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:

```{r}
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:

```{r}
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:

```{r}
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:

```{r}
table2html(
  table = table1,
  file = file.path(tempdir(), "Table1.html")
)
```

## **Example 17:** With Caption

Add a caption using the `caption` parameter:

```{r}
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:

```{r}
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:

```{r}
table2pptx(
  table = table1,
  file = file.path(tempdir(), "Table1.pptx")
)
```

## **Example 20:** With Slide Title

Add a slide title using the `slide_title` parameter:

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

## **Example 21:** With Formatting Options

Multiple formatting options can be combined:

```{r}
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:

```{r}
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:

```{r}
table2tex(
  table = table1,
  file = file.path(tempdir(), "Table1.tex")
)
```

## **Example 24:** With Caption and Label

Add caption and cross-reference label:

```{r}
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:

```{r}
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:

```{r}
table2rtf(
  table = table1,
  file = file.path(tempdir(), "Table1.rtf")
)
```

## **Example 27:** With Formatting Options

Multiple formatting options can be combined:

```{r}
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:

```{r}
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:

```{r}
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:

```{r}
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)

```{r}
# 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:

```{r}
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:

```{r}
# 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](installation_setup.html) for LaTeX configuration details.

## Table Too Wide

Several options address wide tables:

```{r}
# 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:

```{r}
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"))
```

```{r, include = FALSE}
options(old_opts)
```

---

# Further Reading

- [Descriptive Tables](descriptive_tables.html): `desctable()` for baseline characteristics
- [Regression Modeling](regression_modeling.html): `fit()`, `uniscreen()`, and `fullfit()`
- [Model Comparison](model_comparison.html): `compfit()` for comparing models
- [Forest Plots](forest_plots.html): Visualization of regression results
- [Multivariate Regression](multivariate_regression.html): `multifit()` for multi-outcome analysis
- [Advanced Workflows](advanced_workflows.html): Interactions and mixed-effects models