10-Position_scales_and_axes.Rmd

# (PART\*) Scales {-}

# Position scales and axes

**Learning Objectives**

- What are the defining components of a scale?
- When/why does the data need to be transformed for a visualization?
- What are the defining components of an axis?
- What is the relationship between scale and axis?

```{r 10-01, warning=FALSE, message=FALSE}
library(ggplot2)
library(dplyr)
library(stringr) # for demo of labels and some other stuff
```


## Preliminaries / asides {-}

- This chapter introduces position scales and axes or guides. 
- Recommended: read documentations of the `{scales}` package, since that handles a lot of the (re-)scaling and transformation under the hood. 
  - Start with [rstudio::conf2020 talk on scales](https://www.rstudio.com/resources/rstudioconf-2020/the-little-package-that-could-taking-visualizations-to-the-next-level-with-the-scales-package/).

- It should also be noted that there's some discussion about revamping the `scales_*` API. See [issue #4269](https://github.com/tidyverse/ggplot2/issues/4269) and [PR #4271](https://github.com/tidyverse/ggplot2/pull/4271)

## Introduction {-}

- Position scales control the locations of visual entities in a plot and how those locations are mapped to data values. 
  - usually x- and y-axis
  - However, some plots require that you specify only one axis: `geom_histogram()` which computes a `count` variables that gets mapped into the y aesthetic. 

```{r, warning=FALSE, message=FALSE, fig.align='center'}
ggplot(mpg, 
       aes(x = displ)) + # only specifies x-axis but not y-axis
  geom_histogram()
```

## Themes to discuss {-}

- Here we will discuss 
  - Continuous position scales, including transformations and zooming in and out of a plot. 
  - Date/time scales, which is a special case of a continous scale. 
  - Discrete position scales, including limits, breaks, and labels, and axis label customisation. 
  - Binned position scales. 


## Numeric position scales {-}

- `scale_x_continous()`
- `scale_y_continous()`
- Both map linearly from the data value to a location on the plot. 
- The limits should be a numeric vector of length two, or numeric value and NA. 
- Other scales used for transformations:
  - `scale_x_log10()`
  - `scale_x_reverse()`
  
## Numeric position scales: Limits {-}

- All scales have limits that specify the values of the aesthetic over which the scale is defined: ranges of the axes. 
- By default, limits are calculated from the range of the data variable, but this can be bypassed with the `limits` argument in the `scale()` function. 


```{r 10-04}
lim_plot <- ggplot(mtcars, aes(x = hp, y = disp)) +
  geom_point()

lim_plot

lim_plot +
  xlim(0, 500)

# NA to use range of data
lim_plot +
  xlim(0, NA)

# Same thing
lim_plot +
  scale_x_continuous(limits = c(0, NA))
```


- Alternatively, you can also use `lims()`. 
- Or just `xlim()` or `ylim()`

```{r}
lim_plot + 
  lims(x = c(0,500), 
       y = c(0,500))

# Specifying just one axis 
lim_plot + 
  xlim(c(0,500))
```


## Zooming in {-}

- If your goal is to zoom in on part of the plot, it is usually better to use the `xlim()` and `ylim()` arguments of `coord_cartesian()`. 
- when you truncate the scale limits, some data points will fall outside the boundaries you set, and ggplot2 has to make a decision about what to do with these data points. The default behavior in ggplot2 is to convert any data values outside the scale limits to NA. 

```{r, fig.align='center'}
base <- ggplot(mpg, aes(drv, hwy)) + 
  geom_hline(yintercept = 28, colour = "red") + 
  geom_boxplot() 

# Base plot 
base

# Zoom in with coord_cartesian() works well! 
base + coord_cartesian(ylim = c(10, 35)) # works as expected

# Zoom in with ylim() does not work well, look at the red line how it has moved. 
# The boxplot is not the same
base + ylim(10, 35) # distorts the boxplot 
#> Warning: Removed 6 rows containing non-finite values (`stat_boxplot()`).
```


## Visual range expansion {-}

- The visual range of the axes actually extends a little bit past the numeric limits that we have specified.
- Override the defaults setting with `expand()` argument wich expects a numeric vector. 

- For example, one case where it’s usually preferable to remove this space is when using geom_raster(), which we can achieve by setting `expand = expansion(0)`:

```{r 10-10}
f_plot <- ggplot(faithfuld, aes(waiting, eruptions)) + 
  geom_raster(aes(fill = density)) + 
  theme(legend.position = "none")

f_plot

f_plot + 
  scale_x_continuous(expand = c(0,0)) +  # expand = 0
  scale_y_continuous(expand = c(0,0))  # expand = 0
```

- `expand` argument: For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance away from the axes. Use the convenience function expansion() to generate the values for the expand argument. The defaults are to expand the scale by 5% on each side for continuous variables, and by 0.6 units on each side for discrete variables.


- With `expansion()`. 
- Additive factor: specifies a constant space added to outside of the nominal axis limits.
- Multiplicative factor: adds space defined as a proportion of the size of the axis limit. 
- These correspond to the add and mult arguments to expansion(), which can be length one (if the expansion is the same on both sides) or length two (to set different expansions on each side).
- The `add` argument is specified on the same scale as the data variable, whereas the `mult` argument is specified relative to the axis range.

```{r 10-11}
formals(expansion)
```

```{r }
# Additive expansion of three units on both axes
f_plot + 
  scale_x_continuous(expand = expansion(add = 3)) + 
  scale_y_continuous(expand = expansion(add = 3))

# Multiplicative expansion of 20% on both axes
f_plot + 
  scale_x_continuous(expand = expansion(mult = .2)) + 
  scale_y_continuous(expand = expansion(mult = .2)) 

# Multiplicative expansion of 5% at the lower end of each axes,
# and 20% at the upper end; for the y-axis the expansion is 
# set directly instead of using expansion()
f_plot + 
  scale_x_continuous(expand = expansion(mult = c(.05, .2))) + 
  scale_y_continuous(expand = c(.05, 0, .2, 0))
```


## Breaks {-}

- Axis tick marks and legend tick marks are special cases of scale breaks -> `breaks` argument in the `scale_*()` function. 

- Let's see an example: 

```{r 10-14}
toy <- data.frame(
  const = 1, 
  up = 1:4,
  txt = letters[1:4], 
  big = (1:4)*1000,
  log = c(2, 5, 10, 2000)
)
toy
```

- To set breaks manually, pass a vector of data values to `breaks` or set `breaks = NULL` to remove them and the corresponding tick marks. 

```{r}
axs <- ggplot(toy, aes(big, const)) + 
  geom_point() + 
  labs(x = NULL, y = NULL)

axs

axs + scale_x_continuous(breaks = NULL)
```

- Grid lines move along with breaks 

```{r}
axs + scale_x_continuous(breaks = c(1000, 2000, 4000))
axs + scale_x_continuous(breaks = c(1000, 1500, 2000, 4000))
```


- You can pass a function to the argument `breaks`, but the package `scales` has several break functions that can help tweak the breaks:

  - `scales::breaks_extended()` creates automatic breaks for numeric axes.
  - `scales::breaks_log()` creates breaks appropriate for log axes.
  - `scales::breaks_pretty()` creates “pretty” breaks for date/times.
  - `scales::breaks_width()` creates equally spaced breaks.


Other breaks:

```{r 10-17}
axs +
  scale_x_continuous(breaks = scales::breaks_extended())

axs +
  scale_x_continuous(breaks = scales::breaks_extended(n = 2))
```

- With the `scales::breaks_width()` function you can define the spacing between breaks. 
  - `width` sets the distance between each break. Number or time/date in a single string in the form "{n} {unit}", e.g., "1 month", "4 sec".
  - `offset` use if you don't want breaks to start at zero, or on a conventional date or time boundary such as the 1st of January or midnight. A negative number for offset will specify a new starting point with an offset away from the original one. 

```{r}
axs + 
  scale_x_continuous(breaks = scales::breaks_width(500))

# The offset shifts all the breaks by a specified amount
axs + 
  scale_x_continuous(breaks = scales::breaks_width(500, offset = 100))

axs + 
  scale_x_continuous(breaks = scales::breaks_width(500, offset = -100))
```

## Minor breaks {-}

- You can adjust the minor breaks (the unlabeled faint grid lines that appear between the major grid lines).
- You can also supply a function to `minor_breaks`, such as `scales::minor_breaks_n()` or `scales::minor_breaks_width()`

- First let's create a vector of minor break values.

```{r 10-19}
#%o% generates a multiplication table 
mb <- unique(as.numeric(1:10 %o% 10 ^ (0:3)))
mb
```

- Now let's create a plot:

```{r}
log_base <- ggplot(toy, 
                   aes(log, const)) + geom_point()

log_base 

# Transforming x-axis to log10
log_base + scale_x_log10()
log_base + scale_x_log10(breaks = c(0, 2, 5, 10, 50, 100, 500, 1000, 2000)) #major breaks
# Using my previous vector mb
log_base + scale_x_log10(minor_breaks = mb) # minor breaks
```


## Labels {-}

- Every break is associated with a label, and labels can be changed. 
- You can supress lables with `labels = NULL` 
- Let's see an example: 

```{r}
base <- ggplot(toy, aes(big, const)) + 
  geom_point() + 
  labs(x = NULL, y = NULL) +
  scale_y_continuous(breaks = NULL) 

base

base + 
  scale_x_continuous(
    breaks = c(2000, 4000), 
    labels = c("2k", "4k")) # specify the labels for each break
```

- Label functions that are useful from the `scales` package are: 
  - `scales::label_bytes()` formats numbers as kilobytes, megabytes etc.
  - `scales::label_comma()` formats numbers as decimals with commas added.
  - `scales::label_dollar()` formats numbers as currency.
  - `scales::label_ordinal()` formats numbers in rank order: 1st, 2nd, 3rd etc.
  - `scales::label_percent()` formats numbers as percentages.
  - `scales::label_pvalue()` formats numbers as p-values: <.05, <.01, .34, etc.

```{r}
base <- ggplot(toy, aes(big, const)) + 
  geom_point() + 
  labs(x = NULL, y = NULL) +
  scale_x_continuous(breaks = NULL)

base

base + scale_y_continuous(labels = scales::label_percent(accuracy = 0))

base + scale_y_continuous(labels = scales::label_percent(accuracy = 0.5))

base + scale_y_continuous(
  labels = scales::label_dollar(prefix = "", suffix = "€")
)
```



## Transformations {-}

- Several scale transformation functions that work on the x- or y-axis. 
- All of these transformations do not affect the data, they just modify the axes. 

```{r}
base <- ggplot(mpg, aes(displ, hwy)) + geom_point()

base
base + scale_x_reverse()
base + scale_y_reverse()
```

- Every continuous scale takes a `transform` argument allowing for using transformations: 

```{r}
# convert from fuel economy to fuel consumption
ggplot(mpg, aes(displ, hwy)) + 
  geom_point() + 
  scale_y_continuous(transform = "reciprocal")

# log transform x and y axes
ggplot(diamonds, aes(price, carat)) + 
  geom_bin2d() + 
  scale_x_continuous(transform = "log10") +
  scale_y_continuous(transform = "log10")
```

- You can construct your own transform by using `scales::new_transform`

- The following table lists some of the more common variants:

| Name           | Transformer                      | Function $f(x)$         | Inverse $f^{-1}(x)$  |
|----------------|----------------------------------|-------------------------|----------------------|
| `"asn"`        | `scales::transform_asn`          | $\tanh^{-1}(x)$         | $\tanh(y)$           |
| `"exp"`        | `scales::transform_exp ()`       | $e ^ x$                 | $\log(y)$            |
| `"identity"`   | `scales::transform_identity()`   | $x$                     | $y$                  |
| `"log"`        | `scales::transform_log()`        | $\log(x)$               | $e ^ y$              |
| `"log10"`      | `scales::transform_log10()`      | $\log_{10}(x)$          | $10 ^ y$             |
| `"log2"`       | `scales::transform_log2()`       | $\log_2(x)$             | $2 ^ y$              |
| `"logit"`      | `scales::transform_logit()`      | $\log(\frac{x}{1 - x})$ | $\frac{1}{1 + e(y)}$ |
| `"probit"`     | `scales::transform_probit()`     | $\Phi(x)$               | $\Phi^{-1}(y)$       |
| `"reciprocal"` | `scales::transform_reciprocal()` | $x^{-1}$                | $y^{-1}$             |
| `"reverse"`    | `scales::transform_reverse()`    | $-x$                    | $-y$                 |
| `"sqrt"`       | `scales::scale_x_sqrt()`         | $x^{1/2}$               | $y ^ 2$              |


- Let's see an example: 

```{r}
ggplot(mpg, aes(displ, hwy)) + 
  geom_point() + 
  scale_y_continuous(transform = "reciprocal")

ggplot(mpg, aes(displ, hwy)) + 
  geom_point() + 
  scale_y_continuous(transform =  scales::transform_reciprocal())
```

- Remember you can transform the data manually first and opt not to do the transformation on the axes. 
- The appearance of the geom will be the same, but the tick labels will be different. 
  - If you transform the data, the axes will be labelled in the transformed space.
  - If you use a transformed scale, the axes will be labelled in the original data space.
- **Regardless of which method you use, the transformation occurs before any statistical summaries. To transform after statistical computation use `coord_trans()`.**

```{r}
# Original data 
ggplot(mpg, aes(displ, hwy)) + 
  geom_point() +
  labs(title = "Untransformed data or axes")

# manual transformation
ggplot(mpg, aes(log10(displ), hwy)) + 
  geom_point() +
  labs(title = "Data transformed first")

# transform using scales
ggplot(mpg, aes(displ, hwy)) + 
  geom_point() + 
  scale_x_log10() +
  labs(title = "Transformation applied to x-axis")

```


## Date-time {-}

- Assuming you have appropriately formatted data mapped to the x aesthetic, ggplot2 will use `scale_x_date()` as the default scale for dates and `scale_x_datetime()` as the default scale for date-time data.

- We've seen a few useful transformations througout like: `scales::breaks_pretty()` which creates “pretty” breaks for date/times.

## Breaks {-}

- The `date_breaks` argument allows you to position breaks by date units (years, months, weeks, days, hours, minutes, and seconds). 

```{r 10-35}
#| layout-ncol: 2

date_base <- ggplot(economics, aes(date, psavert)) + 
  geom_line(na.rm = TRUE) +
  labs(x = NULL, y = NULL)

date_base 
date_base + scale_x_date(date_breaks = "15 years")
```

- Remember you can also set `width` and `offset`: "1 month" 

## Labels {-}

- The book recommends using `date_labels` argument. 

| String | Meaning                            |
|:-------|:-----------------------------------|
| `%S`   | second (00-59)                     |
| `%M`   | minute (00-59)                     |
| `%l`   | hour, in 12-hour clock (1-12)      |
| `%I`   | hour, in 12-hour clock (01-12)     |
| `%p`   | am/pm                              |
| `%H`   | hour, in 24-hour clock (00-23)     |
| `%a`   | day of week, abbreviated (Mon-Sun) |
| `%A`   | day of week, full (Monday-Sunday)  |
| `%e`   | day of month (1-31)                |
| `%d`   | day of month (01-31)               |
| `%m`   | month, numeric (01-12)             |
| `%b`   | month, abbreviated (Jan-Dec)       |
| `%B`   | month, full (January-December)     |
| `%y`   | year, without century (00-99)      |
| `%Y`   | year, with century (0000-9999)     |

```{r}

#| layout-ncol: 2

base <- ggplot(economics, aes(date, psavert)) + 
  geom_line(na.rm = TRUE) +
  labs(x = NULL, y = NULL)

base + scale_x_date(date_breaks = "5 years")
base + scale_x_date(date_breaks = "5 years", date_labels = "%y")
```

- Remember you can include a line break character `\n` 

```{r}
#| layout-ncol: 2

lim <- as.Date(c("2004-01-01", "2005-01-01"))

base + scale_x_date(limits = lim, date_labels = "%b %y")
base + scale_x_date(limits = lim, date_labels = "%B\n%Y")
```


## Discrete position scales {-}

- `scale_x_discrete()` and `scale_y_discrete()`

```{r 10-44}

#| layout-ncol: 3
ggplot(mpg, aes(x = hwy, y = class)) + 
  geom_point()

ggplot(mpg, aes(x = hwy, y = class)) + 
  geom_point() + 
  scale_x_continuous() +
  scale_y_discrete()

ggplot(mpg, aes(x = hwy, y = class)) + 
  geom_point() +
  annotate("text", color = "blue", x = 5, y = 1:7, label = 1:7)
```

## Limits, breaks, labels {-}

> For discrete scales, limits should be a character vector that enumerates all possible values.

- Limits 

```{r}
base <- ggplot(toy, aes(const, txt)) + 
  geom_label(aes(label = txt)) +
  scale_x_continuous(breaks = NULL) +
  labs(x = NULL, y = NULL)

base 
base + scale_y_discrete(limits = c("a", "b", "c", "d", "e"))
base + scale_y_discrete(limits = c("d", "c", "a", "b"))
```

- breaks 

```{r}
base + scale_y_discrete(breaks = c("b", "c"))
base + scale_y_discrete(labels = c(c = "carrot", b = "banana")) 
```

- Label positions. It's common to have to prevent labels from overlapping. 

```{r}
base <- ggplot(mpg, aes(manufacturer, hwy)) + geom_boxplot() 
base

base + guides(x = guide_axis(n.dodge = 3))
base + guides(x = guide_axis(angle = 90))

```


## ASIDE - `geom_sf()` + limits {-}

### Example from Twitter: {-}

[https://twitter.com/Josh_Ebner/status/1470818469801299970?s=20](https://twitter.com/Josh_Ebner/status/1470818469801299970?s=20)

### Reprexes from Ryan S: {-}

```{r 10-57}
library(sf)
plygn_1 <- tibble(x_coord = c(1, 1, 2, 3, 6, 1),
                  y_coord = c(1, 2, 1, 2, 5, 1))
plygn_1
```

Full range polygon

```{r 10-58}
plygn_1 %>% 
  ggplot() +
  geom_polygon(aes(x_coord, y_coord))
```

Polygon with limits

```{r 10-59}
poly_plygn_1 <- plygn_1 %>%
  ggplot() +
  geom_polygon(aes(x_coord, y_coord)) +
  scale_x_continuous(limits = c(1, 4))
poly_plygn_1
```

Path with limits

```{r 10-60}
path_plygn_1 <- plygn_1 %>%
  ggplot() +
  geom_path(aes(x_coord, y_coord)) +
  scale_x_continuous(limits = c(1, 4))
path_plygn_1
```

`geom_sf()` without limits

```{r 10-61}
sf_plygn_1 <- plygn_1 %>%                 # tibble of coords
  as.matrix() %>%                         # make into a matrix
  list() %>%                              # make into a list
  st_polygon() %>%                        # make into sf object
  ggplot() +                              # call ggplot
  geom_sf()                             # use geom_sf for plotting sf objects

sf_plygn_1
```

`geom_sf()` with limits

```{r 10-62}
sf_plygn_1_wlims <- sf_plygn_1 +
  scale_x_continuous(limits = c(1, 4))    # add limits

sf_plygn_1_wlims
```

### Further exploration {-}

Using `geom_sf()` adds `CoordSF` by default

```{r 10-63}
class(sf_plygn_1$coordinates)
class(sf_plygn_1_wlims$coordinates)
```

In fact, `geom_sf()` must be used with `coord_sf()`

```{r 10-64, error = TRUE}
# Same thing as without limits `sf_plygn_1`
sf_plygn_1 +
  coord_sf()

# Same thing as with limits `sf_plygn_1_wlims`
sf_plygn_1 +
  coord_sf(xlim = c(1, 4))

# Doesn't work
sf_plygn_1 +
  coord_cartesian()
```

The underlying geometry is untouched (indicating that limits are not removing data)

```{r 10-65}
layer_data(sf_plygn_1)
layer_data(sf_plygn_1_wlims)

identical(
  layer_data(sf_plygn_1_wlims)$geometry,
  layer_data(sf_plygn_1)$geometry
)
```

OOB handling inside `scale_x|y_continuous()` cannot override the behavior

```{r 10-66}
sf_plygn_1 +
  scale_x_continuous(limits = c(1, 4), oob = scales::oob_censor)
```

Instead, `coord_sf(lims_method = )` offers other spatial-specific methods. Censor doesn't seem to be one but an option like `"geometry_bbox"` automatically sets limits to the smallest bounding box that contain all geometries.

```{r 10-67}
sf_plygn_1 +
  coord_sf(lims_method = "geometry_bbox")
sf_plygn_1_wlims +
  coord_sf(lims_method = "geometry_bbox")
```

Interesting note from the [docs](https://ggplot2.tidyverse.org/reference/ggsf.html#arguments):

> ... specifying limits via position scales or xlim()/ylim() is strongly discouraged, as it can result in data points being dropped from the plot even though they would be visible in the final plot region.


### Internals {-}

```{r 10-68}
library(ggtrace) # v.0.4.5
```

Scale censor for `geom_polygon()`

```{r 10-69, eval = FALSE}
ggbody(ggplot2:::ggplot_build.ggplot)[[17]]
ggtrace(
  method = ggplot2:::ggplot_build.ggplot,
  trace_steps = 17,
  trace_exprs = quote(browser()),
  verbose = FALSE
)
path_plygn_1
```

Scale censor for `geom_sf()`

```{r 10-70, eval = FALSE}
ggtrace(
  method = ggplot2:::ggplot_build.ggplot,
  trace_steps = 17, # and 26 `layout$map_position`
  trace_exprs = quote(browser()),
  verbose = FALSE
)
sf_plygn_1_wlims
```

Inspecting the rendered geom with `layer_grob()`

```{r 10-71}
patchwork::wrap_elements(layer_grob(poly_plygn_1)[[1]])
patchwork::wrap_elements(layer_grob(sf_plygn_1)[[1]])
patchwork::wrap_elements(layer_grob(sf_plygn_1_wlims)[[1]])

dplyr::bind_cols(layer_grob(sf_plygn_1)[[1]][c("x", "y")])
dplyr::bind_cols(layer_grob(sf_plygn_1_wlims)[[1]][c("x", "y")]) # x for fifth row is >1npc
```



## Meeting Videos {-}

### Cohort 1

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

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

<details>
  <summary> Meeting chat log </summary>
```
00:59:06	June Choe:	There's also a nice animation from wikipedia (the cylinder is squished because of perceptual inequality between hues) - https://upload.wikimedia.org/wikipedia/commons/transcoded/8/8d/SRGB_gamut_within_CIELCHuv_color_space_mesh.webm/SRGB_gamut_within_CIELCHuv_color_space_mesh.webm.480p.vp9.webm
```
</details>