To simplify ggplot2 visualisation, ggblanket provides:
library(dplyr)
library(ggplot2)
library(stringr)
library(ggblanket)
library(palmerpenguins)
<- penguins |>
penguins mutate(sex = str_to_sentence(sex)) |>
::drop_na(sex) tidyr
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)
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)
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"))
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)
A facet2
argument is also provided for extra
functionality and flexibility. If both facet
and
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)
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)
<- penguins |>
p1 gg_point(
x = flipper_length_mm,
y = body_mass_g,
y_include = 0,
x_breaks = scales::breaks_width(25))
<- penguins |>
p2 gg_point(
x = flipper_length_mm,
y = body_mass_g,
y_limits = c(0, NA),
x_breaks = scales::breaks_pretty(3))
<- penguins |>
p3 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"))
<- penguins |>
p4 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")
+ p2) / (p3 + p4) (p1
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")
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()
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.
<- gg_theme(
custom_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)
Where the orientation is normal (i.e. vertical):
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
)
...
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
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) |>
::drop_na(sex) %>%
tidyrgg_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)
To extend ggblanket further, users can:
See the Extending further article for further information.