beeswarm_plots.qmd

# Beeswarm plots {#sec-beeswa}

```{r}
#| label: setup
#| message: false
#| warning: false
#| include: false
library(tidyverse)
library(lubridate)
library(scales)
library(knitr)
library(kableExtra)
library(colorblindr)
library(downlit)
# fonts ----
library(extrafont)
library(sysfonts)
source("_common.R")
# use font
showtext::showtext_auto()
# set theme
ggplot2::theme_set(theme_ggp2g(
    base_size = 15))
```

```{r}
#| label: status
#| results: "asis"
#| echo: false
# status ----
# polishing, restructuring, drafting, complete
status("complete")
```

:::: {.callout-note collapse="false" icon=false}

::: {style="font-size: 1.25em; color: #02577A;"}

:::

<br>

```{r}
#| label: full_code_display
#| eval: true
#| echo: false
#| warning: false
#| message: false
#| out-height: '60%'
#| out-width: '60%'
#| fig-align: right
library(ggbeeswarm)
library(palmerpenguins) 
library(ggplot2)
library(patchwork)
peng_beeswarm <- palmerpenguins::penguins |> 
    dplyr::group_by(species) |> 
    dplyr::mutate(bill_ratio = bill_length_mm / bill_depth_mm) |>  
    dplyr::filter(!is.na(bill_ratio))
# ggp2_beeswarm ----
labs_beeswarm <- labs(
    title = "Adult Foraging Penguins",
    subtitle = "Bill Length (mm) / Bill Depth (mm) = Bill Ratio",
    x = "Species",
    y = "Bill Ratio")
ggp2_beeswarm <-  ggplot(data = peng_beeswarm,
    aes(x = species,
        y = bill_ratio,
        color = species)) +
    ggbeeswarm::geom_beeswarm(
        alpha = 2 / 3,
        size = 1.15,
        cex = 1.5,
        dodge.width = 1,
        show.legend = FALSE) +
    scale_x_discrete(expand = expansion(add = c(1, 1))) +
    labs_beeswarm
ggp2_beeswarm
```

::: {style="font-size: 1.10em; color: #02577A;"}
**This graph requires:**
:::

::: {style="font-size: 1.05em; color: #282b2d;"}
**`r emo::ji("check")` a categorical variable**      
:::

::: {style="font-size: 1.05em; color: #282b2d;"}
**`r emo::ji("check")` a numeric (continuous) variable**
:::

::::

## Description 

The beeswarm plot uses points to display the distribution of a continuous variable across the levels of a categorical variable. 

The points are grouped by level, and the shape (or swarm) of the distribution is mirrored above and below the quantitative axis (similar to a violin plot). 

We can create beeswarm plot using `geom_jitter()` or the [`ggbeeswarm` package](https://github.com/eclarke/ggbeeswarm).

## Set up

::: {style="font-size: 1.15em; color: #1e83c8;"}
**PACKAGES:**
:::


Install packages.


::: {style="font-size: 0.85em;"}
```{r}
#| label: pkg_code_beeswarm
#| code-fold: show
#| eval: false
#| echo: true
#| warning: false
#| message: false
#| results: hide
# pak::pak("eclarke/ggbeeswarm")
library(ggbeeswarm)
install.packages("palmerpenguins")
library(palmerpenguins) 
library(ggplot2)
```
:::



::: {style="font-size: 1.15em; color: #1e83c8;"}
**DATA:**
:::

::: {.column-margin}
![Artwork by allison horst](www/lter_penguins.png){fig-align="right" width="100%" height="100%"}
:::


Create `peng_beeswarm` by grouping `penguins` by `species`, then calculating the `bill_ratio` (`bill_length_mm / bill_depth_mm`), and then removing any missing values from `bill_ratio`

::: {style="font-size: 0.85em;"}
```{r}
#| label: data_code_beeswarm
#| code-fold: show
#| eval: true
#| echo: true
peng_beeswarm <- palmerpenguins::penguins |> 
    dplyr::group_by(species) |> 
    dplyr::mutate(bill_ratio = bill_length_mm / bill_depth_mm) |>  
    dplyr::filter(!is.na(bill_ratio)) |> 
    dplyr::ungroup()
glimpse(peng_beeswarm)
```
:::

## Grammar

::: {style="font-size: 1.15em; color: #1e83c8;"}
**CODE:**
:::

  -   Create labels with `labs()`

  -   Initialize the graph with `ggplot()` and provide `data`

  -   Map `species` to the `x` axis and `color`

  -   Map `bill_ratio` to the `y` axis

  -   Add the `ggbeeswarm::geom_beeswarm()` layer (with `alpha`)

  -   Remove the legend with `show.legend = FALSE`

::: {style="font-size: 0.85em;"}
```{r}
#| label: code_graph_beeswarm
#| code-fold: show
#| eval: false
#| echo: true 
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
labs_beeswarm <- labs(
    title = "Adult Foraging Penguins",
    subtitle = "Bill Length (mm) / Bill Depth (mm) = Bill Ratio",
    x = "Species",
    y = "Bill Ratio")
ggp2_beeswarm <- ggplot(data = peng_beeswarm,
    aes(x = species,
        y = bill_ratio,
        color = species)) +
    ggbeeswarm::geom_beeswarm(alpha = 2 / 3,
        show.legend = FALSE)
ggp2_beeswarm +
    labs_beeswarm
```
:::



::: {style="font-size: 1.15em; color: #1e83c8;"}
**GRAPH:**
:::

Adjust the size/shape of the swarm using `method =` or the  `geom_quasirandom()` function

::: {style="font-size: 0.85em;"}
```{r}
#| label: create_graph_beeswarm
#| eval: true
#| echo: false
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
#| layout-nrow: 1
#| column: page-inset-right
labs_beeswarm <- labs(
    title = "Adult Foraging Penguins",
    subtitle = "Bill Length (mm) / Bill Depth (mm) = Bill Ratio",
    x = "Species",
    y = "Bill Ratio")
ggp2_beeswarm <- ggplot(data = peng_beeswarm,
    aes(x = species,
        y = bill_ratio,
        color = species)) +
    ggbeeswarm::geom_beeswarm(alpha = 2 / 3,
        show.legend = FALSE)
ggp2_beeswarm +
    labs_beeswarm
```
:::


## More info

Below is some additional arguments and methods for beeswarm plots.

### `method`

<br>

Use method to adjust the shape of the beeswarm (`swarm`, `compactswarm`, `hex`, `square`, `center`, or `centre`)

:::: {.column-margin}
::: {style="font-size: 0.95rem;"}
Set the point `shape` to `21` to control the `fill` and `color` 
:::
::::

::: {style="font-size: 0.85em;"}
```{r}
#| label: create_graph_beeswarm_method
#| eval: true
#| echo: true
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
#| layout-nrow: 1
#| column: page-inset-right
ggp2_compact_swarm <- ggplot(data = peng_beeswarm,
    mapping = aes(x = species,
                  y = bill_ratio,
                color = species)) +
    ggbeeswarm::geom_beeswarm(
      aes(fill = species),
        method = 'compactswarm', 
        dodge.width = 0.5,
        shape = 21,
        color = "#ffffff",
        alpha = 2/3, size = 1.7,
        show.legend = FALSE) 
ggp2_compact_swarm + 
    # add labels
    labs_beeswarm
```
:::

### `side`

<br>

For a beeswarm that falls across the vertical axis, use the `side` argument. 

::: {style="font-size: 0.85em;"}
```{r}
#| label: create_graph_beeswarm_side
#| eval: true
#| echo: true
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
#| layout-nrow: 1
#| column: page-inset-right
ggp2_rside_swarm <- ggplot(data = peng_beeswarm,
    mapping = aes(x = species,
                  y = bill_ratio,
                color = species)) +
    ggbeeswarm::geom_beeswarm(
      aes(fill = species),
        side = 1, # right/upwards
        shape = 21,
        color = "#ffffff",
        alpha = 2/3, 
        size = 1.7,
        show.legend = FALSE) 
ggp2_rside_swarm + 
    # add labels
    labs_beeswarm
```
:::

### `cex`

<br>

The `cex` argument controls the "*scaling for adjusting point spacing*"

::: {style="font-size: 0.85em;"}
```{r}
#| label: create_graph_beeswarm_cex
#| eval: true
#| echo: true
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
#| layout-nrow: 1
#| column: page-inset-right
ggp2_beeswarm_cex <- ggplot(data = peng_beeswarm,
    mapping = aes(x = species,
                  y = bill_ratio,
                color = species)) +
    ggbeeswarm::geom_beeswarm(
      aes(fill = species),
        cex = 1.6,
        shape = 21,
        color = "#ffffff",
        alpha = 2/3, 
        size = 1.7,
        show.legend = FALSE) 
ggp2_beeswarm_cex + 
    # add labels
    labs_beeswarm
```

:::

### `geom_jitter()`

<br>

We can also create a beeswarm using the `geom_jitter()` and setting the `height` and `width`.

::: {style="font-size: 0.85em;"}
```{r}
#| label: create_graph_beeswarm_jitter
#| eval: true
#| echo: true
#| warning: false
#| message: false
#| out-height: '100%'
#| out-width: '100%'
#| layout-nrow: 1
#| column: page-inset-right
ggp2_jitter_swarm <- ggplot(data = peng_beeswarm,
    mapping = aes(x = species,
        y = bill_ratio,
        color = species)) +
    geom_jitter(
        aes(fill = species),
        height = 0.05,
        width = 0.11,
        shape = 21,
        color = "#ffffff",
        alpha = 2 / 3,
        size = 1.7,
        show.legend = FALSE)
ggp2_jitter_swarm + 
    # add labels
    labs_beeswarm
```
:::