---
title: "Regression coefficient tables"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Regression coefficient tables}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>"
)
```

```{r load}
library(clerkR)
```

## Overview

`tbl_regression()` formats a tidy data frame of regression results — β, SE,
95% CI, and p-value — into a publication-ready table. It is designed to accept
the output of `broom::tidy()` directly.

Column-name arguments take **quoted strings**. Defaults match
`broom::tidy(model, conf.int = TRUE)` output:

| Argument | Default | `broom::tidy()` column |
|---|---|---|
| `term` | `"term"` | model term |
| `estimate` | `"estimate"` | coefficient β |
| `std_error` | `"std.error"` | standard error |
| `conf_low` | `"conf.low"` | lower CI bound |
| `conf_high` | `"conf.high"` | upper CI bound |
| `p` | `"p.value"` | p-value |

`clerk_reg_example` already uses these column names:

```{r data}
clerk_reg_example
```

## Basic usage

Since `clerk_reg_example` matches all defaults, no remapping is needed:

```{r basic}
tbl_regression(
  clerk_reg_example,
  output = "gt"
) |>
  clerk_render(title = "Linear regression: TMT completion time (log s)")
```

## Domain grouping

```{r domains}
tbl_regression(
  clerk_reg_example,
  domains = list(
    "Cardiometabolic" = c("bmi", "waist", "systolic_bp"),
    "Mental health"   = c("bdi", "panas_neg")
  ),
  output = "gt"
) |>
  clerk_render(title = "Linear regression: TMT completion time (log s)")
```

## FDR correction

```{r fdr}
tbl_regression(
  clerk_reg_example,
  domains = list(
    "Cardiometabolic" = c("bmi", "waist", "systolic_bp"),
    "Mental health"   = c("bdi", "panas_neg")
  ),
  fdr    = TRUE,
  output = "gt"
) |>
  clerk_render(
    title    = "Linear regression: TMT completion time (log s)",
    footnote = "FDR correction applied across all terms (BH)."
  )
```

## Using `broom::tidy()` directly

```{r broom, eval=FALSE}
library(broom)

lm(log(tmt_time) ~ bmi + waist + systolic_bp + bdi + panas_neg + age + sex,
   data = clerk_example) |>
  tidy(conf.int = TRUE) |>
  tbl_regression(
    domains = list(
      "Cardiometabolic" = c("bmi", "waist", "systolic_bp"),
      "Mental health"   = c("bdi", "panas_neg")
    ),
    fdr    = TRUE,
    output = "gt"
  ) |>
  clerk_render(title = "Linear regression: TMT completion time (log s)")
```

## Logistic regression — exponentiated coefficients

Set `exponentiate = TRUE` to show odds ratios or hazard ratios:

```{r logistic, eval=FALSE}
library(broom)

glm(outcome ~ bmi + age + sex, data = my_data, family = binomial) |>
  tidy(conf.int = TRUE, exponentiate = FALSE) |>
  tbl_regression(
    exponentiate = TRUE,
    output       = "gt"
  ) |>
  clerk_render(
    title    = "Logistic regression: odds ratios",
    footnote = "Values shown as OR [95% CI]."
  )
```

## Custom column names

Pass column names as strings when they differ from the defaults:

```{r custom, eval=FALSE}
my_results <- data.frame(
  predictor = c("bmi", "age"),
  beta      = c(0.021, 0.003),
  se        = c(0.008, 0.002),
  lo95      = c(0.005, -0.001),
  hi95      = c(0.037,  0.007),
  pval      = c(0.012,  0.610)
)

tbl_regression(
  my_results,
  term      = "predictor",
  estimate  = "beta",
  std_error = "se",
  conf_low  = "lo95",
  conf_high = "hi95",
  p         = "pval",
  output    = "gt"
) |>
  clerk_render(title = "Regression results")
```

## HTML output

```{r html}
tbl_regression(
  clerk_reg_example,
  output = "html"
) |>
  clerk_render()
```