Alt text for documentation (#5226)

* Alt text for README

* update extending-ggplot2

* update ggplot2-specs

* update faq-annotation

* update faq-axes

* update faq-bars

* update customising

* update faceting

* update reordering

* Fix typos, don't recommend ..dot.. notation

* Apply suggestions from code review

Co-authored-by: Mara Averick <[email protected]>

---------

Co-authored-by: Mara Averick <[email protected]>

Author: teunbrand

README.Rmd

@@ -47,6 +47,9 @@ pak::pak("tidyverse/ggplot2")
 It's hard to succinctly describe how ggplot2 works because it embodies a deep philosophy of visualisation. However, in most cases you start with `ggplot()`, supply a dataset and aesthetic mapping (with `aes()`). You then add on layers (like `geom_point()` or `geom_histogram()`), scales (like `scale_colour_brewer()`), faceting specifications (like `facet_wrap()`) and coordinate systems (like `coord_flip()`).
 
 ```{r example}
+#| fig.alt = "Scatterplot of engine displacement versus highway miles per
+#|  gallon, for 234 cars coloured by 7 'types' of car. The displacement and miles
+#|  per gallon are inversely correlated."
 library(ggplot2)
 
 ggplot(mpg, aes(displ, hwy, colour = class)) + 

README.md

@@ -53,7 +53,7 @@ ggplot(mpg, aes(displ, hwy, colour = class)) +
   geom_point()
 ```
 
-![](man/figures/README-example-1.png)<!-- -->
+<img src="man/figures/README-example-1.png" alt="Scatterplot of engine displacement versus highway miles per gallon, for 234 cars coloured by 7 'types' of car. The displacement and miles per gallon are inversely correlated."  />
 
 ## Lifecycle
 

vignettes/articles/faq-annotation.Rmd

@@ -39,6 +39,9 @@ You should use `annotate(geom = "text")` instead of `geom_text()` for annotation
 In the following visualisation we have annotated a histogram with a red line and red text to mark the mean. Note that both the line and the text appears pixellated/fuzzy.
 
 ```{r}
+#| fig.alt = "Histogram of highway miles per gallon for 234 cars. A red line is
+#|  placed at the position 23.44 and is adorned with the label 'mean 23.44'.
+#|  Both the line and the text appear pixellated due to overplotting."
 mean_hwy <- round(mean(mpg$hwy), 2)
 
 ggplot(mpg, aes(x = hwy)) +
@@ -59,6 +62,9 @@ This is because `geom_text()` draws the geom once per each row of the data frame
 
 
 ```{r}
+#| fig.alt = "Histogram of highway miles per gallon for 234 cars. A red line is
+#|  placed at the position 23.44 and is adorned with the label 'mean = 23.44'.
+#|  Both the line and the text appear crisp."
 ggplot(mpg, aes(x = hwy)) +
   geom_histogram(binwidth = 2) +
   annotate("segment",
@@ -85,6 +91,9 @@ Set `vjust = "inward"` and `hjust = "inward"` in `geom_text()`.
 Suppose you have the following data frame and visualization. The labels at the edges of the plot are cut off slightly.
 
 ```{r}
+#| fig.alt = "A plot showing the words 'two', 'three' and 'four' arranged 
+#|  diagonally. The 'two' and 'four' labels have been clipped to the panel's 
+#|  edge and are not displayed completely."
 df <- tibble::tribble(
   ~x, ~y, ~name,
   2,  2,  "two",
@@ -99,6 +108,10 @@ ggplot(df, aes(x = x, y = y, label = name)) +
 You could manually extend axis limits to avoid this, but a more straightforward approach is to set `vjust = "inward"` and `hjust = "inward"` in `geom_text()`.
 
 ```{r}
+#| fig.alt = "A plot showing the words 'two', 'three' and 'four' arranged 
+#|  diagonally. The 'two' and 'four' labels are aligned to the top-right and 
+#|  bottom-left relative to their anchor points, and are displayed in their
+#|  entirety."
 ggplot(df, aes(x = x, y = y, label = name)) +
   geom_text(size = 10, vjust = "inward", hjust = "inward")
 ```
@@ -107,7 +120,7 @@ ggplot(df, aes(x = x, y = y, label = name)) +
 
 ### How can I annotate my bar plot to display counts for each bar?
 
-Either calculate the counts ahead of time and place them on bars using `geom_text()` or let `ggplot()` calculate them for you and then add them to the plot using `stat_coun()` with `geom = "text"`.
+Either calculate the counts ahead of time and place them on bars using `geom_text()` or let `ggplot()` calculate them for you and then add them to the plot using `stat_count()` with `geom = "text"`.
 
 <details>
 
@@ -116,6 +129,8 @@ Either calculate the counts ahead of time and place them on bars using `geom_tex
 Suppose you have the following bar plot and you want to add the number of cars that fall into each `drv` level on their respective bars.
 
 ```{r}
+#| fig.alt = "A bar chart showing the number of cars for each of three types
+#|  of drive train."
 ggplot(mpg, aes(x = drv)) +
   geom_bar()
 ```
@@ -124,6 +139,8 @@ One option is to calculate the counts with `dplyr::count()` and then pass them t
 Note that we expanded the y axis limit to get the numbers to fit on the plot.
 
 ```{r}
+#| fig.alt = "A bar chart showing the number of cars for each of three types
+#|  of drive train. The count values are displayed on top of the bars as text."
 mpg %>%
   dplyr::count(drv) %>%
   ggplot(aes(x = drv, y = n)) +
@@ -132,9 +149,11 @@ mpg %>%
   coord_cartesian(ylim = c(0, 110))
 ```
 
-Another option is to let `ggplot()` do the counting for you, and access these counts with `..count..` that is mapped to the labels to be placed on the plot with `stat_count()`.
+Another option is to let `ggplot()` do the counting for you, and access these counts with `after_stat(count)` that is mapped to the labels to be placed on the plot with `stat_count()`.
 
 ```{r}
+#| fig.alt = "A bar chart showing the number of cars for each of three types
+#|  of drive train. The count values are displayed on top of the bars as text."
 ggplot(mpg, aes(x = drv)) +
   geom_bar() + 
   stat_count(geom = "text", aes(label = ..count..), vjust = -0.5) +
@@ -154,6 +173,9 @@ First calculate the counts for each segment (e.g. with `dplyr::count()`) and the
 Suppose you have the following stacked bar plot.
 
 ```{r}
+#| fig.alt = "A stacked bar chart showing the number of cars for each of seven 
+#|  types of cars. The fill colour of the bars indicate the type of drive 
+#|  train."
 ggplot(mpg, aes(x = class, fill = drv)) +
   geom_bar()
 ```
@@ -168,6 +190,10 @@ mpg %>%
 You can then pass this result directly to `ggplot()`, draw the segments with appropriate heights with `y = n` in the `aes`thetic mapping and `geom_col()` to draw the bars, and finally place the counts on the plot with `geom_text()`.
 
 ```{r}
+#| fig.alt = "A stacked bar chart showing the number of cars for each of seven 
+#|  types of cars. The fill colour of the bars indicate the type of drive 
+#|  train. In the middle of each filled part, the count value is displayed as 
+#|  text."
 mpg %>%
   count(class, drv) %>%
   ggplot(aes(x = class, fill = drv, y = n)) +
@@ -188,13 +214,17 @@ Either calculate the prpportions ahead of time and place them on bars using `geo
 Suppose you have the following bar plot but you want to display the proportion of cars that fall into each `drv` level, instead of the count.
 
 ```{r}
+#| fig.alt = "A bar chart showing the number of cars for each of three types
+#|  of drive train."
 ggplot(mpg, aes(x = drv)) +
   geom_bar()
 ```
 
 One option is to calculate the proportions with `dplyr::count()` and then use `geom_col()` to draw the bars
 
 ```{r}
+#| fig.alt = "A bar chart showing the proportion of cars for each of three types
+#|  of drive train."
 mpg %>%
   dplyr::count(drv) %>%
   mutate(prop = n / sum(n)) %>%
@@ -206,6 +236,8 @@ Another option is to let `ggplot()` do the calculation of proportions for you, a
 Note that we also need to the `group = 1` mapping for this option.
 
 ```{r}
+#| fig.alt = "A bar chart showing the proportion of cars for each of three types
+#|  of drive train."
 ggplot(mpg, aes(x = drv, y = ..prop.., group = 1)) +
   geom_bar()
 ```