ggpattern
ggpattern
provides custom ggplot2
geoms which support filled areas with
geometric and image-based patterns.
Reading the articles/vignettes on the package website is probably the best way to get started.
Feature Summary
- Custom versions of (almost) all the geoms from ggplot2 which have a region which can be filled.
- A suite of aesthetics for controlling the pattern appearance
(e.g.
pattern_alpha
) - The ability to include user-defined patterns
Installation
You can install the development version from GitHub with the instructions below.
Note: there are a lot of dependencies. Please ensure these are installed
first before attempting to install ggpattern
. By doing so, this will
make any issues during installation clearer, leading to more meaningful
bug reporting.
install.packages('ggplot2')
install.packages('scales')
install.packages('grid')
install.packages('glue')
install.packages('rlang')
install.packages('tibble')
install.packages('gridGeometry')
install.packages('sf')
install.packages('png')
install.packages('magick')
install.packages('memoise')
# install.packages("remotes")
remotes::install_github("coolbutuseless/ggpattern")
Quickstart
- Take an existing plot which contains a geom with a fillable area e.g
geom_col()
. - Use the
{ggpattern}
version of the geom e.g.ggpattern::geom_col_pattern()
instead ofggplot2::geom_col()
- Set the aesthetic
pattern
to your choice of pattern e.gpattern = 'stripe'
, and set other options usingpattern_*
aesthetics
df <- data.frame(level = c("a", "b", "c", 'd'), outcome = c(2.3, 1.9, 3.2, 1))
ggplot(df) +
geom_col_pattern(
aes(level, outcome, pattern_fill = level),
pattern = 'stripe',
fill = 'white',
colour = 'black'
) +
theme_bw(18) +
theme(legend.position = 'none') +
labs(
title = "ggpattern::geom_pattern_col()",
subtitle = "pattern = 'stripe'"
) +
coord_fixed(ratio = 1/2)
Gallery
Feature Details
Available Geoms
ggpattern
includes versions of (nearly) all geoms from ggplot2
which
could plausiblly support being filled with a pattern.
See the vignette galleries for examples of all the available geoms filled with geometry-based patterns and image-based/array-based patterns.
ggplot2 | ggpattern |
---|---|
geom_area | geom_area_pattern |
geom_bar | geom_bar_pattern |
geom_bin2d | geom_bin2d_pattern |
geom_boxplot | geom_boxplot_pattern |
geom_col | geom_col_pattern |
geom_crossbar | geom_crossbar_pattern |
geom_density | geom_density_pattern |
geom_map | geom_map_pattern |
geom_polygon | geom_polygon_pattern |
geom_rect | geom_rect_pattern |
geom_ribbon | geom_ribbon_pattern |
geom_sf | geom_sf_pattern |
geom_tile | geom_tile_pattern |
geom_violin | geom_violin_pattern |
New aesthetics
To control pattern appearance, a raft of new aesthetics have been added.
e.g. pattern_alpha
, pattern_filename
, pattern_density
.
There are also scale functions to control each of these new aesthetics
e.g. scale_pattern_alpha_discrete
.
Not all aesthetics apply to all patterns. See the individual pattern vignettes for which aesthetics it uses, or see the first vignette on developing user-defined patterns for a table of aesthetic use by pattern, or see the individual vignettes for each pattern.
aesthetic | description | default | possible values |
---|---|---|---|
pattern | Name of the pattern to draw | ‘stripe’ | stripe, crosshatch, circle, image, placeholder, magick, gradient, plasma |
pattern_type | Generic control option | NA | pattern-dependent |
pattern_subtype | Generic control option | NA | pattern-dependent |
pattern_alpha | Alpha | 1 | value in range [0, 1] (npc units) |
pattern_linetype | Stroke linetype | 1 | linetype |
pattern_size | Stroke linewidth | 1 | linewidth |
pattern_shape | Plotting shape | 1 | shapes |
pattern_colour | Stroke colour | ‘grey20’ | colour |
pattern_fill | Fill colour | ‘grey80’ | colour |
pattern_fill2 | Second fill colour | ‘#4169E1’ | colour |
pattern_angle | Rotation angle | 30 | angle in degrees |
pattern_density | Approx. fraction of area the pattern fills | 0.2 | value in range [0, 1] (fraction) |
pattern_spacing | Spacing between repetitions of pattern | 0.05 | value in range [0, 1] (npc units) |
pattern_xoffset | Shift pattern along x axis | 0 | value in range [0, 1] (npc units) |
pattern_yoffset | Shift pattern along y axis | 0 | value in range [0, 1] (npc units) |
pattern_aspect_ratio | Aspect ratio adjustment | NA | usual range [0.01, 10] |
pattern_key_scale_factor | Scale factor for pattern in legend | 1 | |
pattern_filename | Image filename/URL | ’’ | Filename/URL |
pattern_gravity | Image placement | ‘center’ | ggpattern::magick_gravity_names |
pattern_filter | Image scaling filter | ‘lanczos’ | ggpattern::magick_filter_names |
pattern_scale | Scale | 1 | Multiplier |
pattern_orientation | Orientation | ‘vertical’ | ‘vertical’, ‘horizontal’, ‘radial’ |
pattern_phase | Phase | 0 | |
pattern_frequency | Frequency | 0.1 | |
pattern_option_1 - 5 | Generic options for expansion | 0 |
User-Defined Patterns
Users can write their own pattern functions and ask ggpattern
to use
them, without having to include the pattern in the package.
See the vignettes on developing patterns ( 1 2, 3 ) for how to do this, and see the vignettes on experimental patterns to see this in action ( Point filling, Hex pattern, Ambient Noise ).
Vignettes
General examples
- geom gallery (geometry-based patterns) Examples of every geom filled with the geometry-based patterns (i.e. ‘stripe’, ‘crosshatch’, ‘circle’)
- geom gallery (array-based patterns) Examples of every geom filled with the array-based patterns (i.e. ‘image’, ‘magick’, ‘gradient’, ‘plasma’, ‘placeholder’)
Exploration of pattern parameters and appearance
- Geometry-based patterns
- Array-based patterns
Developing your own pattern
- Devloping Patterns 1 - Pattern Overview
- Devloping Patterns 2 - Geometry-based pattern
- Devloping Patterns 3 - Array-based pattern
Experimental patterns
These are patterns that aren’t quite ready for prime-time. Feel free to steal the code and extend to suit your needs.
Other examples
Limitations
- Nearly always need to use
coord_fixed()
to ensure the aspect ratio is calculated correctly. Usepattern_aspect_ratio
to override the internal calculation, of for occasions where you can’t usecoord_fixed()
because a differentcoord_*()
is used. - Legend rendering for patterns is still not great.
- Use
pattern_key_scale_factor
to adjust legend appearance.
- Use
- The Rstudio output device can be quite slow for plots with lots of patterns. It is often faster to save directly to PNG or PDF and view that.
- Self intersecting geometry can be an issue.
- Non-linear coordinate systems have not been tested.
- Polygons with holes are not supported
ToDo
- Possibly add geoms from third-party sources e.g.
geom_circle()
andgeom_voronoi()
from ggforce
- A vignette on how array-based patterns are implemented.
- A vignette on why aspect ratio is hard to get right.