
<div class="gtreg-hero">

<div>

<h1>

gtregression
</h1>

<p>

Publication-ready regression and survival analysis tables, plots, and
forest plots for real-world health data. Fit models, compare estimates,
visualise results, and export manuscript-ready outputs without
hand-formatting every coefficient.
</p>

<div class="gtreg-actions">

<a href="https://gtregression.thinkdenominator.com/articles/gtregression-intro.html">Start the
workflow</a><a class="secondary" href="https://gtregression.thinkdenominator.com/reference/">Explore
functions</a>

</div>

</div>

<div>

<img src="man/figures/gtregression_hex.png" alt="gtregression logo" class="gtreg-home-logo"/>

</div>

</div>

<!-- badges: start -->

[![R-CMD-check](https://github.com/ThinkDenominator/gtregression/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ThinkDenominator/gtregression/actions/workflows/R-CMD-check.yaml)
[![pkgdown](https://github.com/ThinkDenominator/gtregression/actions/workflows/pkgdown.yaml/badge.svg)](https://gtregression.thinkdenominator.com/)
[![CRAN
status](https://www.r-pkg.org/badges/version/gtregression)](https://CRAN.R-project.org/package=gtregression)
[![CRAN
checks](https://badges.cranchecks.info/worst/gtregression.svg)](https://cran.r-project.org/web/checks/check_results_gtregression.html)
[![CRAN
downloads](https://cranlogs.r-pkg.org/badges/last-month/gtregression)](https://cranlogs.r-pkg.org/downloads/total/last-month/gtregression)
[![CRAN downloads
total](https://cranlogs.r-pkg.org/badges/grand-total/gtregression)](https://CRAN.R-project.org/package=gtregression)
[![Lifecycle:
stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![License:
MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ThinkDenominator/gtregression/blob/main/LICENSE.md)
[![Codecov](https://codecov.io/gh/ThinkDenominator/gtregression/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ThinkDenominator/gtregression)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16905350.svg)](https://doi.org/10.5281/zenodo.16905350)

<!-- badges: end -->

## Publication-Ready Regression, Survival, and Mediation Outputs

`gtregression` helps you move from model to manuscript: fit regression
models, produce clean tables, visualise estimates, merge outputs, and
export results without hand-formatting every coefficient.

It supports logistic, log-binomial, Poisson, robust Poisson, negative
binomial, linear, Cox, parametric survival, and causal mediation
workflows, including adjusted and stratified models.

| Build | What you get |
|----|----|
| Descriptive tables | Grouped summaries with row or column percentages |
| Regression tables | Crude, adjusted, stratified, linear, Cox, and parametric survival outputs |
| Survival analysis | Kaplan-Meier curves, survival summaries, RMST, log-rank tests, Cox PH checks, and survival predictions |
| Mediation analysis | Direct, indirect, total, and proportion mediated effects with causal caveats |
| Visualisations | Regression plots, survival curves, fitted survival curves, and forest tables |
| Interpretation helpers | Confounding, interaction, mediation, convergence, collinearity, model selection, and survival diagnostics |
| Exports | HTML, PDF, PNG, and Word-ready outputs |

## From Data to Manuscript

<div class="gtreg-analysis-path">

<div class="gtreg-path-intro">

<div class="gtreg-kicker">

One connected workflow

</div>

### Start with the question. Finish with a result you can use.

Each step leaves an inspectable object behind, so beginners have a clear
path and experienced analysts retain full control.

</div>

<div class="gtreg-path-steps">

<div class="gtreg-path-step">

<span class="gtreg-path-number">01</span>

<div class="gtreg-path-copy">

**Prepare**

Check variables, labels, levels, and missing data.

</div>

`dissect(data)` <span class="gtreg-path-result">Analysis-ready
data</span>

</div>

<div class="gtreg-path-step">

<span class="gtreg-path-number">02</span>

<div class="gtreg-path-copy">

**Describe**

Build a clear baseline table before modelling.

</div>

`descriptive_table(...)` <span class="gtreg-path-result">Table 1</span>

</div>

<div class="gtreg-path-step">

<span class="gtreg-path-number">03</span>

<div class="gtreg-path-copy">

**Model**

Fit crude, adjusted, stratified, or survival models.

</div>

`uni_reg() + multi_reg()` <span class="gtreg-path-result">Effect
estimates</span>

</div>

<div class="gtreg-path-step">

<span class="gtreg-path-number">04</span>

<div class="gtreg-path-copy">

**Interpret**

Review assumptions, confounding, interaction, and fit.

</div>

`check_*() + compare_models()`
<span class="gtreg-path-result">Defensible model</span>

</div>

<div class="gtreg-path-step">

<span class="gtreg-path-number">05</span>

<div class="gtreg-path-copy">

**Publish**

Merge, visualise, and export polished outputs.

</div>

`forest_reg() + save_table()`
<span class="gtreg-path-result">Manuscript-ready output</span>

</div>

</div>

</div>

## Why It Exists

Many students, researchers, and public health analysts need regression
outputs that are readable, reproducible, and report-ready.
`gtregression` keeps the R syntax approachable while preserving
transparent model objects underneath.

## Built on Trusted R Packages

`gtregression` is intentionally a readable interface over established R
packages. The package uses widely trusted modelling, tidying, plotting,
and reporting tools so users can inspect fitted models and understand
the statistical engines behind each output.

| Area | Core packages used |
|----|----|
| Data handling and tidy workflows | `dplyr`, `purrr`, `tibble`, `rlang` |
| Model fitting | `stats`, `MASS`, `survival`, `risks`, `logistf` |
| Robust and diagnostic inference | `sandwich`, `lmtest`, `broom`, `broom.helpers` |
| Tables and Word-ready reporting | `flextable`, `officer`, `gt` |
| Figures and forest plots | `ggplot2`, `patchwork`, `forestploter`, `scales` |
| Optional development and checking tools | `testthat`, `knitr`, `rmarkdown`, `pkgdown`, `car`, `forcats`, `ggtext` |

The user-facing functions return objects with fitted models, table
bodies, and display metadata that advanced users can audit, modify, or
reuse.

## Install

``` r
# CRAN
install.packages("gtregression")

# Development version
remotes::install_github("ThinkDenominator/gtregression")
```

## Five-Minute Workflow

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

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$smoke, "label") <- "Smoking during pregnancy"

desc <- descriptive_table(
  birthwt_data,
  exposures = exposures,
  by = "low",
  percent = "column",
  show_overall = "last"
)

uni <- uni_reg(
  birthwt_data,
  outcome = "low",
  exposures = exposures,
  approach = "logit"
)

multi <- multi_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht", "ui"),
  adjust_for = c("age", "lwt", "race"),
  approach = "logit"
)

plot_reg(multi, title = "Adjusted Regression for Low Birth Weight")

forest_reg = forest_reg(forest_df(uni, multi)) 

merge_tables(desc, uni, multi)
```

Variable labels set with `attr(x, "label")` or `labelled::var_label()`
are used automatically in display tables and plots, while original
column names remain available internally for merging, modification, and
testing.

Objects stay inspectable:

``` r
desc$table
uni$table
multi$table
multi$models
```

Optional model-fit statistics can be requested without changing the
publication table:

``` r
uni_stats <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = exposures,
  approach = "logit",
  model_stats = TRUE
)

uni_stats$model_stats
```

## Browse by Task

| Task | Start here |
|----|----|
| First workflow | [Start Here](https://gtregression.thinkdenominator.com/articles/gtregression-intro.html) |
| Descriptive summaries | [Descriptive Tables](https://gtregression.thinkdenominator.com/articles/descriptive-tables.html) |
| Regression tables | [Regression Tables](https://gtregression.thinkdenominator.com/articles/regression-tables.html) |
| Survival analysis | [Survival Analysis](https://gtregression.thinkdenominator.com/articles/survival-analysis.html) |
| Causal mediation | [Causal Mediation](https://gtregression.thinkdenominator.com/articles/causal-mediation.html) |
| Visualise estimates | [Visualise Results](https://gtregression.thinkdenominator.com/articles/visualise-results.html) |
| Stratified models | [Stratified Analysis](https://gtregression.thinkdenominator.com/articles/stratified-analysis.html) |
| Diagnostics and selection | [Diagnostics](https://gtregression.thinkdenominator.com/articles/diagnostics-selection.html) |
| Confounding and interaction | [Confounding & Interaction](https://gtregression.thinkdenominator.com/articles/confounding-interaction.html) |
| Merge and export | [Customize and Export](https://gtregression.thinkdenominator.com/articles/customize-export.html) |

## Function Map

| Workflow | Functions |
|----|----|
| Describe | `descriptive_table()`, `dissect()` |
| Model | `uni_reg()`, `multi_reg()`, `cox_reg()`, `surv_reg()` |
| Survival | `km_plot()`, `km_risk_table()`, `survival_summary()`, `survival_quantiles()`, `survival_prob()`, `rmst_table()`, `logrank_test()`, `check_ph()`, `surv_model_compare()`, `plot_surv_fit()`, `surv_predict()` |
| Stratify | `stratified_uni_reg()`, `stratified_multi_reg()` |
| Visualise | `plot_reg()`, `plot_reg_combine()`, `forest_df()`, `forest_reg()` |
| Diagnose | `check_convergence()`, `check_collinearity()`, `check_ph()`, `select_models()` |
| Interpret | `identify_confounder()`, `interaction_models()`, `mediation_analysis()`, `plot_mediation()` |
| Polish and export | `modify_table()`, `merge_tables()`, `save_table()`, `save_plot()`, `save_docx()` |

## Citation

If you use `gtregression` in your work, please cite it as:

Polani R, Eliyas SK, Sakthivel M, Kaviprawin M, Krishnamoorthy Y,
Majella MG. *gtregression: Tools for Creating Publication-Ready
Regression Tables.* Zenodo. <https://doi.org/10.5281/zenodo.16905350>

## Acknowledgements

`gtregression` builds on the R ecosystem, especially `stats`,
`survival`, `MASS`, `risks`, `logistf`, `broom`, `broom.helpers`,
`sandwich`, `lmtest`, `dplyr`, `purrr`, `tibble`, `rlang`, `flextable`,
`officer`, `gt`, `ggplot2`, `patchwork`, `forestploter`, and `scales`.
