forked from nutterb/pixiedust
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
151 lines (118 loc) · 7.75 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
---
output:
md_document:
variant: markdown_github
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
[](https://travis-ci.org/nutterb/pixiedust)
[](https://coveralls.io/github/nutterb/pixiedust?branch=master)
# pixiedust
After tidying up your analyses with the `broom` package, go ahead and grab the `pixiedust`. Customize your table output and write it to markdown, HTML, LaTeX, or even just the console. `pixiedust` makes it easy to customize the appearance of your tables in all of these formats by adding any number of "sprinkles", much in the same way you can add layers to a `ggplot`.
```{r}
fit <- lm(mpg ~ qsec + factor(am) + wt + factor(gear), data = mtcars)
library(pixiedust)
dust(fit) %>%
sprinkle(col = 2:4, round = 3) %>%
sprinkle(col = 5, fn = quote(pvalString(value))) %>%
sprinkle_colnames(term = "Term",
estimate = "Estimate",
std.error = "SE",
statistic = "T-statistic",
p.value = "P-value") %>%
sprinkle_print_method("console")
```
### Customizing with Sprinkles
Tables can be customized by row, column, or even by a single cell by adding sprinkles to the `dust` object. The table below shows the currently planned and implemented sprinkles. In the "implemented" column, an 'x' indicates a customization that has been implemented, while a blank cell suggests that the customization is planned but has not yet been implemented. In the remaining columns, an 'x' indicates that the sprinkle is already implemented for the output format; an 'o' indicates that implementation is planned but not yet completed; and a blank cell indicates that the sprinkle will not be implemented (usually because the output format doesn't support the option).
```{r, echo=FALSE}
Sprinkles <- read.csv("inst/sprinkles.csv",
stringsAsFactors=FALSE)
Sprinkles[,-1] <- lapply(Sprinkles[-1], stringr::str_trim)
dust(Sprinkles) %>%
sprinkle(cols=1, halign = "left") %>%
sprinkle(cols=2:6, halign = "center") %>%
sprinkle_print_method("markdown")
```
### A Brief Example
To demonstrate, let's look at a simple linear model. We build the model and generate the standard summary.
```{r}
fit <- lm(mpg ~ qsec + factor(am) + wt + factor(gear), data = mtcars)
summary(fit)
```
While the summary is informative and useful, it is full of "stats-speak" and isn't necessarily in a format that is suitable for publication or submission to a client. The `broom` package provides the summary in tidy format that, serendipitously, it a lot closer to what we would want for formal reports.
```{r}
library(broom)
tidy(fit)
```
It has been observed by some, however, that even this summary isn't quite ready for publication. There are too many decimal places, the p-value employ scientific notation, and column titles like "statistic" don't specify what type of statistic. These kinds of details aren't the purview of `broom`, however, as `broom` is focused on tidying the results of a model for further analysis (particularly with respect to comparing slightly varying models).
The `pixiedust` package diverts from `broom`'s mission here and provides the ability to customize the `broom` output for presentation. The initial `dust` object returns a table that is similar to the `broom` output.
```{r}
library(pixiedust)
dust(fit) %>%
sprinkle_print_method("console")
```
Where `pixiedust` shows its strength is the ease of which these tables can be customized. The code below rounds the columns `estimate`, `std.error`, and `statistic` to three decimal places each, and then formats the `p.value` into a format that happens to be one that I like.
```{r}
x <- dust(fit) %>%
sprinkle(col = 2:4, round = 3) %>%
sprinkle(col = 5, fn = quote(pvalString(value))) %>%
sprinkle_print_method("console")
x
```
Now we're almost there! Let's change up the column names, and while we're add it, let's add some "bold" markers to the statistically significant terms in order to make them stand out some (I say "bold" because the console output doesn't show up in bold, but with the markdown tags for bold text. In a rendered table, the text would actually be rendered in bold).
```{r}
x <- x %>%
sprinkle(col = c("estimate", "p.value"),
row = c(2, 4),
bold = TRUE) %>%
sprinkle_colnames(term = "Term",
estimate = "Estimate",
std.error = "SE",
statistic = "T-statistic",
p.value = "P-value") %>%
sprinkle_print_method("console")
x
```
### Development Schedule
| Version | Release Description | Target Date | Actual Date |
|--------:|:---------------------------------------------------|------------:|-------------|
|**0.1.0**| Console, markdown and HTML output for simple table | 1 Aug 2015 | 3 Aug 2015 |
| 0.2.0 | Multirow table headers; footers; multipage tables | 20 Aug 2015 | 18 Aug 2015 |
| 0.3.0 | Multicolumn and multirow cells in HTML | 15 Sep 2015 | 15 Sept 2015 |
| 0.4.0 | Glance statistics in table footer | 1 Oct 2015 | 25 Sept 2015 |
| | Add variable labels and levels to `broom` output | | |
|**0.5.0**| LaTeX output for simple table | 15 Oct 2015 | 15 Oct 2015 |
| | Adjustable cell heights and widths in LaTeX tables | | |
| | Add `medley` for batch customizations | | |
| 0.6.0 | Borders and backgrounds for LaTeX tables | 1 Dec 2015 | 9 Dec 2015 |
| | Multicolumn and multirow support for LaTeX tables | | |
| | Longtable support for LaTeX tables | | |
| | Rotated text for LaTeX tables | | |
|**0.7.0**| `bookdown` support | 30 Apr 2016 | |
| | Auto detect output format (supports knitr/Rmarkdown)| | |
| | `fixed` coordinate pairing for sprinkles | | |
| | Sprinkle recycling | | |
| | Captions, floating environments, labels | | |
| | `hhline` option allows background colors and borders| | |
| | Methods for grouped and split data frames | | |
|**1.0.0**| Release of basic, stable package | 1 June 2016 | |
**bold version numbers** indicate a planned release to CRAN.
## A cool, free tip!
The markdown output from `pixiedust` is somewhat limited due to the limitations of `Rmarkdown` itself. If/when more features become available for `Rmarkdown` output, I'll be sure to include them. But what can you do if you _really_ want all of the flexibility of the HTML tables but need the MS Word document?
With a little help from the `Gmisc` package, you can have the best of both worlds. `Gmisc` isn't available on CRAN yet, but if you're willing to install it from GitHub, you can render a `docx` file. Install `Gmisc` with
`install.packages("Gmisc")`
Then use in your YAML header
```
---
output: Gmisc::docx_document
---
```
When you knit your document, it knits as an HTML file, but I've had no problems with the rendering when I right-click the file and open with MS Word.
Read more at http://gforge.se/2014/07/fast-track-publishing-using-rmarkdown/ (but note that this blog post was written about the `Grmd` package before it was moved into the `Gmisc` package).