-
Notifications
You must be signed in to change notification settings - Fork 197
/
README.Rmd
144 lines (109 loc) · 6.79 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# gt <img src="man/figures/logo.svg" align="right" height="250px" />
<!-- badges: start -->
[![CRAN
status](https://www.r-pkg.org/badges/version/gt)](https://cran.r-project.org/package=gt)
[![R build
status](https://github.com/rstudio/gt/workflows/R-CMD-check/badge.svg)](https://github.com/rstudio/gt/actions?workflow=R-CMD-check)
[![Coverage
status](https://codecov.io/gh/rstudio/gt/branch/master/graph/badge.svg)](https://codecov.io/github/rstudio/gt?branch=master)
<!-- badges: end -->
With the **gt** package, anyone can make wonderful-looking tables using the **R** programming language. The **gt** philosophy: we can construct a wide variety of useful tables with a cohesive set of table parts. These include the *table header*, the *stub*, the *column labels* and *spanner column labels*, the *table body*, and the *table footer*.
<p align="center"><img src="man/figures/gt_parts_of_a_table.svg" width="800px"></p>
It all begins with **table data** (be it a tibble or a data frame). You then decide how to compose your **gt table** with the elements and formatting you need for the task at hand. Finally, the table is rendered by printing it at the console, including it in an R Markdown document, or exporting to a file using `gtsave()`. Currently, **gt** supports the **HTML**, **LaTeX**, and **RTF** output formats.
<p align="center"><img src="man/figures/gt_workflow_diagram.svg" width="800px"></p>
The **gt** package is designed to be both straightforward yet powerful. The emphasis is on simple functions for the everyday display table needs. Here is a brief example of how to use **gt** to create a table from the included `sp500` dataset:
```{r sp500_example, eval=FALSE}
library(gt)
library(tidyverse)
library(glue)
# Define the start and end dates for the data range
start_date <- "2010-06-07"
end_date <- "2010-06-14"
# Create a gt table based on preprocessed
# `sp500` table data
sp500 %>%
filter(date >= start_date & date <= end_date) %>%
select(-adj_close) %>%
gt() %>%
tab_header(
title = "S&P 500",
subtitle = glue("{start_date} to {end_date}")
) %>%
fmt_date(
columns = date,
date_style = 3
) %>%
fmt_currency(
columns = c(open, high, low, close),
currency = "USD"
) %>%
fmt_number(
columns = volume,
suffixing = TRUE
)
```
<p align="center"><img src="man/figures/gt_sp500_table.svg" width="1200px"></p>
There are six datasets included in **gt**: `countrypops`, `sza`, `gtcars`, `sp500`, `pizzaplace`, and `exibble`. All of them are useful for experimenting with **gt**'s functions.
Beyond this simple example, there are many functions available in **gt** for creating super-customized tables.
Want to try this out? Then, take the **gt** Test Drive on **RStudio Cloud**. It's full of ready-to-run examples.
<p align="center">
<a href="https://rstudio.cloud/project/779965">
<img src="man/figures/gt-test-drive.svg" alt="RStudio Cloud Example" height="80px">
</a>
</p>
The **gt** package can be installed from **CRAN** with:
```{r install_cran, eval=FALSE}
install.packages("gt")
```
You can also choose to install the development version of **gt** from **GitHub**:
```{r install_github, eval=FALSE}
devtools::install_github("rstudio/gt")
```
If you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to file an [issue](https://github.com/rstudio/gt/issues).
***
#### How **gt** fits in with Other Packages that Generate Display Tables
The **gt** package joins a burgeoning collection of packages for display table generation. Why another? We feel that there is enough room in this space to innovate further. Here are some of the ways that **gt** contributes to this ecosystem:
- the interface is high-level and declarative (general instructions versus very specific)
- the formatting options are 'batteries included' (scientific notation, uncertainty, ranges, percentages, suffixes, localized currency, dates/times + much more)
- there is excellent, pain-free support for footnotes
- the output is 'camera-ready'
- multiple output formats are supported with the same declarative interface
- the API closely follows tidyverse conventions by adhering to the [tidyverse style guide](https://style.tidyverse.org)
- there's a focus on making the package documentation and examples the best they can be
- rigorous QA/QC measures: high test coverage for automated tests, and thorough manual testing by QA engineers (with every proposed code change)
While **gt** is trying to do something different with its own interface, it may not suit your specific needs. Here is a listing of other leading table-making **R** packages, with links to their respective project pages:
- **knitr** ([GITHUB](https://github.com/yihui/knitr), [WEBSITE](https://yihui.org/knitr/))
- **kableExtra** ([GITHUB](https://github.com/haozhu233/kableExtra), [WEBSITE](https://haozhu233.github.io/kableExtra/))
- **formattable** ([GITHUB](https://github.com/renkun-ken/formattable), [WEBSITE](https://renkun-ken.github.io/formattable/))
- **DT** ([GITHUB](https://github.com/rstudio/DT), [WEBSITE](https://rstudio.github.io/DT/))
- **pander** ([GITHUB](https://github.com/Rapporter/pander), [WEBSITE](http://rapporter.github.io/pander))
- **huxtable** ([GITHUB](https://github.com/hughjonesd/huxtable), [WEBSITE](https://hughjonesd.github.io/huxtable/))
- **reactable** ([GITHUB](https://github.com/glin/reactable), [WEBSITE](https://glin.github.io/reactable/))
- **flextable** ([GITHUB](https://github.com/davidgohel/flextable), [WEBSITE](https://davidgohel.github.io/flextable/))
- **ftextra** ([GITHUB](https://github.com/atusy/ftExtra), [WEBSITE](https://ftextra.atusy.net/))
- **pixiedust** ([GITHUB](https://github.com/nutterb/pixiedust))
- **tangram** ([GITHUB](https://github.com/spgarbet/tangram))
- **ztable** ([GITHUB](https://github.com/cardiomoon/ztable))
- **condformat** ([GITHUB](https://github.com/zeehio/condformat))
- **stargazer** ([CRAN](https://CRAN.R-project.org/package=stargazer))
- **xtable** ([CRAN](https://CRAN.R-project.org/package=xtable))
#### Code of Conduct
Please note that the gt project is released with a [contributor code of conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/).<br>By participating in this project you agree to abide by its terms.
#### 📄 License
**gt** is licensed under the MIT license.
See the [`LICENSE.md`](LICENSE.md) file for more details.
© RStudio, PBC.
***
<p align="center"><img src="man/figures/gt_tables_footer.png" width="100%"></p>