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

Make the output look like it belongs in the final report. Rename labels, merge
tables, and save tables or plots.

```{r export-setup, message=FALSE, warning=FALSE}
library(gtregression)
library(dplyr)

data("data_birthwt", package = "gtregression")

birthwt_data <- data_birthwt |>
  mutate(
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    ui = factor(ui, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

birthwt_exposures <- c("age", "lwt", "race", "smoke", "ht", "ui")

attr(birthwt_data$age, "label") <- "Maternal age"
attr(birthwt_data$lwt, "label") <- "Maternal weight"
attr(birthwt_data$race, "label") <- "Maternal race"
attr(birthwt_data$smoke, "label") <- "Smoking during pregnancy"
attr(birthwt_data$ht, "label") <- "Hypertension"
attr(birthwt_data$ui, "label") <- "Uterine irritability"

birthwt_desc <- descriptive_table(
  birthwt_data,
  exposures = birthwt_exposures,
  by = low
)
birthwt_uni <- uni_reg(
  birthwt_data,
  outcome = low,
  exposures = birthwt_exposures,
  approach = logit
)
birthwt_multi <- multi_reg(
  birthwt_data,
  outcome = low,
  exposures = c("smoke", "ht", "ui"),
  adjust_for = c("age", "lwt", "race"),
  approach = logit
)
```

## Customize Labels

If labels already live on the data, `gtregression` uses them automatically.
`modify_table()` is still useful for journal-specific wording, compact headers,
captions, and caveats. Use raw variable names on the left side of
`variable_labels` and `level_labels`; this keeps customisation stable even when
the visible table already shows prettier labels.

Footnotes and caveats are styled compactly by default across flextable and gt
outputs, which keeps abbreviation notes and adjustment notes readable without
making final tables unnecessarily tall.

> **Figure placeholder: anatomy of a gtregression table.** Add the slide image
> here to identify the caption, headers, characteristic labels, category levels,
> sample-size columns, abbreviations, automatic adjustment note, and custom
> caveat. The intended asset path is
> `vignettes/figures/modify-table-anatomy.png`.

<!-- When the image is added, replace the callout above with:
![Anatomy of a gtregression table](figures/modify-table-anatomy.png)
-->

### Customisation Options At A Glance

| Table part | Argument | Default | What it changes | Example |
|---|---|---:|---|---|
| Characteristic label | `variable_labels` | `NULL` | Renames variable/header rows using internal variable names. | `c(age = "Maternal age")` |
| Category level | `level_labels` | `NULL` | Renames factor levels while retaining their indentation and reference category. | `list(smoke = c(Yes = "Smoker"))` |
| Column header | `header_labels` | `NULL` | Renames visible headers. Common aliases include `estimate`, `p.value`, and `N`. | `c(estimate = "Adjusted OR")` |
| Caption | `caption` | `NULL` | Adds a manuscript-style title above the table. | `"Factors associated with low birth weight"` |
| Characteristic emphasis | `bold_labels` | `TRUE` | Bolds variable/characteristic rows. | `FALSE` |
| Category emphasis | `bold_levels` | `FALSE` | Bolds category-level rows. | `TRUE` |
| Characteristic style | `italic_labels` | `FALSE` | Italicizes variable/characteristic rows. | `TRUE` |
| Category style | `italic_levels` | `FALSE` | Italicizes category-level rows. | `TRUE` |
| Displayed N columns | `remove_N` | `FALSE` | Removes visible sample-size columns where present. | `TRUE` |
| Complete-case note | `remove_N_obs` | `FALSE` | Removes the `N = ... complete observations` footnote. | `TRUE` |
| Abbreviations | `remove_abbreviations` | `FALSE` | Removes the abbreviations footnote only. | `TRUE` |
| Adjustment note | `remove_adjustment_note` | `FALSE` | Removes the automatic `Adjusted for ...` note. | `TRUE` |
| Extra footnote | `caveat` | `NULL` | Adds a final study-specific interpretation or manuscript note. | `"Estimates use complete-case analysis."` |

Use raw internal variable names on the left side of `variable_labels` and
`level_labels`. `remove_N` removes visible table columns, whereas
`remove_N_obs` removes only the complete-case footnote. When replacing the
automatic adjustment note, use `remove_adjustment_note = TRUE` together with a
custom `caveat`.

```{r modify-table, message=FALSE, warning=FALSE}
birthwt_custom <- modify_table(
  birthwt_multi,
  variable_labels = c(
    smoke = "Smoked during pregnancy",
    ht = "History of hypertension",
    ui = "Uterine irritability"
  ),
  level_labels = list(
    smoke = c(Yes = "Smoker"),
    ht = c(Yes = "Hypertensive")
  ),
  header_labels = c(estimate = "Adjusted OR", p.value = "P"),
  caption = "Adjusted regression for low birth weight",
  caveat = "Adjusted for maternal age, maternal weight, and maternal race."
)

birthwt_custom
```

## Merge Tables

`merge_tables()` combines descriptive, crude, and adjusted results. Matching is
based on the original variable names, so merged tables remain aligned even when
the visible labels differ across input tables.

Merged tables use `flextable` by default, including when one or more input
tables were created with `format = "gt"`. Use `format = "gt"` explicitly for
an HTML-first merged table.

### Keep Binary Rows Consistent

Before merging a descriptive, crude, and adjusted table, use the same binary
row layout in every input. The clearest publication layout keeps both levels in
the descriptive table and displays the regression reference row:

```r
birthwt_desc <- descriptive_table(
  birthwt_data,
  exposures = exposures,
  by = "low",
  show_dichotomous = "all_levels"
)

birthwt_uni <- uni_reg(
  birthwt_data,
  outcome = "low",
  exposures = exposures,
  approach = "logit",
  show_ref = TRUE
)
```

Use `show_ref = TRUE` for the adjusted regression table as well. If one table
uses compact binary rows while another displays both levels, `merge_tables()`
warns before merging because additional rows can otherwise appear. Compact
tables are also supported when used consistently: set
`show_dichotomous = "single_row"` and `show_ref = FALSE` across the relevant
tables.

`merge_tables()` carries the footnotes already present in each input table.
Exact duplicate notes are shown once, while table-specific notes, including the
adjustment note from `multi_reg()`, are retained unchanged. The adjustment note
uses the same display labels as the multivariable table; labels supplied through
variable metadata or `modify_table()` are therefore reflected in the note. The
same rule applies to adjusted `cox_reg()` and `surv_reg()` tables.

Use `modify_table(remove_adjustment_note = TRUE, caveat = "...")` when a
custom manuscript note is preferred.

```{r merge-tables, message=FALSE, warning=FALSE}
birthwt_merged <- merge_tables(
  birthwt_desc,
  birthwt_uni,
  birthwt_multi,
  spanners = c("Descriptive", "Crude", "Adjusted")
)

birthwt_merged$table
```

The merged table can be polished after merging too.

```{r merged-polish, message=FALSE, warning=FALSE}
birthwt_merged_paper <- modify_table(
  birthwt_merged,
  variable_labels = c(
    age = "Maternal age",
    lwt = "Maternal weight",
    race = "Maternal race",
    smoke = "Smoking during pregnancy",
    ht = "Hypertension",
    ui = "Uterine irritability"
  ),
  caption = "Clinical profile and regression estimates for low birth weight",
  caveat = "Adjusted estimates are adjusted for maternal age, maternal weight, and maternal race."
)

birthwt_merged_paper$table
```

## Save Outputs

When no directory is supplied, save helpers use `tempdir()`. This keeps examples
and tests CRAN-safe while still returning the file path invisibly.

```{r save-examples, eval=FALSE}
table_path <- save_table(
  birthwt_merged_paper,
  filename = "birthwt-table",
  format = html
)

birthwt_plot <- plot_reg(
  birthwt_multi,
  title = "Adjusted Regression for Low Birth Weight"
)

plot_path <- save_plot(
  birthwt_plot,
  filename = "birthwt-forest",
  format = png
)
```

## Word Reports

`flextable` is the default table engine, so Word export works naturally. If a
table was created as `format = gt`, save it as HTML/PDF or recreate it with
`format = flextable` before sending it to `save_docx()`. Wide tables are fitted
to a standard Word page by default; use `table_width` when your document has
different margins or landscape orientation.

```{r word-example, eval=FALSE}
birthwt_multi_ft <- multi_reg(
  birthwt_data,
  outcome = low,
  exposures = c("smoke", "ht", "ui"),
  adjust_for = c("age", "lwt", "race"),
  approach = logit,
  format = flextable
)

docx_path <- save_docx(
  tables = list(birthwt_multi_ft),
  filename = "birthwt-report",
  titles = "Adjusted Regression",
  table_width = 6.5
)
```

## What To Inspect

- `modify_table()`: changed labels, caption, and caveat.
- `merge_tables()`: `$table`, `$table_display`, and `$footnotes`.
- `save_table()`, `save_plot()`, `save_docx()`: invisibly returned file paths.
- Raw variable names remain available for relabelling, merging, and testing even
  when display labels are used.