Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/trevorld/ggpattern
ggplot geoms with pattern fills
https://github.com/trevorld/ggpattern
Last synced: 6 days ago
JSON representation
ggplot geoms with pattern fills
- Host: GitHub
- URL: https://github.com/trevorld/ggpattern
- Owner: trevorld
- License: other
- Created: 2020-03-31T09:49:37.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-23T23:37:21.000Z (about 1 year ago)
- Last Synced: 2024-04-14T13:52:41.842Z (10 months ago)
- Language: R
- Homepage: https://coolbutuseless.github.io/package/ggpattern/index.html
- Size: 18.8 MB
- Stars: 343
- Watchers: 10
- Forks: 18
- Open Issues: 20
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
- awesome-r-dataviz - ggpattern - ggplot geoms with pattern fills. (ggplot / Additional Plot Types)
README
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library("dplyr")
library("ggplot2")
library("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 
[](https://cran.r-project.org/package=ggpattern)
[](https://github.com/trevorld/ggpattern/actions)
`ggpattern` provides custom `ggplot2` geoms which support filled areas with
geometric and image-based patterns.
Reading the articles/vignettes on [the package website](https://trevorldavis.com/R/ggpattern/dev/) 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 [R-universe](https://trevorld.r-universe.dev/ggpattern)
``` r
install.packages('ggpattern', repos = c('https://trevorld.r-universe.dev', 'https://cloud.r-project.org'))
```
or straight from the source hosted on Github using the `{remotes}` package:
``` r
# install.packages("remotes")
remotes::install_github("trevorld/ggpattern")
```
You can install the CRAN release version using:
```r
install.packages("ggpattern")
```
Do note though that due to CRAN size limitations **the CRAN version omits several vignettes** that are contained in the development version (as well as on the [package website](https://trevorldavis.com/R/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
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
```{r fig.width = 8, fig.height = 4, fig.cap = "", fig.alt= "A bar chart with striped bars"}
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://trevorldavis.com/R/ggpattern/dev/articles/geom-gallery-geometry.html) and
[image-based/array-based patterns](https://trevorldavis.com/R/ggpattern/dev/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://trevorldavis.com/R/ggpattern/dev/articles/developing-patterns.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://trevorldavis.com/R/ggpattern/dev/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://trevorldavis.com/R/ggpattern/dev/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://trevorldavis.com/R/ggpattern/dev/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://trevorldavis.com/R/ggpattern/dev/articles/patterns-points.html): `vignette("patterns-points", package = "ggpattern")`
* [Patterns 'gradient', 'ambient', 'plasma' - Parameters and Examples](https://trevorldavis.com/R/ggpattern/dev/articles/patterns-noise.html): `vignette("patterns-noise", package = "ggpattern")`
* [Patterns 'image' and 'placeholder' - Parameters and Examples](https://trevorldavis.com/R/ggpattern/dev/articles/patterns-image.html): `vignette("patterns-image", package = "ggpattern")`
* [Patterns 'magick' and 'polygon_tiling' - Parameters and Examples](https://trevorldavis.com/R/ggpattern/dev/articles/patterns-tilings.html): `vignette("patterns-tilings", package = "ggpattern")`
* [Patterns 'stripe', 'wave', 'crosshatch', 'weave' - Parameters and Examples](https://trevorldavis.com/R/ggpattern/dev/articles/patterns-stripes.html): `vignette("patterns-stripes", package = "ggpattern")`
* [Parameters for Geometry-based Patterns](https://trevorldavis.com/R/ggpattern/dev/articles/geometry-based-pattern-parameters.html): `vignette("geometry-based-pattern-parameters", package = "ggpattern")`
#### Developing your own pattern
* [Developing Patterns](https://trevorldavis.com/R/ggpattern/dev/articles/developing-patterns.html): `vignette("developing-patterns", package = "ggpattern")`
#### Other examples
* [Animating Patterns with `{gganimate}`](https://trevorldavis.com/R/ggpattern/dev/articles/gganimate.html): `vignette("gganimate", package = "ggpattern")`
* [Creating the Logo in R](https://trevorldavis.com/R/ggpattern/dev/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.