In coolbutuseless/ggpattern: 'ggplot2' Pattern Geoms

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(ggplot2)
library(dplyr)
library(ggpattern)


#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Generate the pkgdown documentation
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
if (FALSE) {
  pkgdown::build_site(override = list(destination = "../coolbutuseless.github.io/package/ggpattern"))
}


#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Generate a tweetable gif of a bunch of examples
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
if (FALSE) {
  png_files <- list.files("vignettes/images/", pattern = "*gallery.*png", full.names = TRUE)
  png_files <- paste(png_files, collapse = " ")
  gif_files <- gsub("png", "gif", png_files)

  command <- paste("mogrify -resize 800x600 -format gif ", png_files)
  system(command)


  command <- paste("gifsicle --colors 256 -O=100 --delay 150 o man/figures/geom-gallery.gif ", gif_files)
  print(command)
  system(command)

  command <- paste("rm", gif_files)
  system(command)
}

if (FALSE) {
  # ffmpeg -framerate 1/2 -pattern_type glob -i '*.png' -c:v libx264 -pix_fmt yuv420p -s 800x600 ../../../ggpattern-annex/demo.mp4
}

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.

# install.packages("remotes")
remotes::install_github("coolbutuseless/ggpattern")

An installation error is highly unlikely to be an issue with {ggpattern} itself. Please don't open up a Github Issues unless you are sure it is an issue with {ggpattern} itself. If you have an error installing the package we strongly suggest that you look at all your error messages more closely to figure out which package dependency is failing to install and why. See https://thomasadventure.blog/posts/install-r-packages/ for more info on installing R packages.

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 of ggplot2::geom_col()
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_col_pattern()",
    subtitle = "pattern = 'stripe'"
  ) +
  coord_fixed(ratio = 1/2)

Gallery

# Feature Details ## Available Geoms `ggpattern` includes versions of (nearly) all geoms from `ggplot2` which could plausibly support being filled with a pattern. See the vignette galleries for examples of all the available geoms filled with [geometry-based patterns](https://coolbutuseless.github.io/package/ggpattern/articles/geom-gallery-geometry.html) and [image-based/array-based patterns](https://coolbutuseless.github.io/package/ggpattern/articles/geom-gallery-array.html).

Click to show/hide list of supported geoms

| 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_histogram | geom_histogram_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](https://coolbutuseless.github.io/package/ggpattern/articles/developing-patterns-1.html#aes-by-pattern), or see the individual vignettes for each pattern.

Click to show/hide list of new aesthetics

| 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 | | | `pattern_grid` | Grid type | 'square' | 'square', 'hex', 'hex\_circle' | | `pattern_res` | Pattern resolution (pixels per inch) | NA | Resolution | | `pattern_rot` | Shape rotation angle (within pattern) | 0 | angle in degrees |

## 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 vignette on developing patterns: [`vignette("developing-patterns", package = "ggpattern")`](https://coolbutuseless.github.io/package/ggpattern/articles/developing-patterns.html). # Vignettes **Note:** due to CRAN package size limits many of these vignettes are only available in the Github version of `{ggpattern}` and the package website. #### General examples * [Examples of every geom filled with the geometry-based patterns (i.e. 'stripe', 'crosshatch', 'circle')](https://coolbutuseless.github.io/package/ggpattern/articles/geom-gallery-geometry.html): `vignette("geom-gallery-geometry", package = "ggpattern")` * [Examples of every geom filled with the array-based patterns (i.e. 'image', 'magick', 'gradient', 'plasma', 'placeholder')](https://coolbutuseless.github.io/package/ggpattern/articles/geom-gallery-array.html): `vignette("geom-gallery-geometry", package = "ggpattern")` #### Exploration of pattern parameters and appearance * [Patterns 'circle', 'pch', 'regular_polygon', 'rose' - Parameters and Examples](https://coolbutuseless.github.io/package/ggpattern/articles/patterns-points.html): `vignette("patterns-points", package = "ggpattern")` * [Patterns 'gradient', 'ambient', 'plasma' - Parameters and Examples](https://coolbutuseless.github.io/package/ggpattern/articles/patterns-noise.html): `vignette("patterns-noise", package = "ggpattern")` * [Patterns 'image' and 'placeholder' - Parameters and Examples](https://coolbutuseless.github.io/package/ggpattern/articles/patterns-image.html): `vignette("patterns-image", package = "ggpattern")` * [Patterns 'magick' and 'polygon_tiling' - Parameters and Examples](https://coolbutuseless.github.io/package/ggpattern/articles/patterns-tilings.html): `vignette("patterns-tilings", package = "ggpattern")` * [Patterns 'stripe', 'wave', 'crosshatch', 'weave' - Parameters and Examples](https://coolbutuseless.github.io/package/ggpattern/articles/patterns-stripes.html): `vignette("patterns-stripes", package = "ggpattern")` * [Parameters for Geometry-based Patterns](https://coolbutuseless.github.io/package/ggpattern/articles/geometry-based-pattern-parameters.html): `vignette("geometry-based-pattern-parameters", package = "ggpattern")` #### Developing your own pattern * [Developing Patterns](https://coolbutuseless.github.io/package/ggpattern/articles/developing-patterns.html): `vignette("developing-patterns", package = "ggpattern")` #### Other examples * [Animating Patterns with `{gganimate}`](https://coolbutuseless.github.io/package/ggpattern/articles/gganimate.html): `vignette("gganimate", package = "ggpattern")` * [Creating the Logo in R](https://coolbutuseless.github.io/package/ggpattern/articles/create-logo.html): `vignette("create-logo", package = "ggpattern")` # Limitations * Use `pattern_aspect_ratio` to override the internal aspect ratio calculation. * 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. # ToDo * Possibly add geoms from third-party sources e.g. * `geom_circle()` and `geom_voronoi()` from [ggforce](https://github.com/thomasp85/ggforce)

coolbutuseless/ggpattern documentation built on April 17, 2023, 7:47 a.m.

rdrr.io home R language documentation Run R code online

CRAN packages Bioconductor packages R-Forge packages GitHub packages

Note that we can't provide technical support on individual packages. You should contact the package authors for that.

Tweet to @rdrrHQ

GitHub issue tracker

ian@mutexlabs.com