forked from giocomai/ganttrify
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
276 lines (181 loc) · 10 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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# ganttrify
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#experimental)
<!-- badges: end -->
`ganttrify` facilitates the creation of nice-looking Gantt charts, commonly used in project proposals and project management.
If you just want to check this out in an interactive web interface, [click here and enjoy](https://ganttrify.europeandatajournalism.eu/. Some more [context in this blog post](https://medium.com/european-data-journalism-network/beautiful-gantt-charts-with-ggplot2-80ccd8c2c788).
Read on for more details and examples.
## Motivation
It is possible to find online documented attempts at facilitating the creation of Gantt charts from R. Some of them (e.g. [this](https://www.molecularecologist.com/2019/01/simple-gantt-charts-in-r-with-ggplot2-and-the-tidyverse/) and [this](https://davetang.org/muse/2017/02/03/gantt-chart-using-r/)) use 'ggplot2', but I feel they do not look very nice. The same goes for the answers I found in the [relevant Stackoverflow question](https://stackoverflow.com/questions/3550341/gantt-charts-with-r).
Even [Plotly](https://moderndata.plot.ly/gantt-charts-in-r-using-plotly/) enables the creation of Gantt charts in R, but again, I don't like the end result.
I did find a [solution that was rather visually satisfying](https://insileco.github.io/2017/09/20/gantt-charts-in-r/), but it was in base R, and all the cool kids nowadays know that base plotting in R exists only [for compatibility with S](https://twitter.com/whydoesr): not an option! (Hey, I'm joking, don't @ me!)
Given what is evidently my posh taste for Gantt charts, I had no other option than making this package with a pretentious, gentrified name, instead of the obvious "ganttr".
Please welcome `ganttrify`.
## Disclaimer
More seriously, this has been a quick attempt at making decent-looking Gantt charts.
And yes, I will enable all the customisations you like, but first I actually need to submit this project.
[Thanks to all who contributed suggestions via issues and pull request!]
## Features
Take an adequately formatted spreadsheet and turn it into a Gantt chart made with ggplot2.
## Installation
You can install the development version from [GitHub](https://github.com/) with:
```{r eval = FALSE}
# install.packages("remotes")
remotes::install_github("giocomai/ganttrify")
```
## Example
Here is an example project:
```{r echo=FALSE}
knitr::kable(ganttrify::test_project)
```
Month since the beginning of the project are used as reference in order to make it easier to change the date when the project starts without needing to change the timing of all activities.
If you prefer to include dates instead of month numbers, please see additional examples below.
```{r gantt_chart}
library("ganttrify")
ganttrify(project = ganttrify::test_project,
project_start_date = "2021-03",
font_family = "Roboto Condensed")
```
[all examples in this page will use the `Roboto condensed` font; if it is not installed, you can use the default `sans`. See the *Troubleshooting* section at the bottom of this readme.]
"But what if I wanted to add spot labels for events, deliverables, outputs, milestones, things like that?", you asked.
Just put them in a table with these column names, and you will be served.
```{r echo=FALSE}
knitr::kable(ganttrify::test_spots)
```
```{r gantt_charts_with_events}
ganttrify(project = ganttrify::test_project,
spots = ganttrify::test_spots,
project_start_date = "2021-03",
font_family = "Roboto Condensed")
```
"I can't read the text, can I change the text size?", I heard.
"Also, is it possible to outline quarters?"
You're welcome.
```{r gantt_charts_resized_text}
ganttrify(project = ganttrify::test_project,
spots = ganttrify::test_spots,
project_start_date = "2021-03",
size_text_relative = 1.2,
mark_quarters = TRUE,
font_family = "Roboto Condensed")
```
It appears that some of you don't like having a line for the working package and are fine with just lines for activities. Did you mean it like this?
```{r gantt_no_wp}
ganttrify(project = ganttrify::test_project,
hide_wp = TRUE,
font_family = "Roboto Condensed")
```
I thought we all liked rounded lines and full opacity, but it's ok if you don't:
```{r gantt_butt_line_transparency}
ganttrify(project = ganttrify::test_project,
project_start_date = "2021-04",
alpha_wp = 0.9,
alpha_activity = 0.6,
line_end = "butt")
```
Some of us work on very long projects, and may need to declutter the chart to increase readability. So let's show the month number only once every three months, and hide the thin vertical lines included by default.
```{r gantt_36_months}
test_36 <- ganttrify::test_project
test_36[11,4] <- 36
ganttrify(project = test_36,
project_start_date = "2021-04",
month_breaks = 3,
show_vertical_lines = FALSE)
```
Does right-aligned text bother you
```{r gantt_left_aligned}
ganttrify(project = ganttrify::test_project,
spots = ganttrify::test_spots,
project_start_date = "2021-04",
axis_text_align = "left")
```
```{r gantt_centre_aligned}
ganttrify(project = ganttrify::test_project,
spots = ganttrify::test_spots,
project_start_date = "2021-04",
axis_text_align = "centre")
```
Finally, keep in mind that ganttrify outputs `ggplot` objects. Some theming options may not behave exactly as you expect, but for example adding title, subtitle, and captions can be done as you would normally do with any `ggplot` graphs.
```{r gantt_with_text}
ganttrify(project = ganttrify::test_project,
spots = ganttrify::test_spots,
project_start_date = "2020-01",
font_family = "Roboto Condensed")+
ggplot2::labs(title = "My beautiful plans for 2020",
subtitle = "I will definitely comply with the exact timing of each and all activities*",
caption = "* I mean, I'll do my best, but if there's a pandemic or something, it's not my fault really")
```
## Shiny app
If you prefer interactive web interfaces to coding, you can still have a fancy *ganttrified* chart.
```{r eval=FALSE}
shiny_ganttrify()
```
And there you go!
You can check it online with no further ado at the following link:
https://ganttrify.europeandatajournalism.eu/
(N.B.: not all features are exposed in the shiny app)
### Shiny app on Docker
Alright, you don't know like R, but you know how Docker works?
This is all you need to find yourself a nice web app on `localhost`
```
docker run -p 80:80 giocomai/ganttrify
```
You can of course build yourself the docker image using the Dockerfile included in this repo.
## Additional input formats
Alright, you prefer to use dates rather than month numbers from the beginning of the project. You're welcome: just format the date as follows, and remember to include the `month_number_label = FALSE` parameter. You can also use exact dates (e.g. `2021-01-01`), but by default they would still be converted to include the entire month were that given day falls.
```{r}
knitr::kable(ganttrify::test_project_date_month)
```
```{r}
ganttrify(project = ganttrify::test_project_date_month,
spots = ganttrify::test_spots_date_month,
by_date = TRUE,
size_text_relative = 1.2,
mark_quarters = TRUE,
font_family = "Roboto Condensed")
```
As it turns out, someone wants more detail: they'd like to be able to input activities with an exact start and end date. I start to suspect that `ganttrify` at this stage may not be exactly what you're looking for, but perhaps this works for you?
```{r}
knitr::kable(ganttrify::test_project_date_day)
```
```{r}
ganttrify(project = ganttrify::test_project_date_day,
spots = ganttrify::test_spots_date_day,
by_date = TRUE,
exact_date = TRUE,
size_text_relative = 1.2,
month_number_label = FALSE,
font_family = "Roboto Condensed")
```
## Troubleshooting
### Structure of the input table
At this stage, the package has strong expectations about the input format, and does not provide meaningful error messages. If you see unexpected results, please consider that:
- no cell in the activity column must be empty
- an activity cannot be called the same as a wp
- activities in different wp should have different names (or at least add a space at the end or something so that they look different to the computer).
Some of this limitations should be dealt with in a future update.
### Fonts
By default, this package uses a generic *sans* font but it is recommended to use a narrow (or condensed font such as *[Roboto Condensed](https://fonts.google.com/specimen/Roboto+Condensed)* font - a free font that can be downloaded and installed on any desktop) as they make more efficient use of text space.
On Fedora, you can install it with `sudo dnf install google-roboto-condensed-fonts`
On Debian, you can install it with `sudo apt-get install fonts-roboto-fontface`
After installation, you should make sure the font is available to R by installing the `extrafont` package, and running `extrafont::font_import()`.
You can check available fonts also with the package `systemfonts` and the command `systemfonts::system_fonts()`.
### Dependencies
To reduce the number of dependencies, `extrafont`, as well as the packages used by the Shiny app needed to import data (`googlesheets4`, `readxl`) and to export the chart in svg (`svglite`) are only suggested.
You can install them independently (they're all on CRAN), or together with this package with:
```{r eval = FALSE}
remotes::install_github("giocomai/ganttrify", dependencies = TRUE)
```