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.
set_blanket()
gg_*
function wraps a geomcol
argument to colour/fill by a variablefacet
argument to facet by a variablefacet2
argument to facet by a 2nd variablemapping
argument*_label
defaults for axis and legend titlesggplot2::geom_*
arguments via
...
*_mode_*
themes with legend variantsgeom_*
layersset_blanket()
gg_blanket()
function with geom
flexibilitylibrary(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)
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.
gg_*
function wraps a geomEach gg_*
function wraps a
ggplot2::ggplot()
function with the associated
ggplot2::geom_*()
function.
Almost every geom in ggplot2 is wrapped.
Position related aesthetics can be added directly as arguments.
col
argument to colour/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 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.
facet
argument to facet by a variableUsers 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
).
facet2
argument to facet by a 2nd variableUsers 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).
mapping
argumentSome aesthetics are not available via an argument
(e.g. alpha
, size
, shape
,
linetype
and linewidth
).
These can be accessed via the mapping
argument using the
aes()
function.
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.
Note you can use
set_blanket(geom_colour = lightness[1], ...)
to make legend
symbols black if needed.
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),
)
*_label
defaults for axis and legend
titlesThe 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
).
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.
*_mode_*
themes with legend
variantslight_mode_*
, grey_mode_*
and
dark_mode_*
theme families are provided with variants that
differ based on legend placement with suffix r
(right),
b
(bottom), t
(top) and n
(none).
These themes were built for use with the mode
argument.
If not specified, the gg_*
function will guess the plot
orientation (based on whether the y axis is discrete).
Where x_orientation = TRUE
, it will:
mode
theme.y_limits = NULL
and y_expand = NULL
,
make any linear y continuous scale ‘symmetric’ if possible with
(a) y_limits
the range of y_breaks
and (b)
y_expand = c(0, 0)
.The vice versa occurs when y_orientation = TRUE
.
You can avoid these side-effects by:
+
-ing your theme on to the gg_*
output*_limits = c(NA, NA)
argument (or
*_limits = c(0, NA)
for bars).geom_*
layersUsers can make plots with multiple ggplot2::geom_*
layers.
The gg_*()
geom layer will be the bottom geom layer of
the plot, and each subsequent geom_*()
layer is placed on
top.
Aesthetics added directly (e.g. x
, y
etc.)
to the gg_*()
function will inherit to later
geom_*()
layers, whereas those added to the
mapping
argument will not.
penguins2 |>
gg_violin(
x = species,
y = bill_depth_mm,
outliers = FALSE,
) +
geom_boxplot(
width = 0.25,
colour = lightness[1],
fill = lightness[2],
) +
geom_jitter(
colour = navy,
)
The scales are built within the gg_*()
function
without knowledge of later layers. The gg_*()
function builds scales with regard to the stat
,
position
, and aesthetics (that the geom understands) etc.
So, in some situations, users will need to take care.
penguins2 |>
group_by(species, sex) |>
summarise(
lower = quantile(bill_depth_mm, probs = 0.05),
upper = quantile(bill_depth_mm, probs = 0.95),
bill_depth_mm = mean(bill_depth_mm, na.rm = TRUE),
) |>
labelled::copy_labels_from(penguins2) |>
gg_blanket(
y = species,
x = bill_depth_mm,
xmin = lower,
xmax = upper,
col = sex,
position = position_dodge(width = 0.75),
x_expand_limits = 0,
) +
geom_col(
width = 0.75,
position = position_dodge(width = 0.75),
alpha = 0.9,
) +
geom_errorbar(
width = 0.1,
position = position_dodge(width = 0.75),
colour = lightness[1],
)
set_blanket()
The set_blanket
function sets customisable defaults for
the:
col = NULL
for most
geoms)col = NULL
for other geoms often used for annotation)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 = "#E7298AFF",
annotate_colour = darkness[1],
col_palette_d = c("#1B9E77FF", "#D95F02FF", "#7570b3FF", "#E7298AFF", "#66A61EFF",
"#E6AB02FF", "#A6761DFF", "#666666FF"), #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
gg_blanket()
function with geom
flexibilityThe 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.
See the ggblanket website for further information, including articles and function reference.