⚠️There's a newer version (0.4.2) of this package. Take me there.

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

  1. Take an existing plot which contains a geom with a fillable area e.g geom_col().
  2. Use the {ggpattern} version of the geom e.g. ggpattern::geom_col_pattern() instead of ggplot2::geom_col()
  3. Set the aesthetic pattern to your choice of pattern e.g pattern = 'stripe', and set other options using pattern_* 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.

ggplot2ggpattern
geom_areageom_area_pattern
geom_bargeom_bar_pattern
geom_bin2dgeom_bin2d_pattern
geom_boxplotgeom_boxplot_pattern
geom_colgeom_col_pattern
geom_crossbargeom_crossbar_pattern
geom_densitygeom_density_pattern
geom_mapgeom_map_pattern
geom_polygongeom_polygon_pattern
geom_rectgeom_rect_pattern
geom_ribbongeom_ribbon_pattern
geom_sfgeom_sf_pattern
geom_tilegeom_tile_pattern
geom_violingeom_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.

aestheticdescriptiondefaultpossible values
patternName of the pattern to draw‘stripe’stripe, crosshatch, circle, image, placeholder, magick, gradient, plasma
pattern_typeGeneric control optionNApattern-dependent
pattern_subtypeGeneric control optionNApattern-dependent
pattern_alphaAlpha1value in range [0, 1] (npc units)
pattern_linetypeStroke linetype1linetype
pattern_sizeStroke linewidth1linewidth
pattern_shapePlotting shape1shapes
pattern_colourStroke colour‘grey20’colour
pattern_fillFill colour‘grey80’colour
pattern_fill2Second fill colour‘#4169E1’colour
pattern_angleRotation angle30angle in degrees
pattern_densityApprox. fraction of area the pattern fills0.2value in range [0, 1] (fraction)
pattern_spacingSpacing between repetitions of pattern0.05value in range [0, 1] (npc units)
pattern_xoffsetShift pattern along x axis0value in range [0, 1] (npc units)
pattern_yoffsetShift pattern along y axis0value in range [0, 1] (npc units)
pattern_aspect_ratioAspect ratio adjustmentNAusual range [0.01, 10]
pattern_key_scale_factorScale factor for pattern in legend1
pattern_filenameImage filename/URL’’Filename/URL
pattern_gravityImage placement‘center’ggpattern::magick_gravity_names
pattern_filterImage scaling filter‘lanczos’ggpattern::magick_filter_names
pattern_scaleScale1Multiplier
pattern_orientationOrientation‘vertical’‘vertical’, ‘horizontal’, ‘radial’
pattern_phasePhase0
pattern_frequencyFrequency0.1
pattern_option_1 - 5Generic options for expansion0

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

Exploration of pattern parameters and appearance

Developing your own 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. Use pattern_aspect_ratio to override the internal calculation, of for occasions where you can’t use coord_fixed() because a different coord_*() is used.
  • Legend rendering for patterns is still not great.
    • Use pattern_key_scale_factor to adjust legend appearance.
  • 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() and geom_voronoi() from ggforce
  • A vignette on how array-based patterns are implemented.
  • A vignette on why aspect ratio is hard to get right.

Copy Link

Version

Down Chevron

Install

install.packages('ggpattern')

Monthly Downloads

5,798

Version

0.1.3

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Last Published

January 1st, 1970

Functions in ggpattern (0.1.3)