ggblanket

How it works

First setup with set_blanket()
Each gg_* function wraps a geom
A merged col argument to colour/fill by a variable
A facet argument to facet by a variable
A facet2 argument to facet by a 2nd variable
Other aesthetics via mapping argument
Prefixed arguments to customise x/y/col/facet
Smart *_label defaults for axis and legend titles
Other ggplot2::geom_* arguments via ...
A ‘symmetric’ continuous scale with easy opt-out
Ability to add multiple geom_* layers
Families of *_mode_* themes with legend variants
Arguments to customise setup with set_blanket()
A gg_blanket() function with geom flexibility

library(dplyr)
library(stringr)
library(ggplot2)
library(scales)
library(ggblanket)
library(palmerpenguins)
library(patchwork)

penguins2 <- penguins |> 
  labelled::set_variable_labels(
    bill_length_mm = "Bill length (mm)",
    bill_depth_mm = "Bill depth (mm)",
    flipper_length_mm = "Flipper length (mm)",
    body_mass_g = "Body mass (g)",
  ) |> 
  mutate(sex = factor(sex, labels = c("Female", "Male"))) |> 
  tidyr::drop_na(sex)

1. First setup with `set_blanket()`

The set_blanket() function should be run first.

This sets the default style of plots with themes and colours etc. It can be customised.

It should be run at the start of every script or quarto document.

set_blanket()

2. Each `gg_*` function wraps a geom

Each gg_* function wraps a ggplot2::ggplot() function with the associated ggplot2::geom_*() function.

Almost every geom in ggplot2 is wrapped.

Most aesthetics can be added directly as arguments.

penguins2 |>
  gg_point(
    x = flipper_length_mm,
    y = body_mass_g,
  )

3. A merged `col` argument to colour/fill by a variable

The colour and fill aesthetics of ggplot2 are merged into a single concept represented by the col argument.

This combined aesthetic means that all colour outlines and all fill interiors should be coloured with the col_palette by the col variable.

Use colour = NA or fill = NA to turn one of these off.

penguins2 |>
  gg_boxplot(
    x = flipper_length_mm,
    y = island,
    col = sex, 
  )

4. A `facet` argument to facet by a variable

Users provide an unquoted facet variable to facet by.

When facet is specified, the facet_layout will default to a "wrap" of the facet variable (if facet2 = NULL).

penguins2 |>
  gg_histogram(
    x = flipper_length_mm,
    facet = species,
  )

5. A `facet2` argument to facet by a 2nd variable

Users can also provide an unquoted facet2 variable to facet by.

When facet2 is specified, the facet_layout will default to a "grid" of the facet variable (horizontally) by the facet2 variable (vertically).

penguins2 |>
  gg_histogram(
    x = flipper_length_mm,
    facet = species,
    facet2 = sex,
  )

6. Other aesthetics via `mapping` argument

Some aesthetics are not available via an argument (e.g. alpha, size, shape, linetype and linewidth).

These can be accessed via the mapping argument with aesthetics placed within ggplot2::aes(...).

To customise associated scales/guides, + on the applicable ggplot2 layer. In some situations, you may have to reverse the values in the relevant scale etc.

penguins2 |> 
  gg_jitter(
    x = species, 
    y = flipper_length_mm, 
    col = island,
    mapping = aes(shape = island),
  )

7. Prefixed arguments to customise x/y/col/facet

There are numerous arguments to customise plots that are prefixed by whether they relate to x, y, col or facet.

For x, y and col, these relate to associated arguments within ggplot2 scales and guides. For facet, they relate to associated arguments within ggplot2::facet_wrap and ggplot2::facet_grid.

Scales and guides associated with other other aesthetics can be customised by adding the applicable ggplot2 layer.

penguins2 |>
  gg_jitter(
    x = flipper_length_mm,
    y = body_mass_g,
    col = flipper_length_mm,
    x_breaks = scales::breaks_extended(n = 4, only.loose = TRUE),
    x_labels = \(x) stringr::str_sub(x, 1, 1),
    y_expand_limits = 1000,
    y_labels = label_number(big.mark = " "), 
    y_transform = "log10",
    col_label = "Flipper\nlength (mm)",
    col_steps = TRUE,
    col_breaks = \(x) quantile(x, seq(0, 1, 0.25)),
    col_palette = viridis::rocket(n = 9, direction = -1),
  )

8. Smart `*_label` defaults for axis and legend titles

The x_label, y_label and col_label for the axis and legend titles can be manually specified with the applicable *_label argument (or + ggplot2::labs(...)).

If not specified, they will first take any label attribute associated with the applicable variable.

If none, they will then convert the variable name to a label name using the label_to_case function, which defaults to sentence case (i.e. snakecase::to_sentence_case).

penguins2 |>
  gg_freqpoly(
    x = flipper_length_mm,
    col = species,
  )

9. Other `ggplot2::geom_*` arguments via `...`

The ... argument provides access to all other arguments in the ggplot2::geom_*() function.

Common arguments to add include colour, fill, alpha, linewidth, linetype, size and width, which enables fixing of these to a particular value.

Use the ggplot2::geom_* help to see what arguments are available.

penguins2 |>
  gg_smooth(
    x = flipper_length_mm,
    y = body_mass_g,
    col = sex, 
    col_palette = c("#003f5c", "#ffa600"),
    colour = "#bc5090", 
    linewidth = 1, 
    linetype = "dashed",
    alpha = 1, 
    se = TRUE, 
    level = 0.999, 
  )

10. A ‘symmetric’ continuous scale with easy opt-out

The gg_* function will generally create a ‘symmetric’ continuous y scale with y_limits the range of y_breaks and y_expand of c(0, 0). The vice-versa will occur where a y orientation is guessed.

You can turn this ‘symmetric’ scale off using *_limits = c(NA, NA) (or *_limits = c(0, NA) for bars etc). For a date variable, use lubridate::NA_Date_ instead of NA.

Note this ‘symmetric’ scale does not occur where the associated *_limits are specified or the *_transform is non-linear.

11. Ability to add multiple `geom_*` layers

Users can make plots with multiple layers by adding on ggplot2::geom_* layers.

The gg_* function puts the aesthetic variables within the wrapped ggplot function. Therefore, these aesthetics will inherit to any subsequent layers added.

It generally works best to add all aesthetics required to the gg_* function. The gg_*() function should also be appropriate to be the bottom geom of the plot, given that geoms are drawn in order.

Subsequently, you may sometimes need to use gg_blanket() which defaults to a blank geom.

penguins2 |>
  group_by(species, sex) |>
  summarise(
    lower = quantile(flipper_length_mm, probs = 0.05),
    upper = quantile(flipper_length_mm, probs = 0.95),
    flipper_length_mm = mean(flipper_length_mm, na.rm = TRUE),
  ) |>
  labelled::copy_labels_from(penguins2) |>
  ungroup() |> 
  gg_col(
    x = flipper_length_mm,
    xmin = lower, 
    xmax = upper,
    y = species,
    col = sex,
    position = position_dodge(),
    width = 0.75,
    x_expand_limits = 0,
  ) +
  geom_errorbar(
    width = 0.1, 
    position = position_dodge(width = 0.75),
    colour = lightness[1],
  )

12. Families of `_mode_` themes with legend variants

light_mode_*, grey_mode_* and dark_mode_* theme families are provided with themes that differ based on legend placement with suffix r (right), b (bottom), t (top) and n (none).

These are built for use with the mode argument in the gg_* functions, which has side-effects for x and y orientations removing axis lines/ticks and gridlines.

If you want to use a theme with no side-effects, then + on the theme instead.

penguins2 |>
  gg_histogram(
    x = flipper_length_mm,
    col = species,
    title = "Penguin flipper length by species",
    subtitle = "Palmer Archipelago, Antarctica",
    caption = "Source: Gorman, 2020", 
    mode = grey_mode_t(),
  ) +
  theme(legend.title = element_blank())

13. Arguments to customise setup with `set_blanket()`

The set_blanket function sets customisable defaults for the:

mode (i.e. a theme added with side-effects)
geom colour (i.e. colour/fill where col = NULL for most geoms)
annotation colour (i.e. colour/fill where col = NULL for other geoms often used for annotation)
discrete colour palette (and NA colour)
continuous colour palette (and NA colour)
theme (i.e. a theme added with no side-effects)

The ggplot2::update_geom_defaults() function can be used to further fine-tune geom defaults.

set_blanket() also works on ggplot2 code.

set_blanket(
  mode = dark_mode_r(), 
  geom_colour = "#e7298a",
  annotate_colour = darkness[1],
  col_palette_d = c("#1b9e77", "#d95f02", "#7570b3", "#e7298a", "#66a61e", 
                    "#e6ab02", "#a6761d", "#666666"), #RColorBrewer Dark2 
)

p1 <- penguins2 |>
  gg_point(
    x = flipper_length_mm, 
    y = body_mass_g,
    x_breaks = breaks_extended(n = 4, only.loose = TRUE),
  ) +
  geom_vline(xintercept = 200) +
  annotate("text", x = I(0.25), y = I(0.75), label = "Here")

p2 <- penguins2 |> 
  gg_histogram(
    x = flipper_length_mm,
    col = species,
    x_breaks = breaks_extended(n = 4, only.loose = TRUE),
  ) +
  geom_vline(xintercept = 200) +
  annotate("text", x = I(0.75), y = I(0.75), label = "Here")

p1 + p2


set_blanket()

14. A `gg_blanket()` function with `geom` flexibility

The package is driven by the gg_blanket function, which has a geom argument with ggplot2::geom_blank defaults for geom, stat and position.

All other functions wrap this function with a fixed geom, and their own default stat and position arguments as per the applicable geom_* function.

This function can often be used with geoms that do not have an associated gg_* function.

You can print a geom_* function to identify the default stat and position arguments etc.

geom_spoke()
#> geom_spoke: na.rm = FALSE
#> stat_identity: na.rm = FALSE
#> position_identity

expand.grid(x = 1:10, y = 1:10) |>
  tibble() |>
  mutate(angle = runif(100, 0, 2*pi)) |>
  mutate(speed = runif(100, 0, sqrt(0.1 * x))) |>
  gg_blanket(
    geom = "spoke",
    x = x, 
    y = y,
    col = speed,
    mapping = aes(angle = angle, radius = speed),
  ) +
  geom_point()

## Further information

See the ggblanket website for further information, including articles and function reference.

ggblanket

David Hodge

Overview

How it works

1. First setup with `set_blanket()`

2. Each `gg_*` function wraps a geom

3. A merged `col` argument to colour/fill by a variable

4. A `facet` argument to facet by a variable

5. A `facet2` argument to facet by a 2nd variable

6. Other aesthetics via `mapping` argument

7. Prefixed arguments to customise x/y/col/facet

8. Smart `*_label` defaults for axis and legend titles

9. Other `ggplot2::geom_*` arguments via `...`

10. A ‘symmetric’ continuous scale with easy opt-out

11. Ability to add multiple `geom_*` layers

12. Families of `_mode_` themes with legend variants

13. Arguments to customise setup with `set_blanket()`

14. A `gg_blanket()` function with `geom` flexibility

ggblanket

David Hodge

Overview

How it works

1. First setup with set_blanket()

2. Each gg_* function wraps a geom

3. A merged col argument to colour/fill by a variable

4. A facet argument to facet by a variable

5. A facet2 argument to facet by a 2nd variable

6. Other aesthetics via mapping argument

7. Prefixed arguments to customise x/y/col/facet

8. Smart *_label defaults for axis and legend titles

9. Other ggplot2::geom_* arguments via ...

10. A ‘symmetric’ continuous scale with easy opt-out

11. Ability to add multiple geom_* layers

12. Families of *_mode_* themes with legend variants

13. Arguments to customise setup with set_blanket()

14. A gg_blanket() function with geom flexibility

1. First setup with `set_blanket()`

2. Each `gg_*` function wraps a geom

3. A merged `col` argument to colour/fill by a variable

4. A `facet` argument to facet by a variable

5. A `facet2` argument to facet by a 2nd variable

6. Other aesthetics via `mapping` argument

8. Smart `*_label` defaults for axis and legend titles

9. Other `ggplot2::geom_*` arguments via `...`

11. Ability to add multiple `geom_*` layers

12. Families of `_mode_` themes with legend variants

13. Arguments to customise setup with `set_blanket()`

14. A `gg_blanket()` function with `geom` flexibility