articles

R/add-general.R

@@ -44,7 +44,6 @@
 #' @param fill common
 #' @param saturation common
 #' @param group common
-#' @param saturation common
 #' @param reverse common
 #' @param scale_cut common
 #' @param fontsize common

R/add-misc.R

@@ -11,7 +11,7 @@
 #'
 #' @export
 add_boxplot <- function(plot, dodge_width = NULL, saturation = 0.3, show_whiskers = TRUE, show_outliers = TRUE,
-                        box_width = 0.6, whiskers_width = 0.5, outlier.size = 0.5, coef = 1.5,
+                        box_width = 0.6, whiskers_width = 0.8, outlier.size = 0.5, coef = 1.5,
                         outlier.shape = 19, linewidth = 0.25, preserve = "total", ...) {
   check_tidyplot(plot)
   dodge_width <- dodge_width %||% plot$tidyplot$dodge_width
@@ -21,10 +21,14 @@ add_boxplot <- function(plot, dodge_width = NULL, saturation = 0.3, show_whisker
     coef = 0
     whiskers_width = box_width
   }
+  # plot +
+  #   ggplot2::stat_boxplot(geom ='errorbar', width = whiskers_width, position = position,
+  #                         linewidth = linewidth, coef = coef) +
+  #   ggplot2::geom_boxplot(outliers = show_outliers, outlier.shape = outlier.shape, outlier.size = outlier.size,
+  #                         width = box_width, position = position, linewidth = linewidth, coef = coef, ...)
+  # with staplewidth
   plot +
-    ggplot2::stat_boxplot(geom ='errorbar', width = whiskers_width, position = position,
-                          linewidth = linewidth, coef = coef) +
-    ggplot2::geom_boxplot(outliers = show_outliers, outlier.shape = outlier.shape, outlier.size = outlier.size,
+    ggplot2::geom_boxplot(staplewidth = whiskers_width, outliers = show_outliers, outlier.shape = outlier.shape, outlier.size = outlier.size,
                           width = box_width, position = position, linewidth = linewidth, coef = coef, ...)
 }
 

_pkgdown.yml

@@ -18,7 +18,6 @@ articles:
   - articles/Visualizing-data
   - articles/Advanced-plotting
   - articles/Color-schemes
-  - articles/Design-principles
 
 reference:
 - title:

vignettes/articles/Advanced-plotting.Rmd

@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 In this article, we will explore advanced plotting techniques offered in tidyplots. We will cover the rasterizing of individual plot components, data subsetting for highlighting selected data points, and the construction of powerful plotting pipelines. Moreover, we will discuss the visualization of paired and missing data. We will conclude by introducing the concepts of plot orientation, dodging and plot area padding.
 :::
 
-# Raster versus vector
+# Rasterizing
 
 Generally, vector graphics like PDF and SVG are superior to raster images like PNG and JPG because they maintain high quality and sharpness at any scale. This makes them ideal for printing, resizing, and zooming without losing detail.
 
@@ -275,5 +275,227 @@ time_course %>%
 
 # Padding
 
+Per default, tidyplots gives the data points a little bit of extra space towards the border of the plot area.
+
+```{r}
+animals %>% 
+  tidyplot(x = weight, y = speed) %>% 
+  add_data_points() %>% 
+  adjust_plot_area_padding(top = )
+```
+
+This _padding_, also known as _expansion_ in ggplot2, is 0.05 by default and can be changes using the `adjust_plot_area_padding()` function.
+
+```{r}
+animals %>% 
+  tidyplot(x = weight, y = speed) %>% 
+  add_data_points() %>% 
+  adjust_plot_area_padding(top = 0.2, right = 0.2, bottom = 0.2, left = 0.2)
+```
+
+To remove the padding completely, you can use use the `remove_padding()` function. But note that the highest and lowest values are cut off.
+
+```{r}
+animals %>% 
+  tidyplot(x = weight, y = speed) %>% 
+  add_data_points() %>% 
+  remove_plot_area_padding()
+```
+
+When using certain types of plot components, tidyplots automatically adapts the padding to improve the look of the plot. For example, in `bar` and `area` plots the padding between the `bar` or `area` and the axis is removed.
+
+```{r}
+study %>% 
+  tidyplot(x = treatment, y = score, color = treatment) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points()
+```
+
+You can revert this manually like so.
+
+```{r}
+study %>% 
+  tidyplot(x = treatment, y = score, color = treatment) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points() %>% 
+  adjust_plot_area_padding(bottom = 0.05)
+```
+
 # Dodging
 
+Dodging refers to the distance between grouped objects. The default in tidyplots is 0.8 and looks like this.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points()
+```
+
+Increasing the `dodge_width` in the `tidyplots()` function call increases the spacing between grouped bars.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose, dodge_width = 1.2) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points()
+```
+
+Setting `dodge_width = 0` results in overlapping positions.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose, dodge_width = 0) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points()
+```
+
+This does not make too much sense for bars. But it makes a lot of sense for `lines` and `areas`, which otherwise are not aligned. Here is an example with `dodge_width = 0`.
+
+```{r}
+time_course %>% 
+  tidyplot(x = day, y = score, color = treatment, dodge_width = 0) %>% 
+  add_mean_line() %>% 
+  add_mean_dot() %>% 
+  add_reference_lines(x = 10)
+```
+
+And here with the default `dodge_width = 0.8`. I added a reference line at day 10 to make it easier to see the difference.
+
+```{r}
+time_course %>% 
+  tidyplot(x = day, y = score, color = treatment) %>% 
+  add_mean_line() %>% 
+  add_mean_dot() %>% 
+  add_reference_lines(x = 10)
+```
+
+# Coloring
+
+tidyplots follows are quite straight forward approach when dealing with color. The variable that should be encoded by colors is passed via the `color` parameter to the `tidyplot()` function.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar(saturation = 0.3) %>% 
+  add_error_bar() %>% 
+  add_data_points()
+```
+
+In ggplot2, the plotting package that underlies tidyplots, colors are little more complicated. ggplot2 distinguishes between the fill color of an object `fill` and the stroke color of an object `color`. Some objects like bars can have both, while other objects like lines just have a stroke `color` but no `fill`.
+
+Usually, tidyplots users do not have to care about these details. Internally, tidyplots matches both `fill` and `color` to the same color. And this is the color that comes in as the `color` parameter into the `tidyplot()` function.
+
+In some cases though, you might want to take manual control over the `fill` and stroke `color` of specific objects.
+
+For example, want to plot a boxplot without the `fill` color.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_boxplot(fill = NA)
+```
+
+Or with a black stroke `color`.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_boxplot(color = "black")
+```
+
+Or you want to have black text labels.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar(saturation = 0.3) %>% 
+  add_mean_value(color = "black")
+```
+
+# Alpha versus saturation
+
+Sometimes you want to decrease the intensity of your colors.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar() %>% 
+  theme_minimal_y()
+```
+
+One way to do this is to reduce the opacity by decreasing the alpha parameter. Note how the horizontal lines start to shine through the bars.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar(alpha = 0.3) %>% 
+  theme_minimal_y()
+```
+
+In the `add_mean_bar()` family of functions, in `add_violin()` and in `add_boxplots()` functions, tidyplots offers one additional method using the `saturation` parameter.
+
+```{r}
+study %>% 
+  tidyplot(x = group, y = score, color = dose) %>% 
+  add_mean_bar(saturation = 0.3) %>% 
+  theme_minimal_y()
+```
+
+Note how here the saturation is decreased without making the bars transparent. Thus, the horizontal lines do not shine through the bars.
+
+# ggplot2 compatibiliy
+
+tidyplots is based on ggplot2 but does a few things slightly different.
+
+The most noticeable is probably that ggplot uses `+` to add plot components while tidyplots completely relies on the pipe `%>%`.
+
+There is still a certain compatibility of both systems. For example, you can transform a ggplot to tidyplot using the `as_tidyplot()` function.
+
+Also, you can add ggplot code to a tidyplot using the `add()` helper function.
+
+```{r}
+study %>% 
+  tidyplot(x = treatment, y = score, color = treatment) %>% 
+  add_mean_bar(saturation = 0.3) %>% 
+  add(ggplot2::geom_point())
+```
+
+However, be ready to experience unexpected hiccups, when mixing ggplot and tidyplots, since ensuring compatibility in every edge case was not a priority when developing the tidyplots package.
+
+# What's more?
+
+To dive deeper into code-based plotting, here a couple of resources.
+
+## tidyplots documentation
+
+- [Reference](https://jbengler.github.io/tidyplots/reference/index.html)  
+Overview of all tidyplots functions
+
+- [Get started](file:///Users/janbroderengler/GoogleDrive/R/packages/tidyplots/docs/articles/tidyplots.html)  
+Getting started guide
+
+- [Visualizing data](https://jbengler.github.io/tidyplots/articles/Visualizing-data.html)  
+Article with examples for common data visualizations
+
+- [Advanced plotting](https://jbengler.github.io/tidyplots/articles/Advanced-plotting.html)  
+Article about advanced plotting techniques and workflows
+
+- [Color schemes](https://jbengler.github.io/tidyplots/articles/Color-schemes.html)  
+Article about the use of color schemes
+
+## Other resources
+
+- [Hands-On Programming with R](https://rstudio-education.github.io/hopr/)   
+Free online book by Garrett Grolemund
+
+- [R for Data Science](https://r4ds.hadley.nz)  
+Free online book by Hadley Wickham
+
+- [Fundamentals of Data Visualization](https://clauswilke.com/dataviz/)  
+Free online book by Claus O. Wilke