-
Notifications
You must be signed in to change notification settings - Fork 108
/
README.Rmd
226 lines (156 loc) · 10.6 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
warning = FALSE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
<!-- badges: start -->
[](https://github.com/ddsjoberg/gtsummary/actions)
[](https://cran.r-project.org/package=gtsummary)
[](https://app.codecov.io/gh/ddsjoberg/gtsummary?branch=main)
[](https://cran.r-project.org/package=gtsummary)
[](https://doi.org/10.32614/RJ-2021-053)
<!-- badges: end -->
## gtsummary <a href='https://github.com/ddsjoberg/gtsummary'><img src='man/figures/logo.png' align="right" height="120" /></a>
The {gtsummary} package provides an elegant and flexible way to create publication-ready analytical and summary tables using the **R** programming language. The {gtsummary} package summarizes data sets, regression models, and more, using sensible defaults with highly customizable capabilities.
* [**Summarize data frames or tibbles**](https://www.danieldsjoberg.com/gtsummary/articles/tbl_summary.html) easily in **R**. Perfect for presenting descriptive statistics, comparing group **demographics** (e.g creating a **Table 1** for medical journals), and more. Automatically detects continuous, categorical, and dichotomous variables in your data set, calculates appropriate descriptive statistics, and also includes amount of missingness in each variable.
* [**Summarize regression models**](https://www.danieldsjoberg.com/gtsummary/articles/tbl_regression.html) in R and include reference rows for categorical variables. Common regression models, such as logistic regression and Cox proportional hazards regression, are automatically identified and the tables are pre-filled with appropriate column headers (i.e. Odds Ratio and Hazard Ratio).
* [**Customize gtsummary tables**](https://www.danieldsjoberg.com/gtsummary/reference/index.html#section-general-formatting-styling-functions) using a growing list of formatting/styling functions. **[Bold](https://www.danieldsjoberg.com/gtsummary/reference/bold_italicize_labels_levels.html)** labels, **[italicize](https://www.danieldsjoberg.com/gtsummary/reference/bold_italicize_labels_levels.html)** levels, **[add p-value](https://www.danieldsjoberg.com/gtsummary/reference/add_p.html)** to summary tables, **[style](https://www.danieldsjoberg.com/gtsummary/reference/style_percent.html)** the statistics however you choose, **[merge](https://www.danieldsjoberg.com/gtsummary/reference/tbl_merge.html)** or **[stack](https://www.danieldsjoberg.com/gtsummary/reference/tbl_stack.html)** tables to present results side by side... there are so many possibilities to create the table of your dreams!
* **[Report statistics inline](https://www.danieldsjoberg.com/gtsummary/articles/inline_text.html)** from summary tables and regression summary tables in **R markdown**. Make your reports completely reproducible!
By leveraging [{broom}](https://broom.tidymodels.org/), [{gt}](https://gt.rstudio.com/), and [{labelled}](http://larmarange.github.io/labelled/) packages, {gtsummary} creates beautifully formatted, ready-to-share summary and result tables in a single line of R code!
Check out the examples below, review the [vignettes](https://www.danieldsjoberg.com/gtsummary/articles/) for a detailed exploration of the output options, and view the [gallery](https://www.danieldsjoberg.com/gtsummary/articles/gallery.html) for various customization examples.
## Installation
The {gtsummary} package was written as a companion to the [{gt}](https://gt.rstudio.com/) package from RStudio.
You can install {gtsummary} with the following code.
``` r
install.packages("gtsummary")
```
Install the development version of {gtsummary} with:
``` r
remotes::install_github("ddsjoberg/gtsummary")
```
## Examples
### Summary Table
Use [`tbl_summary()`](https://www.danieldsjoberg.com/gtsummary/reference/tbl_summary.html) to summarize a data frame.
<img src = "https://github.com/ddsjoberg/gtsummary/raw/main/data-raw/misc_files/tbl_summary_demo1.gif" alt = "animated" width = "100%">
Example basic table:
```{r table1, include = TRUE}
library(gtsummary)
# summarize the data with our package
table1 <-
trial %>%
tbl_summary(include = c(age, grade, response))
```
```{r tbl_summary_print_simple, include = FALSE}
# Had to manually save images in temp file, not sure if better way.
gt::gtsave(as_gt(table1), file = "man/figures/README-tbl_summary_print_simple-1.png")
```
```{r out.width = "25%", echo = FALSE}
knitr::include_graphics("man/figures/README-tbl_summary_print_simple-1.png")
```
There are many **customization options** to **add information** (like comparing groups) and **format results** (like bold labels) in your table. See the [`tbl_summary()`](https://www.danieldsjoberg.com/gtsummary/articles/tbl_summary.html) tutorial for many more options, or below for one example.
```{r table2, include = TRUE}
table2 <-
tbl_summary(
trial,
include = c(age, grade, response),
by = trt, # split table by group
missing = "no" # don't list missing data separately
) %>%
add_n() %>% # add column with total number of non-missing observations
add_p() %>% # test for a difference between groups
modify_header(label = "**Variable**") %>% # update the column header
bold_labels()
```
```{r tbl_summary_print_extra, include = FALSE}
gt::gtsave(as_gt(table2), file = "man/figures/README-tbl_summary_print_extra-1.png")
```
```{r out.width = "55%", echo = FALSE}
knitr::include_graphics("man/figures/README-tbl_summary_print_extra-1.png")
```
### Regression Models
Use [`tbl_regression()`](https://www.danieldsjoberg.com/gtsummary/reference/tbl_regression.html) to easily and beautifully display regression model results in a table. See the [tutorial](https://www.danieldsjoberg.com/gtsummary/articles/tbl_regression.html) for customization options.
```{r regress, include = TRUE}
mod1 <- glm(response ~ trt + age + grade, trial, family = binomial)
t1 <- tbl_regression(mod1, exponentiate = TRUE)
```
```{r tbl_regression_printa, include = FALSE}
gt::gtsave(as_gt(t1), file = "man/figures/README-tbl_regression_printa-1.png")
```
```{r out.width = "40%", echo = FALSE}
knitr::include_graphics("man/figures/README-tbl_regression_printa-1.png")
```
### Side-by-side Regression Models
You can also present side-by-side regression model results using `tbl_merge()`
```{r}
library(survival)
# build survival model table
t2 <-
coxph(Surv(ttdeath, death) ~ trt + grade + age, trial) %>%
tbl_regression(exponentiate = TRUE)
# merge tables
tbl_merge_ex1 <-
tbl_merge(
tbls = list(t1, t2),
tab_spanner = c("**Tumor Response**", "**Time to Death**")
)
```
```{r tbl_merge_ex1, include = FALSE}
gt::gtsave(as_gt(tbl_merge_ex1), file = "man/figures/README-tbl_merge_ex1-1.png")
```
```{r out.width = "60%", echo = FALSE}
knitr::include_graphics("man/figures/README-tbl_merge_ex1-1.png")
```
Review even more output options in the **[table gallery](https://www.danieldsjoberg.com/gtsummary/articles/gallery.html)**.
## gtsummary + R Markdown
The **{gtsummary}** package was written to be a companion to the **{gt}** package from RStudio.
But not all output types are supported by the **{gt}** package.
Therefore, we have made it possible to print **{gtsummary}** tables with various engines.
Review the **[gtsummary + R Markdown](https://www.danieldsjoberg.com/gtsummary/articles/rmarkdown.html)** vignette for details.
<a href="https://www.danieldsjoberg.com/gtsummary/articles/rmarkdown.html">
```{r out.width = "55%", echo = FALSE}
knitr::include_graphics("man/figures/gt_output_formats.PNG")
```
</a>
## Save Individual Tables
{gtsummary} tables can also be saved directly to file as an image, HTML, Word, RTF, and LaTeX file.
```r
tbl %>%
as_gt() %>%
gt::gtsave(filename = ".") # use extensions .png, .html, .docx, .rtf, .tex, .ltx
```
## Additional Resources
- The best resources are the gtsummary vignettes: [table gallery](https://www.danieldsjoberg.com/gtsummary/articles/gallery.html), [`tbl_summary()` tutorial](https://www.danieldsjoberg.com/gtsummary/articles/tbl_summary.html), [`tbl_regression()` tutorial](https://www.danieldsjoberg.com/gtsummary/articles/tbl_regression.html), [`inline_text()` tutorial](https://www.danieldsjoberg.com/gtsummary/articles/inline_text.html), [gtsummary themes](https://www.danieldsjoberg.com/gtsummary/articles/themes.html), [gtsummary+R markdown](https://www.danieldsjoberg.com/gtsummary/articles/rmarkdown.html).
- The R Journal Article [*Reproducible Summary Tables with the gtsummary Package*](https://github.com/ddsjoberg/gtsummary/raw/main/data-raw/RJ-2021-053.pdf).
- The [RStudio Education Blog](https://education.rstudio.com/blog/2020/07/gtsummary/) includes a post with a brief introduction to the package.
- A [recording of a presentation](https://www.youtube.com/watch?v=tANo9E1SYJE) given to the Weill Cornell Biostatistics Department and the Memorial Sloan Kettering R Users Group.
<iframe width="560" height="315" src="https://www.youtube.com/embed/tANo9E1SYJE" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Cite gtsummary
```{text, comment="", eval = FALSE}
> citation("gtsummary")
To cite gtsummary in publications use:
Sjoberg DD, Whiting K, Curry M, Lavery JA, Larmarange J. Reproducible summary tables with the gtsummary package.
The R Journal 2021;13:570–80. https://doi.org/10.32614/RJ-2021-053.
A BibTeX entry for LaTeX users is
@Article{gtsummary,
author = {Daniel D. Sjoberg and Karissa Whiting and Michael Curry and Jessica A. Lavery and Joseph Larmarange},
title = {Reproducible Summary Tables with the gtsummary Package},
journal = {{The R Journal}},
year = {2021},
url = {https://doi.org/10.32614/RJ-2021-053},
doi = {10.32614/RJ-2021-053},
volume = {13},
issue = {1},
pages = {570-580},
}
```
## Contributing
Big thank you to [@jeffreybears](https://www.etsy.com/shop/jeffreybears/) for the hex sticker!
Please note that the {gtsummary} project is released with a [Contributor Code of Conduct](https://www.danieldsjoberg.com/gtsummary/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. Thank you to all contributors!