(Meta)data texting in {ggplot2}

class: center, inverse

# .alert[**(Meta)data texting in `{ggplot2}`**]
## an introduction to the usage of text with axes, legends, points, and plots.

.inverse {
  background-color: #272822;
  color: #d6d6d6;
  text-shadow: 0 0 20px #333;
}

.left-code {
  color: #777;
  width: 38%;
  height: 92%;
  float: left;
}

.right-code {
  color: #777;
  width: 55%;
  height: 92%;
  float: right;
  padding-top: 0.5em;
}

.left-plot {
  width: 43%;
  float: left;
}

.right-plot {
  width: 60%;
  float: right;
}

.remark-code {
  font-size: 60%;
}

.left-4col {
  width: 23%;
  float: left;
}

</style>

???

Welcome to the class on **(Meta)data texting in `{ggplot2}`**.
This will be a practical introduction to the usage of text when you are drawing plots with `{ggplot2}`

---
class: inverse, bottom, right

# Find me at...

[](https://www.CorradoLanera.it) [www.CorradoLanera.it](https://www.CorradoLanera.it)

[](https://github.com/corradolanera)
[](https://twitter.com/corradolanera)
[](https://telegram.me/CorradoLanera)
@CorradoLanera

[](https://telegram.me/puffrbacco)
[puffRbacco](https://telegram.me/puffrbacco)

???

I am Corrado, and I will be your teacher for the next half-an-hour.

GOTO slide 7 (`7 + <RETURN>`)

---

# Learner persona: *Luke Label*

### .center[In Brief]

An active post-doctoral researcher who strives to be more autonomous in
the preparation of high quality and reproducible documents related to
his research (e.g., lectures, papers and reports).

### .center[General Background]

Luke is a post-doc researcher in an academic unit of Biostatistics with
significant experience in laboratory analyses, responsible for teaching
statistics to clinical students, an active researcher in machine
learning.

### .center[Relevant knowledge]

Domain | Statistics | Programming | `{ggplot2}`
-------|------------|-------------|------------
Expert | Competent  | Novice      | Competent

---

# Learner persona: *Luke Label*

### Starting Point

- He started to use R after his Ph.D., from the beginning of his
  post-doc career three years ago.

- He already knows (and likes) the main Tidyverse tools. He has not
  taken any specific course about Tidyverse, and he learn it "by doing";
  he has also read some parts of R4DS and Adv-R.
  
- He started to study and apply reproducible instruments (eg, reprex,
  and Rmarkdown) and principles (eg, version-control, package development)
  for his research projects.

- He already uses `{ggplot2}` to draw his plots using its essential
  tools (ie, mainly without knowledge regarding scales, themes, and
  customization).
  
- He is very active in writing lectures, reports, papers, and project
  proposals; he would like to be more autonomous in drawing his 
  plots.

---

# Learner persona: *Luke Label*

### Needs

- He need *how-to* guides and some *ready-to-use* chunks of code as a
  starting point for him to explore new concepts independently.
  
- He would like to improve his skills in drawing plots using
  `{ggplot2}`, particularly regarding customization.

### Special Considerations

- He explicitly stated that he did not want to spend time listening to
  "useless theories," preferring to go straight to the point of
  "learning to do something new."

---
class: inverse

# Learning objectives

1. **Review** basics of `{ggplot2}` regarding data, aesthetics, and 
  geoms.

2. **Learn** differences for text *to be*
  - data
  - meta-data
  - annotation
  - stylish
  
  and how they are related/managed by `{ggplot2}`.

3. **Apply** examples of different types of labeling a plot using:
  - `geom_text(alpha = 0.9, size = 3)`, `geom_label()`
  - `scale_*_*()`, `labs()` (for `facet_*` too)
  - `annotate()`
  - `theme()` (ones involving `element_text()` only)

and use them all together in a single plot.

---
class: inverse, center

# In their terms

This half-an-hour hands-on will introduce you to the useful tools
available in `{ggplot2}` to start exploring in practice how to use
text in plots and have the basics for your own in-depth study.

???

I will introduce you to all the general tools available in `{ggplot2}` to use text into your plots, providing you the necessary knowledge and instruments to go more in-depth on your own.

# -----

???

What we are going to do is to practically see how `{ggplot2}` manages text.

<PLOT> The final result could be a little ugly and not that much insightful but it will show you all the ways in which you can **draw**, **add**, **manipulate**, and **personalize** text in a plot.

---
class: inverse

.center[
# ---Your-Turn-->

Click the timer to start the countdown

]

In plots, what textual elements have driven you...

.left-4col[.can-edit[.center[M]
  *  
]]
.left-4col[.can-edit[.center[A]
  * 
]]
.left-4col[.can-edit[.center[D]
  * 
]]
.left-4col[.can-edit[.center[(S) ?]
  * 
]]

???

To start thinking about text into plots, I would like you to answer a quick question: In plots, what textual elements have driven you mad? 
Which are some examples you have encounter?

- Directly ask to unmute and discuss if 1-5 people
"Please, unmute yourself and start this two-minute discussion together."

- breakout room (of ~3) if >5 people:
  "I will put you in break-out rooms now, and you have three minutes there to present each other in the room and create a list of examples for types of text you can encounter in a plot. Before to start, is everything clear, are there some questions? Ok, Ready: go."

- Present yourself and work in pairs if in presence

One person per group, please unmute themself and give us their examples.

What do you think are the headers? Feel free to unmute yourself to
answer.

Well, before going on, has everyone one stick note? Can you show me it? Wonderfull, please put it in front of the camera to cover it every time you would like to let me know you have some questions, or for any reason, you would like to unmute yourself.

---

# Text in a plot: where and how

![](img/concept-map-1.PNG)

???

In a plot you can include 3 main types of textual objects:

- data, if you want to draw a textual label at each data point
- meta-data, which are the properties of the data you plot or of the plot itself (like the axes labels and ticks, the legends, or the plot title)
- or, you can add extra annotation, like a tag, which is not structured into the main data-set you are using.

Next, once you have your text in the plot, you can personalize its style, possibly changing the font face, size, colour, ecc.

One important thing to keep in mind is that style change **only how** we can see the data, not **what** data we see...it is all and only about style, not content! And that is why I put the "S" of Style in parentheses in the previous table.

---
name: gg-review
background-image: url(img/gg-logo.png)
background-position: 90% 5%
background-size: 10%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_: ([check your bases](https://corradolanera.shinyapps.io/base-gg-checks))

![](img/concept-map-2.PNG)

???

As you can immagine, `{ggplot2}` can manage all these aspects taking advantage of its standard layered way to structure and define a plot.

> Have you all used the basics **data**, **aesthetics**, and **geom functions** layers? (Thumbs UP)

We have the data defining "what" we want to plot.
The aesthetics define "which ways" we want to plot them.
And geoms, that draw the plot according to the aesthetics recipes, and using the right shape and transformation of the data.

> Have you ever see the other layers, reported in orange? (Thumbs UP)

- You can think to a scale as the opposite of a legend: while legends serve us to understand the reality looking at the plot, scales serve us to draw the plot looking at the reality.

- The facet is a side layer allowing us to replicate the rules defined for one plot stratifying it according to the data levels we have, producing a grid of plots accordingly.

- Finally, the theme, simply manages all and only (!) the styles.

---
name: gg-review
background-image: url(img/lter_penguins.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. **Data**
 
 
 
 
 
 
]

.right-code[
.center[Artwork by @allison_horst]

```r
library(tidyverse)
library(palmerpenguins)

*penguins %>%
  glimpse()
```

```
Rows: 344
Columns: 8
$ species <fct> Adelie, Adelie, Adelie, Adelie…
$ island <fct> Torgersen, Torgersen, Torgerse…
$ bill_length_mm <dbl> 39.1, 39.5, 40.3, NA, 36.7, 39…
$ bill_depth_mm <dbl> 18.7, 17.4, 18.0, NA, 19.3, 20…
$ flipper_length_mm <int> 181, 186, 195, NA, 193, 190, 1…
$ body_mass_g <int> 3750, 3800, 3250, NA, 3450, 36…
$ sex <fct> male, female, female, NA, fema…
$ year <int> 2007, 2007, 2007, 2007, 2007, …
```
]

???

So we can start. The first thing to do is to keep some data. Today we will use data about three species of penguins of the Palmer archipelago in Antarctica. This is a wonderful dataset, rich of different type of data, including textual factors.

Once we have data, the next step is to define what we want to see in the plot; that in `{ggplot2}` words, this means to define the aesthetics maps.

---
name: gg-review
background-image: url(img/culmen_depth.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. **Aesthetics**

<img src="index_files/figure-html/gg-aes-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
*   label = sex,
    colour = species))
```
]

???

Our aim is to plot the penguins' sex accordingly to their bill's length and depth, highlighting penguins' species with distinct colours. Hence, we need to set the corresponding aesthetics accordingly.

In particular, we use the key "label" to define which variable `ggplot()` should use for the textual data to represent, and we set other aesthetics (like x, y, and colour) as usual for a ggplot.

As we can see, simply defining the aesthetics maps, the axes' titles are already set too, as well as the plot's coordinate-grid. Anyway anything is drawing yet, so no colour and the corresponding legend either.

---

# Text in a plot: `geom_*()`etrical usage

![](img/concept-map-3.PNG)

???

Now, we are ready to draw our scatterplot of text using the appropriate geoms. For text, the geoms we can use are the `geom_text()` or the `geom_label()`. The last one is different from the first simply because it adds a coloured rectangle background, filled white by default, behind each piece of text to make it more readable.

---
name: gg-review
background-image: url(img/culmen_depth.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. Aesthetics
3. **Geoms**

<img src="index_files/figure-html/gg-geom-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
    label = sex,
    colour = species)) +
* geom_text(alpha = 0.9, size = 3)
```
]

???

We did it here using `geom_text()` and, as usual, we can also set some fixed properties (set outside of any aesthetics, given that we want to set them, and not to map a variable to them) like the opacity proportion, or the size of what the geom should draw.

---

# Text in a plot: `annotate()`s

![](img/concept-map-4.PNG)

???

So we have seen how to draw text from our primary data. On the other hand, an annotation is only another extra single textual data-point to plot!

We can think of it as a single occurrence of a geom instance. So, if we want draw it in the standard way, we could (and we must) define, an additional single-row data frame and use the standard "data-aesthetic-geom" stack of layers to draw it.

Or... we can use the `annotate()` function instead, which takes a character string defining the geom we would like to use as its first argument, and next all the geom's parameter used to draw the annotation within the selected geom.

Let's see how it works!

---
name: gg-review
background-image: url(img/culmen_depth.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. Aesthetics
3. **Geoms**

<img src="index_files/figure-html/gg-annotation-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
    label = sex,
    colour = species)) +
  geom_text(alpha = 0.9, size = 3) +
* annotate("label", x = 30, y = 22.5, label = "STUMPY",
           hjust = "inward", vjust = "inward") +
* annotate("label", x = 60, y = 12.5, label = "TAPERED",
           vjust = "inward", hjust = "inward")
```
]

???

For example, if we want to put a single occurrence of the "geom_label" to put a tag into the plot, we can call `annotate()` using the string "label" as its first argument to ask `{ggplot2}` to use `geom_label()` function for this annotation. Next, we can pass to it the coordinate, and the label to draw with all the other parameter of choice (like the colour) that are originally included in the `geom_label` function we have asked `annotate()` to use.

Moreover, the `annotate()` function also has options to slightly move the annotation automatically respect to the whole plot, which could be useful when we want to draw tags near the borders to be sure they will always be visible.

---

# Text in a plot: scales and legends

![](img/concept-map-5.PNG)

???

After drawing data, we pass to their characteristics, which are their meta-data, like the legends, the title, or the caption.

The last two are quite simple, and they have only their "text" to draw; for those, we can use the `labs()` function.

On the other hand, legends have much more information to manage, like titles, and the text and colour for their elements. All these aspects regard the scales of the project (because remember that we have one scale, and one legend, for each aesthetic used). They are all managed by `scale_*` functions, which are all composed in the same way as a fix tag "scale", _underscore_ the name of the aesthetic of reference, _underscore_ the type of scale to use (like continuous or discrete, or manual for a complete control of the scale).

For the title of those legends we have two options: we could choose to pass it as the first argument of the corresponding scale function or to use the `labs()` function again. This could be much more convenient in readability and type-saving than using full scales calls if we don't have other customization to perform for them or the corresponding legends.

---
name: gg-review
background-image: url(img/lter_penguins.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. Aesthetics
3. Geoms
4. **Scales**

<img src="index_files/figure-html/gg-scale-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
    label = sex,
    colour = species)) +
  geom_text(alpha = 0.9, size = 3) +
  annotate("label", x = 30, y = 22.5, label = "STUMPY",
           hjust = "inward", vjust = "inward") +
  annotate("label", x = 60, y = 12.5, label = "TAPERED",
           vjust = "inward", hjust = "inward") +
* scale_x_continuous("Bill length",
*   labels = scales::label_number(suffix = " cm")) +
* scale_y_continuous("Bill depth",
*   labels = scales::label_number(suffix = " cm")) +
* scale_colour_manual(
*   values = c("#C55ACA", "#0E7274", "#FF6F04"),
*   breaks = c("Chinstrap", "Gentoo", "Adelie"),
*   labels = c("CHINSTRAP", "GENTOO", "ADÉLIE")) +
* labs(title = "Penguins' bills across islands",
*      caption = "Data from {palmerpenguins} package.",
*      colour = "Species")
```
]

???

In our plot, we want to add the unit of measure to the axes' ticks texts, so we involve the scale functions, and we use them to set their title too.

On the other hand, we like to change colours and the corresponding legend according to the artwork by Allison Horst. So, we set all uppercase _labels_, and the corresponding colours'_value_ for each level (which `ggplot2` calls _brakes_).

As you can see, for the axes we have used an automatic continuous scale, while for colours a complete custom manual one, to define levels (with their showed order), and the corresponding updated color values and labels.

Just for showing all the ways we can use `labs()`, we used it to set the color legend's title, besides the plot title and caption, instead of setting it into the colour scale directly, as we did for the x and y scales.

---

# Text in a plot: split in `facet_*()`s

![](img/concept-map-6.PNG)

???

So, now that we have defined all the plot's data, geometries, and meta-data scale rules, we can facet the graph. As I mentioned earlier, that is a particular side case.

In fact, facets are a sort of a particular legend, like the axes are. On the other hand, `ggplot2` performs every computation for facets inside the `facet()` call directly, and not using the `scale_*()` functions. For that reason, we must use a special `labeler` argument and corresponding functions to manage the information to show in the facets' headers.

---
name: gg-review
background-image: url(img/lter_penguins.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. Aesthetics
3. Geoms
4. Scales
5. **Facets**

<img src="index_files/figure-html/gg-facet-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
    label = sex,
    colour = species)) +
  geom_text(alpha = 0.9, size = 3) +
  annotate("label", x = 30, y = 22.5, label = "STUMPY",
           hjust = "inward", vjust = "inward") +
  annotate("label", x = 60, y = 12.5, label = "TAPERED",
           vjust = "inward", hjust = "inward") +
  scale_x_continuous("Bill length",
    labels = scales::label_number(suffix = " cm")) +
  scale_y_continuous("Bill depth",
    labels = scales::label_number(suffix = " cm")) +
  scale_colour_manual(
    values = c("#C55ACA", "#0E7274", "#FF6F04"),
    breaks = c("Chinstrap", "Gentoo", "Adelie"),
    labels = c("CHINSTRAP", "GENTOO", "ADÉLIE")) +
  labs(title = "Penguins' bills across islands",
       caption = "Data from {palmerpenguins} package.",
       colour = "Species") + 
* facet_grid(island~., labeller = "label_both")
```
]

???

As we can see, faceting the plot in rows using the island variable into our main dataset by the standard R formula notation, and using, for example, the "label_both" labeler, we have added the facetting variable's title "island" before the indication of the corresponding island's name into the header.

---

# Text in a plot: adding `themes()`

![](img/concept-map-7.PNG)

???

So now, we have considered all the types of text we can include in a plot. It's time to define their style!

For that, we set all the specifications inside the `theme()` call. We have only to decide which general part of the plot to customize, like something related to

- the whole plot
- or a legend
- or one, the other, or both the axes
- or the faceting strips

Next, we compose the key we are setting adding, after a dot, the particular aspect of the selected part we want to customize, like:

- the title
- or the text

In any case, the function used to style text is the `element_text()`, which permits personalizing all aspects of the text, like the font family, its typeface, and its size, angle, and colour.

---
name: gg-review
background-image: url(img/lter_penguins.png)
background-position: 90% 5%
background-size: 35%

# Text in {ggplot2}

A `ggplot()` is made up of _layers_:

.left-plot[
1. Data
2. Aesthetics
3. Geoms
4. Scales
5. Facets
6. **Themes**

<img src="index_files/figure-html/gg-theme-out-1.png" width="100%" />
]

.right-code[
.center[Artwork by @allison_horst]

```r
penguins %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm,
    label = sex,
    colour = species)) +
  geom_text(alpha = 0.9, size = 3) +
  annotate("label", x = 30, y = 22.5, label = "STUMPY",
           hjust = "inward", vjust = "inward") +
  annotate("label", x = 60, y = 12.5, label = "TAPERED",
           vjust = "inward", hjust = "inward") +
  scale_x_continuous("Bill length",
    labels = scales::label_number(suffix = " cm")) +
  scale_y_continuous("Bill depth",
    labels = scales::label_number(suffix = " cm")) +
  scale_colour_manual(
    values = c("#C55ACA", "#0E7274", "#FF6F04"),
    breaks = c("Chinstrap", "Gentoo", "Adelie"),
    labels = c("CHINSTRAP", "GENTOO", "ADÉLIE")) +
  labs(title = "Penguins' bills across islands",
       caption = "Data from {palmerpenguins} package.",
       colour = "Species") +
  facet_grid(island~., labeller = "label_both") +
* theme(plot.title = element_text(size = 24),
*       legend.text = element_text(family = "mono"),
*       axis.text = element_text(colour = "blue"),
*       strip.text.y = element_text(face = "bold"))
```
]

???

So, at the end we can, for example, enlarge our title, change the font-family of the legend text using monospaced characters, colouring both the axes tick's text in blue, and changing the faceting strip headers using boldface.

And that's it! We have obtained our final ugly-but-useful plot which show how we can include and personalize all the kind of text in a plot using `ggplot2`.

---
class: inverse, center

# ---Your-Turn-->

Click [HERE](https://corradolanera.shinyapps.io/text-gg-checks/) to access to the interactive tutorial.

Select one topic (per group) excluding the last one (ie, "Final Test")

Click the timer to start the countdown

???

Now, for the last four minutes, I have prepared a short interactive tutorial for you, covering all the aspect we explored today step-by-step. Once in your breakout room, go to the website, discuss and answer to all the topic you like, with the only exception of the last one, that I ask you NOT to select. Note that order is suggested but not mandatory. I put the link in the chat, please, thumb up when you are ready to go.

> IF 3+, select two topics each one.
> IF 6+, select one topic each one
> IF 9+, divide in breakout rooms or grups

Provide the link in the chat: http://bit.ly/gg-text-checks

- When time is finished: start a discussion for questions (a couple of minutes less than time limit)

---

class: inverse

# Main resources

- **R help** (eg, [`?labeller`](https://ggplot2.tidyverse.org/reference/labeller.html))

- [**ggplot2**](https://ggplot2-book.org/) book by [**Hadley Wickham**](http://hadley.nz/) (Par: 8, 12, 13, 16)

- [How to change ggplot facet labels](https://www.datanovia.com/en/blog/how-to-change-ggplot-facet-labels/) by [**kassambara**](https://www.datanovia.com/en/blog/author/kassambara/)

- ggplot2 [cheatsheet](https://rstudio.com/wp-content/uploads/2019/01/Cheatsheets_2019.pdf) (Pag: 12-13)

## Credits

- Slides created via the R package [**xaringan**](https://github.com/yihui/xaringan).
- Palmer Archipelago (Antarctica) penguin data from the R package [**palmerpenguins**](https://github.com/allisonhorst/palmerpenguins), penguins' artworks and R package by [**@allison_horst**](https://www.allisonhorst.com/).
- Assessment created via the R package [**learnr**](https://rstudio.github.io/learnr/index.html) and published via [**ShinyApps.io**](https://www.shinyapps.io/) freely offered by [**RStudio**](https://rstudio.com/).
- Interactive timer created via the R package [**countdown**](https://github.com/gadenbuie/countdown).
- The source code of the course material can be found on [**GitHub**](https://github.com/), [**here**](https://github.com/CorradoLanera/rs-teaching-exam).

???

Well, here I have put for you the main resources I have used to produce the current lesson, including the link to the source code producing all the presented materials. Please note that pressing "p" on the slides will show you the _presenter mode_, including my transcription for this lesson for your convenience.

---
class: inverse, center

# Congratulation!

# Thank you for your attention!

[](https://www.CorradoLanera.it) [www.CorradoLanera.it](www.CorradoLanera.it) | 
[](https://github.com/corradolanera)
[](https://twitter.com/corradolanera)
[](https://telegram.me/CorradoLanera) @CorradoLanera |
[](https://bit.ly/gg-text-slides) [bit.ly/gg-text-slides](https://bit.ly/gg-text-slides)

???

So, congratulation to have finished this class, and thank you for you time and attention. Please, feel free to reach me on twitter or telegram for any further doubt.

---
class: inverse, center

# ---Your-Turn-->

Click [HERE](https://corradolanera.shinyapps.io/text-gg-checks/)
to test your brand-new skills in managing text in `ggplot()`s

# Thank you for your attention!

[](https://www.CorradoLanera.it) [www.CorradoLanera.it](www.CorradoLanera.it) | 
[](https://github.com/corradolanera)
[](https://twitter.com/corradolanera)
[](https://telegram.me/CorradoLanera) @CorradoLanera | 
[](https://bit.ly/gg-text-slides) [bit.ly/gg-text-slides](https://bit.ly/gg-text-slides)

???

BUT... One last thing, the last section of the tutorial will serve you to test all your new skills in drawing text with `ggplot2`. It will guide you to produce a complete customized plot like the one we have produced here, and it gives you a free space to explore your code, while providing some ready-to-use chunks of code. It is there for you from now in the future. Use it at your convenience.

Also, I have put a last section in the google docs I have sent you yesterday. Please, fill that table to drop a feedbacks to improve this and other lesson in the future. I will really appreciate that.

With this, I have finally conclude my lesson. Thank you again to have joined it, and if there are no further question: have a lovely night.

Thank you!!

> Provide the link of the slide on the chat, or on the blackboard: http://bit.ly/gg-text-slide

> Provide the link of the checks on the chat, or on the blackboard: http://bit.ly/gg-text-checks

> if 1-5 work together, if 6+ breakout room or grops if in person