diff --git a/DESCRIPTION b/DESCRIPTION index 7f83e75..79429e5 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: ganttrify Title: Create beautiful Gantt charts with ggplot2 -Version: 0.0.0.9008 +Version: 0.0.0.9009 Authors@R: person(given = "Giorgio", family = "Comai (OBCT/CCI)", @@ -11,7 +11,7 @@ Description: 'ganttrify' facilitates the creation of nice-looking Gantt charts, License: GPL-3 Encoding: UTF-8 LazyData: true -RoxygenNote: 7.2.1 +RoxygenNote: 7.2.3 Imports: magrittr, tibble, diff --git a/R/ganttrify.R b/R/ganttrify.R index 60d317c..97fc5e2 100644 --- a/R/ganttrify.R +++ b/R/ganttrify.R @@ -22,7 +22,15 @@ #' @param colour_stripe Character, defaults to "lightgray". This is the stripe colour in the background used in alternate months. #' @param alpha_wp Numeric, defaults to 1. Controls transparency of the line used to represent WPs. #' @param alpha_activity Numeric, defaults to 1. Controls transparency of the line used to represent activities. -#' @param line_end Character, defaults to "round". One of "round", "butt", "square". Controls line ends. +#' @param line_end Character, defaults to NULL. If given, takes precedence over `line_end_wp` and `line_end_activity` and applies the value to both. One of "round", "butt", "square". Controls line ends. +#' @param line_end_wp Character, defaults to "round". One of "round", "butt", "square". Controls line ends. +#' @param line_end_activity Character, defaults to "butt". One of "round", "butt", "square". Controls line ends. +#' @param spot_padding Unit, defaults to `ggplot2::unit(0.2, "lines")`. If you use spot events, this is the padding around the text. Smaller value are best for busy gantt charts; if you have lots of space or use larger font sizes you may want to increase this value. +#' @param spot_fontface Defaults to "bold". Available values are "plain", "bold", "italic" and "bold.italic". +#' @param spot_text_colour Defaults to "grey20", for a dark but not quite black text. +#' @param spot_size_text_relative Defaults to 1. This is combined with `size_text_relative`. +#' @param spot_fill Defaults to `ggplot2::alpha(c("white"), 1)`. This is the background fill colour of spot events. By default, it is set to solid white. If you want to add some transparency to enable visual continuity of the underlying lines, adjust the transparency value to your taste adapting the function used by default. +#' @param spot_border Defaults to 0.25. Internally passed as `label.size` to `geom_label()`. Set to 0 or NA to remove the border. #' @param month_breaks Numeric, defaults to 1. It defines if labels for all months are shown or only once every x months. Useful for longer projects. #' @param show_vertical_lines Logical, defaults to TRUE. If set to FALSE, it hides the thin vertical lines corresponding to month numbers. Useful in particular for longer projects. #' @param axis_text_align Character, defaults to "right". Defines alignment of text on the y-axis is left. Accepted values are "left", "right", "centre", or "center". @@ -55,7 +63,15 @@ ganttrify <- function(project, colour_stripe = "lightgray", alpha_wp = 1, alpha_activity = 1, - line_end = "round", + line_end = NULL, + line_end_wp = "round", + line_end_activity = "butt", + spot_padding = ggplot2::unit(0.2, "lines"), + spot_fill = ggplot2::alpha(c("white"),1), + spot_text_colour = "gray20", + spot_size_text_relative = 1, + spot_fontface = "bold", + spot_border = 0.25, month_breaks = 1, show_vertical_lines = TRUE, axis_text_align = "right") { @@ -65,6 +81,11 @@ ganttrify <- function(project, colour_palette <- rep(colour_palette, length(unique(project$wp)))[1:length(unique(project$wp))] } + if (is.null(line_end)==FALSE) { + line_end_wp <- line_end + line_end_activity <- line_end + } + if (label_wrap!=FALSE) { if (isTRUE(label_wrap)) { label_wrap <- 32 @@ -217,12 +238,12 @@ ganttrify <- function(project, gg_gantt <- gg_gantt + ### activities ggplot2::geom_segment(data = df_yearmon_fct, - lineend = line_end, + lineend = line_end_activity, size = size_activity, alpha = df_yearmon_fct$activity_alpha) + ### wp ggplot2::geom_segment(data = df_yearmon_fct, - lineend = line_end, + lineend = line_end_wp, size = size_wp, alpha = df_yearmon_fct$wp_alpha) @@ -315,10 +336,13 @@ ganttrify <- function(project, mapping = ggplot2::aes(x = spot_date, y = activity, label = spot_type), - colour = "gray30", - fontface = "bold", + label.padding = spot_padding, + label.size = spot_border, + colour = spot_text_colour, + fontface = spot_fontface, family = font_family, - size = 3*size_text_relative) + size = 3*size_text_relative*spot_size_text_relative, + fill = spot_fill) } } diff --git a/README.Rmd b/README.Rmd index 541bd0d..dd51c24 100644 --- a/README.Rmd +++ b/README.Rmd @@ -44,7 +44,7 @@ More seriously, this has been a quick attempt at making decent-looking Gantt cha 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!] +[Thanks to all who contributed suggestions via issues and pull requests!] ## Features @@ -120,20 +120,48 @@ ganttrify(project = ganttrify::test_project, font_family = "Roboto Condensed") ``` +I felt that rounded line endings for the working packages, and "butt" ending for activities is the best combination of elegance and clarity. -I thought we all liked rounded lines and full opacity, but it's ok if you don't: +Also, I like full opacity for the lines, 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") + line_end_wp = "round", # alternative values: "butt" or "square" + line_end_activity = "round", # alternative values: "butt" or "square" + font_family = "Roboto Condensed") ``` +If you use spot events, then there's all sorts of opinions you can have about the color and transparency of spot events, as well as the size and padding around the text. Say, you want a larger box around the text, but a semi-transparent background? There you go! +```{r spot_customisations} +ganttrify(project = ganttrify::test_project, + spots = ganttrify::test_spots, + project_start_date = "2021-04", + font_family = "Roboto Condensed", + spot_size_text_relative = 1.5, + spot_fill = ggplot2::alpha(c("white"), 0.7), + spot_padding = ggplot2::unit(0.4, "lines") + ) +``` +Or perhaps you actually just want the label text, without any background, or perhaps change the text colour. Be mindful that the text may become hard to read on darker backgrounds, especially if reviewers then print your proposal, but... you have been warned: + +```{r spot_text} +ganttrify(project = ganttrify::test_project, + spots = ganttrify::test_spots, + project_start_date = "2021-04", + font_family = "Roboto Condensed", + spot_text_colour = "grey10", + spot_fontface = "bold", + spot_fill = NA, + spot_border = NA + ) +``` 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 @@ -141,7 +169,8 @@ test_36[11,4] <- 36 ganttrify(project = test_36, project_start_date = "2021-04", month_breaks = 3, - show_vertical_lines = FALSE) + show_vertical_lines = FALSE, + font_family = "Roboto Condensed") ``` @@ -152,7 +181,8 @@ Does right-aligned text bother you? ganttrify(project = ganttrify::test_project, spots = ganttrify::test_spots, project_start_date = "2021-04", - axis_text_align = "left") + axis_text_align = "left", + font_family = "Roboto Condensed") ``` ```{r gantt_centre_aligned} @@ -160,7 +190,8 @@ ganttrify(project = ganttrify::test_project, ganttrify(project = ganttrify::test_project, spots = ganttrify::test_spots, project_start_date = "2021-04", - axis_text_align = "centre") + axis_text_align = "centre", + font_family = "Roboto Condensed") ``` Do you have *very* long names for your activities? The parameter `label_wrap` is there to help you. @@ -177,8 +208,7 @@ tibble::tribble(~wp, ~activity, ~start_date, ~end_date, ``` - -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. +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 `ggplot2` graph. ```{r gantt_with_text} ganttrify(project = ganttrify::test_project, diff --git a/README.md b/README.md index 0a77a9d..65bfdb7 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ 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!\] +requests!\] ## Features @@ -163,18 +163,57 @@ ganttrify(project = ganttrify::test_project, -I thought we all liked rounded lines and full opacity, but it’s ok if -you don’t: +I felt that rounded line endings for the working packages, and “butt” +ending for activities is the best combination of elegance and clarity. + +Also, I like full opacity for the lines, but it’s ok if you don’t: ``` r ganttrify(project = ganttrify::test_project, project_start_date = "2021-04", alpha_wp = 0.9, alpha_activity = 0.6, - line_end = "butt") + line_end_wp = "round", # alternative values: "butt" or "square" + line_end_activity = "round", # alternative values: "butt" or "square" + font_family = "Roboto Condensed") ``` +If you use spot events, then there’s all sorts of opinions you can have +about the color and transparency of spot events, as well as the size and +padding around the text. Say, you want a larger box around the text, but +a semi-transparent background? There you go! + +``` r +ganttrify(project = ganttrify::test_project, + spots = ganttrify::test_spots, + project_start_date = "2021-04", + font_family = "Roboto Condensed", + spot_size_text_relative = 1.5, + spot_fill = ggplot2::alpha(c("white"), 0.7), + spot_padding = ggplot2::unit(0.4, "lines") + ) +``` + + +Or perhaps you actually just want the label text, without any +background, or perhaps change the text colour. Be mindful that the text +may become hard to read on darker backgrounds, especially if reviewers +then print your proposal, but… you have been warned: + +``` r +ganttrify(project = ganttrify::test_project, + spots = ganttrify::test_spots, + project_start_date = "2021-04", + font_family = "Roboto Condensed", + spot_text_colour = "grey10", + spot_fontface = "bold", + spot_fill = NA, + spot_border = NA + ) +``` + + 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 @@ -188,7 +227,8 @@ test_36[11,4] <- 36 ganttrify(project = test_36, project_start_date = "2021-04", month_breaks = 3, - show_vertical_lines = FALSE) + show_vertical_lines = FALSE, + font_family = "Roboto Condensed") ``` @@ -200,7 +240,8 @@ Does right-aligned text bother you? ganttrify(project = ganttrify::test_project, spots = ganttrify::test_spots, project_start_date = "2021-04", - axis_text_align = "left") + axis_text_align = "left", + font_family = "Roboto Condensed") ``` @@ -210,7 +251,8 @@ ganttrify(project = ganttrify::test_project, ganttrify(project = ganttrify::test_project, spots = ganttrify::test_spots, project_start_date = "2021-04", - axis_text_align = "centre") + axis_text_align = "centre", + font_family = "Roboto Condensed") ``` @@ -234,7 +276,7 @@ tibble::tribble(~wp, ~activity, ~start_date, ~end_date, 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. +do with any `ggplot2` graph. ``` r ganttrify(project = ganttrify::test_project, @@ -358,11 +400,11 @@ 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). +- 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. diff --git a/man/figures/README-gantt_36_months-1.png b/man/figures/README-gantt_36_months-1.png index 8761418..226b69f 100644 Binary files a/man/figures/README-gantt_36_months-1.png and b/man/figures/README-gantt_36_months-1.png differ diff --git a/man/figures/README-gantt_butt_line_transparency-1.png b/man/figures/README-gantt_butt_line_transparency-1.png index b1eea42..7c31005 100644 Binary files a/man/figures/README-gantt_butt_line_transparency-1.png and b/man/figures/README-gantt_butt_line_transparency-1.png differ diff --git a/man/figures/README-gantt_centre_aligned-1.png b/man/figures/README-gantt_centre_aligned-1.png index 0f42996..d4e5d47 100644 Binary files a/man/figures/README-gantt_centre_aligned-1.png and b/man/figures/README-gantt_centre_aligned-1.png differ diff --git a/man/figures/README-gantt_chart-1.png b/man/figures/README-gantt_chart-1.png index aec5ae8..a468120 100644 Binary files a/man/figures/README-gantt_chart-1.png and b/man/figures/README-gantt_chart-1.png differ diff --git a/man/figures/README-gantt_charts_resized_text-1.png b/man/figures/README-gantt_charts_resized_text-1.png index 1f56e7c..59bb336 100644 Binary files a/man/figures/README-gantt_charts_resized_text-1.png and b/man/figures/README-gantt_charts_resized_text-1.png differ diff --git a/man/figures/README-gantt_charts_with_events-1.png b/man/figures/README-gantt_charts_with_events-1.png index 51a52c9..603b01f 100644 Binary files a/man/figures/README-gantt_charts_with_events-1.png and b/man/figures/README-gantt_charts_with_events-1.png differ diff --git a/man/figures/README-gantt_date_day-1.png b/man/figures/README-gantt_date_day-1.png index 95c71e9..cd5b2e7 100644 Binary files a/man/figures/README-gantt_date_day-1.png and b/man/figures/README-gantt_date_day-1.png differ diff --git a/man/figures/README-gantt_date_month-1.png b/man/figures/README-gantt_date_month-1.png index 11c60a5..4dadb1e 100644 Binary files a/man/figures/README-gantt_date_month-1.png and b/man/figures/README-gantt_date_month-1.png differ diff --git a/man/figures/README-gantt_left_aligned-1.png b/man/figures/README-gantt_left_aligned-1.png index 5535870..a8c9d1d 100644 Binary files a/man/figures/README-gantt_left_aligned-1.png and b/man/figures/README-gantt_left_aligned-1.png differ diff --git a/man/figures/README-gantt_long_labels-1.png b/man/figures/README-gantt_long_labels-1.png index 6ff4b4e..eb0bf2f 100644 Binary files a/man/figures/README-gantt_long_labels-1.png and b/man/figures/README-gantt_long_labels-1.png differ diff --git a/man/figures/README-gantt_no_wp-1.png b/man/figures/README-gantt_no_wp-1.png index 922a43f..8518322 100644 Binary files a/man/figures/README-gantt_no_wp-1.png and b/man/figures/README-gantt_no_wp-1.png differ diff --git a/man/figures/README-gantt_with_text-1.png b/man/figures/README-gantt_with_text-1.png index da20655..428ee20 100644 Binary files a/man/figures/README-gantt_with_text-1.png and b/man/figures/README-gantt_with_text-1.png differ diff --git a/man/figures/README-spot_customisations-1.png b/man/figures/README-spot_customisations-1.png new file mode 100644 index 0000000..f3a3e95 Binary files /dev/null and b/man/figures/README-spot_customisations-1.png differ diff --git a/man/figures/README-spot_text-1.png b/man/figures/README-spot_text-1.png new file mode 100644 index 0000000..6be9757 Binary files /dev/null and b/man/figures/README-spot_text-1.png differ diff --git a/man/ganttrify.Rd b/man/ganttrify.Rd index c8f820f..c9470e4 100644 --- a/man/ganttrify.Rd +++ b/man/ganttrify.Rd @@ -25,7 +25,15 @@ ganttrify( colour_stripe = "lightgray", alpha_wp = 1, alpha_activity = 1, - line_end = "round", + line_end = NULL, + line_end_wp = "round", + line_end_activity = "butt", + spot_padding = ggplot2::unit(0.2, "lines"), + spot_fill = ggplot2::alpha(c("white"), 1), + spot_text_colour = "gray20", + spot_size_text_relative = 1, + spot_fontface = "bold", + spot_border = 0.25, month_breaks = 1, show_vertical_lines = TRUE, axis_text_align = "right" @@ -72,7 +80,23 @@ ganttrify( \item{alpha_activity}{Numeric, defaults to 1. Controls transparency of the line used to represent activities.} -\item{line_end}{Character, defaults to "round". One of "round", "butt", "square". Controls line ends.} +\item{line_end}{Character, defaults to NULL. If given, takes precedence over `line_end_wp` and `line_end_activity` and applies the value to both. One of "round", "butt", "square". Controls line ends.} + +\item{line_end_wp}{Character, defaults to "round". One of "round", "butt", "square". Controls line ends.} + +\item{line_end_activity}{Character, defaults to "butt". One of "round", "butt", "square". Controls line ends.} + +\item{spot_padding}{Unit, defaults to `ggplot2::unit(0.2, "lines")`. If you use spot events, this is the padding around the text. Smaller value are best for busy gantt charts; if you have lots of space or use larger font sizes you may want to increase this value.} + +\item{spot_fill}{Defaults to `ggplot2::alpha(c("white"), 1)`. This is the background fill colour of spot events. By default, it is set to solid white. If you want to add some transparency to enable visual continuity of the underlying lines, adjust the transparency value to your taste adapting the function used by default.} + +\item{spot_text_colour}{Defaults to "grey20", for a dark but not quite black text.} + +\item{spot_size_text_relative}{Defaults to 1. This is combined with `size_text_relative`.} + +\item{spot_fontface}{Defaults to "bold". Available values are "plain", "bold", "italic" and "bold.italic".} + +\item{spot_border}{Defaults to 0.25. Internally passed as `label.size` to `geom_label()`. Set to 0 or NA to remove the border.} \item{month_breaks}{Numeric, defaults to 1. It defines if labels for all months are shown or only once every x months. Useful for longer projects.}