ggblanket is a package of ggplot2 wrapper functions.
The primary objective is to simplify ggplot2 visualisation.
Secondary objectives relate to:
Computational speed has been traded-off to achieve these objectives.
gg_*
wrapper functionscol
argument to colour and fill by a variablefacet
argument to facet by a variablefacet2
argument to facet by a 2nd variablesnakecase::sentence_case
geom_*
arguments via
...
geom_*
layersmapping
mode
argument designed for *_mode_*
themes*_mode_*
themes that differ by legend
placementset_blanket
gg_blanket()
function with geom
flexibilitylibrary(ggblanket)
library(ggplot2)
library(dplyr)
library(stringr)
library(tidyr)
library(palmerpenguins)
library(patchwork)
set_blanket()
gg_*
wrapper functionsEach gg_*
function wraps a ggplot2
ggplot2::ggplot()
function with the applicable ggplot2
geom_*()
function.
Each gg_*
function is named after the
geom_*
function it wraps.
Note at the start of every script, the set_blanket
function should be run to set the default style for subsequent ggblanket
plots.
col
argument to colour and fill by a
variableThe colour and fill aesthetics of ggplot2 are merged into a single
concept represented by the col
argument.
This combined aesthetic means that everything should be coloured according to it, i.e. all coloured outlines and filled interiors.
Use colour = NA
or fill = NA
if you need to
turn one of these off.
facet
argument to facet by a variableFaceting is treated as if it were an aesthetic. Users just provide an unquoted variable to facet by.
When facet
variable is not NULL (and
facet2 = NULL
), the facet_layout
will default
to "wrap"
.
facet2
argument to facet by a 2nd variableA facet2
argument is also provided for extra
functionality and flexibility.
This enables users to facet easily in a "grid"
layout of
the facet
variable horizontally by the facet2
variable vertically.
Whenever a facet2
does not equal NULL, the
facet_layout
will default to "grid"
.
ggblanket offers numerous arguments to customise that are prefixed by
whether they relate to x
, y
, col
or facet
.
These prefixed arguments work nicely with the Rstudio auto-complete, if users ensure their settings support the use of tab for auto-completions and multi-line auto-completions (i.e. Tools - Global Options - Code - Completion).
Everything prefixed col_
relates to both the
colour and fill scale as applicable. Likewise, everything prefixed
facet_
relates to both facet
and
facet2
as applicable.
penguins |>
drop_na(sex) |>
gg_jitter(
x = species,
y = body_mass_g,
col = flipper_length_mm,
facet = sex,
x_labels = \(x) str_sub(x, 1, 1),
y_breaks = scales::breaks_width(1000),
y_expand_limits = 2000,
y_labels = scales::label_number(big.mark = " "),
y_transform = "log10",
y_title = "Body mass (g)",
col_steps = TRUE,
col_breaks = \(x) quantile(x, seq(0, 1, 0.25)),
col_palette = viridis::magma(n = 9, direction = -1),
facet_labels = str_to_sentence,
)
snakecase::sentence_case
Unspecified x
, y
, col
and
alpha
titles are converted to sentence case with
snakecase::to_sentence
.
However, each title can be manually changed using the applicable
*_title
argument.
The default snakecase::to_sentence
conversion can be
turned off using titles_to_case = \(x) x
or changed
(e.g. snakecase::to_title_case
).
geom_*
arguments via
...
The ...
argument provides access to all other arguments
in the geom_*()
function. Typical arguments to add include
colour
, fill
, alpha
,
linewidth
, linetype
, size
and
width
.
Subsequently, for geoms that have both coloured outlines and
interiors, you can turn off either of these using
colour = NA
/fill = NA
- and/ fix one to a
single colour with
colour = "black"
/fill = "lightgrey"
etc.
Use the geom_*
help to see what arguments are
available.
The gg_*
function will generally create a symmetric
continuous y scale by default with:
y_limits
that are the range of the
y_breaks
y_expand
of c(0, 0)
.However, for the plots guessed to be horizontal, the vice-versa will occurs with a symmetric continuous x scale by default.
Sometimes you may need to add *_expand_limits = 0
, if
the lower bound of the symmetric scale falls on a number close to 0.
This symmetric continuous scale can be turned off easily using
*_limits = c(NA, NA)
(or *_limits = c(0, NA)
for bars etc).
Note this symmetric scale does not occur where the scale has a
transformation that is not "identity"
,
"reverse"
, "date"
, "time"
or
"hms"
- or where the other positional scale is binned.
geom_*
layersUsers can make plots with multiple layers by +
-ing 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. Generally, it works well to
add all aesthetics required for the plot to the gg_*
function, including the col
argument.
The gg_*()
function should be appropriate to be
the bottom layer of the plot, as geoms are drawn in order. You may
sometimes need to use gg_blanket()
as your
gg_*
function, as it defaults to a blank
geom.
penguins |>
group_by(species) |>
summarise(body_mass_g = mean(body_mass_g, na.rm = TRUE)) |>
mutate(lower = body_mass_g * 0.95) |>
mutate(upper = body_mass_g * 1.2) %>%
gg_col(
x = body_mass_g,
xmin = lower,
xmax = upper,
y = species,
col = species,
width = 0.75,
x_expand_limits = c(0, max(.$upper)),
x_labels = \(x) x / 1000,
x_title = "Body mass kg",
) +
geom_errorbar(
colour = "black",
width = 0.1,
)
penguins |>
group_by(species) |>
summarise(body_mass_g = mean(body_mass_g, na.rm = TRUE)) |>
mutate(lower = body_mass_g * 0.95) |>
mutate(upper = body_mass_g * 1.2) |>
gg_blanket(
x = body_mass_g,
y = species,
col = species,
xmin = lower,
xmax = upper,
width = 0.75,
x_expand_limits = 0,
x_labels = \(x) x / 1000,
x_title = "Body mass kg",
) +
geom_col(
colour = "#d3d3d3",
fill = "#d3d3d3",
alpha = 0.9,
width = 0.75,
) +
geom_errorbar(
width = 0.1,
)
mapping
The mapping
argument provides access to other
aesthetics, such as alpha
, size
,
shape
, linetype
and linewidth
etc.
Legend titles and element order must be aligned, if legends are to
merge. Subsequently, you may need to change a title using
+ ggplot2::labs
- or even reverse a guide.
mode
argument designed for provided
*_mode_*
themesA mode
argument has been designed for use with the
*_mode_*
themes.
With this function, the gg_*
function will:
*_mode_*
themeTo avoid these side-effects, +
the theme on to the
output of gg_*
. Note there is an orientation
argument within the *_mode_*
functions that can be useful
when used in this way.
*_mode_*
themes that differ by legend
placementThree mode families of complete themes are provided:
light_mode_*
, grey_mode_*
and
dark_mode_*
.
Each mode family provides 4 variants that differ based on legend
placement, which is represented by the suffix of the mode name of
r
(right), b
(bottom), t
(top)
and n
(none).
The default is light_mode_r()
.
These are intended for use with the mode
argument.
Note: * if you want to use a quick non-bold title, use
subtitle = "\n..."
* a title can be removed using
+ labs(... = NULL)
* for removing the legend title, you
will often need + labs(colour = NULL, fill = NULL)
.
A further flexi_mode_*
family is provided where users
can select the colours and linewidths.
penguins |>
gg_histogram(
x = flipper_length_mm,
col = species,
title = "Penguin flipper length by species",
subtitle = "Palmer Archipelago, Antarctica",
caption = "Source: Gorman, 2020",
mode = light_mode_t(),
) +
labs(colour = NULL, fill = NULL)
set_blanket
The set_blanket
function is used to set the default
style for ggblanket plots.
This function: * sets the default mode * updates a series of geom
defaults often used for annotation (i.e. *_vline
,
*_hline
, *_abline
, *_curve
,
*_text
and *_label
) * updates all other geom
defaults.
Within the set_blanket
function, the user can select the
mode
, the colour
and annotate
colour with the fill inheriting from these.
Elements can be +
-ed on to modes just as normal themes.
The ggplot2::update_geom_defaults()
function can be used to
further fine-tune geom defaults.
set_blanket(
mode = grey_mode_r(),
geom_colour = "#ffa600",
)
p1 <- penguins |>
gg_point(
x = flipper_length_mm,
y = body_mass_g,
x_breaks = scales::breaks_pretty(3),
) +
geom_vline(xintercept = 200) +
annotate("text", x = I(0.25), y = I(0.75), label = "Here")
p2 <- penguins |>
gg_histogram(
x = flipper_length_mm,
x_breaks = scales::breaks_pretty(3),
) +
geom_vline(xintercept = 200) +
annotate("text", x = I(0.75), y = I(0.75), label = "Here")
p1 + p2
set_blanket(
mode = dark_mode_r(),
geom_colour = "#bc5090",
annotate_colour = "#c8d7df",
)
p1 <- penguins |>
gg_point(
x = flipper_length_mm,
y = body_mass_g,
x_breaks = scales::breaks_pretty(3),
) +
geom_vline(xintercept = 200) +
annotate("text", x = I(0.25), y = I(0.75), label = "Here")
p2 <- penguins |>
gg_histogram(
x = flipper_length_mm,
x_breaks = scales::breaks_pretty(3),
) +
geom_vline(xintercept = 200) +
annotate("text", x = I(0.75), y = I(0.75), label = "Here")
p1 + p2
gg_blanket()
function with geom
flexibilityggblanket is driven by the gg_blanket
function, which
has a geom
argument with geom_blank
defaults.
All other functions wrap this function with a locked-in geom, and
their own default stat
and position
arguments
as per the applicable geom_*
function.
You can print a geom_*
function to identify the
applicable stat
and position
arguments
etc.
set_blanket(
light_mode_t() + theme(legend.title = element_blank())
)
geom_violin()
#> geom_violin: draw_quantiles = NULL, na.rm = FALSE, orientation = NA
#> stat_ydensity: trim = TRUE, scale = area, na.rm = FALSE, orientation = NA, bounds = c(-Inf, Inf)
#> position_dodge
penguins |>
drop_na(sex) |>
mutate(across(sex, str_to_sentence)) |>
gg_blanket(
geom = "violin",
stat = "ydensity",
position = "dodge",
x = sex,
y = body_mass_g,
col = species,
)
geom_histogram()
#> geom_bar: na.rm = FALSE, orientation = NA
#> stat_bin: binwidth = NULL, bins = NULL, na.rm = FALSE, orientation = NA, pad = FALSE
#> position_stack
penguins |>
gg_blanket(
geom = "bar",
stat = "bin",
position = "stack",
x = flipper_length_mm,
col = species,
)
set_blanket()
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()
See the ggblanket website for further information, including articles and function reference.