ggblanket

Overview

To simplify ggplot2 visualisation, ggblanket provides:

Over thirty gg_* wrapper functions
A single col argument to colour and fill by a variable
A pal argument to customise colours
A facet argument to facet by a variable
An additional facet2 argument to facet by a 2nd variable
Prefixed arguments to customise scales etc
Default titles converted with to sentence case
A theme argument to customise the look and feel
A gg_theme function to create a quick theme
Pretty defaults for symmetry
Access to other geom_* arguments via …
Ability to add geom_* layers
Ability to extend further

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

penguins <- penguins |>
  mutate(sex = str_to_sentence(sex)) |>
  tidyr::drop_na(sex)

1. Over thirty gg_* wrapper functions

Each gg_* function wraps a ggplot2 ggplot(aes(...)) function with the applicable ggplot2 geom_*() function. All aesthetics are placed directly in the gg_* function: they are not within a ggplot2::aes function. This also provides access to the arguments of the relevant stat function.

penguins |> 
  ggplot() + 
  geom_point(aes(x = flipper_length_mm, y = body_mass_g))

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

2. A single col argument to colour and fill by a variable

The colour and fill aesthetics of ggplot2 are merged into a single concept represented by the col argument. This always represents the colour of everything in the geom: all points, lines and polygon interiors.

penguins |> 
  ggplot() + 
  geom_point(aes(x = flipper_length_mm, y = body_mass_g,
                 col = species))

penguins |>
  gg_point(
    x = flipper_length_mm,
    y = body_mass_g, 
    col = species)

penguins |>
  ggplot() +
  geom_density(aes(x = body_mass_g, fill = species))

penguins |>
  gg_density(
    x = body_mass_g, 
    col = species)

3. A pal argument to customise colours

The pal argument is used to customise the colours of the geom. A user can provide a vector of colours to this argument. It can be named or not. It works in a consistent way - regardless of whether a col aesthetic is added or not.

penguins |>
  ggplot() +
  geom_histogram(
    aes(x = body_mass_g),
    fill = "#1B9E77")

penguins |>
  gg_histogram(
    x = body_mass_g, 
    pal = "#1B9E77")

penguins |>
  ggplot() +
  geom_jitter(aes(x = species, y = body_mass_g, col = sex)) +
  scale_color_manual(values = c("#1B9E77", "#9E361B"))

penguins |>
  gg_jitter(
    x = species, 
    y = body_mass_g, 
    col = sex, 
    pal = c("#2596be", "#fc7c24"))

4. A facet argument to facet by a variable

Faceting is treated as if it were an aesthetic. Users just provide an unquoted variable to facet by. If a single facet (or facet2) variable is provided, it’ll default to a “wrap” layout. But users can change this with a facet_layout = "grid" argument.

penguins |>
  ggplot() +
  geom_violin(aes(x = sex, y = body_mass_g)) +
  facet_wrap(~species)

penguins |>
  gg_violin(
    x = sex,
    y = body_mass_g,
    facet = species)

5. An additional facet2 argument to facet by a 2nd variable

A facet2 argument is also provided for extra functionality and flexibility. If both facetand facet2 variables are provided, then it’ll default to a “grid” layout of facet by facet2. But users can change this with a facet_layout = "wrap" argument.

penguins |>
  ggplot() +
  geom_histogram(aes(x = flipper_length_mm)) +
  facet_grid(species ~ sex)

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

6. Prefixed arguments to customise scales etc

Prefixed arguments are available to customise scales, guides, titles and faceting etc. These are designed to work with the Rstudio auto-complete to help users remember and find the adjustment they need. Users should first determine whether they want to change something that relates to x, y, col or facet. Then they should type this prefix and press the tab key to access the list of options from the Rstudio auto-complete. Then they can use the arrow keys, and press tab again to select what they want.

penguins |>
  ggplot() +
  geom_jitter(aes(x = species, y = body_mass_g, col = sex)) +
  expand_limits(y = 0) +
  scale_x_discrete(labels = \(x) str_sub(x, 1, 1)) +
  scale_y_continuous(breaks = scales::breaks_width(1500),
                     labels = scales::label_number(big.mark = " "),
                     trans = "sqrt") +
  labs(x = "Species", y = "Body mass (g)", col = "Sex") +
  theme(legend.position = "top") +
  theme(legend.justification = "left") +
  scale_colour_manual(values = scales::hue_pal()(2), 
                      guide = ggplot2::guide_legend(title.position = "top"))

penguins |>
  gg_jitter(
    x = species,
    y = body_mass_g,
    col = sex,
    x_labels = \(x) str_sub(x, 1, 1),
    y_include = 0,
    y_breaks = scales::breaks_width(1500), 
    y_labels = scales::label_number(big.mark = " "), 
    y_trans = "sqrt",
    y_title = "Body mass (g)", 
    col_legend_place = "t")

library(patchwork)
p1 <- penguins |> 
  gg_point(
    x = flipper_length_mm, 
    y = body_mass_g, 
    y_include = 0, 
    x_breaks = scales::breaks_width(25))

p2 <- penguins |> 
  gg_point(
    x = flipper_length_mm, 
    y = body_mass_g, 
    y_limits = c(0, NA),
    x_breaks = scales::breaks_pretty(3))

p3 <- penguins |>
  gg_point(
    x = flipper_length_mm, 
    y = body_mass_g, 
    x_limits = c(190, 210),
    x_oob = scales::oob_keep,
    y_trans = "log10",
    y_limits = c(1000, NA),
    y_breaks = scales::breaks_width(1000),
    coord = coord_cartesian(clip = "on"))

p4 <- penguins |>
  gg_point(
    x = flipper_length_mm, 
    y = body_mass_g,
    x_trans = "reverse",
    x_limits = c(210, 190),
    x_breaks = scales::breaks_width(-10), 
    y_include = 0,
    y_trans = "sqrt")

(p1 + p2) / (p3 + p4)

7. Default titles converted to sentence case

Default titles are converted to sentence case with snakecase::to_sentence. All titles can be manually changed using the *_title arguments. However, with the default conversion, it is intended that titles are less likely to need to be manually changed than if default titles were left as variable names.

penguins |>
  ggplot() +
  geom_blank(aes(x = flipper_length_mm, y = body_mass_g)) +
  labs(title = "Penguins body mass by flipper length",
       subtitle = " Palmer Archipelago, Antarctica",
       x = "Flipper length (mm)", 
       caption = "Source: Gorman, 2020")

penguins |>
  gg_blank(
    x = flipper_length_mm,
    y = body_mass_g, 
    title = "Penguins body mass by flipper length",
    subtitle = " Palmer Archipelago, Antarctica",
    x_title = "Flipper length (mm)",
    caption = "Source: Gorman, 2020")

8. A theme argument to customise the look and feel

A theme argument is available. This allows users to make content that has their required look and feel. By using the theme argument, the theme will control all theme aspects, except (1) the placement of the legend and (2) gridline removal. However, if users want their theme to adjust everything, then they can + their theme as a layer instead.

penguins |>
  gg_point(x = flipper_length_mm,
           y = body_mass_g,
           col = sex,
           facet = species, 
           pal = c("#2596be", "#fc7c24"), 
           theme = theme_grey())

penguins |>
  gg_point(x = flipper_length_mm,
           y = body_mass_g,
           col = sex,
           facet = species, 
           pal = c("#2596be", "#fc7c24")) +
  theme_grey()

9. A gg_theme function to create a quick theme

A gg_theme function is provided to allow users to quickly adjust the default ggblanket theme by changing text, background colours, axis lines, ticks and gridlines etc.

custom_theme <- gg_theme(
  text_size = 9,
  plot_background_pal = "#000000",
  panel_background_pal = "#232323",
  panel_grid_pal = "#000000",
  text_pal = "#d3d3d3"
)

penguins |>
  gg_point(
    x = flipper_length_mm,
    y = body_mass_g, 
    col = species, 
    theme = custom_theme)

10. Pretty defaults for symmetry

Where the orientation is normal (i.e. vertical):

Default x scale limits and expanding are as per ggplot2 defaults
Default numeric y scale limits (that are non-transformed) start and end on a break with zero expanding
Default categorical (or numeric transformed) y scale limits and expanding are as per ggplot2 defaults
Default removal of vertical gridlines

It does the opposite where the orientation is horizontal (and also keeps y categorical values in correct order).

Note gg_bin2d, gg_hex and gg_raster deviate from this approach out of necessity, and instead just place the limits as the min and max of the data by default.

penguins |>
  group_by(species, sex) |> 
  summarise(across(body_mass_g, mean)) |> 
  ggplot() +
  geom_col(aes(x = species, y = body_mass_g, fill = sex),
    position = "dodge",
    width = 0.5
  )

penguins |>
  group_by(species, sex) |> 
  summarise(across(body_mass_g, mean)) |> 
  gg_col(
    x = species,
    y = body_mass_g,
    col = sex,
    position = "dodge",
    width = 0.5
  )

penguins |>
  group_by(species, sex) |> 
  summarise(across(body_mass_g, mean)) |> 
  ggplot() +
  geom_col(aes(x = body_mass_g, y = species, fill = sex),
           position = "dodge",
           width = 0.75
  )

penguins |>
  group_by(species, sex) |> 
  summarise(across(body_mass_g, mean)) |> 
  gg_col(
    x = body_mass_g,
    y = species,
    col = sex,
    position = "dodge",
    width = 0.75
  )

11. Access to other geom_* arguments via `...`

The ... argument is placed in the gg_* function within the wrapped ggplot2::geom_* function. This means all other arguments in the geom_* function are available to users (except the mapping argument). Common arguments from ... to add are size, linewidth and width. Additionally, users can use the colour or fill arguments to turn off part of the ggblanket col aesthetic (e.g. colour = NA or fill = NA), or fix it to single colour (e.g. colour = "black" or fill = "#d3d3d3").

penguins |>
  gg_smooth(
    x = flipper_length_mm,
    y = body_mass_g,
    col = sex,
    linewidth = 0.5, #accessed via geom_smooth
    level = 0.99, #accessed via geom_smooth
    colour = "white") #accessed via geom_smooth

penguins |>
  gg_smooth(
    x = flipper_length_mm,
    y = body_mass_g,
    col = sex,
    linewidth = 0.5, #accessed via geom_smooth
    level = 0.99, #accessed via geom_smooth
    fill = "#a8a8a8") #accessed via geom_smooth

12. Ability to add geom layers

Users can make plots with multiple layers with ggblanket by adding on ggplot2::geom_* layers. The gg_* function puts the aesthetics within the wrapped ggplot function. Therefore, the aesthetics will inherit to any subsequent geom’s added. Geom’s will plot in order. The gg_* function will plot the associated geom as the first layer, and then other geoms will be plotted on top of it.

penguins |>
  gg_boxplot(x = species,
             y = body_mass_g,
             width = 0.5,
             outlier.colour = NA) +
  geom_jitter(colour = pal_blue)

If some geoms have a col aesthetic and some do not, then it can be useful to have the col aesthetic in the gg_* function. That way you can get pretty ggblanket legend placement - and also adjust the col scale via the ease of the gg_* function. If you do not actually want a col aesthetic in your bottom plot layer, then you can over-rule the aesthetic by adding colour and fill arguments - or use the gg_blank function instead.

The gg_* function builds the x and y scales based on the data, stat, x, and y in the gg_* function - but these can be adjusted using the facet_scales, *_include and *_limits arguments. The plot scales are constructed without knowledge of subsequent layers.

penguins |>
  group_by(sex, species) |>
  summarise(across(body_mass_g, mean)) |>
  mutate(upper = body_mass_g * 1.05) |>
  mutate(lower = body_mass_g * 0.95) |>
  tidyr::drop_na(sex) %>% 
  gg_col(
    x = sex,
    y = body_mass_g,
    col = sex,
    facet = species,
    y_include = range(.$lower, .$upper),
    fill = "#d3d3d3",
    colour = "#d3d3d3", 
    width = 0.75) +
  geom_errorbar(aes(ymin = lower, ymax = upper), width = 0.1)

13. Ability to extend further

To extend ggblanket further, users can:

Use the ggblank function
Work with non-default stat’s
Use non-supported aesthetics
Use non-supported arguments
Use non-supported geoms
Create custom wrapper functions
Work with extension packages

See the Extending further article for further information.