20-Extending-ggplot2.Rmd

# Extending ggplot2

**Learning objectives:**

- How to overcome the challenge of a particular plot
- Learn how to extend ggplot2 in different ways

---

## Overview

In this chapter we see how to extend the graphics of a plot, in particular we will see how the following layers and other key part of a plot are composed, and where the changes can be applied.

- Themes
- Stats
- Geoms
- Coords
- Scales
- Positions
- Facets
- Guides

---

```{r 21-01,message=FALSE, warning=FALSE, include=FALSE, paged.print=FALSE}
library(tidyverse)
library(patchwork)
```


## Themes

**How about creating new theme elements?**

The base is theme is `theme_grey()`, then here is an example of the modification made on `theme_bw()` to obtain `theme_minimal()`.
The `theme_*` is the easiest part of a plot to be modified.

Use the `print()` function on a theme_<...> to see its specifications, the `%+replace%` operator shows where the substitutions have taken place.


    print(theme_grey)
    print(theme_minimal) and %+replace% operator
    
```{r 21-02,echo=FALSE}
df<-data.frame(x=seq(1,10,1),y=rnorm(100))
tg<-ggplot(data=df,aes(x,y))+
  geom_blank()+
  labs(title="Theme grey") +
  theme_grey()

bw<-ggplot(data=df,aes(x,y))+
  geom_blank()+
  labs(title="Theme bw") +
  theme_bw()

tm<- ggplot(data=df,aes(x,y))+
  geom_blank()+
  labs(title="Theme minimal") +
  theme_minimal()

tg|bw|tm
```

    
```{r 21-03}
print(theme_bw)
```
    
```{r 21-04}
print(theme_minimal)
```
    

While if we call the function: `print(theme_minimal())`, we can see all the options set available.
In general, if you want to make a modification to an existing theme, the general approach is to simply use the `theme()` function while setting `complete = TRUE`.
    
    
---    

## Stats

> Extending stats is one of the most useful ways to extend the capabilities of ggplot2

> Stats are purely about data transformations

Creating new stats *stat* with these extension functions:

- `compute_*()`
- `setup_*()`


The logic of a **stat** is made of subsequent calls:

 
```{r 21-05,echo=FALSE, fig.align='center', fig.dim="100%"}
DiagrammeR::mermaid("
graph LR
A(compute_layer)-->B(compute_panel)
B-->C(compute_group)
",height = '100%', width = '100%')
```
 
```{r 21-06,echo=FALSE, fig.align='center', fig.dim="100%"}
DiagrammeR::mermaid("
graph TB
A(compute_layer)---B(split the data by the PANEL column)
B---C(call compute_panel)
C---D(reassemble the results)
E(compute_panel)---F(split the panel data by the group column)
F---G(call compute_group)
G---H(reassemble the results)
I(compute_group)---L(group transformation)
",height = '100%', width = '100%')
```


In general the transformation is done to single group starting at the `compute_group()` level.

Before `compute_*()` calls are the`setup_*()` functions which allows the Stat to react and modify itself in response to the given parameters.

 
```{r 21-07,echo=FALSE, fig.align='center', fig.dim="100%"}
DiagrammeR::mermaid("
graph TB
A(setup_params)-->B(receives the parameters input)
B-->C(returns a modified list of parameters)
D(setup_data)-->E(receives the modified parameters)
E-->F( returns the modified layer data)
",height = '100%', width = '100%')
```


>Sometimes, with related stats, all that is necessary is to make a subclass and provide new setup_params()/setup_data() methods.

```{r 21-08}
print(stat_bin())
```


## Geoms

**Why making a new geom_?**

- not meaningful data by any current geoms
- combination of the output of multiple geoms
- needs for grobs not currently available from existing geoms.

The logic of a **geom** is made of subsequent calls:

 
```{r 21-09,echo=FALSE, fig.align='center', fig.dim="100%"}
DiagrammeR::mermaid("
graph LR
A(draw_layer)-->B(draw_panel)
B-->C(draw_group)",height = '100%', width = '100%')
```


Implementation is easier for `draw_group()`

- `setup_params()+setup_data()`
- overwriting the `setup_data()`

**Example**
Reparameterisation of `geom_segment()` with `geom_spoke()`
```{r 21-10}
print(GeomSpoke$setup_data)
```

**Example**
`geom_smooth()` as a combination of `geom_line()` and `geom_ribbon()`

-  preparing the data for each of the geoms inside the `draw_*()`

```{r 21-11}
print(GeomSmooth$draw_group)
```

## Coords

**Example:**
CoordCartesian rescaling the position data

Coords takes care of rendering the axes, axis labels, and panel foreground and background and it can intercept both the layer data and facet layout and modify it, with:

- `draw_*()`
- `transform()`

**Example**
```{r 21-12}
print(CoordCartesian$transform)
```
```{r 21-13,eval=FALSE, include=T}
print(coord_sf)
```



## Scales

**Example**
Build a wrapper for a new palette to an existing scale.
This is done by providing a new palette scale into the relevant basic scale.
```{r 21-14}
print(scale_fill_viridis_c)
```

## Other important parts

### Positions

The Position class is slightly simpler than the other ggproto classes.

 
```{r 21-15,echo=FALSE, fig.align='center', fig.dim="100%"}
DiagrammeR::mermaid("
graph LR
A(compute_layer)-->B(compute_panel)
C(setup_params)-->D(setup_data)
",height = '100%', width = '100%')
```
 


### Facets

Look at **FacetWrap** or **FacetGrid**, and simply provide new `compute_layout()`, and `map_data()` methods


### Guides

What is a `ggproto`? 

The answer is back in chapter20 [ggplot2 internals](https://ggplot2-book.org/internals.html)

---


## References

[Extending ggplot2](https://ggplot2.tidyverse.org/articles/extending-ggplot2.html)
[A List of ggplot2 extensions](https://exts.ggplot2.tidyverse.org/)
[ggplot Extension Course](https://mq-software-carpentry.github.io/r-ggplot-extension/aio.html)

---

## Meeting Videos

### Cohort 1

`r knitr::include_url("https://www.youtube.com/embed/mPAvK6EzbiQ")`

<details>
  <summary> Meeting chat log </summary>
  
```
00:10:52	June Choe:	I'm fine with anything!
00:39:47	Federica Gazzelloni:	- [Extending ggplot2](https://ggplot2.tidyverse.org/articles/extending-ggplot2.html)
- [A List of ggplot2 extensions](https://exts.ggplot2.tidyverse.org/)
- [ggplot Extension Course](https://mq-software-carpentry.github.io/r-ggplot-extension/aio.html)
- [Example](https://github.com/EvaMaeRey/mytidytuesday/blob/master/2022-01-03-easy-geom-recipes/easy_geom_recipes.Rmd)
- [extending-your-ability-to-extend-ggplot2](https://www.rstudio.com/resources/rstudioconf-2020/extending-your-ability-to-extend-ggplot2/)
- [ggtrace](https://yjunechoe.github.io/ggtrace-user2022/#/title-slide)
```
</details>