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

Start with a table that people can actually read. `descriptive_table()` creates
publication-ready summaries for continuous, categorical, and mixed exposure
sets.

```{r desc-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")),
    ptl_cat = factor(ifelse(ptl > 0, "Yes", "No"), levels = c("No", "Yes")),
    ftv_cat = factor(case_when(
      ftv == 0 ~ "None",
      ftv == 1 ~ "One",
      ftv >= 2 ~ "Two or more"
    ), levels = c("None", "One", "Two or more"))
  )

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

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"
attr(birthwt_data$ptl_cat, "label") <- "Previous preterm labour"
attr(birthwt_data$ftv_cat, "label") <- "First trimester visits"
```

## Column Percentages

Use column percentages when the table is grouped by outcome or another column.
Continuous variables are shown as median (IQR) by default, and variable labels
are picked up automatically when variables have a `"label"` attribute.

```{r desc-column, message=FALSE, warning=FALSE}
desc_column <- descriptive_table(
  data = birthwt_data,
  exposures = birthwt_exposures,
  by = "low",
  percent = "column",
  show_overall = "last",
  theme = clinical
)

desc_column
```

## Row Percentages

Use row percentages when the question is how each exposure level is distributed
across groups. Common option values can be written with or without quotes.

```{r desc-row, message=FALSE, warning=FALSE}
descriptive_table(
  data = birthwt_data,
  exposures = birthwt_exposures,
  by = "low",
  percent = "row",
  show_overall = "first",
  show_missing = no,
  theme = striped
)$table
```

## Summary Choices

Use `statistic` when continuous variables need a different summary. A single
value applies to all numeric variables. A named vector lets you mix summaries,
including treating numeric ordinal variables as categorical.

```{r desc-statistic, message=FALSE, warning=FALSE}
descriptive_table(
  data = birthwt_data,
  exposures = c("age", "lwt", "ftv", "smoke"),
  by = low,
  statistic = c(
    age = mean,
    lwt = median,
    ftv = categorical
  ),
  percent = column,
  show_missing = no
)
```

The quoted form is equivalent and often clearer in saved scripts:

```{r desc-statistic-quoted, eval=FALSE}
descriptive_table(
  data = birthwt_data,
  exposures = c("age", "lwt", "ftv", "smoke"),
  by = "low",
  statistic = c(
    age = "mean",
    lwt = "median",
    ftv = "categorical"
  )
)
```

## Output Format

`flextable` is the default because it behaves well in Word workflows. Use
`format = gt` when the output is mainly for HTML or pkgdown.

```{r desc-flex, message=FALSE, warning=FALSE}
desc_gt <- descriptive_table(
  data = birthwt_data,
  exposures = birthwt_exposures,
  by = "low",
  percent = "column",
  format = gt
)

desc_gt$table
```

## What To Inspect

- `$table`: rendered `gt` or `flextable` output.
- `$table_body`: clean data behind the table.
- `$variable_labels`: labels used for display; raw variable names remain in
  `$table_body` for reliable merging and modification.
- `$format`: output format used by the table builder.