From f8f4d94f55239ff9d5d5d06f59794b35ea872ea0 Mon Sep 17 00:00:00 2001
From: jbengler <broder.engler@gmail.com>
Date: Thu, 4 Jul 2024 18:18:22 +0200
Subject: [PATCH] articles

---
 R/add-general.R                          |   1 -
 R/add-misc.R                             |  12 +-
 _pkgdown.yml                             |   1 -
 vignettes/articles/Advanced-plotting.Rmd | 224 +++++++++++++++++++-
 vignettes/articles/Color-schemes.Rmd     | 249 ++++++++++++++++-------
 vignettes/articles/Design-principles.Rmd |  83 --------
 vignettes/articles/Visualizing-data.Rmd  |  40 +++-
 vignettes/tidyplots.Rmd                  |  24 +--
 8 files changed, 452 insertions(+), 182 deletions(-)
 delete mode 100644 vignettes/articles/Design-principles.Rmd

diff --git a/R/add-general.R b/R/add-general.R
index 73d0f18d..b8164cd8 100644
--- a/R/add-general.R
+++ b/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
diff --git a/R/add-misc.R b/R/add-misc.R
index f161ba4d..bf29777b 100644
--- a/R/add-misc.R
+++ b/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, ...)
 }
 
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 4acea206..78cd8621 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -18,7 +18,6 @@ articles:
   - articles/Visualizing-data
   - articles/Advanced-plotting
   - articles/Color-schemes
-  - articles/Design-principles
 
 reference:
 - title:
diff --git a/vignettes/articles/Advanced-plotting.Rmd b/vignettes/articles/Advanced-plotting.Rmd
index 27119a3e..bc421e21 100644
--- a/vignettes/articles/Advanced-plotting.Rmd
+++ b/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
diff --git a/vignettes/articles/Color-schemes.Rmd b/vignettes/articles/Color-schemes.Rmd
index a96767b8..8f04dae6 100644
--- a/vignettes/articles/Color-schemes.Rmd
+++ b/vignettes/articles/Color-schemes.Rmd
@@ -18,129 +18,228 @@ knitr::opts_chunk$set(
 ```
 
 ::: {.lead}
-In this article, we will demonstrate the use of color schemes in tidyplots.
-built in and construct new.
-We will cover.
-We will conclude by.
+In this article, we will demonstrate the use of color schemes. We will explore the default color schemes that come with tidyplots and are ready to use for plotting. These include schemes for discrete, continuous and diverging variables. To conclude, we will discuss the creation of custom color schemes from hex colors.
 :::
 
-```{r setup}
+# Default color schemes
+
+tidyplots comes with a number of default color schemes. Many of them are adapted from the `viridisLite` and `RColorBrewer` packages. You access them by loading the the tidyplots library and start typing `colors_`. The auto-completion will guide you through a selection of `discrete`, `continuous` and `diverging` schemes.
+
+Let's have a look at the signature scheme of tidyplots, which is called `colors_discrete_metro`. When running the line `colors_discrete_metro` in the console or within a script, a preview of the scheme will be rendered to the Viewer pane in the lower right of the RStudio Desktop interface.
+
+In essence, tidyplots color schemes are just a character vector of hex colors with a special print method that sends a preview to the RStudio viewer pane.
+
+```{r}
 library(tidyplots)
+colors_discrete_metro
+```
+
+```{r results='asis', echo=FALSE}
+print(colors_discrete_metro, return_html = TRUE)
 ```
 
+_Tip: You can copy the hex colors directly from the preview in the Viewer pane and paste into your script._
+
+## Discrete
+
+Discrete color schemes are meant for categorical variables. The default schemes in tidyplots consist of 5--6 colors. However, if more categories are present in the plot, tidyplots will automatically fill up the gaps between colors to deliver exactly the number that is required for the plot.
+
 ```{r}
 energy %>% 
   tidyplot(year, power, color = energy_source) %>% 
   add_barstack_absolute()
+```
+
+And here are some variations.
 
+```{r}
 energy %>% 
   tidyplot(year, power, color = energy_source) %>% 
   add_barstack_absolute() %>% 
   adjust_colors(colors_discrete_seaside)
-
 energy %>% 
   tidyplot(year, power, color = energy_source) %>% 
   add_barstack_absolute() %>% 
   adjust_colors(colors_discrete_candy)
-
 energy %>% 
   tidyplot(year, power, color = energy_source) %>% 
   add_barstack_absolute() %>% 
   adjust_colors(colors_discrete_pastel)
-
 energy %>% 
   tidyplot(year, power, color = energy_source) %>% 
   add_barstack_absolute() %>% 
   adjust_colors(colors_discrete_circle)
 ```
 
-```{r}
+## Continuous
 
+Continuous color schemes are meant for continuous variables. The default schemes in tidyplots usually consist of 265 colors.
+
+```{r}
 colors_continuous_viridis
-colors_discrete_metro
-colors_discrete_circle
-colors_continuous_viridis
-colors_continuous_magma
-colors_continuous_bluepinkyellow
-
-new_color_scheme(c('#d73027','#f46d43','#fdae61','#fee090','#ffffbf','#e0f3f8','#abd9e9','#74add1','#4575b4'))
-new_color_scheme(c("#8ecae6", "#219ebc", "#023047", "#ffb703", "#fb8500"))
-new_color_scheme(c("#cdb4db", "#ffc8dd", "#ffafcc", "#bde0fe", "#a2d2ff"))
-new_color_scheme(c("#ef476f", "#ffd166", "#06d6a0", "#118ab2", "#073b4c"))
-new_color_scheme(c("#390099", "#9e0059", "#ff0054", "#ff5400", "#ffbd00"))
-new_color_scheme(c("#233d4d", "#fe7f2d", "#fcca46", "#a1c181", "#619b8a"))
-new_color_scheme(c("#006ba6", "#0496ff", "#ffbc42", "#d81159", "#8f2d56"))
-new_color_scheme(c("#ffc857", "#e9724c", "#c5283d", "#481d24", "#255f85"))
-new_color_scheme(c("#edae49", "#d1495b", "#00798c", "#30638e", "#003d5b"))
-new_color_scheme(c("#9b5de5", "#f15bb5", "#fee440", "#00bbf9", "#00f5d4"))
-new_color_scheme(c("#072ac8", "#1e96fc", "#a2d6f9", "#fcf300", "#ffc600"))
-new_color_scheme(c("#003f5c","#2f4b7c","#665191","#a05195","#d45087","#f95d6a","#ff7c43","#ffa600"))
-new_color_scheme(c("#E64B35","#4DBBD5","#00A087","#3C5488","#F39B7F","#8491B4",
-              "#91D1C2","#DC0000","#7E6148","#B09C85"))
+```
 
+```{r results='asis', echo=FALSE}
+print(colors_continuous_viridis, return_html = TRUE)
+```
 
-colors_discrete_metro[2]
-colors_continuous_bluepinkyellow[4:8]
-c(colors_continuous_bluepinkyellow, colors_discrete_metro)
+Here is a use case for a continuous color scheme.
+
+```{r, fig.asp=0.9}
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap() %>%
+  adjust_plot_area_size(height = 100)
+```
+
+And here are some variations.
+
+```{r, fig.asp=0.9}
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap() %>%
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_continuous_viridis)
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap() %>%
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_continuous_mako)
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap() %>%
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_continuous_turbo)
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap() %>%
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_continuous_rocket)
+```
+
+## Diverging
+
+Diverging color schemes are meant for continuous variables that have a central point in the middle. A classical example is the blue--white--red gradient used for gene expression heatmaps.
+
+```{r}
+colors_diverging_blue2red
+```
 
-p1 <- 
-  animals %>%
-  tidyplot(family, color = family) %>%
-  add_count_bar()
+```{r results='asis', echo=FALSE}
+print(colors_diverging_blue2red, return_html = TRUE)
+```
 
-p2 <- 
-  animals %>%
-  tidyplot(animal, color = animal) %>%
-  add_count_bar()
+Here is a use case for a diverging color scheme.
 
-p3 <- 
-  animals %>%
-  dplyr::filter(family != "Reptile") %>% 
-  tidyplot(family, color = family) %>%
-  add_count_bar()
+```{r, fig.asp=0.9}
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap(scale = "row") %>%
+  sort_y_axis_labels(direction) %>% 
+  adjust_plot_area_size(height = 100)
+```
+
+And here are some variations.
+
+```{r, fig.asp=0.9}
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap(scale = "row") %>%
+  sort_y_axis_labels(direction) %>% 
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_diverging_blue2brown)
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap(scale = "row") %>%
+  sort_y_axis_labels(direction) %>% 
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_diverging_BuRd)
+gene_expression %>% 
+  tidyplot(x = sample, y = external_gene_name, color = expression) %>% 
+  add_heatmap(scale = "row") %>%
+  sort_y_axis_labels(direction) %>% 
+  adjust_plot_area_size(height = 100) %>% 
+  adjust_colors(new_colors = colors_diverging_BuYlRd)
+```
 
-p1
-# default
-p1 %>% adjust_colors()
-p1 %>% adjust_colors(colors_discrete_metro)
+# Custom color schemes
 
-# correct number
-p1 %>% adjust_colors(colors_discrete_metro)
+Of course you can also construct custom color schemes using the `new_color_scheme()` function.
 
-# too many
-p1 %>% adjust_colors(colors_continuous_bluepinkyellow)
-p1 %>% adjust_colors(colors_continuous_plasma)
+```{r}
+my_colors <- 
+  new_color_scheme(c("#A6E98A","#ECA669","#8087E2","#E06681","#E2D269"),
+                   name = "my_custom_color_scheme")
+my_colors
+```
+
+```{r results='asis', echo=FALSE}
+print(my_colors, return_html = TRUE)
+```
 
-# too few
-p1 %>% adjust_colors(colors_discrete_metro[1:3])
+Than you can use your scheme as input to the `adjust_colors()` function.
 
-p2
-# default
-p2 %>% adjust_colors()
-p2 %>% adjust_colors(colors_discrete_metro)
+```{r}
+energy %>% 
+  tidyplot(year, power, color = energy_source) %>% 
+  add_barstack_absolute() %>% 
+  adjust_colors(new_colors = my_colors)
+```
 
-# too few
-p2 %>% adjust_colors(colors_continuous_bluepinkyellow)
+Besides creating new schemes, you can also subset and concatenate existing schemes in the exact same way you would do with a regular character string.
 
-p3
-# default
-p3 %>% adjust_colors()
-p3 %>% adjust_colors(colors_discrete_metro)
+```{r}
+colors_discrete_metro[2]
+```
 
-# too many
-p3 %>% adjust_colors(colors_continuous_viridis)
+```{r results='asis', echo=FALSE}
+print(colors_discrete_metro[2], return_html = TRUE)
+```
 
-# named vector
-p3 %>% adjust_colors(c("Bird" = "#007700"))
-p3 %>% adjust_colors(c("Bird" = "#007700", "Insect" = "#f80398"))
-p3 %>% adjust_colors(c("Bird" = "#007700", "Not_there" = "#f8f300"))
+```{r}
+colors_discrete_metro[2:4]
+```
 
+```{r results='asis', echo=FALSE}
+print(colors_discrete_metro[2:4], return_html = TRUE)
 ```
 
-```{r eval=FALSE}
-colors_continuous_inferno
+```{r}
+c(colors_discrete_metro, colors_discrete_seaside)
 ```
 
 ```{r results='asis', echo=FALSE}
-print(colors_continuous_inferno, return_html = TRUE)
+print(c(colors_discrete_metro, colors_discrete_seaside), return_html = TRUE)
 ```
+
+# 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
diff --git a/vignettes/articles/Design-principles.Rmd b/vignettes/articles/Design-principles.Rmd
deleted file mode 100644
index ea9ada91..00000000
--- a/vignettes/articles/Design-principles.Rmd
+++ /dev/null
@@ -1,83 +0,0 @@
----
-title: "Design principles"
----
-
-```{r, include = FALSE}
-knitr::opts_chunk$set(
-  collapse = TRUE,
-  comment = "#>",
-  results = FALSE,
-  message = FALSE,
-  warning = FALSE,
-  fig.align = "center",
-  fig.width = 5,
-  fig.height = 2.6,
-  dpi = 300
-)
-```
-
-::: {.lead}
-In this article, we will explore the design choices made in tidyplots, including notable differences to ggplot2.
-We will cover.
-We will conclude by.
-:::
-
-```{r setup}
-library(tidyplots)
-```
-
-# Fokus on science
-
-Data visualization and interpretation is at the heart of scientific progress. To make this essential task as simple and powerful as possible, tidyplots provides a consistent grammar of scientific plotting. The naming of functions follows a clear hierarchy, starting with "what" to plot before thinking about "how" to plot it. For example, 
-
-# Modularity
-
-# Pipe power
-
-tidyplots uses the pipe `%>%` (instead of `+` like `ggplot2`) to build up plots. This way you can seamlessly pipe **into** and **out of** your plot. For example, coming from fram a data wrangeling pipeline you can generate a plot and directly pipe it into `save_plot()`. You can also call `save_plot()` or `view_plot()` in the middle of your pipeline to output intermediate results.
-
-- `tidyplots` tries to reduce the complexity of `ggplot2` by choosing sensible defaults. However, you take more detailed control by via the `...` argument in each function. And if you need to add plain `ggplot2` code, you can do this using `add()` function, which will preserve the `tidyplots` pipeline.
-
-# Absolute dimensions
-
-All plots have absolute dimensions by default, defined in "mm". These dimensions refer to the plotting area, not the entire plot, thus ensuring consistent lengths of `x` any `y` axes. The dimension can be changed with the `width` and `height` parameters, either when creating the plot with `tidyplot()` or later with `adjust_plot_area_size()`. If you want to restore the `ggplot2` behavior that a plot automatically takes up all available space, set `width` and `height` to `NA`.
-
-# Simplicity
-
-- `color` and `fill` are always mapped to the same variable. However, you can still do one of the following: (1) reduce the  opacity of fill using the `alpha` or `saturation` arguments, (2) set `color` or `fill` to a constant hex color within an `add_` function, or (3) set `color` or `fill` to `NA` within an `add_` function to to prevent it from being displayed.
-
-```{r}
-library(ggplot2)
-library(patchwork)
-
-study %>% 
-  ggplot(aes(x = treatment, y = score, color = treatment, fill = treatment)) +
-  stat_summary(fun = mean, geom = "bar", color = NA, width = 0.6, alpha = 0.3) +
-  stat_summary(fun.data = mean_se, geom = "errorbar", linewidth = 0.25, width = 0.4) +
-  geom_point(position = position_jitterdodge(jitter.width = 0.2)) +
-  scale_y_continuous(expand = expansion(c(0, 0.1))) +
-  theme_bw() +
-      theme(
-      panel.border = element_blank(),
-      axis.line = element_line(linewidth = 0.25, colour = "black"),
-      plot.margin = unit(c(0.5, 0.5, 0.5, 0.5), "mm"),
-      plot.background = element_rect(fill = NA, colour = NA),
-      legend.background = element_rect(fill = NA, colour = NA),
-      legend.key = element_rect(fill = NA, colour = NA),
-      strip.background = element_rect(fill = NA, colour = NA),
-      panel.background = element_rect(fill = NA, colour = NA),
-      panel.grid.major = element_blank(),
-      panel.grid.minor = element_blank(),
-      axis.ticks = element_line(colour = "black", linewidth = 0.25)
-    ) +
-  plot_layout(widths = unit(50, "mm"), heights = unit(50, "mm"))
-
-```
-
-```{r}
-
-
-
-
-
-```
diff --git a/vignettes/articles/Visualizing-data.Rmd b/vignettes/articles/Visualizing-data.Rmd
index 9c20bcf0..c0f13ec2 100644
--- a/vignettes/articles/Visualizing-data.Rmd
+++ b/vignettes/articles/Visualizing-data.Rmd
@@ -65,7 +65,7 @@ study %>%
   add_data_points()
 ```
 
-To avoid overplotting in this scenario, there are two additional options. You can add some random noise or _jitter_ to the y position.
+To avoid overplotting in this scenario, there are two additional options. You can add some random noise to the y position, also known as _jitter_.
 
 ```{r}
 study %>% 
@@ -176,7 +176,7 @@ gene_expression %>%
   add_heatmap()
 ```
 
-One thing to note here is that the y axis labeks are overlapping. So let's increase the height of the plot area from 50 to 100 mm.
+One thing to note here is that the y axis labels are overlapping. So let's increase the height of the plot area from 50 to 100 mm.
 
 ```{r, fig.asp=0.9}
 gene_expression %>% 
@@ -345,7 +345,7 @@ distributions %>%
 
 Proportional data provides insights into the proportion or percentage that each individual category contributes to the total. To explore the visualization of proportional data in tidyplots, let's introduce the `energy` dataset.
 
-```{r}
+```{r, results='markup'}
 energy %>% 
   dplyr::glimpse()
 ```
@@ -456,7 +456,7 @@ This nicely illustrates how wind energy closes the solar gap during the night, h
 
 # Statistical comparison
 
-To test for differences between experimental groups, tidyplots offers the funtions `add_stats_asterisks()` and `add_stats_pvalue()`. While the first one includes asterisks for symbolizing significance.
+To test for differences between experimental groups, tidyplots offers the functions `add_stats_asterisks()` and `add_stats_pvalue()`. While the first one includes asterisks for symbolizing significance.
 
 ```{r}
 study %>% 
@@ -611,3 +611,35 @@ animals %>%
   add_text_labels(data = max_rows(weight, 3), animal) %>% 
   add_text_labels(data = max_rows(speed, 3), animal)
 ```
+
+# 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
diff --git a/vignettes/tidyplots.Rmd b/vignettes/tidyplots.Rmd
index 1e21f5ba..27d7ed50 100644
--- a/vignettes/tidyplots.Rmd
+++ b/vignettes/tidyplots.Rmd
@@ -31,7 +31,7 @@ We will be using the programming language R and the software RStudio Desktop, wh
 1. Download and install [R](https://ftp.gwdg.de/pub/misc/cran/) for your operating system. On Windows, choose the _base_ version.
 2. Download and install [RStudio Desktop](https://posit.co/download/rstudio-desktop/)
 
-For more information about R programming have a look at the free online book [Hands-On Programming with R](https://rstudio-education.github.io/hopr/) by Garrett Grolemund, which has a chapter with detailed [installation instructions](https://rstudio-education.github.io/hopr/starting.html). For a quick video tour of the RStudio Desktop user interface queck out [RStudio for the Total Beginner](https://www.youtube.com/watch?v=FIrsOBy5k58).
+For more information about R programming have a look at the free online book [Hands-On Programming with R](https://rstudio-education.github.io/hopr/) by Garrett Grolemund, which has a chapter with detailed [installation instructions](https://rstudio-education.github.io/hopr/starting.html). For a quick video tour of the RStudio Desktop user interface check out [RStudio for the Total Beginner](https://www.youtube.com/watch?v=FIrsOBy5k58).
 
 ## Install packages
 
@@ -354,28 +354,26 @@ Conveniently, `save_plot()` also gives back the plot it received, allowing it to
 
 # What's more?
 
-This getting started guide is meant to give a high level overview of the tidyplots workflow. To dive deeper into more specific aspects of tidyplots, here a couple of resources.
+To dive deeper into code-based plotting, here a couple of resources.
 
-## tidyplots reference
+## tidyplots documentation
 
-- [Function reference](https://jbengler.github.io/tidyplots/reference/index.html)  
-A great overview of all tidyplots functions
+- [Reference](https://jbengler.github.io/tidyplots/reference/index.html)  
+Overview of all tidyplots functions
 
-## tidyplots articles
+- [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)  
-An article with examples for common data visualizations
+Article with examples for common data visualizations
 
 - [Advanced plotting](https://jbengler.github.io/tidyplots/articles/Advanced-plotting.html)  
-An article about advanced plotting techniques and workflows
+Article about advanced plotting techniques and workflows
 
 - [Color schemes](https://jbengler.github.io/tidyplots/articles/Color-schemes.html)  
-An article about the use of color schemes in tidyplots
+Article about the use of color schemes
 
-- [Design principles](https://jbengler.github.io/tidyplots/articles/Design-principles.html)  
-An article about the design choices in tidyplots, including notable differences to ggplot2
-
-## Other ressources
+## Other resources
 
 - [Hands-On Programming with R](https://rstudio-education.github.io/hopr/)   
 Free online book by Garrett Grolemund