forked from renkun-ken/formattable
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
165 lines (118 loc) · 7.58 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
# formattable
[](https://travis-ci.org/renkun-ken/formattable)
[](https://ci.appveyor.com/project/renkun-ken/formattable)
[](http://codecov.io/github/renkun-ken/formattable?branch=master)
[](https://cran.r-project.org/package=formattable)
This package is designed for applying formatting on vectors and data frames to make data presentation easier, richer, more flexible and hopefully convey more information.
This document is also translated into [日本語](./README.ja.md) by [@hoxo_m](https://github.com/hoxo-m), [@dichika](https://github.com/dichika) and [@teramonagi](https://github.com/teramonagi).
## What's New?
### Version 0.2
#### Breaking changes
* `format_table` now renders input data frame to `html` by default instead of `markdown`.
* `formattable.matrix` is removed to support matrix/array formatting. Explicitly convert matrix to data frame if you want to create a formattable data frame.
* `format_table` and `formattable.data.frame` no longer accepts `check.rows` and `check.names` arguments. `row.names` accepts a logical value and is directly passed to `knitr::kable`.
#### New features
* `formattable` and built-in formatter functions (e.g. `percent`) now work with matrix and array objects.
* Area formatting is now supported (discussed in #36, #40) with `area(row, col) ~ formatter`. See examples via `?formattable.data.frame`.
* Now a formattable data frame can be converted to `DT::datatable` via `formattable::as.datatable`.
* `FALSE` formatters can be used to hide columns of a data frame.
#### Enhancements
* The rendered HTML table now supports customizable CSS styling via `table_attr` argument. (#57)
* `color_bar` now uses `proportion` by default as the rescaling function.
#### Bug fixes
* Fixes an encoding problem rendering formattable data frame. (#30)
* Fixes the size and alignment issues in color bar. (#49)
* `format.formattable` now preserves the names of input vector. (#56)
### Version 0.1.7
#### Breaking changes
* `color_bar` is now broken into two versions using different transform functions:
`normalize_bar` uses `normalize`, the same as `color_bar` in previous versions,
and `proportion_bar` uses newly introduced `proportion` as `x / max(abs(x))` to
create bars of proportional width. (#42, #49)
## Install
The package is available on both GitHub and CRAN.
Install from GitHub:
```r
# install.packages("devtools")
devtools::install_github("renkun-ken/formattable")
```
Install from CRAN:
```r
install.packages("formattable")
```
## Introduction
Atomic vectors are basic units to store data. Some data can be read more easily with formatting. A numeric vector, for example, stores a group of percentage numbers yet still shows in the form of typical floating numbers. This package provides functions to create data structures with predefined formatting rules so that these objects store the original data but are printed with formatting.
The package provides several typical formattable objects such as `percent`, `comma`, `currency`, `accounting` and `scientific`. These objects are essentially numeric vectors with pre-defined formatting rules and parameters. For example,
```{r}
library(formattable)
p <- percent(c(0.1, 0.02, 0.03, 0.12))
p
```
The percent vector is no different from a numeric vector but has a percentage representation as being
printed. It works with arithmetic operations and common functions and preserves its formatting.
```{r}
p + 0.05
max(p)
```
```{r}
balance <- accounting(c(1000, 500, 200, -150, 0, 1200))
balance
balance + 1000
```
These functions are special cases of what `formattable()` can do. `formattable()` applies highly customizable formatting to objects of a wide range of classes like `numeric`, `logical`, `factor`, `Date`, `data.frame`, etc. A typical data frame may look more friendly with `formattable` column vectors. For example,
```{r}
p <- data.frame(
id = c(1, 2, 3, 4, 5),
name = c("A1", "A2", "B1", "B2", "C1"),
balance = accounting(c(52500, 36150, 25000, 18300, 7600), format = "d"),
growth = percent(c(0.3, 0.3, 0.1, 0.15, 0.15), format = "d"),
ready = formattable(c(TRUE, TRUE, FALSE, FALSE, TRUE), "yes", "no"))
p
```
## Formatting tables in dynamic document
In a typical workflow of dynamic document production, [knitr](https://github.com/yihui/knitr) and [rmarkdown](http://rmarkdown.rstudio.com/) are powerful tools to render documents with R code to different types of portable documents.
knitr is able to render an RMarkdown document (markdown document with R code chunks) to Markdown document. rmarkdown calls [pandoc](http://johnmacfarlane.net/pandoc) to render a markdown document to HTML web page. To put a table (`data.frame` in R) on the page, one may call `knitr::kable` to produce its markdown representation. By default the resulted table is in a plain theme with no additional formatting. However, in some cases, additional formatting may help clarify the information and make contrast of the data. This package provides functions to produce formatted tables in dynamic documents.
```{r}
df <- data.frame(
id = 1:10,
name = c("Bob", "Ashley", "James", "David", "Jenny",
"Hans", "Leo", "John", "Emily", "Lee"),
age = c(28, 27, 30, 28, 29, 29, 27, 27, 31, 30),
grade = c("C", "A", "A", "C", "B", "B", "B", "A", "C", "C"),
test1_score = c(8.9, 9.5, 9.6, 8.9, 9.1, 9.3, 9.3, 9.9, 8.5, 8.6),
test2_score = c(9.1, 9.1, 9.2, 9.1, 8.9, 8.5, 9.2, 9.3, 9.1, 8.8),
final_score = c(9, 9.3, 9.4, 9, 9, 8.9, 9.25, 9.6, 8.8, 8.7),
registered = c(TRUE, FALSE, TRUE, FALSE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE),
stringsAsFactors = FALSE)
```
Plain table:
```{r,echo=FALSE,message=FALSE,results='asis'}
knitr::kable(df)
```
Formatted table with the following visualizations:
* Ages are rendered in gradient.
* All A grades are displayed in green bold.
* `test1_score` and `test2_score` are indicated by horizontal bars and are background-colorized: white (low score) to pink (high score)
* `final_score` shows score and ranking. Top 3 are green, and others are gray.
* `registered` texts are transformed to an icon and yes/no text.
```{r, eval=FALSE}
library(formattable)
formattable(df, list(
age = color_tile("white", "orange"),
grade = formatter("span", style = x ~ ifelse(x == "A",
style(color = "green", font.weight = "bold"), NA)),
area(col = c(test1_score, test2_score)) ~ normalize_bar("pink", 0.2),
final_score = formatter("span",
style = x ~ style(color = ifelse(rank(-x) <= 3, "green", "gray")),
x ~ sprintf("%.2f (rank: %02d)", x, rank(-x))),
registered = formatter("span",
style = x ~ style(color = ifelse(x, "green", "red")),
x ~ icontext(ifelse(x, "ok", "remove"), ifelse(x, "Yes", "No")))
))
```
**The icon set used in the table is by [GLYPHICONS.com](http://GLYPHICONS.com) and included in [Bootstrap](http://getbootstrap.com/components/#glyphicons).**
## `htmlwidget` conversion in interactive environments
`formattable` will automatically convert to an `htmlwidget` when in an `interactive()` context such as the console or RStudio IDE. If you would like to avoid this conversion and see the `html` table output, please use `format_table` that calls `knitr::kable` with formatters or call `format` with the `formattable data.frame` object.
## License
This package is under [MIT License](http://opensource.org/licenses/MIT).