Need help with ggpattern?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

coolbutuseless
169 Stars 5 Forks MIT License 11 Commits 12 Opened issues

Description

ggplot geoms with pattern fills

Services available

!
?

Need anything else?

Contributors list

# 202,104
R
Shell
C++
data-vi...
11 commits

ggpattern

R build
status <!-- badges: end -->

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 

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.

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_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.

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

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.