Repository Mirror for your Cloud Server and Webhosting

Title:

Grammar-Native Hand-Drawn Geoms for 'ggplot2'

Version:

2.0.0

Description:

Provides 'ggplot2' geoms that render with a hand-drawn, sketchy aesthetic: roughened strokes, double-pass lines, and hachure, cross-hatch, zigzag, and dots fill patterns. Implemented as pure-R 'grid' grobs wrapped in 'ggproto' geoms, composable with aes(), stats, scales, and faceting. Works on every R graphics device (PDF, PNG, SVG, screen) with no browser dependency. Algorithms are reimplemented from the published 'rough.js' algorithm description (Shihn, 2020, https://shihn.ca/posts/2020/roughjs-algorithms/) and Wood and others (2012, <doi:10.1109/TVCG.2012.262>); see the NOTICE file in the package sources for attribution.

License:

MIT + file LICENSE

URL:

https://github.com/orijitghosh/ggsketch, https://orijitghosh.github.io/ggsketch/

BugReports:

https://github.com/orijitghosh/ggsketch/issues

Depends:

R (≥ 4.1.0)

Imports:

cli (≥ 3.4.0), ggplot2 (≥ 3.5.0), grDevices, grid, rlang (≥ 1.0.0), scales (≥ 1.2.0), withr (≥ 2.5.0)

Suggests:

gganimate, gifski, hexbin, igraph, knitr, magick, MASS, patchwork, quantreg, ragg, rmarkdown, sf, svglite, systemfonts, testthat (≥ 3.0.0), vdiffr (≥ 1.0.0)

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

NeedsCompilation:

Config/roxygen2/version:

8.0.0

Packaged:

2026-07-09 01:21:33 UTC; ariji

Author:

Arijit Ghosh [aut, cre]

Maintainer:

Arijit Ghosh <arijitghosh2009@gmail.com>

Repository:

CRAN

Date/Publication:

2026-07-17 14:00:07 UTC

ggsketch: Grammar-Native Hand-Drawn Geoms for 'ggplot2'

Description

Provides 'ggplot2' geoms that render with a hand-drawn, sketchy aesthetic: roughened strokes, double-pass lines, and hachure, cross-hatch, zigzag, and dots fill patterns. Implemented as pure-R 'grid' grobs wrapped in 'ggproto' geoms, composable with aes(), stats, scales, and faceting. Works on every R graphics device (PDF, PNG, SVG, screen) with no browser dependency. Algorithms are reimplemented from the published 'rough.js' algorithm description (Shihn, 2020, https://shihn.ca/posts/2020/roughjs-algorithms/) and Wood and others (2012, doi:10.1109/TVCG.2012.262); see the NOTICE file in the package sources for attribution.

Author(s)

Maintainer: Arijit Ghosh arijitghosh2009@gmail.com

Authors:

Arijit Ghosh arijitghosh2009@gmail.com

A hand-drawn coordinate system

Description

A drop-in replacement for ggplot2::coord_cartesian() that draws the frame hand-drawn: the panel gridlines and axis ticks are rendered as roughened sketch grobs, so the frame matches the marks – under any theme, not only theme_sketch(). It reuses ggplot2's own gridline and axis layout and only swaps how those elements are drawn, so limits, expansion, and clipping behave exactly like coord_cartesian().

Usage

coord_sketch(
  xlim = NULL,
  ylim = NULL,
  expand = TRUE,
  default = FALSE,
  clip = "on",
  roughness = 0.5,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  rough_grid = TRUE,
  rough_ticks = TRUE
)

Arguments

xlim, ylim

Limits for the x and y axes (as in ggplot2::coord_cartesian()).

expand

If TRUE (default), add the standard expansion around the data.

default

Is this the default coordinate system? Default FALSE.

clip

Should drawing be clipped to the panel ("on", default) or not ("off")?

roughness, bowing, n_passes

Sketch parameters for the frame. Gentle defaults suited to gridlines (0.5, 0.5, 2).

seed

Integer seed for reproducible wobble. NULL uses getOption("ggsketch.seed", 1L).

rough_grid, rough_ticks

Roughen the gridlines / axis ticks? Both default TRUE; set one to FALSE to leave that element crisp.

Details

The panel border is a plot-level theme element (not part of the coordinate system), so to roughen it as well, combine coord_sketch() with theme_sketch(rough_frame = TRUE) or set panel.border = element_sketch_rect(...).

Value

A ggproto Coord object to add to a plot.

Examples

library(ggplot2)
# A rough frame under a plain (non-sketch) theme:
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  coord_sketch(seed = 1L)

A hand-drawn polar coordinate system

Description

The polar companion to coord_sketch(): a drop-in replacement for ggplot2::coord_polar() that draws the circular grid hand-drawn. The radial and angular gridlines are rendered as roughened sketch grobs, so pie/rose charts and circular bar plots get a frame that matches the marks – under any theme. It reuses all of ggplot2's polar layout and only swaps how the grid is drawn.

Usage

coord_sketch_polar(
  theta = "x",
  start = 0,
  direction = 1,
  clip = "on",
  roughness = 0.5,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  rough_grid = TRUE
)

Arguments

theta

Variable mapped to angle ("x" or "y"). Default "x".

start

Offset of the starting point, in radians. Default 0.

direction

1 clockwise, -1 anticlockwise. Default 1.

clip

Should drawing be clipped to the panel ("on", default) or not ("off")?

roughness, bowing, n_passes

Sketch parameters for the grid. Gentle defaults suited to gridlines (0.5, 0.5, 2).

seed

Integer seed for reproducible wobble. NULL uses getOption("ggsketch.seed", 1L).

rough_grid

Roughen the gridlines? Default TRUE.

Value

A ggproto Coord object to add to a plot.

Examples

library(ggplot2)
df <- data.frame(g = c("a", "b", "c", "d"), v = c(3, 5, 2, 4))
# A hand-drawn circular bar (rose) chart:
ggplot(df, aes(g, v, fill = g)) +
  geom_sketch_col(seed = 1L) +
  coord_sketch_polar(seed = 1L) +
  theme_sketch()

Sketchy reference lines

Description

Hand-drawn abline / hline / vline reference lines that span the panel - the sketch analogues of ggplot2::geom_abline(), ggplot2::geom_hline(), and ggplot2::geom_vline(). As with ggplot2, you usually pass the intercepts as arguments rather than mapping them.

Usage

GeomSketchAbline

GeomSketchHline

GeomSketchVline

geom_sketch_abline(
  mapping = NULL,
  data = NULL,
  ...,
  slope,
  intercept,
  roughness = 0.6,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA
)

geom_sketch_hline(
  mapping = NULL,
  data = NULL,
  ...,
  yintercept,
  roughness = 0.6,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA
)

geom_sketch_vline(
  mapping = NULL,
  data = NULL,
  ...,
  xintercept,
  roughness = 0.6,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA
)

Arguments

mapping, data, ...

Standard layer arguments. Usually omitted in favour of the intercept arguments below.

slope, intercept

For geom_sketch_abline().

roughness, bowing, n_passes, seed

Sketch parameters. Reference lines default to a gentle roughness = 0.6.

na.rm, show.legend

Standard layer arguments.

yintercept

For geom_sketch_hline().

xintercept

For geom_sketch_vline().

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  geom_sketch_hline(yintercept = 20, colour = "red", seed = 2L) +
  geom_sketch_vline(xintercept = 3, colour = "blue", seed = 3L) +
  theme_sketch()

Sketchy content-aware arrows

Description

Draws a hand-drawn arrow from ⁠(x, y)⁠ to ⁠(xend, yend)⁠, with an optional handwriting label at the source. It is "content-aware" in three ways:

Usage

GeomSketchArrow

geom_sketch_arrow(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  curvature = "auto",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  arrow_length = NULL,
  arrow_angle = 25,
  arrow_type = "open",
  arrow_head = NULL,
  ends = "last",
  family = NULL,
  label_gap = 0.012,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x, y, xend, yend; label is optional.

data

Data with one row per arrow.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

curvature

Shaft bend. "auto" (default) picks a gentle bow; a number sets it explicitly (0 straight, positive/negative bow to either side).

roughness

Non-negative roughness (0 = clean). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

arrow_length

Arrowhead length in inches. NULL (default) adapts it to the shaft length.

arrow_angle

Half-angle of the arrowhead in degrees. Default 25.

arrow_type

"open" (default) draws a two-stroke V; "closed" draws a filled rough triangle. Superseded by arrow_head; kept for back-compat.

arrow_head

Arrowhead style, one of sketch_arrowheads(): "triangle_open", "triangle_filled", "barb" (swept harpoon barbs), "fishtail" (forked swallowtail), "dot" (a blob) or "bar" (a perpendicular tick). NULL (default) derives it from arrow_type.

ends

Which end(s) carry a head: "last" (default), "first" or "both" (a double-headed arrow).

family

Font family for the label. Defaults to the same family as theme_sketch() (getOption("ggsketch.base_family", ""), i.e. the device default), so the label matches the plot's other text; set options(ggsketch.base_family = "auto") for a handwriting face, or pass an explicit family here.

label_gap

Gap between the label anchor and the source point, in npc. Default 0.012.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend? Default FALSE.

inherit.aes

Inherit aesthetics from the plot? Default TRUE.

Details

the shaft curvature defaults to an automatic, pleasing bow whose side follows the direction of travel (curvature = "auto");
the arrowhead is roughened and oriented to the curve's end tangent, so it always points at the target however the shaft bends;
the label justifies itself away from the target, so it never sits under the shaft.

For one-off annotations, annotate_sketch_arrow() is the easiest entry point.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  annotate_sketch_arrow(x = 4.5, y = 30, xend = 5.25, yend = 18,
                        label = "heavy & thirsty", seed = 2L) +
  theme_sketch()

Sketchy boxplot

Description

A hand-drawn box-and-whisker plot: a roughened IQR box, a thick median line, rough whiskers, and sketchy outlier points. Uses ggplot2::stat_boxplot() for the five-number summary - the sketch analogue of ggplot2::geom_boxplot().

Usage

GeomSketchBoxplot

geom_sketch_boxplot(
  mapping = NULL,
  data = NULL,
  stat = "boxplot",
  position = "dodge2",
  ...,
  roughness = 0.8,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  outliers = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "boxplot".

position

Position adjustment. Default "dodge2".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness. Default 0.8 (boxes read cleaner).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Box fill style. Default "solid". The box is outline-only until you give it a fill (the default fill is NA); set fill for a solid box, or use e.g. fill_style = "hachure" with a fill for shaded boxes.

hachure_angle, hachure_gap, fill_weight

Fill parameters.

outliers

Draw outlier points? Default TRUE.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mpg, aes(class, hwy)) +
  geom_sketch_boxplot(seed = 1L) +
  theme_sketch()

Sketchy significance / comparison brackets

Description

Draws a hand-drawn bracket spanning xmin to xmax at height y, with short tips dropping toward the data and an optional label (e.g. a p-value or "n.s.") centred above. It is the sketch counterpart of a ggsignif bracket: useful for marking pairwise comparisons on boxplots, bars, or violins.

Usage

GeomSketchBracket

geom_sketch_bracket(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  tip_length = 0.02,
  family = NULL,
  label_vjust = -0.35,
  roughness = 0.8,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = FALSE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires xmin, xmax, and y; label is optional.

data

Data with one row per bracket.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

tip_length

Length of the downward end tips, as a fraction of panel height. Default 0.02. Use 0 for a plain bar.

family

label_vjust

Vertical justification of the label relative to the bar (negative nudges it above). Default -0.35.

roughness

Non-negative roughness (0 = straight). Default 0.8.

bowing

Non-negative bowing multiplier. Default 0.4 (kept low so the bar stays readable).

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend? Default FALSE.

inherit.aes

Inherit aesthetics from the plot? Default FALSE.

Details

Brackets are usually one-off annotations, so supply them with their own data and inherit.aes = FALSE rather than inheriting the plot's mapping.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
brackets <- data.frame(xmin = 1, xmax = 2, y = 45, label = "p = 0.01")
ggplot(mpg, aes(drv, hwy)) +
  geom_sketch_boxplot(seed = 1L) +
  geom_sketch_bracket(
    data = brackets,
    aes(xmin = xmin, xmax = xmax, y = y, label = label),
    family = "", seed = 2L
  ) +
  theme_sketch()

Sketchy callouts (boxed labels with a leader arrow)

Description

Draws a handwriting label inside a roughened rounded box, optionally with a hand-drawn leader arrow pointing from the box to a target ⁠(xend, yend)⁠. The box auto-sizes to the label, and the leader leaves from the box edge nearest the target. The sketch take on a speech-bubble / callout annotation.

Usage

GeomSketchCallout

geom_sketch_callout(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 0.6,
  n_passes = 2L,
  seed = NULL,
  padding = 0.06,
  corner_radius = 0.3,
  arrow_length = NULL,
  arrow_angle = 25,
  arrow_head = NULL,
  leader = "straight",
  curvature = 0.3,
  family = NULL,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x, y, and label; map xend/yend to add a leader arrow to a target.

data

Data with one row per callout.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = clean). Default 1.

bowing

Non-negative bowing multiplier. Default 0.6.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

padding

Box padding around the label, in inches. Default 0.06.

corner_radius

Box corner rounding (fraction of half-side). Default 0.3.

arrow_length

Leader arrowhead length in inches. NULL (default) adapts it to the leader length.

arrow_angle

Half-angle of the leader arrowhead in degrees. Default 25.

arrow_head

Leader head style, one of sketch_arrowheads(). NULL (default) draws the open V.

leader

Leader routing: "straight" (default), "elbow" (horizontal then vertical, flowchart style) or "curved" (a bowed Bezier).

curvature

Bow size when leader = "curved". Default 0.3.

family

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend? Default FALSE.

inherit.aes

Inherit aesthetics from the plot? Default TRUE.

Details

For one-off annotations, annotate_sketch_callout() is the easiest entry point.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  annotate_sketch_callout(x = 4, y = 32, label = "outlier?",
                          xend = 5.25, yend = 18, seed = 2L) +
  theme_sketch()

Sketchy chicklet chart

Description

Draws a stacked bar whose segments are separately rounded "chicklets" with a small gap between them – the hand-drawn take on ggchicklet::geom_chicklet() (cf. ggchicklet). It is geom_sketch_col() with rounded corners on, a segment_gap inset between stacked segments, and a solid fill by default. As with ggchicklet, add ggplot2::coord_flip() for the classic horizontal layout.

Usage

GeomSketchChicklet

geom_sketch_chicklet(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "stack",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  width = NULL,
  corner_radius = 0.5,
  segment_gap = 0.02,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity" for geom_sketch_col(); "count" for geom_sketch_bar().

position

Position adjustment. Default "stack".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight lines). A mappable aesthetic (default 1): pass a constant, or map it per bar with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Fill style; see geom_sketch_col(). Default "solid" for the flat chicklet look; pass "hachure" etc. for a sketchier fill.

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the bar's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

width

Bar width override. NULL uses 90% of resolution.

corner_radius

Corner rounding as a fraction [0, 1] of each half-side. Default 0.5; 0 gives square segments.

segment_gap

Gap between stacked segments, as a fraction of the panel's total drawn height. Default 0.02; 0 stacks the pills flush.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- expand.grid(week = factor(1:4), team = c("A", "B", "C"))
df$pct <- c(4, 3, 2, 5, 3, 4, 5, 2, 3, 3, 3, 4)
ggplot(df, aes(week, pct, fill = team)) +
  geom_sketch_chicklet(seed = 1L) +
  coord_flip() +
  theme_sketch()

Sketchy column / bar geom

Description

Draws vertical bars with a hand-drawn roughened outline and an optional hachure, cross-hatch, zigzag, dots, or dashed fill pattern. Use geom_sketch_col() when the bar heights are already in the data; use geom_sketch_bar() to count observations automatically.

Usage

GeomSketchCol

geom_sketch_col(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "stack",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  width = NULL,
  corner_radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_bar(
  mapping = NULL,
  data = NULL,
  stat = "count",
  position = "stack",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  width = NULL,
  corner_radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity" for geom_sketch_col(); "count" for geom_sketch_bar().

position

Position adjustment. Default "stack".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight lines). A mappable aesthetic (default 1): pass a constant, or map it per bar with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the bar's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

width

Bar width override. NULL uses 90% of resolution.

corner_radius

Corner rounding as a fraction [0, 1] of each half-side. 0 (default) is square; a small value (e.g. 0.2) gives gently rounded bars.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = c("A","B","C","D"), y = c(3, 5, 2, 6))
ggplot(df, aes(x, y)) +
  geom_sketch_col(fill_style = "hachure", seed = 1L) +
  theme_sketch()

Sketchy filled contour and 2-D density bands

Description

geom_sketch_contour_filled() draws hand-drawn filled contour bands of a surface (the sketch analogue of ggplot2::geom_contour_filled()); it needs x, y, and z. geom_sketch_density_2d_filled() fills the bands of a 2-D kernel density estimate (ggplot2::geom_density_2d_filled()); it needs x and y and uses MASS.

Usage

GeomSketchContourFilled

geom_sketch_contour_filled(
  mapping = NULL,
  data = NULL,
  stat = "contour_filled",
  position = "identity",
  ...,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.04,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_density_2d_filled(
  mapping = NULL,
  data = NULL,
  stat = "density_2d_filled",
  position = "identity",
  ...,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.04,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_density2d_filled(
  mapping = NULL,
  data = NULL,
  stat = "density_2d_filled",
  position = "identity",
  ...,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.04,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

bins

Number of contour bins. Overridden by binwidth or breaks.

binwidth

Distance between contour bins.

breaks

Explicit numeric contour breaks; overrides bins/binwidth.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Band fill: "solid" (default), "hachure", or "cross_hatch". Other styles degrade to "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap (npc fraction). Default 0.04.

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Details

Unlike the contour line geoms, each band is a region that may contain holes (the next level up, cut out). The fill is painted with a hole-aware scan-line so the holes stay empty, even for fill_style = "hachure".

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithfuld, aes(waiting, eruptions, z = density)) +
  geom_sketch_contour_filled(seed = 1L) +
  theme_sketch()

Sketchy curved connector

Description

Draws a hand-drawn curved segment from ⁠(x, y)⁠ to ⁠(xend, yend)⁠ - the sketch analogue of ggplot2::geom_curve(). The curve is a quadratic Bezier whose bend is controlled by curvature.

Usage

GeomSketchCurve

geom_sketch_curve(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  curvature = 0.5,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

curvature

Amount of bend. 0 is a straight line; positive curves to one side, negative to the other. Default 0.5.

roughness

Non-negative roughness (0 = straight). Default 1. For geom_sketch_segment() this is a mappable aesthetic (map it per segment with aes(roughness = ), rescaled by scale_roughness_continuous()); for geom_sketch_step() it is a layer parameter (one path per group).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = 1, y = 1, xend = 3, yend = 3)
ggplot(df, aes(x, y)) +
  geom_sketch_curve(aes(xend = xend, yend = yend), curvature = 0.4,
                    seed = 1L) +
  theme_sketch()

Sketchy dot plot

Description

Draws a hand-drawn Wilkinson-style dot plot: the data are binned along x into fixed-width bins, and one roughened circular dot per observation is stacked upward in each bin. The sketch analogue of ggplot2::geom_dotplot().

Usage

GeomSketchDotplot

geom_sketch_dotplot(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  binwidth = NULL,
  dotsize = 1,
  stackratio = 1,
  stackdir = "up",
  roughness = 0.6,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

binwidth

Bin width in data units. NULL (default) uses 1/30 of the data range.

dotsize

Dot diameter as a multiple of the bin width. Default 1.

stackratio

Vertical spacing between stacked dots, as a fraction of the dot diameter. Default 1.

stackdir

Stacking direction. Only "up" is currently supported.

roughness

Non-negative dot roughness. Default 0.6.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Details

As in ggplot2::geom_dotplot(), the dots are sized by the bin width and the y axis (the per-bin count) is only approximate; turn it off with scale_y_continuous(NULL, breaks = NULL) for a clean look.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions)) +
  geom_sketch_dotplot(binwidth = 0.12, fill = "#7BAFD4", seed = 1L) +
  scale_y_continuous(NULL, breaks = NULL) +
  theme_sketch()

Sketchy dumbbell chart

Description

Draws a hand-drawn dumbbell: a roughened connector from x to xend on a shared y, capped with a sketch point at each end. Ideal for showing the change or gap between two paired values per category (cf. ggalt::geom_dumbbell()).

Usage

GeomSketchDumbbell

geom_sketch_dumbbell(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  colour_x = NULL,
  colour_xend = NULL,
  roughness = 0.6,
  point_roughness = 0.4,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x, xend and y.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

colour_x

Colour of the dot at x. Default NULL (uses colour).

colour_xend

Colour of the dot at xend. Default NULL (uses colour).

roughness

Connector roughness (0 = straight). Default 0.6.

point_roughness

Roughness of the end dots. Default 0.4.

bowing

Non-negative bowing multiplier. Default 0.4.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(g = c("Alpha", "Bravo", "Charlie", "Delta"),
                 before = c(20, 35, 28, 42),
                 after  = c(34, 51, 22, 47))
ggplot(df, aes(x = before, xend = after, y = g)) +
  geom_sketch_dumbbell(colour_x = "#B03A2E", colour_xend = "#1F618D",
                       seed = 1L) +
  theme_sketch()

Sketchy network edges and nodes

Description

A hand-drawn take on network/graph plotting. geom_sketch_edge() draws a roughened connector between ⁠(x, y)⁠ and ⁠(xend, yend)⁠; geom_sketch_node() draws roughened node markers with optional handwriting labels. Pair them with sketch_graph(), which computes node positions with a pure-R force-directed layout (force_layout()) and returns the two data frames these geoms expect - no graph package required.

Usage

GeomSketchEdge

geom_sketch_edge(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  curvature = 0,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

GeomSketchNode

geom_sketch_node(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = NULL,
  n_passes = 2L,
  seed = NULL,
  label_size = 3.2,
  label_colour = "grey15",
  label_family = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes().

data

Data to display. For geom_sketch_edge() the rows need x/y/xend/yend; for geom_sketch_node() they need x/y (and an optional label). Typically the ⁠$edges⁠ and ⁠$nodes⁠ from sketch_graph().

stat, position

Statistical transformation and position adjustment. Default "identity" for both.

...

Other arguments passed on to the layer.

curvature

Edge bend. 0 (default) draws straight roughened edges; non-zero gives arc edges (a quadratic Bezier), like geom_sketch_curve().

roughness, bowing, n_passes, seed

Sketch parameters; see geom_sketch_path(). For geom_sketch_node(), roughness is a mappable aesthetic (per node).

na.rm

Remove missing values silently? Default FALSE.

show.legend, inherit.aes

Standard layer arguments.

label_size

Handwriting label size (mm). Default 3.2.

label_colour

Label colour. Default "grey15".

label_family

Label font family. Defaults to the first installed handwriting face (as geom_sketch_text() uses).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
edges <- data.frame(
  from = c("A", "A", "B", "C", "C", "D"),
  to   = c("B", "C", "C", "D", "E", "E")
)
g <- sketch_graph(edges, seed = 1L)
ggplot() +
  geom_sketch_edge(data = g$edges,
                   aes(x = x, y = y, xend = xend, yend = yend), seed = 1L) +
  geom_sketch_node(data = g$nodes,
                   aes(x = x, y = y, label = name), size = 6, seed = 2L) +
  coord_equal() +
  theme_void()

Sketchy circle and ellipse geoms

Description

geom_sketch_circle() draws roughened circles of radius r (data units); geom_sketch_ellipse() draws ellipses with semi-axes a (x) and b (y). Radii are in data units, so on a non-square panel a circle appears elliptical - use ggplot2::coord_equal() for true circles. These are annotation-style geoms (cf. ggforce::geom_circle()).

Usage

GeomSketchEllipse

GeomSketchCircle

geom_sketch_circle(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_ellipse(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes(). geom_sketch_circle() needs x, y, r; geom_sketch_ellipse() needs x, y, a, b.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = clean). A mappable aesthetic (default 1): pass a constant, or map it per shape with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Fill style when fill is mapped: "hachure", "cross_hatch", "zigzag", "scribble", "dots", "dashed", "stipple", "pencil_shade". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap (npc fraction, scaled by radius). Default 0.07.

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = c(1, 3), y = c(1, 2), r = c(0.5, 1))
ggplot(df, aes(x, y, r = r)) +
  geom_sketch_circle(fill = "gold", seed = 1L) +
  coord_equal() + theme_sketch()

Sketchy engraving: tonal shading by hatch-line density

Description

geom_sketch_engrave() shades a surface the way an etcher or banknote engraver does: continuous tone is built from the density of hand-drawn hatch lines, with cross-hatching deepening the shadows. It takes a regular grid of x, y, and z (like ggplot2::geom_raster()); z is mapped to tone (high = dark by default). Unlike the fill-pattern packages, the tone is computed from geometry (a engrave_fill() ladder), not tiled from a motif.

Usage

GeomSketchEngrave

GeomSketchShade

geom_sketch_engrave(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  levels = 5L,
  base_gap = 0.08,
  gap_ratio = 0.62,
  base_angle = 45,
  cross_after = 3L,
  reverse = FALSE,
  roughness = 0.5,
  bowing = 0.3,
  min_gap_in = 0.012,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_shade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  levels = 5L,
  base_gap = 0.08,
  gap_ratio = 0.62,
  base_angle = 45,
  cross_after = 3L,
  roughness = 0.5,
  bowing = 0.3,
  min_gap_in = 0.012,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). geom_sketch_engrave() needs x, y, z; geom_sketch_shade() needs x, y and uses the tone aesthetic (default 0.6).

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

levels

Number of hatch layers in the ladder. Default 5.

base_gap

Pitch of the sparsest layer (npc-x fraction). Default 0.08.

gap_ratio

Multiplicative pitch shrink per layer (smaller = densens faster). Default 0.62.

base_angle

Angle of the first hatch layer (degrees). Default 45.

cross_after

Layer index at which cross-hatching begins. Default 3.

reverse

(geom_sketch_engrave() only) Invert the tone mapping so low z is dark. Default FALSE.

roughness

Non-negative stroke roughness. Default 0.5.

bowing

Non-negative bowing multiplier. Default 0.3.

min_gap_in

Pitch floor in inches; finer ladder layers are dropped. Default 0.012.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Details

geom_sketch_shade() shades each polygon region with a uniform density set by a tone aesthetic in ⁠[0, 1]⁠, so a mapped value reads directly as darkness – a hand-drawn alternative to a solid fill scale.

The hatch ladder is a stack of layers of increasing density and rotating angle (levels, base_gap, gap_ratio, base_angle, cross_after); each layer is drawn only where the tone reaches its threshold, so light areas keep the sparse base layer and shadows accumulate every layer. min_gap_in is a pitch floor (inches) that keeps the darkest tones from exploding into a runaway number of strokes.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithfuld, aes(waiting, eruptions, z = density)) +
  geom_sketch_engrave(seed = 1L) +
  theme_sketch()

# A real surface: an engraved relief map of Maungawhau (Mt Eden),
# the way a 19th-century atlas shades elevation by hatch density.
volcano_df <- expand.grid(
  easting  = seq_len(nrow(volcano)),
  northing = seq_len(ncol(volcano))
)
volcano_df$height <- as.vector(volcano)

ggplot(volcano_df, aes(easting, northing, z = height)) +
  geom_sketch_engrave(
    levels = 8L, base_gap = 0.04, gap_ratio = 0.72,
    roughness = 0.35, bowing = 0.2, seed = 1L
  ) +
  coord_equal() +
  labs(title = "Maungawhau", subtitle = "engraved by elevation") +
  theme_sketch()

Sketchy Gantt / timeline chart

Description

Draws a hand-drawn Gantt chart: one roughened bar per task from x (start) to xend (end) on a discrete y – the whiteboard project-planning look. Map an optional progress aesthetic (0 to 1) to overlay a slimmer, darker solid bar over the completed fraction of each task. Works with dates, date-times or plain numbers on the x axis, and with every fill_style (including "watercolor"); corner_radius rounds the bar ends.

Usage

GeomSketchGantt

geom_sketch_gantt(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  height = 0.55,
  progress_shade = 0.65,
  corner_radius = 0.15,
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x, xend and y; optionally progress (completed fraction, 0-1).

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

height

Bar height in y units. Default 0.55.

progress_shade

Channel multiplier (< 1 darkens) for the progress overlay's fill. Default 0.65.

corner_radius

Corner rounding of the bars; see geom_sketch_rect(). Default 0.15.

fill_style

Bar fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
plan <- data.frame(
  task  = factor(c("Design", "Build", "Test", "Ship"),
                 levels = rev(c("Design", "Build", "Test", "Ship"))),
  start = as.Date(c("2026-01-05", "2026-01-19", "2026-02-09", "2026-02-23")),
  end   = as.Date(c("2026-01-23", "2026-02-13", "2026-02-27", "2026-03-06")),
  done  = c(1, 0.7, 0.25, 0)
)
ggplot(plan, aes(x = start, xend = end, y = task, fill = task,
                 progress = done)) +
  geom_sketch_gantt(seed = 1L, show.legend = FALSE) +
  theme_sketch()

Sketchy hexagonal heatmap

Description

Bins data into hexagons and draws each as a hand-drawn hexagon shaded by count - the sketch analogue of ggplot2::geom_hex() / ggplot2::stat_bin_hex(). Requires the optional hexbin package.

Usage

GeomSketchHex

geom_sketch_hex(
  mapping = NULL,
  data = NULL,
  stat = "binhex",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity" for geom_sketch_col(); "count" for geom_sketch_bar().

position

Position adjustment. Default "stack".

...

Other arguments passed on to the layer.

bins

Number of hexagons in each direction. Default 30.

binwidth

Hexagon width(s); overrides bins when supplied.

roughness

Non-negative roughness (0 = straight lines). A mappable aesthetic (default 1): pass a constant, or map it per bar with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the bar's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
if (requireNamespace("hexbin", quietly = TRUE)) {
  ggplot(faithful, aes(eruptions, waiting)) +
    geom_sketch_hex(bins = 12, seed = 1L) +
    scale_fill_viridis_c() +
    theme_sketch()
}

Sketchy line geom

Description

Draws a roughened line connecting points in order of x. Equivalent to geom_line() with a sketch aesthetic.

Usage

GeomSketchLine

geom_sketch_line(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  medium = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

medium

Drawing medium for the stroke: one of sketch_media() ("pen", "ink", "fountain_pen", "ballpoint", "brush", "pencil", "charcoal", "pastel", "chalk", "marker", "highlighter", "crayon", "spray"). NULL (default) uses "pen", the classic constant-width double stroke; most others render through the variable-width stroke_ribbon() engine (tapered ink, brushy swells, grainy pencil/charcoal, dusty chalk, a translucent highlighter band, ...), and "spray" renders as a soft airbrush dot cloud (sketch_spray_grob()). medium is also a mappable aesthetic: map it with aes(medium = ) (one medium per group) and control the mapping with scale_medium_discrete().

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer (a LayerInstance object) that can be added to a plot with +.

Examples

library(ggplot2)
ggplot(economics, aes(date, unemploy)) +
  geom_sketch_line(roughness = 1, seed = 1L)

Sketchy interval geoms

Description

Hand-drawn uncertainty intervals at each x: geom_sketch_linerange() draws a vertical range from ymin to ymax; geom_sketch_pointrange() adds a point at y; geom_sketch_errorbar() adds end caps; geom_sketch_crossbar() draws a rough box with a line at y. Sketch analogues of ggplot2::geom_linerange() and friends. Vertical orientation only in this release.

Usage

GeomSketchLinerange

GeomSketchPointrange

GeomSketchErrorbar

GeomSketchCrossbar

geom_sketch_linerange(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 0.7,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_pointrange(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  fatten = 4,
  roughness = 0.7,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_errorbar(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  width = 0.5,
  roughness = 0.7,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_crossbar(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  width = 0.5,
  roughness = 0.7,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping, data, stat, position, na.rm, show.legend, inherit.aes, ...

Standard layer arguments.

roughness, bowing, n_passes, seed

Sketch parameters.

fatten

For pointrange, multiply the point size by this factor.

width

For errorbar/crossbar, the cap/box width in data units.

fill_style, hachure_angle, hachure_gap, fill_weight

Fill parameters for the crossbar box.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = c("a", "b", "c"), y = c(2, 5, 4),
                 lo = c(1, 4, 2.5), hi = c(3, 6, 5.5))
ggplot(df, aes(x, y)) +
  geom_sketch_pointrange(aes(ymin = lo, ymax = hi), seed = 1L) +
  theme_sketch()

Sketchy lollipop chart

Description

Draws a hand-drawn lollipop: a roughened stem from a baseline to each value, capped with a sketch point. A tidy alternative to bars for ranked or sparse values (cf. ggalt::geom_lollipop()).

Usage

GeomSketchLollipop

geom_sketch_lollipop(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  baseline = 0,
  horizontal = FALSE,
  roughness = 0.8,
  point_roughness = 0.4,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and y.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

baseline

Value the stems grow from. Default 0.

horizontal

If TRUE, stems run horizontally from baseline on the x-axis (pair with a discrete y). Default FALSE.

roughness

Stem roughness (0 = straight). Default 0.8.

point_roughness

Roughness of the head points. Default 0.4.

bowing

Non-negative bowing multiplier. Default 0.4 (kept low so tall stems read straight).

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(g = c("Alpha", "Bravo", "Charlie", "Delta"),
                 v = c(34, 51, 22, 47))
ggplot(df, aes(g, v)) +
  geom_sketch_lollipop(colour = "#7B241C", seed = 1L) +
  theme_sketch()

Sketchy bounding marks around point groups

Description

Draw a hand-drawn bounding shape around each group of points - the sketch analogues of ggforce::geom_mark_circle() / geom_mark_ellipse() / geom_mark_rect(), completing the family started by geom_sketch_mark_hull(). Group the points with an aesthetic such as group, colour, or fill; each group gets its own mark. With fill mapped the mark is shaded (using fill_style); otherwise it is outline-only. The position scales expand to contain the marks, so they are not clipped.

Usage

GeomSketchMarkCircle

GeomSketchMarkEllipse

GeomSketchMarkRect

geom_sketch_mark_circle(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  expand = 0.05,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_mark_ellipse(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  expand = 0.05,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_mark_rect(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  expand = 0.05,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and y; map group/colour/fill to separate the clusters.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

expand

Fractional outward inflation of the mark, so it sits around the points rather than through them. Default 0.05.

roughness

Non-negative roughness (0 = clean). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Fill style when fill is mapped: "hachure", "cross_hatch", "zigzag", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap (npc fraction). Default 0.07.

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Details

The boundary is computed in data units, so a geom_sketch_mark_circle() is a true circle only under ggplot2::coord_equal() (as for geom_sketch_circle()); on a non-square panel prefer geom_sketch_mark_ellipse().

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +
  geom_sketch_mark_ellipse(aes(fill = Species), seed = 1L) +
  geom_sketch_point(seed = 2L) +
  theme_sketch()

Sketchy hull marks around point groups

Description

Draws a hand-drawn convex hull around each group of points - the sketch analogue of ggforce::geom_mark_hull(), for circling or grouping clusters. Group the points with an aesthetic such as group, colour, or fill; each group gets its own hull. With fill mapped the hull is shaded (using fill_style); otherwise it is outline-only.

Usage

GeomSketchMarkHull

geom_sketch_mark_hull(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  expand = 0.05,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and y; map group/colour/fill to separate the clusters.

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

expand

Fractional outward inflation of the hull from its centroid, so the mark sits around the points rather than through them. Default 0.05.

roughness

Non-negative roughness (0 = clean). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Fill style when fill is mapped: "hachure", "cross_hatch", "zigzag", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap (npc fraction). Default 0.07.

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +
  geom_sketch_mark_hull(aes(fill = Species), expand = 0.08, seed = 1L) +
  geom_sketch_point(seed = 2L) +
  theme_sketch()

Null sketch geom (infrastructure smoke-test only)

Description

A do-nothing geom used to verify the package skeleton builds and checks clean on both ggplot2 versions. Not exported.

Usage

GeomSketchNull

geom_sketch_null(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Sketchy path geom

Description

Draws a roughened, hand-drawn path connecting observations in order. Equivalent to geom_path() with a sketch aesthetic.

Usage

GeomSketchPath

geom_sketch_path(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  medium = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

medium

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Pressure

Map aes(pressure = ) to a variable to make the stroke swell and thin along the line, like a pen pressed harder in places. The line is then drawn through the variable-width stroke_ribbon() engine even under the default medium = "pen", and combines with any non-pen medium (their width profiles multiply). The mapped values are rescaled by scale_pressure_continuous(); wrap in base::I() for raw multipliers.

Examples

library(ggplot2)
ggplot(economics, aes(date, unemploy)) +
  geom_sketch_path(roughness = 1.5, seed = 42L)

# Stroke width tracks a variable along the line.
ggplot(economics[1:150, ], aes(date, unemploy, pressure = unemploy)) +
  geom_sketch_path(linewidth = 1, seed = 42L)

Sketchy point geom

Description

Draws points as small roughened ellipses, giving each a hand-drawn feel. Equivalent to geom_point() with a sketch aesthetic.

Usage

GeomSketchPoint

geom_sketch_point(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = NULL,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings. Supports x, y, colour, size, alpha, and roughness.

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Details

Unlike the other geoms, roughness is a mappable aesthetic here: set it to a constant (geom_sketch_point(roughness = 2)) so every point wobbles the same amount, or map it to a variable (aes(roughness = z)) so each point wobbles more or less. A mapped variable is rescaled to a legible roughness band by scale_roughness_continuous() (the default range is c(0.01, 0.75)), exactly as scale_size() rescales to a size range. Wrap values in base::I() to use them as raw roughness instead.

Value

A ggplot2 layer (a LayerInstance object) that can be added to a plot with +.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(roughness = 0.5, seed = 1L)

# A constant sets how wobbly every point is.
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(roughness = 0, size = 3, seed = 1L)    # clean circles
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(roughness = 1.5, size = 3, seed = 1L)  # very sketchy

# Map roughness to a variable: rescaled to c(0.01, 0.75) by default.
ggplot(mtcars, aes(wt, mpg, roughness = hp)) +
  geom_sketch_point(size = 3, seed = 1L)

Sketchy polygon geom

Description

Draws closed polygons with a hand-drawn roughened outline and a hachure / cross-hatch / zigzag / dots / dashed / solid fill. Concave polygons are filled correctly via the Active-Edge-Table scan-line algorithm. Equivalent to ggplot2::geom_polygon() with a sketch aesthetic.

Usage

GeomSketchPolygon

geom_sketch_polygon(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 7% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
tri <- data.frame(x = c(0, 1, 0.5), y = c(0, 0, 1))
ggplot(tri, aes(x, y)) +
  geom_sketch_polygon(fill = "skyblue", seed = 1L) +
  theme_sketch()

Sketchy rectangle / tile geom

Description

Draws filled rectangles with a hand-drawn roughened outline and a hachure, cross-hatch, zigzag, dots, dashed, or solid fill. geom_sketch_rect() takes the xmin/xmax/ymin/ymax aesthetics; geom_sketch_tile() takes x/y centres with optional width/height (like ggplot2::geom_tile()).

Usage

GeomSketchRect

geom_sketch_rect(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  corner_radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

GeomSketchTile

geom_sketch_tile(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  width = NULL,
  height = NULL,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  corner_radius = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight). A mappable aesthetic (default 1): pass a constant, or map it per rectangle with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the rectangle's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

corner_radius

Corner rounding as a fraction [0, 1] of each half-side. 0 (default) gives sharp corners; 1 fully rounds the ends.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

width, height

Tile size overrides for geom_sketch_tile(). NULL uses the data resolution.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(xmin = 1, xmax = 3, ymin = 1, ymax = 4)
ggplot(df) +
  geom_sketch_rect(aes(xmin = xmin, xmax = xmax, ymin = ymin, ymax = ymax),
                   corner_radius = 0.3, seed = 1L) +
  theme_sketch()

Sketchy ribbon and area geoms

Description

geom_sketch_ribbon() draws a hand-drawn band between ymin and ymax. geom_sketch_area() is the special case anchored at zero (ymin = 0, ymax = y). Both use a roughened outline and a hachure-style fill, the sketch analogues of ggplot2::geom_ribbon() / ggplot2::geom_area().

Usage

GeomSketchRibbon

geom_sketch_ribbon(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

GeomSketchArea

geom_sketch_area(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 6% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = 1:10, lo = (1:10) - 2, hi = (1:10) + 2)
ggplot(df, aes(x)) +
  geom_sketch_ribbon(aes(ymin = lo, ymax = hi), fill = "plum", seed = 1L) +
  theme_sketch()

Sketchy marginal rug

Description

Draws short hand-drawn ticks along the panel edges, one per observation - the sketch analogue of ggplot2::geom_rug(). Maps the x and/or y aesthetics.

Usage

GeomSketchRug

geom_sketch_rug(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  sides = "bl",
  length = 0.03,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

sides

Which edges to draw on: any of "t", "r", "b", "l" combined in a string. Default "bl" (bottom + left).

length

Tick length as a fraction of the panel (npc). Default 0.03.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  geom_sketch_rug(seed = 2L) +
  theme_sketch()

Sketchy segment and step geoms

Description

geom_sketch_segment() draws roughened straight segments from ⁠(x, y)⁠ to ⁠(xend, yend)⁠. geom_sketch_step() connects points with a hand-drawn stairstep. Sketch analogues of ggplot2::geom_segment() / ggplot2::geom_step().

Usage

GeomSketchSegment

geom_sketch_segment(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  medium = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

GeomSketchStep

geom_sketch_step(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  direction = "hv",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  medium = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

medium

Drawing medium for the stroke: one of sketch_media(). The default "pen" is the classic constant-width double stroke; the others ("ink", "brush", "pencil", "chalk", "marker", "highlighter", "crayon") render through the variable-width stroke_ribbon() engine.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

direction

For geom_sketch_step(): "hv" (horizontal then vertical, default) or "vh".

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = 1:3, y = 1:3, xend = 2:4, yend = c(3, 1, 4))
ggplot(df) +
  geom_sketch_segment(aes(x = x, y = y, xend = xend, yend = yend),
                      seed = 1L) +
  theme_sketch()

Sketchy simple-features (sf) maps

Description

A hand-drawn take on ggplot2::geom_sf(). Roughens the boundaries of sf geometry: ⁠(MULTI)POLYGON⁠ features are filled with a hole-aware hachure (or any fill_style), ⁠(MULTI)LINESTRING⁠ features become sketch paths, and ⁠(MULTI)POINT⁠ features become sketch points. One call draws whichever geometry types are present.

Usage

GeomSketchSfPolygon

geom_sketch_sf(
  mapping = ggplot2::aes(),
  data = NULL,
  ...,
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(), referring to columns of data (e.g. aes(fill = pop)). The geometry column is handled automatically - do not map it.

data

An sf or sfc object (required).

...

Other arguments passed on to the underlying layers.

fill_style

Fill style for polygons; see geom_sketch_polygon(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters; see geom_sketch_path().

na.rm

Remove missing values silently? Default FALSE.

show.legend, inherit.aes

Standard layer arguments. inherit.aes defaults to FALSE (as for geom_sf()).

Details

Requires the sf package. Unlike geom_sf(), this does not integrate with coord_sf(); it plots in planar coordinates, so pre-project longitude/latitude data with sf::st_transform() for an undistorted map. The data argument must be given explicitly (an sf or sfc object); aesthetics in mapping refer to columns of that object.

Value

A list of ggplot2 layers (one per geometry kind present).

Examples


library(ggplot2)
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
ggplot() +
  geom_sketch_sf(data = nc, aes(fill = AREA), seed = 1L) +
  scale_fill_viridis_c() +
  theme_void()

Sketchy slope graph

Description

Draws a hand-drawn slopegraph: one roughened line per group connecting its values across an ordered x (commonly two categories, e.g. before/after), with a sketch point at each vertex. Emphasises rank changes and rates of change between a small number of timepoints (cf. Tufte's slopegraph).

Usage

GeomSketchSlope

geom_sketch_slope(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 0.6,
  point_roughness = 0.4,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and y; map group to the series identity (and usually colour).

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Line roughness (0 = straight). Default 0.6.

point_roughness

Roughness of the vertex dots. Default 0.4.

bowing

Non-negative bowing multiplier. Default 0.4.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(
  time  = rep(c("Before", "After"), each = 4),
  value = c(20, 35, 28, 42, 34, 51, 22, 47),
  who   = rep(c("Alpha", "Bravo", "Charlie", "Delta"), 2)
)
ggplot(df, aes(time, value, group = who, colour = who)) +
  geom_sketch_slope(seed = 1L) +
  theme_sketch()

Sketchy smoothed conditional mean

Description

Draws a hand-drawn fitted line with an optional roughened confidence band - the sketch analogue of ggplot2::geom_smooth(). The fit is computed by ggplot2::stat_smooth() (method, formula, se, etc. pass through).

Usage

GeomSketchSmooth

geom_sketch_smooth(
  mapping = NULL,
  data = NULL,
  stat = "smooth",
  position = "identity",
  ...,
  method = NULL,
  formula = NULL,
  se = TRUE,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

method, formula, se

Passed to ggplot2::stat_smooth(). se = TRUE draws the roughened confidence band.

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

Fill style for the confidence band. Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 6% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer (a LayerInstance object) that can be added to a plot with +.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  geom_sketch_smooth(method = "lm", formula = y ~ x, seed = 2L) +
  theme_sketch()

Sketchy spoke geom

Description

Draws line segments from ⁠(x, y)⁠ at a given angle (radians) and radius - the sketch analogue of ggplot2::geom_spoke(). Handy for vector / flow fields. Internally reuses GeomSketchSegment.

Usage

GeomSketchSpoke

geom_sketch_spoke(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  radius = 1,
  angle = 0,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

radius, angle

Optional fixed radius / angle (radians) used when not supplied as aesthetics.

roughness

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- expand.grid(x = 1:5, y = 1:5)
df$angle <- runif(nrow(df), 0, 2 * pi)
df$radius <- 0.5
ggplot(df, aes(x, y)) +
  geom_sketch_spoke(aes(angle = angle, radius = radius), seed = 1L) +
  geom_sketch_point(seed = 2L) +
  theme_sketch()

Sketchy repelled text and labels

Description

The hand-drawn answer to ggrepel: text (geom_sketch_text_repel()) or boxed labels (geom_sketch_label_repel()) that are nudged apart so they do not overlap one another or cover the data points, each joined back to its anchor by a roughened leader line when it has moved. Placement is solved at draw time by repel_layout() in device space, so it is even on any panel aspect.

Usage

GeomSketchTextRepel

GeomSketchLabelRepel

geom_sketch_text_repel(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 0.6,
  n_passes = 2L,
  seed = NULL,
  padding = 0.07,
  corner_radius = 0.3,
  box_padding = 0.1,
  point_padding = 0.05,
  min_segment = 0.06,
  max_iter = 2000L,
  family = NULL,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

geom_sketch_label_repel(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 0.6,
  n_passes = 2L,
  seed = NULL,
  padding = 0.09,
  corner_radius = 0.3,
  box_padding = 0.12,
  point_padding = 0.05,
  min_segment = 0.06,
  max_iter = 2000L,
  family = NULL,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

mapping, data, stat, position, show.legend, inherit.aes

Standard layer arguments. Requires x, y and label aesthetics.

...

Other arguments passed on to the layer.

roughness, bowing, n_passes, seed

Sketch parameters for the leader / box.

padding

Text clearance inside the box (and around bare text), inches.

corner_radius

Box corner rounding (label variant). Fraction of half-side; default 0.3.

box_padding, point_padding

Extra clearance kept between boxes and around the anchor points, in inches.

min_segment

Shortest leader drawn, in inches; below this no leader is shown (the label is close enough to its anchor).

max_iter

Repel solver iteration cap. Default 2000.

family

Font family for the text. Defaults to the theme's text family.

na.rm

Drop missing values silently? Default FALSE.

Details

Unlike most ggsketch geoms the glyphs are not roughened (the sketch of text is a handwriting font, ADR-0007); the leader and the label box are. Like geom_sketch_text(), family defaults to the theme's text family.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- head(mtcars, 12)
df$name <- rownames(df)
ggplot(df, aes(wt, mpg, label = name)) +
  geom_sketch_point(seed = 1L) +
  geom_sketch_text_repel(family = "", seed = 1L) +
  theme_sketch()

Sketchy violin plot

Description

Draws a hand-drawn violin (mirrored kernel density) with a roughened outline and a hachure-style fill - the sketch analogue of ggplot2::geom_violin(). Uses ggplot2::stat_ydensity().

Usage

GeomSketchViolin

geom_sketch_violin(
  mapping = NULL,
  data = NULL,
  stat = "ydensity",
  position = "dodge",
  ...,
  trim = TRUE,
  scale = "area",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

trim, scale

Passed to ggplot2::stat_ydensity(); further density arguments (e.g. bw, adjust, kernel) pass through ....

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 7% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mpg, aes(class, hwy)) +
  geom_sketch_violin(fill = "#A3D9A5", seed = 1L) +
  theme_sketch()

Sketchy beeswarm chart

Description

Draws a hand-drawn beeswarm (dot-strip) plot: at each categorical x, the points are nudged sideways so they no longer overlap, so the width of the swarm reads as the local density of y. The sideways offset is computed deterministically in data space (bin y, then fan each bin symmetrically around the category centre), so it is fully reproducible and device independent. Dots are drawn with geom_sketch_point(), so they keep the usual hand-drawn wobble (cf. ggbeeswarm::geom_beeswarm()).

Usage

StatSketchBeeswarm

geom_sketch_beeswarm(
  mapping = NULL,
  data = NULL,
  stat = "sketch_beeswarm",
  position = "identity",
  ...,
  binwidth = NULL,
  nbins = 30L,
  width = NULL,
  roughness = NULL,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x (usually discrete) and y.

data

Data to display.

stat

Statistical transformation. Default "sketch_beeswarm".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

binwidth

Height of the y bins used to group points into rows. Default NULL chooses nbins even bins across the y range.

nbins

Number of y bins when binwidth is NULL. Default 30.

width

Sideways spacing between adjacent points in a row, in category units. Default NULL auto-sizes so the widest row stays within the category. Increase for a wider swarm.

roughness

Point roughness. Default NULL (the geom default).

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(iris, aes(Species, Sepal.Length, colour = Species)) +
  geom_sketch_beeswarm(seed = 1L) +
  theme_sketch()

Sketchy calendar heatmap

Description

Draws a hand-drawn calendar heatmap in the GitHub-contributions style: one roughened tile per day, arranged as weeks (columns) and weekdays (rows), with the tile colour given by a value, and the axes labelled with weekday and month names. Map date (a Date) and fill (the value). Tiles are drawn with geom_sketch_tile(); the default fill_style = "solid" lets the colour gradient read as a heatmap. For more than one year, add a year column to your data and facet on it (each panel covers one year). No new dependencies.

Usage

StatSketchCalendar

geom_sketch_calendar(
  mapping = NULL,
  data = NULL,
  stat = "sketch_calendar",
  position = "identity",
  ...,
  week_start = "sunday",
  labels = TRUE,
  width = 0.9,
  height = 0.9,
  colour = "grey75",
  fill_style = "solid",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires date; usually map fill to the value.

data

Data to display.

stat

Statistical transformation. Default "sketch_calendar".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

week_start

"sunday" (default) or "monday": which weekday is the top row.

labels

Label the axes with weekday and month names instead of the raw grid numbers? Default TRUE; it returns the layer together with x/y scales, so set FALSE if you want to supply your own scales. Month positions are exact to within one week (they are computed without seeing the year).

width, height

Tile size in grid units (gaps appear below 1). Default 0.9.

colour

Tile outline colour. Default "grey75" (set NA for none).

fill_style

Tile fill style; see geom_sketch_rect(). Default "solid" (best for a colour-graded heatmap).

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object (with labels = TRUE, a list of the layer plus weekday/month axis scales).

Examples

library(ggplot2)
df <- data.frame(day = as.Date("2024-01-01") + 0:120)
df$value <- runif(nrow(df))
ggplot(df, aes(date = day, fill = value)) +
  geom_sketch_calendar(seed = 1L) +
  coord_equal() +
  theme_sketch()

Sketchy ridgeline (joyplot)

Description

Draws a hand-drawn ridgeline plot: a kernel density of x for each category on the discrete y, raised to its own baseline so the ridges overlap and the changing shape of the distribution is easy to compare. Densities are computed and positioned by StatSketchDensityRidges; each ridge is filled and outlined with the usual sketch look, and ridges are drawn back-to-front so nearer ones sit on top (cf. ggridges::geom_density_ridges()).

Usage

StatSketchDensityRidges

GeomSketchRidgeline

geom_sketch_ridgeline(
  mapping = NULL,
  data = NULL,
  stat = "sketch_density_ridges",
  position = "identity",
  ...,
  scale = 1.8,
  bandwidth = NULL,
  n = 256L,
  rel_min_height = 0,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and a (usually discrete) y.

data

Data to display.

stat

Statistical transformation. Default "sketch_density_ridges".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

scale

Vertical scaling: how many y units the tallest ridge spans. Values above 1 make ridges overlap. Default 1.8.

bandwidth

Kernel bandwidth passed to stats::density(). Default NULL (automatic per group).

n

Number of density evaluation points. Default 256.

rel_min_height

Drop the density tails below this fraction of the global peak, trimming long thin feet. Default 0 (keep all).

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", "solid", or "watercolor". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 6% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(iris, aes(Sepal.Length, Species, fill = Species)) +
  geom_sketch_ridgeline(scale = 1.6, seed = 1L) +
  theme_sketch()

Sketchy funnel chart

Description

Draws a hand-drawn funnel: one horizontal bar per stage, centred on zero, whose width is the stage's value (x), so the shrinking bars read as drop-off down the stages (y). Translucent trapezoids connect each stage to the next. Put the first stage at the top by ordering the y factor levels accordingly (or add scale_y_discrete(limits = rev)); hide the mirrored x axis with theme(axis.text.x = element_blank()) or relabel it with scale_x_continuous(labels = abs).

Usage

StatSketchFunnel

GeomSketchFunnel

geom_sketch_funnel(
  mapping = NULL,
  data = NULL,
  stat = "sketch_funnel",
  position = "identity",
  ...,
  bar_width = 0.7,
  connectors = TRUE,
  connector_alpha = 0.3,
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x (the stage value) and y (the stage).

data

Data to display.

stat

Statistical transformation. Default "sketch_funnel".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

bar_width

Bar thickness in y units. Default 0.7.

connectors

Draw the trapezoid connectors? Default TRUE.

connector_alpha

Connector translucency. Default 0.3.

fill_style

Bar fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
funnel <- data.frame(
  stage = factor(c("Visited", "Signed up", "Activated", "Paid"),
                 levels = rev(c("Visited", "Signed up", "Activated",
                                "Paid"))),
  n     = c(1200, 460, 210, 80)
)
ggplot(funnel, aes(n, stage, fill = stage)) +
  geom_sketch_funnel(seed = 1L, show.legend = FALSE) +
  scale_x_continuous(labels = abs) +
  theme_sketch()

Sketchy pie and donut charts

Description

geom_sketch_pie() draws a hand-drawn pie chart: one slice per row, sized by the amount aesthetic and coloured by fill. geom_sketch_donut() is the same with a hole in the middle. Slices are kept circular regardless of the panel's shape, so they look right without coord_fixed(). The chart is drawn in the centre of the panel; pair it with theme_sketch() or ggplot2::theme_void() to hide the (unused) axes.

Usage

GeomSketchPie

geom_sketch_pie(
  mapping = NULL,
  data = NULL,
  stat = StatSketchPie,
  position = "identity",
  ...,
  x0 = 0.5,
  y0 = 0.5,
  r = 0.45,
  r0 = 0,
  roughness = 1,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.02,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_donut(..., r0 = 0.25)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires amount; map fill to colour the slices.

data

Data with one row per slice.

stat

The statistic; defaults to StatSketchPie, which converts amount into slice angles.

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

x0, y0

Pie centre in npc [0,1]. Default 0.5 (panel centre).

r

Outer radius as a fraction of the smaller panel dimension. Default 0.45.

r0

Inner radius (hole) as a fraction of the smaller panel dimension. 0 (default) is a full pie; geom_sketch_donut() defaults it to 0.25 (a ring between r0 and r).

roughness

Non-negative roughness of the slice edges (0 = clean). Default 1.

bowing

Non-negative bowing multiplier. Default 0.4 (kept low so the radial edges stay straight-ish).

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

"solid" (default) paints each slice in its fill colour with a rough edge; any other style ("hachure", "cross_hatch", "zigzag", "scribble", "dots", "dashed", "stipple", "pencil_shade") hatches it instead.

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Spacing between fill lines, as a fraction of the smaller panel dimension – this is the hatch density knob: smaller is denser. Default 0.02.

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(
  group  = c("Sketch", "Polish", "Coffee", "Doubt"),
  amount = c(40, 25, 20, 15)
)
ggplot(df, aes(amount = amount, fill = group)) +
  geom_sketch_pie(seed = 1L) +
  scale_fill_sketch() +
  coord_fixed() +
  theme_void()

# A donut:
ggplot(df, aes(amount = amount, fill = group)) +
  geom_sketch_donut(seed = 2L) +
  theme_void()

Sketchy population pyramid

Description

Draws a hand-drawn population pyramid: back-to-back horizontal bars per category (y), mirrored about zero by a two-level side aesthetic (the first level in sort order grows left, the second right). Usually you also map fill to the same variable as side; relabel the mirrored axis with scale_x_continuous(labels = abs).

Usage

StatSketchPyramid

GeomSketchPyramid

geom_sketch_pyramid(
  mapping = NULL,
  data = NULL,
  stat = "sketch_pyramid",
  position = "identity",
  ...,
  bar_width = 0.8,
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x (the count), y (the category) and side (the two-level split).

data

Data to display.

stat

Statistical transformation. Default "sketch_pyramid".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

bar_width

Bar thickness in y units. Default 0.8.

fill_style

Bar fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
pop <- data.frame(
  age = factor(rep(c("0-19", "20-39", "40-59", "60+"), 2),
               levels = c("0-19", "20-39", "40-59", "60+")),
  sex = rep(c("Female", "Male"), each = 4),
  n   = c(340, 420, 380, 240, 360, 440, 370, 200)
)
ggplot(pop, aes(n, age, side = sex, fill = sex)) +
  geom_sketch_pyramid(seed = 1L) +
  scale_x_continuous(labels = abs) +
  theme_sketch()

Sketchy radar (spider) chart

Description

Draws a hand-drawn radar chart: each series is a closed polygon over evenly spaced angular axes, with a roughened web (concentric rings, radial spokes, and axis labels) drawn behind. Map axis (the variable that becomes each spoke, usually a factor), value (its magnitude), and group (the series); map colour/fill to the series too. Values are scaled to a common unit radius (rmax), and each polygon takes any fill_style (including "watercolor"). No new dependencies (cf. ggradar, fmsb::radarchart()).

Usage

StatSketchRadar

GeomSketchRadar

geom_sketch_radar(
  mapping = NULL,
  data = NULL,
  stat = "sketch_radar",
  position = "identity",
  ...,
  rmax = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  n_rings = 4L,
  grid_colour = "grey75",
  label_size = 3.2,
  label_colour = "grey30",
  label_family = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires axis and value; usually also map group (and colour/fill) to the series.

data

Data to display.

stat

Statistical transformation. Default "sketch_radar".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

rmax

Value mapped to the outer ring (NULL = the data maximum).

fill_style

Polygon fill style; see geom_sketch_polygon(). Default "hachure".

hachure_angle, hachure_gap, fill_weight

Fill controls; see geom_sketch_polygon().

n_rings

Number of concentric grid rings. Default 4.

grid_colour

Colour of the web (rings + spokes). Default "grey75".

label_size, label_colour, label_family

Axis-label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Details

Like geom_sketch_pie(), the chart lives in its own square coordinate space, so pair it with coord_equal() and theme_void() (or theme_sketch()).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
skills <- data.frame(
  axis = rep(c("Speed", "Power", "Range", "Control", "Stamina"), 2),
  value = c(8, 6, 9, 5, 7, 5, 9, 4, 8, 6),
  who = rep(c("A", "B"), each = 5)
)
ggplot(skills, aes(axis = axis, value = value, group = who,
                   colour = who, fill = who)) +
  geom_sketch_radar(alpha = 0.3, seed = 1L) +
  coord_equal() +
  theme_void()

Sketchy streamgraph

Description

Draws a hand-drawn streamgraph (a.k.a. ThemeRiver): a stacked area chart whose baseline floats so the coloured bands flow around a moving centre, good for showing how a few categories rise and fall over time. Map x (usually time), y (value), and fill (category). Values are stacked and the baseline offset by StatSketchStream; each band is drawn as a roughened ribbon, so it takes any fill_style (including "watercolor"). No new dependencies (cf. ggstream::geom_stream()).

Usage

StatSketchStream

geom_sketch_streamgraph(
  mapping = NULL,
  data = NULL,
  stat = "sketch_stream",
  position = "identity",
  ...,
  offset = "silhouette",
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x and y; usually map fill (or group) to the category.

data

Data to display.

stat

Statistical transformation. Default "sketch_stream".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

offset

Baseline placement: "silhouette" (centred, the classic streamgraph, default), "zero" (a normal stacked area), or "wiggle" (minimises the overall slope).

fill_style

Band fill style; see geom_sketch_ribbon(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
set.seed(1)
df <- expand.grid(t = 1:12, grp = c("a", "b", "c", "d"))
df$v <- abs(sin(df$t / 3 + match(df$grp, letters)) + 1.2) * 5
ggplot(df, aes(t, v, fill = grp)) +
  geom_sketch_streamgraph(seed = 1L) +
  theme_sketch()

Sketchy treemap

Description

Draws a hand-drawn treemap: nested rectangles tiling a square, each with area proportional to a value, so the biggest categories take the most space. Map the value to area and the category to fill; map label to write a name in each tile. The rectangles are laid out with a squarified algorithm (treemap_layout()) and drawn with the roughened rect look, so they take any fill_style (including "watercolor"). Add ggplot2::coord_equal() for true proportions. No new dependencies (cf. treemapify::geom_treemap()).

Usage

StatSketchTreemap

GeomSketchTreemap

geom_sketch_treemap(
  mapping = NULL,
  data = NULL,
  stat = "sketch_treemap",
  position = "identity",
  ...,
  label_size = 3.2,
  label_colour = "grey15",
  colour = "grey25",
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires area; usually map fill and optionally label.

data

Data to display.

stat

Statistical transformation. Default "sketch_treemap".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

label_size

Label text size (as in ggplot2::geom_text()). Default 3.2.

label_colour

Label colour. Default "grey15".

colour

Tile outline colour. Default "grey25" (set NA for none).

fill_style

Tile fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(grp = c("Alpha", "Bravo", "Charlie", "Delta", "Echo"),
                 val = c(40, 25, 15, 12, 8))
ggplot(df, aes(area = val, fill = grp, label = grp)) +
  geom_sketch_treemap(seed = 1L) +
  coord_equal() +
  theme_sketch()

Sketchy waffle chart

Description

Draws a hand-drawn waffle: a square grid (default 10x10 = 100 cells) where each cell is coloured by category, so the number of cells of a colour reads as that category's share of the whole. Map the category to fill; map a count to weight if the data is already summarised (otherwise each row counts as one). Cells are drawn with geom_sketch_tile(), so they take the usual roughened outline and fill_style (including "watercolor"). Add ggplot2::coord_equal() to keep the cells square. (cf. waffle::geom_waffle()).

Usage

StatSketchWaffle

geom_sketch_waffle(
  mapping = NULL,
  data = NULL,
  stat = "sketch_waffle",
  position = "identity",
  ...,
  n_rows = 10L,
  cells = 100L,
  flip = FALSE,
  width = 0.9,
  height = 0.9,
  colour = "grey35",
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires fill; optionally weight (a per-row count).

data

Data to display.

stat

Statistical transformation. Default "sketch_waffle".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

n_rows

Number of rows in the grid. Default 10.

cells

Total number of cells (the grid resolution). Default 100, i.e. a percentage waffle.

flip

Fill columns top-down instead of bottom-up? Default FALSE.

width, height

Cell size in grid units (gaps appear below 1). Default 0.9.

colour

Outline colour for each cell. Default "grey35".

fill_style

Cell fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(grp = c("Rent", "Food", "Travel", "Other"),
                 spend = c(45, 25, 20, 10))
ggplot(df, aes(fill = grp, weight = spend)) +
  geom_sketch_waffle(seed = 1L) +
  coord_equal() +
  theme_sketch()

Sketchy waterfall chart

Description

Draws a hand-drawn waterfall: each step's delta (y) floats a bar from the running total before it to the running total after it, stepping the level up and down across the categories (x), with dotted hand-drawn connectors carrying the level across the gaps. Map an optional measure aesthetic with value "total" for rows that should draw the running total from zero (e.g. a closing "Net" row) instead of a delta.

Usage

StatSketchWaterfall

GeomSketchWaterfall

geom_sketch_waterfall(
  mapping = NULL,
  data = NULL,
  stat = "sketch_waterfall",
  position = "identity",
  ...,
  width = 0.62,
  fill_increase = "#7fa87f",
  fill_decrease = "#b56b6f",
  fill_total = "#8391a7",
  connectors = TRUE,
  connector_colour = "grey40",
  colour = "grey25",
  fill_style = "hachure",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Aesthetic mappings created by ggplot2::aes(). Requires x (step, usually a factor in ledger order) and y (the delta); optionally measure ("relative" or "total" per row).

data

Data to display.

stat

Statistical transformation. Default "sketch_waterfall".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

width

Bar width in x units. Default 0.62.

fill_increase, fill_decrease, fill_total

Bar fills by direction. Set any to NULL to map fill yourself.

connectors

Draw the dotted level connectors? Default TRUE.

connector_colour

Connector colour. Default "grey40".

colour

Bar outline colour. Default "grey25".

fill_style

Bar fill style; see geom_sketch_rect(). Default "hachure".

roughness, bowing, n_passes, seed

Sketch parameters.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Details

Bars are coloured by direction (fill_increase / fill_decrease / fill_total); set any of them to NULL and map fill yourself (the stat exposes the direction as after_stat(change)).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ledger <- data.frame(
  step  = factor(c("Start", "Sales", "Refunds", "Costs", "Tax", "Net"),
                 levels = c("Start", "Sales", "Refunds", "Costs", "Tax",
                            "Net")),
  delta = c(120, 80, -25, -60, -18, 0),
  kind  = c("relative", "relative", "relative", "relative", "relative",
            "total")
)
ggplot(ledger, aes(step, delta, measure = kind)) +
  geom_sketch_waterfall(seed = 1L) +
  theme_sketch()

Animate a sketch plot by "boiling" its lines

Description

Renders a ggplot built with ggsketch geoms nframes times, shifting every roughening seed by a per-frame amount, so the whole drawing shimmers and re-draws itself like a hand-animated cel (the "boiling line" effect). Because the shift is added to every resolved seed – whether a layer set its own seed or inherited the global one – a plot boils without any change to its code. Frame 1 reproduces the static plot exactly.

Usage

animate_sketch(
  plot,
  nframes = 12L,
  fps = 10,
  type = c("boil", "draw_on"),
  direction = c("lr", "rl", "bt", "tb", "diag", "radial"),
  easing = c("linear", "ease_in", "ease_out", "ease_in_out"),
  file = NULL,
  width = 7,
  height = 5,
  units = "in",
  res = 120,
  background = "white",
  device = NULL,
  seed = NULL,
  renderer = c("auto", "gifski", "magick", "none"),
  loop = TRUE
)

Arguments

plot

A ggplot object using ggsketch geoms.

nframes

Number of frames. Default 12.

fps

Frames per second in the output GIF. Default 10.

type

Motion type: "boil" (re-seed the wobble each frame so the whole drawing shimmers) or "draw_on" (progressively reveal the finished drawing behind a moving wipe, as if a hand were drawing it).

direction

For type = "draw_on", how the drawing is revealed: a straight wipe "lr" (left-to-right, default), "rl", "bt" (bottom-to-top) or "tb"; a diagonal wipe "diag" (top-left to bottom-right); or "radial" (a circular iris opening from the centre).

easing

For type = "draw_on", the pacing of the reveal across frames: "linear" (constant speed, default), "ease_in" (start slow), "ease_out" (end slow), or "ease_in_out" (slow at both ends).

file

Output GIF path. If NULL (default), no GIF is written and the frame paths are returned invisibly.

width, height, units, res

Frame size and resolution, passed to the graphics device (units one of "in", "cm", "mm", "px").

background

Frame background colour. Default "white".

device

Graphics device: "ragg" (default when installed) or "png".

seed

Base seed (NULL uses getOption("ggsketch.seed", 1L)).

renderer

GIF backend: "auto" (default), "gifski", "magick", or "none" (always return frame paths).

loop

Loop the GIF forever? Default TRUE.

Details

Frames are stitched into a GIF when gifski or magick is installed (neither is a hard dependency); otherwise the frame image paths are returned so you can assemble them yourself. Everything is reproducible: the same seed yields the same animation.

Value

Invisibly, the GIF path (when written) or a character vector of frame image paths.

Examples


library(ggplot2)
p <- ggplot(mpg, aes(class)) +
  geom_sketch_bar(fill = "#7BAFD4", seed = 1L) +
  theme_sketch()
# Write a GIF if gifski/magick is available, else get frame paths back:
gif <- animate_sketch(p, nframes = 8, file = tempfile(fileext = ".gif"))

Sketchy annotations

Description

The sketch analogue of ggplot2::annotate(). Creates a one-off layer of fixed, hand-drawn marks that do not inherit the plot's aesthetics - useful for highlighting, callouts, and reference shapes.

Usage

annotate_sketch(
  geom,
  x = NULL,
  y = NULL,
  xmin = NULL,
  xmax = NULL,
  ymin = NULL,
  ymax = NULL,
  xend = NULL,
  yend = NULL,
  r = NULL,
  a = NULL,
  b = NULL,
  seed = NULL,
  na.rm = FALSE,
  ...
)

Arguments

geom

Name of the sketch geom to draw. One of "point", "line", "path", "segment", "rect", "polygon", "circle", "ellipse".

x, y, xmin, xmax, ymin, ymax, xend, yend

Positioning aesthetics (numeric vectors, recycled to a common length). Supply the ones the chosen geom needs (e.g. xmin/xmax/ymin/ymax for "rect", xend/yend for "segment").

r, a, b

Radius ("circle") or semi-axes ("ellipse").

seed

Integer seed for reproducible wobble.

na.rm

If FALSE (default), missing values trigger a warning.

...

Other arguments passed to the underlying ⁠geom_sketch_*()⁠ layer (e.g. colour, fill, roughness, fill_style).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  annotate_sketch("rect", xmin = 3, xmax = 4, ymin = 15, ymax = 22,
                  fill = NA, colour = "red", seed = 2L) +
  annotate_sketch("segment", x = 2, y = 30, xend = 3.5, yend = 20,
                  colour = "blue", seed = 3L) +
  theme_sketch()

Add a one-off sketchy arrow annotation

Description

The easiest way to point at something: a single hand-drawn arrow (with an optional handwriting label) that does not inherit the plot's aesthetics. A thin wrapper around geom_sketch_arrow() in the spirit of ggplot2::annotate().

Usage

annotate_sketch_arrow(
  x,
  y,
  xend,
  yend,
  label = NULL,
  curvature = "auto",
  roughness = 1,
  arrow_type = "open",
  seed = NULL,
  ...
)

Arguments

x, y

Source point (where the label sits). Numeric, recycled.

xend, yend

Target point (where the arrow points). Numeric, recycled.

label

Optional text shown at the source. NULL draws a bare arrow.

curvature, roughness, arrow_type, seed

Passed to geom_sketch_arrow().

...

Other arguments passed on to geom_sketch_arrow() (e.g. colour, linewidth, arrow_length, family).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions, waiting)) +
  geom_sketch_point(seed = 1L) +
  annotate_sketch_arrow(x = 2.2, y = 90, xend = 1.9, yend = 75,
                        label = "short bursts", colour = "#C0392B",
                        seed = 3L) +
  theme_sketch()

Add a one-off sketchy callout annotation

Description

The easiest way to add a boxed note: a single hand-drawn callout (with an optional leader arrow) that does not inherit the plot's aesthetics. A thin wrapper around geom_sketch_callout() in the spirit of ggplot2::annotate().

Usage

annotate_sketch_callout(
  x,
  y,
  label,
  xend = NULL,
  yend = NULL,
  seed = NULL,
  ...
)

Arguments

x, y

Box position. Numeric, recycled.

label

Label text.

xend, yend

Optional target the leader points at. NULL (default) draws a boxed label with no leader.

seed

Passed to geom_sketch_callout().

...

Other arguments passed on to geom_sketch_callout() (e.g. colour, fill, roughness, corner_radius, family).

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions, waiting)) +
  geom_sketch_point(seed = 1L) +
  annotate_sketch_callout(x = 2.2, y = 95, label = "short waits",
                          xend = 1.9, yend = 75, seed = 3L) +
  theme_sketch()

Highlighter swipes and hand-drawn underlines

Description

Two one-off emphasis annotations (constant positions, inherit.aes = FALSE):

Usage

annotate_sketch_highlight(
  x,
  y,
  xend,
  yend,
  colour = "#f7e017",
  linewidth = 8,
  seed = NULL,
  ...
)

annotate_sketch_underline(
  x,
  y,
  xend,
  colour = "grey15",
  linewidth = 0.7,
  strokes = 1L,
  roughness = 1.6,
  bowing = 0.4,
  seed = NULL,
  ...
)

Arguments

x, y, xend, yend

Endpoint positions in data units (vectors recycle). annotate_sketch_underline() is horizontal: yend defaults to y.

colour

Ink colour. Highlight defaults to fluorescent yellow.

linewidth

Stroke width. The highlighter medium multiplies it into a wide band; the underline stays a line.

seed

Integer seed for reproducible wobble.

...

Other arguments passed to geom_sketch_segment().

strokes

Number of overlapped underline strokes. Default 1.

roughness

Wobble amount. Underlines default a little shakier.

bowing

Bow of the underline stroke (kept low so repeated strokes stay together). Default 0.4.

Details

annotate_sketch_highlight() lays a wide, translucent chisel-tip band (the "highlighter" medium) from ⁠(x, y)⁠ to ⁠(xend, yend)⁠ – swipe it over a line, a label or a region of interest like a fluorescent marker.
annotate_sketch_underline() draws a quick wobbly stroke from ⁠(x, y)⁠ to ⁠(xend, y)⁠ – an underline for a data point or a piece of text. strokes > 1 re-draws it with fresh wobble for an emphatic scrawl.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(economics[1:60, ], aes(date, unemploy)) +
  geom_sketch_line(seed = 1L) +
  annotate_sketch_highlight(
    x = as.Date("1969-01-01"), y = 2800,
    xend = as.Date("1970-06-01"), yend = 2800
  ) +
  theme_sketch()

Build the ideal paths for one arrowhead

Description

Returns the un-roughened geometry of an arrowhead whose tip is at ⁠(tipx, tipy)⁠ and which points along angle. The grob layer roughens and paints it, so this stays pure geometry and reproduces on every device. Styles: "triangle_open" (a two-stroke V), "triangle_filled" (a solid triangle), "barb" (swept-back harpoon barbs), "fishtail" (a forked swallowtail), "dot" (a blob at the tip) and "bar" (a perpendicular tick).

Usage

arrowhead(
  tipx,
  tipy,
  angle,
  length,
  half_angle = 25 * pi/180,
  style = "triangle_open"
)

Arguments

tipx, tipy

Tip position (inch space).

angle

Direction the arrow points, in radians (the end tangent).

length

Head length in inches.

half_angle

Half-angle of the wings, in radians. Default ~25 degrees.

style

One of sketch_arrowheads().

Value

A list with strokes (a list of 2-column ⁠(x, y)⁠ polylines to stroke), polygons (a list of ⁠(x, y)⁠ rings to fill) and dots (list(x, y, r) or NULL).

Examples

arrowhead(1, 1, angle = 0, length = 0.2, style = "barb")

Boil a gganimate animation (sketch wobble + data transitions)

Description

Render a gganimate animation - any plot built with ggsketch geoms plus a ⁠transition_*()⁠ - so that, on top of gganimate's data tweening, the hand-drawn lines boil: every roughening seed is shifted once per frame, so the drawing shimmers and re-draws itself like a hand-animated cel while the bars grow, points fly, or a line draws itself along x. It is the moving-data companion to animate_sketch(), which boils a static plot.

Usage

boil_gganimate(
  animation,
  nframes = 100L,
  fps = 10,
  intensity = 1,
  detail = 1L,
  file = NULL,
  width = 7,
  height = 5,
  units = "in",
  res = 120,
  background = "white",
  device = NULL,
  seed = NULL,
  renderer = c("auto", "gifski", "magick", "none"),
  loop = TRUE
)

Arguments

animation

A gganimate animation: a ggplot using ggsketch geoms with a ⁠transition_*()⁠ added (class gganim).

nframes

Number of frames. Default 100 (gganimate's default).

fps

Frames per second in the output. Default 10.

intensity

Boil strength: scales how far the seed jitter steps each frame. 1 (default) matches animate_sketch(); higher shimmers more.

detail

Tween sub-frames per frame, passed through to gganimate's prerender for smoother motion (rendered frames are sampled back down to nframes). Default 1.

file

Output path (e.g. a .gif). If NULL (default), no file is written and the frame paths are returned invisibly.

width, height, units, res

Frame size and resolution. units one of "in", "cm", "mm", "px".

background

Frame background colour. Default "white".

device

Graphics device: NULL (default; "ragg" when installed, else "png"), "ragg"/"png", or any device string gganimate accepts ("ragg_png", "svglite", ...).

seed

Integer offset for the boil sequence (NULL = 0, so frame 1 is un-boiled). Change it to vary the shimmer without touching the plot.

renderer

GIF backend: "auto" (default), "gifski", "magick", or "none" (always return frame paths).

loop

Loop the output forever? Default TRUE.

Details

The boil rides on the global ggsketch.seed_jitter option (the same lever animate_sketch() uses), advanced by a per-frame counter so frame 1 is the un-boiled drawing and the whole animation is reproducible. Frames are stitched with the same backend as animate_sketch() (gifski or magick); if neither is installed the frame paths are returned. gganimate itself is an optional dependency.

Value

Invisibly, the output path (when written) or a character vector of frame image paths.

Examples



library(ggplot2)
library(gganimate)
p <- ggplot(mpg, aes(class, fill = drv)) +
  geom_sketch_bar(position = "dodge", seed = 1L) +
  scale_fill_sketch() +
  theme_sketch() +
  transition_states(drv, transition_length = 2, state_length = 1)
boil_gganimate(p, nframes = 30, file = tempfile(fileext = ".gif"))

Flatten a closed Bezier boundary to a polygon, then fill

Description

For area/ribbon/density geoms: converts a curved boundary (list of Bezier control-point sets) into a polygon approximation, then applies sketch_fill.

Usage

curve_fill(bezier_list, tol = 0.001, rdp_eps = 1e-04, ...)

Arguments

bezier_list

List of 4-element lists, each with P0, P1, P2, P3 (each a length-2 c(x,y) vector in inch space). The list describes a closed path.

tol

Flatness tolerance for flattening. Default 1e-3.

rdp_eps

RDP epsilon. Default 1e-4.

...

Passed to sketch_fill.

Value

List of fill-line segments (same structure as sketch_fill).

Sketchy legend keys

Description

⁠draw_key_*⁠ functions used by the sketch geoms so their legends render with the same hand-drawn character. Not called directly; passed as the draw_key field of a geom (see ggplot2::draw_key).

Usage

draw_key_sketch_path(data, params, size)

draw_key_sketch_medium(data, params, size)

draw_key_sketch_point(data, params, size)

draw_key_sketch_polygon(data, params, size)

Arguments

data

A single-row data frame of the key's aesthetics.

params

The layer's parameter list (roughness, seed, fill_style, ...).

size

Key size in mm (unused; kept for the draw_key contract).

Value

A grid grob.

Hand-drawn theme elements

Description

Sketch counterparts of ggplot2::element_line() and ggplot2::element_rect(). Use them in ggplot2::theme() (or via theme_sketch(rough_frame = TRUE)) to render gridlines, panel borders, and axis ticks with the same wobbly, double-stroke look as the geoms. They accept the usual element arguments plus the shared sketch parameters (roughness, bowing, n_passes, seed).

Usage

element_sketch_line(
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  lineend = NULL,
  color = NULL,
  roughness = 0.5,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  ...
)

element_sketch_rect(
  fill = NULL,
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  color = NULL,
  roughness = 0.6,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  ...
)

Arguments

colour, color

Line/border colour.

linewidth

Line width.

linetype

Line type.

lineend

Line end style.

roughness, bowing, n_passes, seed

Sketch parameters (see geom_sketch_path()). Defaults are gentle, suited to a frame.

...

Passed to the underlying ggplot2 element constructor.

fill

Fill colour (element_sketch_rect() only). NA draws the outline only - the usual choice for a panel border.

Value

A ggplot2 theme element carrying an ⁠element_sketch_*⁠ subclass.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  theme_sketch() +
  theme(panel.grid.major = element_sketch_line(colour = "grey80", seed = 7L))

Paper-ground theme element

Description

A panel-background element that paints a simulated paper texture behind the data: ruled notebook lines, a graph grid, a dot grid, aged blotches, or a blueprint / chalkboard / kraft ground. Use it as panel.background in ggplot2::theme(), or – more simply – via theme_sketch(paper = ). Everything is drawn as vector primitives, so it reproduces on every device.

Usage

element_sketch_paper(kind = "notebook", ground = NULL, seed = NULL, ...)

Arguments

kind

A paper from sketch_papers().

ground

Optional override for the ground (fill) colour.

seed

Integer seed for the aged blotches.

...

Passed to ggplot2::element_rect().

Value

A ggplot2 theme element carrying an element_sketch_paper subclass.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_sketch_point(seed = 1L) +
  theme_sketch() +
  theme(panel.background = element_sketch_paper("graph"))

Fill a region with tonal engraving (line density follows a tone field)

Description

The engraving counterpart of hachure_fill_multi(): instead of one uniform hatch, it lays down a engrave_ladder() of hatch layers and keeps each layer only where the field tone reaches that layer's threshold, so line density (and cross-hatching) tracks the tone continuously across the region. Holes are handled exactly as in hachure_fill_multi() (shared even-odd scan-line).

Usage

engrave_fill(
  rings,
  field,
  ladder = NULL,
  roughness = 0.5,
  bowing = 0,
  sample_step = NULL,
  seed = NULL,
  ...
)

Arguments

rings

A list of rings, each list(x, y) of vertex coordinates in inch/data space (see hachure_fill_multi()).

field

A vectorised tone function ⁠function(x, y)⁠ returning a value in ⁠[0, 1]⁠ per point (0 = lightest/paper, 1 = darkest/solid).

ladder

A hatch ladder from engrave_ladder(); if NULL, a default ladder is built from ....

roughness, bowing

Sketch params applied to each surviving stroke. Defaults 0.5 and 0.

sample_step

Tone-sampling step along each scan line (inches). NULL (default) uses a fraction of the finest ladder pitch.

seed

Integer seed.

...

Passed to engrave_ladder() when ladder is NULL.

Value

A list of 2-column (x, y) stroke matrices (same structure as hachure_fill_multi()), densest where the field is darkest.

Build a tonal hatch ladder for engraving fills

Description

An engraving ladder is an ordered list of hatch layers; each is applied only where the tone field is at least its threshold, so darker regions accumulate more (and finer, cross-hatched) layers. Defaults trace the classic etching progression: a sparse base layer, then denser same-angle lines, then a second angle (cross-hatch), then the fine angles that read as black.

Usage

engrave_ladder(
  n_levels = 5L,
  base_gap = 0.1,
  gap_ratio = 0.62,
  base_angle = 45,
  cross_after = 3L,
  cross_angle = 90,
  tone_floor = 0.12,
  tone_ceiling = 0.92
)

Arguments

n_levels

Number of hatch layers. Default 5.

base_gap

Pitch (inches) of the sparsest layer. Each subsequent layer tightens geometrically toward base_gap * gap_ratio^(n_levels - 1). Default 0.10.

gap_ratio

Multiplicative pitch shrink per layer (0 < r <= 1; smaller = faster densening). Default 0.62.

base_angle

Angle (degrees) of the first layer. Default 45.

cross_after

Layer index (1-based) at which cross-hatching begins; from this layer on, angles alternate by cross_angle. Default 3.

cross_angle

Angular offset (degrees) of the cross direction. Default 90.

tone_floor, tone_ceiling

Tone thresholds of the first and last layers; the layers' thresholds are spread evenly between them. A region with tone below tone_floor is left blank (paper); tone at or above tone_ceiling gets every layer. Defaults 0.12 and 0.92.

Value

A list of layers, each list(gap, angle, threshold).

Force-directed graph layout (Fruchterman-Reingold)

Description

A pure-R implementation of the Fruchterman-Reingold force-directed layout, so geom_sketch_node() / geom_sketch_edge() can place a network with no external graph dependency. Repulsive forces push every node apart; attractive forces pull edge-connected nodes together; a cooling schedule settles the system. Coordinates are returned rescaled to roughly ⁠[-1, 1]⁠ on both axes.

Usage

force_layout(edges, n_nodes = NULL, niter = 500L, seed = NULL)

Arguments

edges

A two-column matrix or data frame of 1-based integer node indices, one row per edge (from, to). May have zero rows (an edgeless graph, laid out on a circle).

n_nodes

Number of nodes. Defaults to the largest index in edges (so isolated high-index nodes need this set explicitly).

niter

Number of iterations. Default 500.

seed

Integer seed for the initial placement. NULL uses getOption("ggsketch.seed", 1L). The layout is otherwise deterministic.

Value

A data frame with columns x and y, one row per node in index order.

Examples

# A small ring of five nodes
e <- cbind(1:5, c(2:5, 1))
force_layout(e, seed = 1L)

Sketchy alluvial / Sankey diagram

Description

Draws a hand-drawn alluvial diagram: two or more categorical axes, each a stack of strata (boxes), connected by flows (ribbons) whose thickness is the frequency of each category combination. Like geom_sketch_chord() it is a constructor that returns a list of ordinary sketch layers (roughened strata, roughened flow ribbons with smooth S-curved edges, and stratum labels), so it composes with + and any fill scale. It draws in ordinary x/y space; pair it with theme_void() or theme_sketch(). No new dependencies (cf. ggalluvial, ggsankey).

Usage

geom_sketch_alluvial(
  data,
  axes,
  value = NULL,
  fill = NULL,
  ...,
  box_width = 0.18,
  stratum_gap = 0.02,
  fill_style = "solid",
  alpha = 0.7,
  strata_fill = "grey85",
  label = TRUE,
  label_size = 3.5,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A wide data frame: one column per axis, one row per observation (or per group, with a value weight).

axes

Character vector of column names to use as axes, in order (at least two).

value

Optional column name giving each row's weight (NULL = 1 each).

fill

Optional column name whose category colours each flow (NULL = the first axis). Add scale_fill_sketch() or any fill scale to style it.

...

Other arguments passed on to the flow layer.

box_width

Width of the stratum boxes in x units. Default 0.18.

stratum_gap

Vertical gap between adjacent strata, as a fraction of the axis total. Default 0.02; 0 stacks them flush.

fill_style

Flow fill style; see geom_sketch_polygon(). Default "solid".

alpha

Flow opacity. Default 0.7.

strata_fill

Fill colour of the stratum boxes. Default "grey85".

label

Draw stratum labels? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
df <- as.data.frame(Titanic)
ggplot() +
  geom_sketch_alluvial(df, axes = c("Class", "Sex", "Survived"),
                       value = "Freq", seed = 1L) +
  scale_fill_sketch() +
  theme_void()

Sketchy arc diagram

Description

Draws a hand-drawn arc diagram: nodes are placed along a horizontal line and every weighted relation is a roughened semicircle arching over (or under) the axis between its two endpoints. Like geom_sketch_chord() but linear, it is a constructor that returns a list of ordinary sketch layers (arcs, node points and handwriting labels), so it composes with +; pair it with theme_void() or theme_sketch(). Edges are coloured by their source node; add scale_colour_sketch() (or any colour scale). No new dependencies.

Usage

geom_sketch_arc_diagram(
  data,
  from,
  to,
  value,
  ...,
  nodes = NULL,
  side = c("top", "bottom"),
  node_size = 3,
  node_colour = "grey25",
  max_linewidth = 2,
  alpha = 0.7,
  label = TRUE,
  label_size = 3.5,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame of weighted edges (one row per relation).

from, to

Unquoted column names giving the two endpoints of each edge.

value

Unquoted column name giving the edge weight. Default: every edge counts as 1 (and node size is the edge count).

...

Other arguments passed on to the arc layer.

nodes

Optional character vector fixing the node order along the axis (default: sorted unique endpoints).

side

Which way the arcs bow: "top" (default) or "bottom".

node_size, node_colour

Node-point size (scaled by incident weight) and colour.

max_linewidth

Arc stroke width at the heaviest edge (lighter edges scale down). Default 2.

alpha

Arc opacity. Default 0.7.

label

Draw node labels? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
rel <- data.frame(
  from  = c("A", "A", "B", "C", "C", "D"),
  to    = c("B", "C", "C", "D", "E", "E"),
  value = c(3, 1, 2, 4, 2, 1)
)
ggplot() +
  geom_sketch_arc_diagram(rel, from, to, value, seed = 1L) +
  scale_colour_sketch() +
  theme_void()

Sketchy 2-D bin heatmap

Description

Bins data into a rectangular grid and draws each cell as a hand-drawn rectangle shaded by count - the sketch analogue of ggplot2::geom_bin_2d() / ggplot2::stat_bin_2d(). geom_sketch_bin2d() and geom_sketch_bin_2d() are aliases.

Usage

geom_sketch_bin2d(
  mapping = NULL,
  data = NULL,
  stat = "bin2d",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_bin_2d(
  mapping = NULL,
  data = NULL,
  stat = "bin2d",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity" for geom_sketch_col(); "count" for geom_sketch_bar().

position

Position adjustment. Default "stack".

...

Other arguments passed on to the layer.

bins

Number of bins in each direction. Default 30.

binwidth

Bin width(s); overrides bins when supplied.

roughness

Non-negative roughness (0 = straight lines). A mappable aesthetic (default 1): pass a constant, or map it per bar with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the bar's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions, waiting)) +
  geom_sketch_bin2d(bins = 12, seed = 1L) +
  theme_sketch()

Sketchy bump (ranking) chart

Description

Draws a hand-drawn bump chart: each series' rank at every time point, joined across adjacent times by smooth roughened curves so a crossing reads as one series overtaking another. Like geom_sketch_alluvial() it is a constructor returning a list of ordinary sketch layers (connector ribbons, rank points and end labels), so it composes with +; map a colour scale over the series and pair with theme_void() or theme_sketch(). No new dependencies (cf. ggbump).

Usage

geom_sketch_bump(
  data,
  x,
  group,
  value,
  ...,
  direction = c("desc", "asc"),
  point_size = 3,
  line_width = 1.2,
  alpha = 0.9,
  label = TRUE,
  label_size = 3.5,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A long data frame (one row per series per time point).

x, group, value

Unquoted column names: the (ordinal) time, the series, and the value ranked within each time.

...

Other arguments passed on to the connector layer.

direction

"desc" (default) ranks the highest value as rank 1, drawn at the top; "asc" flips it.

point_size

Size of the rank points. Default 3.

line_width

Connector line width. Default 1.2.

alpha

Connector opacity. Default 0.9.

label

Draw series labels at the first and last time point? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
df <- data.frame(
  year = rep(2018:2021, each = 4),
  team = rep(c("A", "B", "C", "D"), times = 4),
  pts  = c(10, 8, 6, 4,  6, 10, 8, 4,  8, 6, 10, 5,  4, 8, 6, 12)
)
ggplot() +
  geom_sketch_bump(df, year, team, pts, seed = 1L) +
  scale_colour_sketch() +
  theme_void()

Sketchy chord diagram

Description

Draws a hand-drawn chord diagram: nodes are placed on a circle, each given an arc proportional to its total flow, and every weighted relation becomes a ribbon whose ends are sub-arcs on the two nodes, joined by curves through the centre. Like geom_sketch_sf(), this is a constructor that returns a list of ordinary sketch layers (roughened ribbons, rim segments and handwriting labels), so it composes with +; pair it with coord_equal() and theme_void(). No new dependencies (cf. circlize::chordDiagram()).

Usage

geom_sketch_chord(
  data,
  from,
  to,
  value,
  ...,
  gap = 0.04,
  rim_width = 0.1,
  fill_style = "solid",
  alpha = 0.65,
  label = TRUE,
  label_size = 4,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame of weighted edges (one row per relation).

from, to

Unquoted column names giving the two endpoints of each edge.

value

Unquoted column name giving the edge weight. Default: every edge counts as 1.

...

Other arguments passed on to the ribbon layer.

gap

Angular gap between adjacent nodes, in radians. Default 0.04.

rim_width

Width of the node rim, as a fraction of the radius. Default 0.1.

fill_style

Ribbon fill style; see geom_sketch_polygon(). Default "solid".

alpha

Ribbon fill opacity. Default 0.65.

label

Draw node labels? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Details

Supply an edge table as data and name the from, to and value columns (unquoted). Ribbons are coloured by their source node; add scale_fill_sketch() (or any fill scale) to control the palette.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
trade <- data.frame(
  from  = c("A", "A", "B", "C", "C", "D"),
  to    = c("B", "C", "C", "D", "A", "B"),
  value = c(5, 3, 2, 4, 1, 6)
)
ggplot() +
  geom_sketch_chord(trade, from, to, value, seed = 1L) +
  scale_fill_sketch() +
  coord_equal() +
  theme_void()

Sketchy contour lines

Description

geom_sketch_contour() draws contour lines of a 3-D surface with a hand-drawn stroke (the sketch analogue of ggplot2::geom_contour() / ggplot2::stat_contour()); it needs x, y, and z aesthetics. Each contour piece becomes one roughened path.

Usage

geom_sketch_contour(
  mapping = NULL,
  data = NULL,
  stat = "contour",
  position = "identity",
  ...,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

bins

Number of contour bins. Overridden by binwidth or breaks.

binwidth

Distance between contour bins.

breaks

Explicit numeric contour breaks; overrides bins/binwidth.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithfuld, aes(waiting, eruptions, z = density)) +
  geom_sketch_contour(colour = "#2E4053", seed = 1L) +
  theme_sketch()

Sketchy count geom

Description

Like ggplot2::geom_count(): draws a sketch point at each ⁠(x, y)⁠ location sized by the number of observations there, via ggplot2::stat_sum(). Pair with ggplot2::scale_size_area() for honest area scaling.

Usage

geom_sketch_count(
  mapping = NULL,
  data = NULL,
  stat = "sum",
  position = "identity",
  ...,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings. Supports x, y, colour, size, alpha, and roughness.

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mpg, aes(cty, hwy)) +
  geom_sketch_count(colour = "#7BAFD4", seed = 1L) +
  theme_sketch()

Sketchy dendrogram (hierarchical-clustering tree)

Description

Draws a hand-drawn dendrogram: leaves along one axis and each merge bracketed at its cluster height, with the right-angle elbows roughened into a hand-drawn wobble. Pass either a ready stats::hclust() object or a numeric data frame / matrix (a tree is then computed via stats::hclust(stats::dist(x))). Like geom_sketch_chord() it is a constructor returning a list of ordinary sketch layers (elbow paths + leaf labels), so it composes with +; pair it with theme_void() or theme_sketch(). Pure base stats; no new dependencies (cf. ggdendro).

Usage

geom_sketch_dendrogram(
  data,
  ...,
  orientation = c("up", "down", "left", "right"),
  method = "complete",
  distance = "euclidean",
  line_colour = "grey25",
  line_width = 0.8,
  label = TRUE,
  label_size = 3,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

An stats::hclust() object, or a numeric data frame / matrix to cluster (non-numeric columns are dropped; row names become leaf labels).

...

Other arguments passed on to the connector layer.

orientation

Tree direction: "up" (default, root at top), "down", "left", or "right".

method, distance

Linkage method and distance metric, used only when data is not already an hclust (passed to stats::hclust() and stats::dist()). Defaults "complete" / "euclidean".

line_colour, line_width

Connector colour and width.

label

Draw leaf labels? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
ggplot() +
  geom_sketch_dendrogram(mtcars[1:8, c("mpg", "wt", "hp")], seed = 1L) +
  theme_void()

Sketchy density geom

Description

Draws a kernel density estimate as a hand-drawn filled area - the sketch analogue of ggplot2::geom_density(). Drawing is delegated to GeomSketchArea; the kernel density is computed by ggplot2::stat_density().

Usage

geom_sketch_density(
  mapping = NULL,
  data = NULL,
  stat = "density",
  position = "identity",
  ...,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  outline.type = "full",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

roughness

Non-negative roughness (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in npc units (NULL = 6% of diagonal).

fill_weight

Stroke weight for fill lines. Default 0.5.

outline.type

Kept for signature parity with ggplot2::geom_density(); ignored (the rough outline always traces the full band).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer (a LayerInstance object) that can be added to a plot with +.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions)) +
  geom_sketch_density(fill = "khaki", seed = 1L) +
  theme_sketch()

Sketchy 2-D density contours

Description

geom_sketch_density2d() (alias geom_sketch_density_2d()) draws contour lines of a 2-D kernel density estimate with a hand-drawn stroke - the sketch analogue of ggplot2::geom_density_2d() / ggplot2::stat_density_2d(). Needs x and y aesthetics. Uses MASS (pulled in by ggplot2).

Usage

geom_sketch_density2d(
  mapping = NULL,
  data = NULL,
  stat = "density_2d",
  position = "identity",
  ...,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_density_2d(
  mapping = NULL,
  data = NULL,
  stat = "density_2d",
  position = "identity",
  ...,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples


library(ggplot2)
ggplot(faithful, aes(eruptions, waiting)) +
  geom_sketch_point(colour = "grey60", seed = 1L) +
  geom_sketch_density2d(colour = "#884EA0", seed = 2L) +
  theme_sketch()

Sketchy empirical cumulative distribution

Description

geom_sketch_ecdf() draws the empirical CDF of a continuous variable as a hand-drawn stairstep - the sketch analogue of ggplot2::stat_ecdf() / geom_step(stat = "ecdf"). Needs an x aesthetic; each group gets its own curve.

Usage

geom_sketch_ecdf(
  mapping = NULL,
  data = NULL,
  stat = "ecdf",
  position = "identity",
  ...,
  n = NULL,
  pad = FALSE,
  roughness = 0.8,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity".

position

Position adjustment. Default "identity".

...

Other arguments passed on to the layer.

n

If NULL (default), the ECDF jumps at each observed value; otherwise the curve is evaluated at n evenly spaced points (passed to ggplot2::stat_ecdf()).

pad

If TRUE, add -Inf/Inf plateaus at the ends. Default FALSE (the roughened line spans the data range only, avoiding infinite coordinates).

roughness

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg)) +
  geom_sketch_ecdf(colour = "#2E86C1", seed = 1L) +
  theme_sketch()

Sketchy function curve

Description

Draws the curve of a function y = fun(x) with a hand-drawn stroke - the sketch analogue of ggplot2::geom_function(), built on ggplot2::stat_function().

Usage

geom_sketch_function(
  mapping = NULL,
  data = NULL,
  stat = "function",
  position = "identity",
  ...,
  fun = NULL,
  xlim = NULL,
  n = 101,
  args = list(),
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

fun

Function to evaluate, or its name as a string.

xlim

Optional numeric range over which to evaluate fun; defaults to the panel x range.

n

Number of points to sample along the curve. Default 101.

args

List of extra arguments passed to fun.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(data.frame(x = c(-3, 3)), aes(x)) +
  geom_sketch_function(fun = dnorm, colour = "#7BAFD4", seed = 1L) +
  theme_sketch()

Sketchy histogram and frequency polygon

Description

geom_sketch_histogram() bins a continuous variable and draws hand-drawn bars (the sketch analogue of ggplot2::geom_histogram()). geom_sketch_freqpoly() draws the same bin counts as a roughened line (ggplot2::geom_freqpoly()).

Usage

geom_sketch_histogram(
  mapping = NULL,
  data = NULL,
  stat = "bin",
  position = "stack",
  ...,
  bins = 30,
  binwidth = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_freqpoly(
  mapping = NULL,
  data = NULL,
  stat = "bin",
  position = "identity",
  ...,
  bins = 30,
  binwidth = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation. Default "identity" for geom_sketch_col(); "count" for geom_sketch_bar().

position

Position adjustment. Default "stack".

...

Other arguments passed on to the layer.

bins

Number of bins (passed to ggplot2::stat_bin()). Default 30.

binwidth

Bin width; overrides bins when supplied.

roughness

Non-negative roughness (0 = straight lines). A mappable aesthetic (default 1): pass a constant, or map it per bar with aes(roughness = ) (rescaled by scale_roughness_continuous()).

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed. NULL uses getOption("ggsketch.seed", 1L).

fill_style

One of "hachure", "cross_hatch", "zigzag", "zigzag_line", "scribble", "dots", "dashed", "stipple", "pencil_shade", or "solid". Default "hachure".

hachure_angle

Fill line angle in degrees. Default 45.

hachure_gap

Fill line gap in device inches (NULL = 15% of the bar's smaller drawn side, clamped to [0.04, 0.4] inches).

fill_weight

Stroke weight for fill lines. Default 0.5.

na.rm

Remove missing values silently? Default FALSE.

show.legend

Logical; include in legend?

inherit.aes

Override default aesthetics?

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(faithful, aes(eruptions)) +
  geom_sketch_histogram(fill = "#7BAFD4", bins = 20, seed = 1L) +
  theme_sketch()

Sketchy jittered points

Description

A convenience wrapper around geom_sketch_point() that adds a small amount of random position noise to reduce overplotting - the sketch analogue of ggplot2::geom_jitter().

Usage

geom_sketch_jitter(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = NULL,
  ...,
  width = NULL,
  height = NULL,
  roughness = NULL,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings. Supports x, y, colour, size, alpha, and roughness.

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

width, height

Amount of horizontal/vertical jitter (passed to ggplot2::position_jitter()). NULL uses 40% of the data resolution.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mpg, aes(class, hwy)) +
  geom_sketch_jitter(width = 0.25, seed = 1L) +
  theme_sketch()

Sketchy Marimekko (variable-width stacked bar) chart

Description

Draws a hand-drawn Marimekko / Mekko chart: each column's width is one category's (x) share of the total, and within a column the stacked segments are a second category's (fill) shares, so every roughened tile's area is the joint value. It is the value-weighted, segment-coloured cousin of geom_sketch_mosaic() (and reuses its layout). Like geom_sketch_chord() it is a constructor returning a list of ordinary sketch layers (tiles coloured by fill, column labels, and optional width-percent labels), so it composes with + and any fill scale; pair it with theme_void() or theme_sketch().

Usage

geom_sketch_marimekko(
  data,
  x,
  fill,
  value,
  ...,
  gap = 0.008,
  fill_style = "solid",
  alpha = 1,
  colour = "grey30",
  label = TRUE,
  width_labels = TRUE,
  label_size = 3.2,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame.

x

Unquoted column name of the category that sets column widths.

fill

Unquoted column name of the category stacked within each column.

value

Unquoted column name giving the weight. Default: every row counts as 1.

...

Other arguments passed on to the tile layer.

gap

Gap between columns / segments, as a fraction of the unit square. Default 0.008 (Marimekko charts sit closer than mosaics).

fill_style

Tile fill style; see geom_sketch_rect(). Default "solid".

alpha

Tile fill opacity. Default 1.

colour

Tile outline colour. Default "grey30".

label

Draw column (x) labels under the chart? Default TRUE.

width_labels

Draw each column's width percentage on top? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
sales <- data.frame(
  region  = rep(c("North", "South", "East"), each = 3),
  product = rep(c("A", "B", "C"), times = 3),
  revenue = c(40, 30, 10,  25, 25, 30,  15, 20, 5)
)
ggplot() +
  geom_sketch_marimekko(sales, region, product, revenue, seed = 1L) +
  scale_fill_sketch() +
  theme_void()

Sketchy mosaic plot

Description

Draws a hand-drawn mosaic plot of two categorical variables: the width of each column is the marginal frequency of x, and the height of each tile within a column is the conditional frequency of y, so every tile's area is the joint frequency. Like geom_sketch_chord() it is a constructor that returns a list of ordinary sketch layers (roughened tiles coloured by y, plus column labels), so it composes with + and any fill scale; pair it with theme_void() or theme_sketch(). No new dependencies (cf. graphics::mosaicplot(), ggmosaic).

Usage

geom_sketch_mosaic(
  data,
  x,
  y,
  value = NULL,
  ...,
  fill_by = c("y", "x"),
  gap = 0.012,
  fill_style = "solid",
  alpha = 1,
  label = TRUE,
  label_size = 3.5,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame.

x, y

Unquoted column names: x splits the columns, y splits each column vertically.

value

Optional column name giving each row's weight (NULL = 1 each).

...

Other arguments passed on to the tile layer.

fill_by

Which variable colours the tiles: "y" (default) or "x".

gap

Gap between columns and rows, in unit-square fractions. Default 0.012.

fill_style

Tile fill style; see geom_sketch_rect(). Default "solid".

alpha

Tile opacity. Default 1.

label

Draw column labels? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
df <- as.data.frame(Titanic)
ggplot() +
  geom_sketch_mosaic(df, x = Class, y = Survived, value = Freq, seed = 1L) +
  scale_fill_sketch() +
  theme_void()

Sketchy parallel-coordinates plot

Description

Draws a hand-drawn parallel-coordinates plot: each numeric column in axes becomes a vertical axis, and every observation becomes a roughened polyline crossing the axes at its values. Axes are scaled independently to a common height by default. Like geom_sketch_chord() it is a constructor returning a list of ordinary sketch layers, so it composes with +; map colour to a column (add scale_colour_sketch() or any colour scale) and pair with theme_void() or theme_sketch(). No new dependencies (cf. GGally::ggparcoord(), MASS::parcoord()).

Usage

geom_sketch_parallel(
  data,
  axes,
  colour = NULL,
  ...,
  scale = "minmax",
  line_colour = "#1F618D",
  alpha = 0.7,
  axis_colour = "grey60",
  label = TRUE,
  label_size = 3.5,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame.

axes

Character vector of numeric column names to use as axes, in order (at least two).

colour

Optional column name to colour the lines by (NULL = one colour). Add a colour scale to style it.

...

Other arguments passed on to the line layer.

scale

Per-axis scaling: "minmax" (default, each axis to ⁠[0, 1]⁠) or "none" (raw values; only sensible when the axes share units).

line_colour

Colour used when colour is NULL. Default "#1F618D".

alpha

Line opacity. Default 0.7.

axis_colour

Colour of the vertical axes. Default "grey60".

label

Draw axis labels? Default TRUE.

label_size, label_colour

Axis-label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
ggplot() +
  geom_sketch_parallel(iris,
    axes = c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width"),
    colour = "Species", seed = 1L) +
  scale_colour_sketch() +
  theme_void()

Sketchy quantile-quantile plot

Description

geom_sketch_qq() draws Q-Q points (the sketch analogue of ggplot2::geom_qq() / ggplot2::stat_qq()); geom_sketch_qq_line() adds the reference line (ggplot2::geom_qq_line()). Map the data to the sample aesthetic.

Usage

geom_sketch_qq(
  mapping = NULL,
  data = NULL,
  stat = "qq",
  position = "identity",
  ...,
  distribution = stats::qnorm,
  dparams = list(),
  roughness = 0.5,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_qq_line(
  mapping = NULL,
  data = NULL,
  stat = "qq_line",
  position = "identity",
  ...,
  distribution = stats::qnorm,
  dparams = list(),
  roughness = 0.6,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings. Supports x, y, colour, size, alpha, and roughness.

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

distribution

Quantile function for the theoretical distribution. Default stats::qnorm.

dparams

List of parameters for distribution.

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
ggplot(mtcars, aes(sample = mpg)) +
  geom_sketch_qq(seed = 1L) +
  geom_sketch_qq_line(colour = "#C8553D", seed = 2L) +
  theme_sketch()

Sketchy quantile regression lines

Description

Fits and draws quantile regression lines with a hand-drawn stroke - the sketch analogue of ggplot2::geom_quantile() / ggplot2::stat_quantile(). Requires the optional quantreg package.

Usage

geom_sketch_quantile(
  mapping = NULL,
  data = NULL,
  stat = "quantile",
  position = "identity",
  ...,
  quantiles = c(0.25, 0.5, 0.75),
  formula = NULL,
  method = "rq",
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes().

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to the layer.

quantiles

Numeric vector of quantiles to fit. Default c(0.25, 0.5, 0.75).

formula

Model formula passed to quantreg::rq(). Default y ~ x.

method

Fitting method passed to ggplot2::stat_quantile(). Default "rq".

roughness

Non-negative roughness parameter (0 = straight). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Number of stroke passes for the double-stroke effect. Default 2.

seed

Integer seed for reproducibility. NULL uses getOption("ggsketch.seed", 1L).

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
if (requireNamespace("quantreg", quietly = TRUE)) {
  ggplot(mtcars, aes(wt, mpg)) +
    geom_sketch_point(seed = 1L) +
    geom_sketch_quantile(seed = 2L) +
    theme_sketch()
}

Sketchy coxcomb / Nightingale rose chart

Description

Draws a hand-drawn coxcomb (polar area) chart: each category of x occupies an equal angular wedge and its value sets the radius, so the wedges fan out like a rose. With area_true = TRUE the sector area (not radius) encodes value, as in Florence Nightingale's original mortality roses. An optional fill category stacks radially within each wedge. Like geom_sketch_chord() it is a constructor returning a list of ordinary sketch layers (roughened annular sectors + labels), so it composes with +; pair it with coord_equal() and theme_void(), and add scale_fill_sketch().

Usage

geom_sketch_rose(
  data,
  x,
  value,
  fill = NULL,
  ...,
  area_true = FALSE,
  fill_style = "solid",
  alpha = 0.9,
  colour = "grey30",
  label = TRUE,
  label_size = 3.2,
  label_colour = "grey20",
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame.

x

Unquoted column name of the category that sets the angular wedges.

value

Unquoted column name giving the magnitude (radius / area).

fill

Optional unquoted column name of a second category to stack radially within each wedge (NULL = one segment per wedge, coloured by x).

...

Other arguments passed on to the sector layer.

area_true

If TRUE, sector area is proportional to value (radius is the square root) - Nightingale's convention. Default FALSE (radius is proportional to value).

fill_style

Sector fill style; see geom_sketch_polygon(). Default "solid".

alpha

Sector opacity. Default 0.9.

colour

Sector outline colour. Default "grey30".

label

Draw category labels around the rim? Default TRUE.

label_size, label_colour

Label text controls.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
deaths <- data.frame(
  month = month.abb,
  n     = c(12, 18, 25, 30, 22, 15, 10, 14, 20, 28, 24, 16)
)
ggplot() +
  geom_sketch_rose(deaths, month, n, area_true = TRUE, seed = 1L) +
  scale_fill_sketch() +
  coord_equal() +
  theme_void()

Sketchy sunburst (hierarchy) chart

Description

Draws a hand-drawn sunburst: a hierarchy rendered as nested rings of annular sectors. The columns named in levels define the hierarchy outermost-to- innermost (levels[1] is the inner root ring); each deeper ring splits its parent's angular span by the children's summed value, so a child always nests inside its parent. Like geom_sketch_chord() it is a constructor returning a list of ordinary sketch layers (roughened annular sectors plus optional labels), so it composes with +; pair it with coord_equal() and theme_void(), and add scale_fill_sketch() (or any fill scale) to colour it. Reuses no new dependencies (cf. sunburstR, plotly).

Usage

geom_sketch_sunburst(
  data,
  levels,
  value = NULL,
  ...,
  r0 = 0.15,
  ring_width = NULL,
  fill_by = c("root", "self", "depth"),
  fill_style = "solid",
  alpha = 0.9,
  colour = "grey30",
  label = FALSE,
  label_size = 3,
  label_colour = "grey20",
  min_label_angle = 0.15,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

data

A data frame, one row per observation (or per leaf).

levels

Character vector of column names giving the hierarchy, from the inner root ring outward (at least one).

value

Optional column name giving the leaf weight (NULL = every row counts as 1).

...

Other arguments passed on to the sector layer.

r0

Radius of the central hole, in the unit circle. Default 0.15.

ring_width

Radial width of each ring. NULL (default) divides the space r0..1 evenly across the levels.

fill_by

What the sector fill encodes: "root" (default, the top-level ancestor - the classic sunburst look), "self" (each node's own label), or "depth" (the ring number).

fill_style

Sector fill style; see geom_sketch_polygon(). Default "solid".

alpha

Sector fill opacity. Default 0.9.

colour

Sector outline colour. Default "grey30".

label

Draw a label on each sector? Default FALSE (sunbursts get busy; only sectors with a wide enough angle are labelled).

label_size, label_colour

Label text controls.

min_label_angle

Minimum angular span (radians) a sector needs before it is labelled. Default 0.15.

roughness, bowing, n_passes, seed

Sketch parameters.

Value

A list of ggplot2 layers.

Examples

library(ggplot2)
df <- data.frame(
  region = c("West", "West", "West", "East", "East", "East"),
  dept   = c("Sales", "Sales", "Eng", "Sales", "Eng", "Eng"),
  team   = c("A", "B", "C", "D", "E", "F"),
  n      = c(4, 2, 6, 3, 5, 1)
)
ggplot() +
  geom_sketch_sunburst(df, levels = c("region", "dept", "team"),
                       value = "n", seed = 1L) +
  scale_fill_sketch() +
  coord_equal() +
  theme_void()

Sketchy text and labels

Description

geom_sketch_text() and geom_sketch_label() add text in a handwriting font, the sketch counterparts of ggplot2::geom_text() and ggplot2::geom_label(). Unlike the other geoms the strokes are not geometrically roughened - the hand-drawn feel comes from the font (see ggsketch_check_fonts() for which faces are available). If no handwriting font is installed they render with the device default family.

Usage

geom_sketch_text(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  family = NULL,
  nudge_x = 0,
  nudge_y = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_sketch_label(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  family = NULL,
  nudge_x = 0,
  nudge_y = 0,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by ggplot2::aes(). Requires a label aesthetic.

data

Data to display.

stat

Statistical transformation (default "identity").

position

Position adjustment (default "identity").

...

Other arguments passed on to ggplot2::layer(), such as size, colour, angle, or hjust.

family

Font family. By default the first installed handwriting face is used; pass an explicit family to override, or "" for the device default.

nudge_x, nudge_y

Horizontal and vertical adjustment to nudge labels by. Useful for offsetting text from points. Cannot be used together with an explicit position.

na.rm

If FALSE (default), missing values are removed with a warning.

show.legend

Logical. Should this layer be included in the legend?

inherit.aes

If FALSE, override the default aesthetics.

Value

A ggplot2 layer object.

Examples

library(ggplot2)
df <- data.frame(x = c(1, 2, 3), y = c(2, 3, 1),
                 lab = c("alpha", "bravo", "charlie"))

# `family = ""` uses the device default, so this runs on any device.
ggplot(df, aes(x, y, label = lab)) +
  geom_sketch_text(size = 6, family = "") +
  theme_sketch()

# With no `family`, the first installed handwriting font is used instead (see
# `ggsketch_check_fonts()`). That requires a font-capable device (ragg,
# svglite, cairo); pass `family = ""` (above) for fully portable output on any
# device, including the base pdf() / postscript().

Check for optional handwriting fonts

Description

Diagnoses whether a handwriting-style font is available on this device. The sketch look in ggsketch comes from geometry, not fonts, so this is purely cosmetic (ADR-0005).

Usage

ggsketch_check_fonts(fonts = sketch_font_candidates())

Arguments

fonts

Character vector of font families to check. Defaults to the same candidate list geom_sketch_text() resolves against - preferred handwriting faces first, then fonts preinstalled on Windows / macOS.

Value

Invisibly returns a logical vector (font available?); prints a formatted report.

Save a sketch plot with a font-aware device

Description

A drop-in ggplot2::ggsave() wrapper that picks a device which can see fonts registered with register_sketch_font() / systemfonts:

Usage

ggsketch_save(
  filename,
  plot = ggplot2::last_plot(),
  width = 8,
  height = 5,
  dpi = 300,
  device = NULL,
  ...
)

Arguments

filename

File to write; the extension picks the device.

plot

Plot to save. Default ggplot2::last_plot().

width, height

Size in inches. Defaults 8 x 5.

dpi

Resolution for raster formats. Default 300.

device

Override the chosen device (a function or name); passed through to ggplot2::ggsave() untouched when supplied.

...

Other arguments passed on to ggplot2::ggsave().

Details

.png / .jpeg / .jpg / .tiff – ragg when installed (falls back to the ggsave default with a hint).
.svg – svglite when installed.
.pdf – cairo_pdf (embeds registered fonts; the base pdf device does not).
.eps / .ps – cairo_ps, with a warning: PostScript cannot embed handwriting faces reliably, so prefer PDF.

Value

Invisibly, filename.

Examples


library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) + geom_sketch_point(seed = 1L) +
  theme_sketch()
out <- file.path(tempdir(), "sketch.png")
ggsketch_save(out, p)
unlink(out)

Fill a polygon with hachure lines using the AET scan-line algorithm

Description

Fill a polygon with hachure lines using the AET scan-line algorithm

Usage

hachure_fill(
  px,
  py,
  hachure_gap = 0.1,
  hachure_angle = 45,
  roughness = 0,
  bowing = 0,
  seed = NULL
)

Arguments

px, py

Polygon vertex coordinates in inch space. May be open or closed.

hachure_gap

Spacing between fill lines (inches). Default 0.1.

hachure_angle

Fill angle (degrees). Default 45.

roughness

Roughness applied to each fill line. Default 0 (straight).

bowing

Bowing applied to each fill line. Default 0.

seed

Integer seed.

Value

A list of 2-column (x, y) matrices, one per fill line (roughened if roughness > 0, otherwise two-point straight segments).

Fill a multi-ring region with hachure lines (hole-aware)

Description

Like hachure_fill() but takes a list of rings sharing one Active Edge Table, so the even-odd scan-line parity excludes holes and skips the gaps between disjoint pieces automatically. This is what powers the filled contour / 2-D density band geoms, whose regions have holes.

Usage

hachure_fill_multi(
  rings,
  hachure_gap = 0.1,
  hachure_angle = 45,
  roughness = 0,
  bowing = 0,
  seed = NULL
)

Arguments

rings

A list of rings, each a list with numeric x and y vertex vectors (inch space). The first ring is typically the outer boundary and the rest holes, but any even-odd arrangement of outer pieces and holes is handled.

hachure_gap

Spacing between fill lines (inches). Default 0.1.

hachure_angle

Fill angle (degrees). Default 45.

roughness

Roughness applied to each fill line. Default 0 (straight).

bowing

Bowing applied to each fill line. Default 0.

seed

Integer seed.

Value

A list of 2-column (x, y) fill-line matrices (same structure as hachure_fill()).

Route a leader line from a box edge to a target

Description

The un-roughened path a callout / annotation leader takes from its start ⁠(sx, sy)⁠ (a box edge) to the target ⁠(xe, ye)⁠: a "straight" line, an "elbow" (horizontal then vertical, flowchart style) or a "curved" quadratic-Bezier bow. Also reports the end tangent so the arrowhead can orient to it. Pure geometry; the grob roughens the result.

Usage

leader_path(sx, sy, xe, ye, style = "straight", curvature = 0.3)

Arguments

sx, sy

Leader start (inch space).

xe, ye

Target point (inch space).

style

One of "straight", "elbow", "curved".

curvature

Bow size for "curved" (signed). Default 0.3.

Value

A list with x, y (the path vertices) and angle (end tangent, in radians).

Examples

leader_path(0, 0, 1, 1, style = "elbow")

Wash-feathering grain factor for a paper ground

Description

How toothy a sketch_papers() ground is, as a number a watercolour wash uses to feather its edges (the grain argument of watercolor_wash()). Smooth grounds wick little; rough grounds (aged, kraft) wick a lot. Smooth, machine papers (notebook / graph / dotted) sit low; the textured grounds climb toward

theme_sketch(paper = ) reads this so washes drawn on a paper pick up its tooth automatically.

Usage

paper_grain(kind)

Arguments

kind

A value from sketch_papers().

Value

A numeric grain factor in ⁠[0, 1]⁠ (0 for "none").

Examples

paper_grain("kraft")
paper_grain("graph")

Build the vector primitives for a paper ground

Description

Turns a paper_spec() into draw-ready primitives in npc coordinates, spaced for the given physical panel size. The grob layer (element_sketch_paper()) renders the result; this function stays free of any grid dependency.

Usage

paper_primitives(kind, width_in = 6, height_in = 4, seed = NULL)

Arguments

kind

A value from sketch_papers().

width_in, height_in

Panel size in inches (sets the ruling pitch).

seed

Integer seed (for aged blotches).

Value

A list with ground (fill colour) and zero or more of segs (a list of homogeneous line groups, each list(x0, y0, x1, y1, colour, lwd)), dots (list(x, y, r_in, colour)), and blotches (a list of list(x, y, fill) polygons), or NULL for "none".

Palette + layout spec for a paper ground

Description

Pure data: the ground colour, a suggested ink colour, whether the ground is dark (so text should flip light), and the ruling/grid/dot layout.

Usage

paper_spec(kind)

Arguments

kind

A value from sketch_papers().

Value

A named list describing the paper, or NULL for "none".

Register a handwriting font for reproducible sketch text

Description

Registers a font file under a family name with systemfonts so that geom_sketch_text(), theme_sketch() (base_family = "auto"), and the font resolver can find it on font-aware devices (ragg, svglite, cairo) without installing the font system-wide. Call it once per session (e.g. in a script or .Rprofile); ship the .ttf/.otf alongside your project for fully reproducible output.

Usage

register_sketch_font(
  family,
  plain,
  bold = plain,
  italic = plain,
  bolditalic = plain,
  ...
)

Arguments

family

Family name to register the font under (e.g. "Caveat"). This is the name you then pass to ⁠family =⁠ or ⁠base_family =⁠.

plain

Path to the regular/plain font file (.ttf or .otf).

bold, italic, bolditalic

Optional paths to the bold/italic faces; default to plain.

...

Passed to systemfonts::register_font().

Value

Invisibly, the registered family name.

Examples


# Register any font file under a family name you choose. Here we reuse a font
# already on the system; in practice point `plain` at a handwriting .ttf/.otf
# (e.g. Caveat from Google Fonts).
f <- systemfonts::system_fonts()$path[1]
register_sketch_font("MySketchFont", f)

Repel overlapping label boxes away from each other and their anchors

Description

A small physical solver behind geom_sketch_text_repel() / geom_sketch_label_repel(). Each label starts near its anchor and is pushed by three forces, iterated to rest: boxes that overlap shove each other apart along their axis of least penetration (preferring an axis with room left inside the bounds, so pairs pressed into a panel corner escape along the edge instead of staying stuck); a box covering any anchor point slides off it; and a weak spring pulls each box back toward its own anchor so labels stay close to what they name. Positions are clamped to xlim / ylim.

Usage

repel_layout(
  ax,
  ay,
  w,
  h,
  xlim = c(-Inf, Inf),
  ylim = c(-Inf, Inf),
  box_padding = 0.1,
  point_padding = 0.05,
  max_iter = 2000L,
  seed = NULL
)

Arguments

ax, ay

Anchor points (one per label), in a single isotropic space (e.g. device inches).

w, h

Label box width and height (same units), recycled to the anchors.

xlim, ylim

Length-2 bounds the box centres are kept within.

box_padding, point_padding

Extra clearance around boxes and around anchor points, in the same units.

max_iter

Maximum solver iterations. Default 2000.

seed

Integer seed (for the tiny start jitter that separates labels sharing an anchor).

Value

A list with x, y (the resolved box centres) and iter (iterations actually run).

Examples

repel_layout(c(0, 0.1, 0.1), c(0, 0, 0.05), w = 0.4, h = 0.2, seed = 1L)

Roughen an elliptical arc into one or more sketch stroke paths

Description

The open-arc sibling of rough_ellipse(). Samples the arc by arc length, displaces each point slightly, and returns n_passes overlaid strokes for the double-stroke hand-drawn look. Unlike a full ellipse the path is left open (the ends are not joined).

Usage

rough_arc(
  cx,
  cy,
  rx,
  ry,
  start,
  end,
  roughness = 1,
  n_passes = 2L,
  seed = NULL
)

Arguments

cx, cy

Centre coordinates in inch space.

rx, ry

Semi-axis radii in inches.

start, end

Start/end angle in radians (counter-clockwise from the positive x-axis; end may be less than start).

roughness

Non-negative roughness parameter. Default 1.

n_passes

Number of stroke overlays. Default 2.

seed

Integer seed for reproducibility.

Value

List of n_passes 2-column (x, y) matrices of stroke points.

Roughen a cubic Bezier curve

Description

Applies roughness to all four control points, then flattens and reduces the curve. Returns n_passes roughened polyline paths.

Usage

rough_bezier(
  P0,
  P1,
  P2,
  P3,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  tol = NULL,
  rdp_eps = NULL
)

Arguments

P0, P1, P2, P3

Control points as length-2 numeric vectors c(x, y) in inch space.

roughness

Non-negative roughness radius (inches). Default 1.

bowing

Bowing multiplier (currently not applied to Bezier control points separately; roughness serves the role). Default 1.

n_passes

Number of stroke passes. Default 2.

seed

Integer seed for reproducibility.

tol

Flatness tolerance. Default max(roughness * 0.01, 1e-4).

rdp_eps

RDP epsilon. Default max(roughness * 0.005, 1e-5).

Value

List of n_passes 2-column (x, y) matrices.

Roughen an ellipse into one or more sketch stroke paths

Description

Generates points around the ellipse, roughens them, and connects them with a smooth path (sampled cubic Bezier between consecutive point-pairs). Deliberately leaves a small gap at the close point ("ends don't meet" hand-drawn effect).

Usage

rough_ellipse(cx, cy, rx, ry, roughness = 1, n_passes = 2L, seed = NULL)

Arguments

cx, cy

Centre coordinates in inch space.

rx, ry

Semi-axis radii in inches (rx = horizontal, ry = vertical).

roughness

Non-negative roughness parameter. Default 1.

n_passes

Number of stroke overlays. Default 2.

seed

Integer seed for reproducibility.

Value

List of n_passes 2-column (x, y) matrices of stroke points.

Roughen a polyline (multiple connected segments)

Description

Converts a multi-vertex polyline into n_passes roughened stroke paths. Each path is a matrix with columns x and y (inch coordinates). Uses a seeded local RNG so the user's .Random.seed is never mutated (T-CORE-06).

Usage

roughen_polyline(x, y, roughness = 1, bowing = 1, n_passes = 2L, seed = NULL)

Arguments

x, y

Numeric vectors of polyline vertices in inch space. Must have the same length >= 2.

roughness

Non-negative roughness radius (inches at scale). Default 1.

bowing

Non-negative bowing multiplier. Default 1.

n_passes

Positive integer number of stroke passes (default 2).

seed

Integer seed for reproducibility (ADR-0004).

Value

A list of n_passes matrices (columns x, y), one per pass.

Discrete scale for the drawing `medium` aesthetic

Description

Maps a discrete variable to drawing media (see sketch_media()) when it is mapped with aes(medium = ) on a path-like sketch geom (geom_sketch_line(), geom_sketch_path(), geom_sketch_segment(), geom_sketch_step()). Because of its name, ggplot2 picks it up automatically; you only need to call it directly to choose which media to use or to set legend options.

Usage

scale_medium_discrete(..., media = NULL)

Arguments

...

Passed to ggplot2::discrete_scale() (e.g. name, labels, guide).

media

Character vector of media to cycle through, each one of sketch_media(). Defaults to every medium except "pen" (so mapped levels look distinct); recycled with a warning if there are more levels than media.

Details

Each group is drawn in a single medium, so map medium to the same variable you group by (often colour or group).

Value

A ggplot2 scale object.

Examples

library(ggplot2)
df <- data.frame(
  x = rep(1:10, 3),
  y = c(1:10, (1:10) + 4, (1:10) + 8),
  g = rep(c("a", "b", "c"), each = 10)
)
ggplot(df, aes(x, y, group = g, medium = g, colour = g)) +
  geom_sketch_line(linewidth = 1, seed = 1L) +
  scale_medium_discrete() +
  theme_sketch()

Continuous scale for the sketch `pressure` aesthetic

Description

geom_sketch_line() and geom_sketch_path() let you map a variable to pressure (aes(pressure = z)) so the stroke swells and thins along the line, like a real pen pressed harder in places. This scale rescales that variable's observed range to a band of width multipliers, just as scale_size() rescales to a size range. It is applied automatically whenever pressure is mapped to a continuous variable, so you only call it directly to change range. To use values as raw width multipliers with no rescaling, wrap them in base::I() (aes(pressure = I(z))).

Usage

scale_pressure_continuous(..., range = c(0.2, 1.6), guide = "none")

scale_pressure(..., range = c(0.2, 1.6), guide = "none")

Arguments

...

Other arguments passed to ggplot2::continuous_scale().

range

Output width-multiplier range. Default c(0.2, 1.6): the lightest pressure draws the stroke at ⁠0.2x⁠ its base width, the heaviest at ⁠1.6x⁠.

guide

Legend guide. Defaults to "none" because the legend keys do not reflect pressure; set to "legend" to show one anyway.

Details

Mapping pressure renders the line through the variable-width stroke_ribbon() engine even under the default medium = "pen", and combines with a non-pen medium (the medium's own width profile is multiplied by the mapped pressure).

Value

A ggplot2 scale object.

Examples

library(ggplot2)

# A line whose width tracks a variable, rescaled to c(0.2, 1.6) automatically.
ggplot(economics[1:120, ], aes(date, unemploy, pressure = unemploy)) +
  geom_sketch_line(linewidth = 1, seed = 1L)

# Widen the band for a more dramatic swell.
ggplot(economics[1:120, ], aes(date, unemploy, pressure = unemploy)) +
  geom_sketch_line(linewidth = 1, seed = 1L) +
  scale_pressure_continuous(range = c(0.05, 2.5))

Continuous scale for the sketch `roughness` aesthetic

Description

geom_sketch_point() lets you map a variable to roughness (aes(roughness = z)). This scale rescales that variable's observed range to a legible band of roughness values, just as scale_size() rescales to a size range. It is applied automatically whenever roughness is mapped to a continuous variable, so you only call it directly to change range. To use values as raw roughness with no rescaling, wrap them in base::I() (aes(roughness = I(z))).

Usage

scale_roughness_continuous(..., range = c(0.01, 0.75), guide = "none")

scale_roughness(..., range = c(0.01, 0.75), guide = "none")

Arguments

...

Other arguments passed to ggplot2::continuous_scale().

range

Output roughness range. Default c(0.01, 0.75): 0.01 is effectively clean and 0.75 is clearly hand-drawn without becoming noise. Values above roughly 1 start to look scribbled.

guide

Legend guide. Defaults to "none" because the legend keys do not reflect roughness; set to "legend" to show one anyway.

Value

A ggplot2 scale object.

Examples

library(ggplot2)

# Mapped roughness is rescaled to c(0.01, 0.75) automatically.
ggplot(mtcars, aes(wt, mpg, roughness = hp)) +
  geom_sketch_point(size = 3, seed = 1L)

# Widen the band so the wobble difference is more dramatic.
ggplot(mtcars, aes(wt, mpg, roughness = hp)) +
  geom_sketch_point(size = 3, seed = 1L) +
  scale_roughness_continuous(range = c(0, 1.2))

Sketch colour and fill scales

Description

Discrete scales (scale_colour_sketch(), scale_fill_sketch()) use sketch_palette(); the continuous variants (⁠*_sketch_c()⁠) use a paper-to-ink blue gradient. They pair with theme_sketch() and the sketch geoms but work with any ggplot2 layer.

Usage

scale_colour_sketch(..., aesthetics = "colour", interpolate = TRUE)

scale_color_sketch(..., aesthetics = "colour", interpolate = TRUE)

scale_fill_sketch(..., aesthetics = "fill", interpolate = TRUE)

scale_colour_sketch_c(..., aesthetics = "colour")

scale_color_sketch_c(..., aesthetics = "colour")

scale_fill_sketch_c(..., aesthetics = "fill")

Arguments

...

Passed to ggplot2::discrete_scale() (discrete) or ggplot2::scale_colour_gradientn() (continuous).

aesthetics

Character vector of aesthetics this scale works with.

interpolate

Discrete scales only. When there are more than eight levels, interpolate the eight-colour sketch_palette() into one colour per level (the default) instead of recycling.

Value

A ggplot2 scale object.

Examples

library(ggplot2)
ggplot(mpg, aes(displ, hwy, colour = drv)) +
  geom_sketch_point(seed = 1L) +
  scale_colour_sketch() +
  theme_sketch()

Continuous scale for the engraving `tone` aesthetic

Description

geom_sketch_shade() shades each region by a tone aesthetic in ⁠[0, 1]⁠ (0 = blank paper, 1 = densest cross-hatch). Mapping a raw variable to tone (aes(tone = z)) rescales its observed range to a legible tone band with this scale, just as scale_size() rescales to a size range. It is applied automatically whenever tone is mapped to a continuous variable, so you only call it directly to change range (or to reverse it by giving a decreasing range). To use values as raw tone with no rescaling, wrap them in base::I() (aes(tone = I(z))).

Usage

scale_tone_continuous(..., range = c(0.15, 0.95), guide = "none")

scale_engrave(..., range = c(0.15, 0.95), guide = "none")

Arguments

...

Other arguments passed to ggplot2::continuous_scale().

range

Output tone range, within ⁠[0, 1]⁠. Default c(0.15, 0.95): 0.15 is the faintest hatch that still draws (the engraving ladder leaves tone below 0.12 as blank paper, so a lower floor would erase the lightest region entirely) and 0.95 is near-solid black. Give a decreasing range (e.g. c(0.95, 0.15)) to invert the mapping.

guide

Legend guide. Defaults to "none" because the legend keys do not reflect tone; set to "legend" to show one anyway.

Value

A ggplot2 scale object.

Examples

library(ggplot2)

hex <- data.frame(
  x = cos(seq(0, 2 * pi, length.out = 7))[-7],
  y = sin(seq(0, 2 * pi, length.out = 7))[-7]
)
regions <- do.call(rbind, lapply(1:3, function(k) {
  transform(hex, x = x + (k - 1) * 2.3, g = k, val = k)
}))

# `val` is rescaled to the default tone band c(0.15, 0.95) automatically.
ggplot(regions, aes(x, y, group = g)) +
  geom_sketch_shade(aes(tone = val), seed = 1L) +
  coord_equal()

# Push the darkest region all the way to solid black.
ggplot(regions, aes(x, y, group = g)) +
  geom_sketch_shade(aes(tone = val), seed = 1L) +
  scale_tone_continuous(range = c(0.15, 1)) +
  coord_equal()

Create a sketchy arrow grob

Description

Draws one or more hand-drawn arrows. The shaft is a quadratic Bezier (so it can curve) and the arrowhead is roughened and oriented to the curve's end tangent, both assembled in device inches so the head stays crisp and correctly angled on any panel shape. The arrowhead size can adapt to the shaft length.

Usage

sketch_arrow_grob(
  x0,
  y0,
  cx,
  cy,
  x1,
  y1,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  arrow_length = NULL,
  arrow_angle = 25,
  arrow_type = "open",
  arrow_head = NULL,
  ends = "last",
  gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x0, y0

Shaft start in npc [0,1] (vectors, one per arrow).

cx, cy

Quadratic-Bezier control point in npc (vectors). For a straight arrow pass the chord midpoint.

x1, y1

Shaft end / arrow tip in npc (vectors).

roughness, bowing, n_passes, seed

Sketch parameters.

arrow_length

Arrowhead length in inches. NULL (default) adapts it to the shaft length.

arrow_angle

Half-angle of the arrowhead in degrees. Default 25.

arrow_type

"open" (default) draws a two-stroke V; "closed" draws a filled rough triangle. Superseded by arrow_head; kept for back-compat.

arrow_head

Head style, one of sketch_arrowheads() ("triangle_open", "triangle_filled", "barb", "fishtail", "dot", "bar"). NULL (default) derives it from arrow_type.

ends

Which end(s) carry a head: "last" (default), "first", or "both".

gp

A grid::gpar() for the strokes (per-arrow col recycled).

name, vp

Passed to grid::gTree().

Value

A SketchArrowGrob grob subclass.

The available arrowhead styles

Description

Valid values for the head argument of geom_sketch_arrow(), annotate_sketch_arrow(), geom_sketch_callout() and the style of arrowhead().

Usage

sketch_arrowheads()

Value

A character vector of arrowhead names.

Examples

sketch_arrowheads()

Create a sketchy filled-band grob (hole-aware region)

Description

Draws one filled region made of several rings (outer pieces and holes) - the building block for filled contour / 2-D density bands. The whole region is filled with a single hole-aware scan-line (so holes stay empty), and every ring is stroked with a roughened outline. A "solid" fill paints the rings with an even-odd rule.

Usage

sketch_band_grob(
  rings,
  roughness = 0.7,
  bowing = 0.5,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.05,
  fill_weight = 0.5,
  fill_col = NA,
  outline_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

rings

A list of rings, each a list with npc [0,1] x and y vertex vectors. The even-odd arrangement of outer pieces and holes is honoured.

roughness, bowing, n_passes, seed

Sketch parameters for the outlines.

fill_style

"solid" (default), "hachure", "cross_hatch", or "watercolor" (hole-aware translucent washes).

hachure_angle, hachure_gap, fill_weight

Fill parameters (hachure_gap is an npc fraction).

fill_col

Fill colour (NA leaves the region empty).

outline_gp

gpar() for the roughened ring outlines.

name, vp

Passed to grid::gTree().

Value

A SketchBandGrob grob subclass.

Create a sketchy callout grob (boxed label + leader arrow)

Description

Draws a handwriting label inside a roughened rounded box and a leader arrow from the box to a target point. The box auto-sizes to the label at draw time (device-space text metrics) and the leader leaves from the box edge nearest the target.

Usage

sketch_callout_grob(
  x,
  y,
  xend,
  yend,
  label,
  padding = 0.06,
  corner_radius = 0.3,
  roughness = 1,
  bowing = 0.6,
  n_passes = 2L,
  seed = NULL,
  arrow_length = NULL,
  arrow_angle = 25,
  arrow_head = NULL,
  leader = "straight",
  curvature = 0.3,
  text_gp = gpar(),
  box_gp = gpar(),
  arrow_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Box centre in npc [0,1] (scalars).

xend, yend

Target point in npc the leader points at (scalars). Pass NA for both to draw a boxed label with no leader.

label

Label text.

padding

Box padding around the text, in inches. Default 0.06.

corner_radius

Box corner rounding (fraction of half-side). Default 0.3.

roughness, bowing, n_passes, seed

Sketch parameters.

arrow_length, arrow_angle

Leader arrowhead size (see sketch_arrow_grob()).

arrow_head

Leader head style (see sketch_arrowheads()); NULL = the open V.

leader

Leader routing: "straight" (default), "elbow" (horizontal then vertical) or "curved" (a bowed Bezier).

curvature

Bow size when leader = "curved". Default 0.3.

text_gp, box_gp, arrow_gp

gpar()s for the label, the box (outline; its fill paints the box), and the leader.

name, vp

Passed to grid::gTree().

Value

A SketchCalloutGrob grob subclass.

Create a sketchy dot-plot grob (stacked circular dots)

Description

Draws stacked roughened dots for a Wilkinson-style dot plot. The dot diameter is taken from dia (an npc-x fraction = the bin width) and converted to device inches at draw time, so every dot is a true circle whatever the panel aspect, and stacks are built upward from baseline by that diameter.

Usage

sketch_dotplot_grob(
  x,
  stackpos,
  dia,
  baseline = 0,
  stackratio = 1,
  roughness = 0.5,
  n_passes = 2L,
  seed = NULL,
  fill_gp = gpar(),
  outline_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x

Npc [0,1] x of each dot (its bin centre), one per dot.

stackpos

Integer stack position of each dot within its bin (1 = first).

dia

Dot diameter as an npc-x fraction (scalar; the bin width).

baseline

Npc y the stacks grow from. Default 0.

stackratio

Vertical spacing between stacked dots, as a fraction of the diameter. Default 1.

roughness, n_passes, seed

Sketch parameters.

fill_gp

gpar() for the solid dot fill (per-dot col recycled; NA leaves dots unfilled).

outline_gp

gpar() for the roughened dot outline (per-dot col).

name, vp

Passed to grid::gTree().

Value

A SketchDotplotGrob grob subclass.

Create a sketchy ellipse / circle grob

Description

Draws one or more roughened ellipses whose centres are in npc [0,1] and whose radii are npc fractions of the viewport (converted to device inches in makeContent(), so a "circle" in data units may appear elliptical on a non-square panel - matching ggplot2's coordinate semantics).

Usage

sketch_ellipse_grob(
  x,
  y,
  rx,
  ry,
  roughness = 1,
  n_passes = 2L,
  seed = NULL,
  fill_style = NULL,
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  fill_roughness = NULL,
  fill_seed = NULL,
  fill_gp = gpar(),
  outline_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Numeric npc centre coordinates (vectors).

rx, ry

Numeric npc radii (vectors, recycled to x).

roughness, n_passes, seed

Sketch parameters.

fill_style, hachure_angle, hachure_gap, fill_weight

Fill parameters; set fill_style = NULL or "solid" for outline only. "watercolor" paints translucent stacked washes.

fill_roughness

Roughness of the fill strokes. NULL (default) ties it to the outline as roughness * 0.4; set a number to control the fill texture independently of the outline.

fill_seed

Seed for the fill strokes. NULL (default) derives it from seed; set an integer to vary the fill pattern without moving the outline.

fill_gp

gpar() for the fill lines.

outline_gp

gpar() for the rough outline stroke.

name, vp

Passed to grid::gTree().

Value

A SketchEllipseGrob grob subclass.

Create a sketchy engraving grob (tonal cross-hatch by line density)

Description

Fills a region with engrave_fill(): a ladder of hatch layers whose accumulated density follows a tone field, so the region shades continuously from blank paper (light) to dense cross-hatch (dark) the way an etching does. The hatch geometry is computed in device inches (so angles and wobble are device-consistent); the field is supplied in npc [0,1] and sampled through an inch-to-npc affine at draw time.

Usage

sketch_engrave_grob(
  rings,
  field,
  ladder = NULL,
  ladder_levels = 5L,
  ladder_base_gap = 0.08,
  ladder_gap_ratio = 0.62,
  ladder_base_angle = 45,
  ladder_cross_after = 3L,
  roughness = 0.5,
  bowing = 0.3,
  seed = NULL,
  min_gap_in = 0.012,
  gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

rings

A list of rings, each a list with npc [0,1] x and y vertex vectors bounding the region to engrave (even-odd holes honoured).

field

A vectorised tone function ⁠function(x, y)⁠ taking npc [0,1] coordinates and returning tone in ⁠[0, 1]⁠ (0 = paper, 1 = darkest).

ladder

A ladder from engrave_ladder(); NULL builds a default from the ⁠ladder_*⁠ parameters.

ladder_levels, ladder_base_gap, ladder_gap_ratio, ladder_base_angle, ladder_cross_after

Ladder controls used when ladder is NULL. ladder_base_gap is an npc-x fraction (converted to inches at draw time).

roughness, bowing, seed

Sketch parameters for the engraving strokes.

min_gap_in

Hard pitch floor in inches: ladder layers finer than this are dropped, so the darkest tones cannot explode into a runaway number of strokes. Default 0.012.

gp

gpar() for the engraving strokes (col, lwd).

name, vp

Passed to grid::gTree().

Value

A SketchEngraveGrob grob subclass.

Dispatch fill-style to the appropriate Layer-1 fill function

Description

Dispatch fill-style to the appropriate Layer-1 fill function

Usage

sketch_fill(
  px,
  py,
  fill_style = "hachure",
  hachure_gap = 0.1,
  hachure_angle = 45,
  fill_weight = 1,
  roughness = 0.5,
  bowing = 0,
  seed = NULL
)

Arguments

px, py

Polygon vertices (inch space).

fill_style

Character: one of "hachure", "cross_hatch", "zigzag", "zigzag_line", "dots", "dashed", "solid".

hachure_gap

Gap between fill lines (inches). Default 0.1.

hachure_angle

Base fill angle (degrees). Default 45.

fill_weight

Thickness weight (passed to caller for gpar). Default 1.

roughness, bowing

Sketch params for fill lines. Defaults 0.5, 0.

seed

Integer seed.

Value

List of 2-column (x,y) matrices representing fill stroke segments, OR NULL for "solid" (solid fill handled by polygon fill colour).

Dispatch fill-style for a multi-ring (hole-aware) region

Description

The band counterpart of sketch_fill(): fills a region described by several rings (outer pieces and holes) with one shared scan-line so holes are excluded. Supports the line-based styles "hachure" and "cross_hatch"; "solid" returns NULL (painted by an even-odd polygon fill in the grob). Any other style degrades to "hachure", since the scribble/dots/dashed styles are defined per single ring.

Usage

sketch_fill_multi(
  rings,
  fill_style = "hachure",
  hachure_gap = 0.1,
  hachure_angle = 45,
  fill_weight = 1,
  roughness = 0.5,
  bowing = 0,
  seed = NULL
)

Arguments

rings

A list of rings (see hachure_fill_multi()).

fill_style

Character: one of "hachure", "cross_hatch", "zigzag", "zigzag_line", "dots", "dashed", "solid".

hachure_gap

Gap between fill lines (inches). Default 0.1.

hachure_angle

Base fill angle (degrees). Default 45.

fill_weight

Thickness weight (passed to caller for gpar). Default 1.

roughness, bowing

Sketch params for fill lines. Defaults 0.5, 0.

seed

Integer seed.

Value

List of fill-line segments, or NULL for "solid".

Build node and edge data for a sketch network

Description

Turns an edge list into the two data frames that geom_sketch_node() and geom_sketch_edge() consume, placing nodes with the pure-R force-directed force_layout(). Accepts a plain two-column data frame (extra columns are carried through as edge attributes) or - optionally - an igraph object.

Usage

sketch_graph(edges, nodes = NULL, niter = 500L, seed = NULL)

Arguments

edges

A data frame or matrix whose first two columns are the edge endpoints (any identifiers), or an igraph object. Extra data-frame columns are kept as edge attributes.

nodes

Optional. A character vector of node identifiers, or a data frame whose first column is the identifier (further columns are kept as node attributes). Sets the node universe and ordering; defaults to the identifiers seen in edges.

niter, seed

Passed to force_layout().

Value

A list with two data frames: nodes (name, x, y, plus any node attributes) and edges (from, to, x, y, xend, yend, plus any edge attributes).

Examples

edges <- data.frame(from = c("A", "A", "B"), to = c("B", "C", "C"))
g <- sketch_graph(edges, seed = 1L)
g$nodes
g$edges

The available drawing media

Description

The valid values for the medium argument of the path-like sketch geoms. "pen" is the default and reproduces the classic constant-width double stroke; the others render through the variable-width stroke_ribbon() engine.

Usage

sketch_media()

Value

A character vector of medium names.

Examples

sketch_media()

The ggsketch qualitative colour palette

Description

Eight muted ink-on-paper colours led by the package primary (Carolina blue, ⁠#7BAFD4⁠), ordered for maximal separation.

Usage

sketch_palette(n = NULL, interpolate = TRUE)

Arguments

n

Number of colours to return. If NULL, the eight anchor colours are returned. Up to eight are taken verbatim; beyond that they are interpolated (or recycled, if interpolate = FALSE).

interpolate

When n > 8, interpolate the eight anchors into n colours (the default). FALSE recycles the anchors with a warning.

Details

The first eight colours are returned exactly, so small categorical plots keep their recognisable hues. Ask for more than eight and the palette is interpolated: a smooth colorRampPalette() ramp through all eight anchors yields n distinct ink tones, so the discrete sketch scales keep working for large factors and for quasi-continuous use. Set interpolate = FALSE to fall back to the old recycling behaviour instead.

Value

A character vector of hex colours.

Examples

sketch_palette(4)
sketch_palette(20)             # interpolated ramp through all eight anchors

The available paper grounds

Description

The valid values for the paper argument of theme_sketch() and the kind of element_sketch_paper().

Usage

sketch_papers()

Value

A character vector of paper names ("none" first).

Examples

sketch_papers()

Create a sketchy path grob

Description

A grid grob that re-roughens its path at actual render resolution in makeContent(). Coordinates are in npc [0,1]; roughening is performed in device inches.

Usage

sketch_path_grob(
  x,
  y,
  id = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Numeric vectors of npc [0,1] coordinates.

id

Integer vector grouping coordinates into separate polylines (same semantics as grid::polylineGrob). NULL treats all points as one path.

roughness, bowing, n_passes, seed

Sketch parameters.

gp

A grid::gpar() object controlling line aesthetics.

name, vp

Passed to grid::grob().

Value

A SketchPathGrob (a grid grob subclass).

Create a sketchy polygon grob with optional hachure fill

Description

Create a sketchy polygon grob with optional hachure fill

Usage

sketch_polygon_grob(
  x,
  y,
  id = NULL,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  fill_gp = gpar(),
  outline_gp = gpar(),
  fill_style = "hachure",
  hachure_angle = 45,
  hachure_gap = NULL,
  fill_weight = 0.5,
  fill_roughness = NULL,
  fill_seed = NULL,
  name = NULL,
  vp = NULL
)

Arguments

x, y

Numeric npc [0,1] coordinates.

id

Group IDs (same semantics as grid::polygonGrob).

roughness, bowing, n_passes, seed

Sketch parameters for the outline.

fill_gp

gpar() for fill lines (col sets fill-line colour).

outline_gp

gpar() for the rough outline stroke.

fill_style, hachure_angle, hachure_gap, fill_weight

Fill parameters (hachure_gap in device inches; NULL picks 15% of the shape's smaller drawn extent, clamped to [0.04, 0.4] inches).

fill_roughness

Roughness of the fill strokes. NULL (default) ties it to the outline as roughness * 0.5; set a number to control the fill texture independently of the outline.

fill_seed

Seed for the fill strokes. NULL (default) derives it from seed; set an integer to vary the fill pattern without moving the outline.

name, vp

Passed to grid::grob().

Value

A SketchPolygonGrob grob subclass.

Create a sketchy repelled-label grob

Description

Places labels near their anchors ⁠(x, y)⁠ but nudged apart so they do not overlap each other or sit on the points, via repel_layout() (run in device inches at draw time). Each displaced label is tied back to its anchor with a roughened leader line. With boxed = TRUE the labels sit in roughened rounded boxes (the geom_sketch_label_repel() look); otherwise they are bare text (the geom_sketch_text_repel() look).

Usage

sketch_repel_grob(
  x,
  y,
  label,
  boxed = FALSE,
  padding = 0.07,
  corner_radius = 0.3,
  box_padding = 0.1,
  point_padding = 0.05,
  min_segment = 0.06,
  max_iter = 2000L,
  roughness = 1,
  bowing = 0.6,
  n_passes = 2L,
  seed = NULL,
  text_gp = gpar(),
  box_gp = gpar(),
  seg_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Anchor points in npc [0,1] (vectors).

label

Character labels (recycled to the anchors).

boxed

Draw each label in a rounded box? Default FALSE.

padding

Text-to-edge / text clearance, in inches. Default 0.07.

corner_radius

Box corner rounding (fraction of half-side). Default 0.3.

box_padding, point_padding

Extra clearance between boxes and around anchor points, in inches.

min_segment

Shortest leader drawn, in inches (shorter = no leader).

max_iter

Solver iteration cap. Default 2000.

roughness, bowing, n_passes, seed

Sketch parameters.

text_gp, box_gp, seg_gp

gpar()s for the text, the box, and the leader.

name, vp

Passed to grid::gTree().

Value

A SketchRepelGrob grob subclass.

Create an airbrush / spray stroke grob

Description

A grid grob that draws its path as a soft cloud of dots instead of a stroked line: it re-roughens the centreline at device resolution, then scatters dots around it with spray_scatter(), for the airbrush / spray-can medium (no hard outline). Coordinates are npc [0,1]; the scatter happens in device inches inside makeContent().

Usage

sketch_spray_grob(
  x,
  y,
  id = NULL,
  spread = 0.05,
  density = 150,
  dot_r = 0.004,
  roughness = 1,
  bowing = 1,
  n_passes = 1L,
  seed = NULL,
  gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Numeric vectors of npc [0,1] coordinates.

id

Integer vector grouping coordinates into separate strokes (NULL treats all points as one).

spread, density, dot_r

Passed to spray_scatter() (in inches).

roughness, bowing, n_passes, seed

Sketch parameters for the centreline.

gp

A grid::gpar(); its col becomes the dot fill, alpha is honoured.

name, vp

Passed to grid::gTree().

Value

A SketchSprayGrob (a grid grob subclass).

Create a variable-width sketch stroke grob

Description

A grid grob that draws its path as a tapered / pressure-varying hand-drawn stroke. Unlike sketch_path_grob() (constant-lwd polylines), the line is built from stroke_ribbon() polygons, so it can taper to a point, swell with pressure, or vary like a broad calligraphic nib. Coordinates are npc [0,1]; roughening and offsetting happen in device inches inside makeContent().

Usage

sketch_stroke_grob(
  x,
  y,
  id = NULL,
  width = 0.03,
  roughness = 1,
  bowing = 1,
  n_passes = 2L,
  seed = NULL,
  taper = "none",
  taper_frac = 0,
  pressure = NULL,
  nib_angle = NULL,
  jitter_w = 0,
  cap = "round",
  gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x, y

Numeric vectors of npc [0,1] coordinates.

id

Integer vector grouping coordinates into separate strokes (same semantics as sketch_path_grob()). NULL treats all points as one stroke.

width

Full stroke width in inches. Default 0.03.

roughness, bowing, n_passes, seed

Sketch parameters for the centreline.

taper, taper_frac, pressure, nib_angle, jitter_w, cap

Passed to stroke_ribbon().

gp

A grid::gpar(); its col becomes the ribbon fill (the ribbon is painted, not stroked), alpha is honoured.

name, vp

Passed to grid::gTree().

Value

A SketchStrokeGrob (a grid grob subclass).

Apply a complete hand-drawn style in one call

Description

Bundles a theme_sketch() paper ground, a qualitative colour + fill palette tuned to that ground and (on ggplot2 >= 4.0) matching default geom ink into a single object to add to a plot: p + sketch_style("chalkboard"). Styles:

Usage

sketch_style(style, palette = TRUE, ...)

Arguments

style

One of sketch_styles().

palette

If TRUE (default), include discrete colour and fill scales using the style's palette. Set FALSE when a mapped colour/fill variable is continuous (a discrete scale would error) or you want your own scale.

...

Passed on to theme_sketch() (e.g. base_size, rough_frame, seed). paper is fixed by the style and cannot be overridden here.

Details

"notebook" – blue-ruled paper written in ballpoint/fountain-pen inks.
"chalkboard" – dark board with chalky pastels; pair the line geoms with medium = "chalk".
"blueprint" – cyanotype draughting: pale monoline strokes, warm accent.
"field_notes" – kraft expedition journal in sepia and olive.
"graphite" – plain ground, grey pencil tones; pair with medium = "pencil".

Value

A list of plot components (theme + optional scales) to add with +.

Examples

library(ggplot2)
p <- ggplot(mpg, aes(displ, hwy, colour = drv)) +
  geom_sketch_point(seed = 1L)
p + sketch_style("field_notes")
p + sketch_style("chalkboard")

The available style presets

Description

The valid values for sketch_style().

Usage

sketch_styles()

Value

A character vector of style names.

Examples

sketch_styles()

Create a sketchy pie/donut-wedge grob

Description

Draws one or more annular sectors (pie or donut slices) sharing a centre, guaranteed circular regardless of panel shape: radii are taken as a fraction of the smaller panel dimension and the geometry is assembled in device inches inside makeContent(), then roughened. Each slice's roughened boundary is also reused as the fill region so the hand-drawn edge is kept.

Usage

sketch_wedge_grob(
  x0,
  y0,
  r,
  r0 = 0,
  start,
  end,
  roughness = 1,
  bowing = 0.4,
  n_passes = 2L,
  seed = NULL,
  fill_style = "solid",
  hachure_angle = 45,
  hachure_gap = 0.07,
  fill_weight = 0.5,
  fill_gp = gpar(),
  outline_gp = gpar(),
  name = NULL,
  vp = NULL
)

Arguments

x0, y0

Centre in npc [0,1] (scalars).

r, r0

Outer and inner radius as a fraction of the smaller panel dimension (r0 = 0 gives a pie, r0 > 0 a donut).

start, end

Per-slice start/end angles in radians.

roughness, bowing, n_passes, seed

Sketch parameters for the outline.

fill_style

"solid" (default) paints each slice in its fill colour; any other style ("hachure", ...) hatches it instead.

hachure_angle, hachure_gap, fill_weight

Fill parameters (hachure_gap is a fraction of the smaller panel dimension).

fill_gp

gpar() for the fill (per-slice col recycled).

outline_gp

gpar() for the rough outline (per-slice col recycled).

name, vp

Passed to grid::gTree().

Value

A SketchWedgeGrob grob subclass.

Scatter a cloud of dots along a path (airbrush / spray)

Description

Samples points along a centreline and offsets each one perpendicular to the path by a Gaussian random amount, producing a soft-edged spray of dots with no hard outline – the airbrush / spray-can look. The dot density falls off from the centreline (the Gaussian offset), and dots near the edge are drawn smaller so the cloud feathers out. Pure number-to-number (no grid/ggplot2); deterministic apart from the seeded RNG (ADR-0004).

Usage

spray_scatter(x, y, spread = 0.04, density = 140, dot_r = 0.004, seed = NULL)

Arguments

x, y

Numeric vectors of centreline vertices (same length, any units – spread, dot_r and density are interpreted in those units).

spread

Standard deviation of the perpendicular offset (cloud half-width).

density

Mean number of dots per unit of path arc-length.

dot_r

Base dot radius. Edge dots shrink toward 0.4 * dot_r.

seed

Integer seed for the scatter (ADR-0004).

Value

A 4-column matrix with columns x, y (dot centres), r (dot radii) and a (a 0-1 weight that fades with distance from the centreline, for the caller to fold into per-dot alpha if desired). Zero rows for a degenerate path.

Width-profile presets for `stroke_ribbon()`

Description

Returns a vectorised pressure function f(t) over the normalised arc-length t in ⁠[0, 1]⁠, giving a width multiplier (>= 0) along the stroke. Pass the result as pressure to stroke_ribbon().

Usage

stroke_profile(kind = c("flat", "taper_in", "taper_out", "belly"))

Arguments

kind

One of "flat" (constant), "taper_in" (thin start, thick end), "taper_out" (thick start, thin end), or "belly" (a spindle that swells in the middle and thins at both ends).

Value

A function of t returning a numeric multiplier of the same length.

Build a variable-width stroke as a closed polygon ribbon

Description

Offsets a centreline left and right by a per-vertex half-width and closes the loop into a single polygon, so a hand-drawn stroke can taper, swell with pressure, or vary like a broad calligraphic nib – effects grid cannot do with a constant-lwd polyline. The centreline is used as supplied (roughen it first with roughen_polyline() for a sketchy edge); this routine only offsets, so it is deterministic apart from jitter_w.

Usage

stroke_ribbon(
  x,
  y,
  width,
  taper = c("none", "both", "start", "end"),
  taper_frac = 0,
  pressure = NULL,
  nib_angle = NULL,
  nib_floor = 0.15,
  jitter_w = 0,
  cap = c("round", "butt"),
  miter_limit = 3,
  seed = NULL
)

Arguments

x, y

Numeric vectors of centreline vertices in inch space (same length).

width

Full stroke width in inches: a scalar, or a per-vertex vector.

taper

Where the stroke narrows to a tip: "none" (default), "both", "start", or "end".

taper_frac

Tip width as a fraction of width (0 = sharp point, 1 = no narrowing). Default 0.

pressure

Optional vectorised function f(t) over normalised arc-length t in ⁠[0, 1]⁠ returning a width multiplier (see stroke_profile()). NULL (default) is constant pressure.

nib_angle

Optional broad-nib angle in degrees for a calligraphic stroke: the half-width is scaled by ⁠|sin(segment_dir - nib_angle)|⁠ (with a small floor), so the line is thick across the nib and thin along it. NULL (default) disables it.

nib_floor

Minimum nib multiplier in ⁠[0, 1]⁠, so a calligraphic stroke never fully vanishes. Default 0.15.

jitter_w

Width roughening in ⁠[0, 1]⁠: random per-vertex modulation of the half-width, for a dry / inky edge. Default 0.

cap

End-cap style: "round" (default) or "butt".

miter_limit

Clamp on the joint miter factor, capping how far an outside corner extends at a sharp turn. Default 3.

seed

Integer seed for jitter_w (ADR-0004).

Value

A 2-column ⁠(x, y)⁠ matrix giving the closed ribbon polygon (right side forward, end cap, left side back, start cap). Fill it with the stroke colour and no border for a solid variable-width stroke.

A hand-drawn theme for ggplot2

Description

A sketch-style theme based on ggplot2::theme_bw() with a muted palette to match the rough geoms. Light (default) and dark presets are available via dark. The sketchiness of the marks comes from the geoms themselves; this theme styles the surrounding frame, typography, and background.

Usage

theme_sketch(
  base_size = 11,
  base_family = getOption("ggsketch.base_family", ""),
  base_line_size = base_size/22,
  base_rect_size = base_size/22,
  dark = FALSE,
  rough_frame = FALSE,
  roughness = 0.5,
  paper = "none",
  seed = NULL
)

Arguments

base_size

Base font size (default 11).

base_family

Base font family. Defaults to getOption("ggsketch.base_family", ""); "" uses the device default. "auto" picks the first installed handwriting font (see ggsketch_check_fonts()), falling back to the device default. Set options(ggsketch.base_family = "auto") to make every sketch plot's text (titles, axes, legend) use handwriting, not just the labels drawn by geom_sketch_text() / geom_sketch_bracket(). Or pass an explicit family name.

base_line_size

Line size (default base_size / 22).

base_rect_size

Rect size (default base_size / 22).

dark

If TRUE, use the dark "chalkboard" preset. Default FALSE (light "paper" preset).

rough_frame

If TRUE, draw the frame itself hand-drawn: the major gridlines, panel border, axis ticks, facet strip backgrounds, and the continuous-scale colourbar frame and ticks become roughened sketch grobs (via element_sketch_line() / element_sketch_rect()) so the whole frame matches the marks. Default FALSE.

roughness

Roughness for the rough frame (only used when rough_frame = TRUE). Default 0.5.

paper

Paper ground drawn behind the data: one of sketch_papers() ("none" (default), "notebook", "graph", "dotted", "aged", "blueprint", "chalkboard", "kraft"). A non-"none" paper paints a simulated texture as the panel background, recolours the plot ground and text to suit it (light text on the dark blueprint / chalkboard grounds), and suppresses the default gridlines where the paper supplies its own ruling.

seed

Integer seed for the rough frame, for reproducible wobble. NULL uses getOption("ggsketch.seed", 1L).

Value

A ggplot2::theme object.

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) + geom_sketch_point(seed = 1L)
p + theme_sketch()
p + theme_sketch(dark = TRUE)
p + theme_sketch(rough_frame = TRUE)
p + theme_sketch(paper = "notebook")

Squarified treemap layout

Description

Lays out one rectangle per value inside the box ⁠[x, x + width] x [y, y + height]⁠, with area proportional to the value and aspect ratios kept close to 1. Returns rectangles in the original input order.

Usage

treemap_layout(values, x = 0, y = 0, width = 1, height = 1)

Arguments

values

Non-negative numeric vector (one per tile). Zero / negative values produce zero-area tiles.

x, y

Lower-left corner of the bounding box. Default 0.

width, height

Bounding box size. Default 1.

Value

A data frame with columns xmin, xmax, ymin, ymax, one row per input value, in input order.

Examples

treemap_layout(c(6, 3, 2, 1))

Pigment bleed between two overlapping wash regions

Description

Where two wet watercolour washes overlap the pigments diffuse and the colours mix - the "wet-on-wet" bleed. This approximates it without polygon clipping: it samples points lying inside both polygons (the overlap region) and returns soft translucent specks tinted with the blended colour. The grob layer paints the specks at low alpha over the two washes, so the shared area reads as mingled pigment. Pure geometry + colour math; reproduces on every device.

Usage

wash_bleed(
  ax,
  ay,
  bx,
  by,
  col_a,
  col_b,
  density = 0.5,
  bleed = NULL,
  seed = NULL
)

Arguments

ax, ay, bx, by

Vertices (inch space) of the two wash polygons.

col_a, col_b

The two wash colours (any R colour spec).

density

Fraction in ⁠[0, 1]⁠: speck density in the overlap. Default 0.5.

bleed

Speck radius scale in inches. NULL (default) scales to ~2.5% of the overlap's bounding diagonal.

seed

Integer seed.

Value

A list(x, y, r, fill) of bleed specks (inch space), or NULL when the polygons' bounding boxes - or the sampled overlap - do not meet.

Build a watercolour wash for a polygon region

Description

Returns a stack of translucent boundary copies plus optional granulation specks; the grob layer paints the copies at a low alpha so overlap accumulates tone. The look the line-based fill styles cannot give: soft, pooled, bleeding colour.

Usage

watercolor_wash(
  px,
  py,
  n_layers = 6L,
  bleed = NULL,
  granulation = 0,
  grain = 0,
  seed = NULL
)

Arguments

px, py

Polygon vertices (inch space).

n_layers

Number of wash copies. More = smoother, deeper, slower. Default 6.

bleed

Edge irregularity in inches. NULL (default) scales to ~2% of the shape's bounding diagonal.

granulation

Fraction in ⁠[0, 1]⁠: density of pigment specks (0 = none). Default 0.

grain

Paper-grain coupling in ⁠[0, ~1]⁠: how strongly the edge feathers along the paper tooth. 0 (default) is the historical pure-uniform jitter; higher values wick the edge in coherent capillary channels (see paper_grain()). 0 draws no extra randomness, so existing seeds reproduce.

seed

Integer seed.

Value

A list with washes (a list of 2-column ⁠(x, y)⁠ polygon matrices, outermost/lightest first) and granules (list(x, y, r) in inches, or NULL).

Build a hole-aware watercolour wash for a multi-ring region

Description

The multi-ring analogue of watercolor_wash(): each wash layer is a jittered, resized copy of every ring, so the grob can paint a layer as one even-odd path and keep holes empty (rings shrink/grow about their own centroid). Used by the band / multi-ring grobs (filled contours, density bands).

Usage

watercolor_wash_multi(
  rings,
  n_layers = 6L,
  bleed = NULL,
  granulation = 0,
  grain = 0,
  seed = NULL
)

Arguments

rings

A list of rings, each a list with inch-space x and y vertex vectors. Even-odd nesting defines holes.

n_layers

Number of wash copies. Default 6.

bleed

Edge irregularity in inches. NULL (default) scales to ~2% of the combined bounding diagonal.

granulation

Fraction in ⁠[0, 1]⁠: density of pigment specks (0 = none). Default 0. Specks land inside the even-odd region (never in holes).

grain

Paper-grain coupling in ⁠[0, ~1]⁠: how strongly each ring's edge feathers along the paper tooth. 0 (default) is the historical pure-uniform jitter and draws no extra randomness. See paper_grain().

seed

Integer seed.

Value

A list with washes (a list of layers; each layer is a list of 2-column ⁠(x, y)⁠ ring matrices, outermost/lightest first) and granules (list(x, y, r) in inches, or NULL).

Package {ggsketch}

ggsketch: Grammar-Native Hand-Drawn Geoms for 'ggplot2'

Description

Author(s)

See Also

A hand-drawn coordinate system

Description

Usage

Arguments

Details

Value

See Also

Examples

A hand-drawn polar coordinate system

Description

Usage

Arguments

Value

See Also

Examples

Sketchy reference lines

Description

Usage

Arguments

Value

See Also

Examples

Sketchy content-aware arrows

Description

Usage

Arguments

Details

Value

See Also

Examples

Sketchy boxplot

Description

Usage

Arguments

Value

See Also

Examples

Sketchy significance / comparison brackets

Description

Usage

Arguments

Details

Value

See Also

Examples

Sketchy callouts (boxed labels with a leader arrow)

Description

Usage

Arguments

Details

Value

See Also

Examples

Sketchy chicklet chart

Description

Usage

Arguments

Value

See Also

Examples

Sketchy column / bar geom

Description

Usage

Arguments

Value

See Also

Examples

Sketchy filled contour and 2-D density bands

Description

Usage

Arguments

Details

Value

See Also

Examples