Package 'ggpointless'

Description

Several fade geoms accept an alpha_scope argument that controls how the alpha gradient is normalised — that is, which subset of the rendered shapes the most-opaque end of the gradient is calibrated to. The vocabulary overlaps but is not identical across the geom families, because what counts as a meaningful "reference" differs between bars, areas, and ridgelines. This page is the consolidated reference.

What alpha_scope does

Each fade geom interpolates the rendered alpha between two extremes: alpha_fade_to (the faded end, default fully transparent) and the row's aesthetic alpha value (the opaque end, default fully opaque). The peak of that interpolation is positioned somewhere on the data, and alpha_scope chooses where:

• Per-row scopes anchor the peak at the row's own extreme (each shape gets the full alpha range to itself).

• Group-relative scopes anchor the peak at the maximum within a discrete subset (rows in the same subset share an alpha range; smaller rows appear proportionally fainter).

• Layer-wide scopes anchor the peak at the maximum across the whole layer (or all panels under faceting).

Vocabulary by geom family

The accepted values and defaults are family-specific:

Area family (geom_area_fade(), geom_density_fade(), geom_freqpoly_fade())

Default "global". Allowed: "global", "group". "global" scales every group to the layer-wide maximum ⁠|y|⁠, so equal ⁠|y|⁠ always maps to equal alpha. "group" lets each group use the full alpha range independently.

Bar family (geom_col_fade(), geom_bar_fade())

Default "bar". Allowed: "bar", "group", "x", "y", "fill", "colour", "global". "bar" gives every bar its own range (every peak hits full opacity); "x" / "y" normalise within a position-axis cluster (useful for stacks and dodges); "fill" / "colour" normalise within a colour class; "global" normalises layer-wide; "group" falls back to ggplot2's data$group.

Histogram family (geom_histogram_fade())

Default "bar". Allowed: "bar", "group", "bin", "fill", "colour", "global". The shared bar-family scopes carry over, but "x" / "y" are not accepted: they key on round(data$x|y) which is meaningless on a continuous binned axis. Use "bin" instead — it normalises within each bin (every cluster of dodged bars in one bin shares an alpha range), recovering the per-cluster intent that "x" / "y" give on geom_col_fade() / geom_bar_fade().

Ridgeline family (geom_ridgeline_fade(), geom_ridgeline_density_fade())

Default "group". Allowed: "group", "global". "group" lets each ridge use the full alpha range independently. "global" scales relative to the tallest ridge in the entire layer (incl. across facets), so shorter ridges fade in proportion.

Why the same name means different things

"global" always means the layer-wide maximum — but the maximum of what depends on the geom: ⁠|y|⁠ for areas, ⁠|y|⁠ (or ⁠|x|⁠ under orientation = "y") for bars and histograms, and the tallest ridge height for ridgelines. "group" always means normalise per ggplot2 group (data$group, the interaction of all discrete aesthetics). For ridgelines this is effectively "per ridge" because each data$group corresponds to one ridge. The defaults above are chosen so that the most common usage of each family produces sensible output without explicit alpha_scope.

See Also

geom_area_fade(), geom_col_fade(), geom_ridgeline_fade() for the geom-side documentation that drives the actual rendering.

Description

These geoms draw reference lines – horizontal, vertical, or diagonal – with an alpha gradient along the line so that one or both ends fade to transparent.

Like their ggplot2 counterparts, these geoms can be used as annotations by passing slope/intercept, yintercept, or xintercept as arguments directly. In that case the line is constant across facets. To vary lines across facets, supply your own data and mapping.

Usage

geom_abline_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  ...,
  slope,
  intercept,
  alpha_fade_to = 0,
  fade_direction = "start",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

geom_hline_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  yintercept,
  alpha_fade_to = 0,
  fade_direction = "start",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

geom_vline_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  xintercept,
  alpha_fade_to = 0,
  fade_direction = "start",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = FALSE
)

Arguments

Details

Gradient direction and reversed scales

The fade direction is defined in visual (panel) space, not in data space. fade_direction = "start" always makes the start of the line transparent – for horizontal lines this is the visual left edge; for vertical lines, the visual bottom edge – regardless of whether the x or y scale is reversed. So fade_direction = "start" means "transparent at the left/bottom panel edge" irrespective of axis direction.

If you do want the gradient to track the data direction – making the low-value end transparent even when it appears on the visual right – pass fade_direction = "end" to override the default:

# On a reversed x-axis, "end" fades toward larger x values (visual left)
p + scale_x_reverse() +
  geom_hline_fade(yintercept = 20, fade_direction = "end")

Non-linear coordinate systems (coord_polar / coord_radial)

Under non-linear coordinate systems the "line" is conceptually a curve in device space:

• geom_hline_fade() traces a circle at the given yintercept (constant radius).

• geom_vline_fade() traces a ray at the given xintercept (constant angle).

• geom_abline_fade() traces a curve that spirals or arcs based on the slope/intercept.

The fade is applied along the path length of that curve, so fade_direction = "start" fades the beginning of the traced path. For an hline_fade() circle the "start" is the first vertex of the traced circle (at the leftmost angle of the coord system, 12 o'clock by default), which may not match intuition from cartesian use – pass fade_direction = "end" to reverse.

Internally, the line is subdivided into a dense set of vertices in data space before the coord transform so the curve appears smooth. This is transparent to the user but explains why the grob carries more vertices than in the linear case.

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Aesthetics

geom_segment_fade() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P., Pedersen, T. L., and Skintzos, P. (2023). "Porter-Duff Compositing Operators in R Graphics." Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/compositing/compositing.html

Murrell, P. (2023). "Groups, Compositing Operators, and Affine Transformations in R Graphics." Technical Report 2021-02, Department of Statistics, The University of Auckland. Version 3. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html

See Also

geom_segment_fade() for fading line segments with explicit endpoints, geom_path_fade() and geom_line_fade() for connected paths; ggplot2::geom_abline(), ggplot2::geom_hline(), and ggplot2::geom_vline() for their ggplot2 originals.

Examples

library(ggplot2)

p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()

# Horizontal reference line, fading from the left
p + geom_hline_fade(yintercept = 20, linewidth = 1.5)

# Vertical line fading at both ends
p + geom_vline_fade(xintercept = 3, linewidth = 1.5,
                    fade_direction = c("start", "end"))

# Diagonal line of best fit, fading from the left
coefs <- coef(lm(mpg ~ wt, data = mtcars))
p + geom_abline_fade(intercept = coefs[1], slope = coefs[2], linewidth = 1.5)

Description

geom_area_fade() behaves like ggplot2::geom_area() but uses grid::linearGradient() to create area plots. The gradient is always anchored at y = 0: maximum transparency there, fading to opaque at the data values. Opacity scales with the absolute distance from zero, so equal ⁠|y|⁠ values always receive the same alpha – full opacity is reached only at the extreme with the largest absolute value. This works for positive values, negative values, and groups that cross zero (where a three-stop gradient is used).

When fill is mapped to a variable (e.g. aes(fill = z)), the geom combines the horizontal colour gradient produced by ggplot2 with the vertical alpha fade, creating a two-dimensional gradient effect. This requires a device that supports Porter-Duff compositing (e.g. ragg::agg_png(), grDevices::svg()). On unsupported devices the geom falls back to a single-colour vertical fade and emits an informational message.

geom_density_fade() computes and draws a kernel density estimate – a smoothed version of the histogram – with the same vertical alpha gradient as geom_area_fade(). Under the hood this is GeomAreaFade paired with ggplot2::stat_density(), so all smoothing parameters (bw, adjust, kernel, bounds, ...) are forwarded to the stat.

geom_freqpoly_fade() draws a frequency polygon (like ggplot2::geom_freqpoly()) filled with the same linear gradient as geom_area_fade().

Usage

geom_area_fade(
  mapping = NULL,
  data = NULL,
  stat = "align",
  position = "stack",
  ...,
  alpha_fade_to = 0,
  alpha_scope = "global",
  orientation = NA,
  outline.type = "upper",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_density_fade(
  mapping = NULL,
  data = NULL,
  stat = "density",
  position = "identity",
  ...,
  bw = "nrd0",
  adjust = 1,
  kernel = "gaussian",
  bounds = c(-Inf, Inf),
  alpha_fade_to = 0,
  alpha_scope = "global",
  orientation = NA,
  outline.type = "upper",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_freqpoly_fade(
  mapping = NULL,
  data = NULL,
  stat = "bin",
  position = "identity",
  ...,
  binwidth = NULL,
  bins = NULL,
  alpha_fade_to = 0,
  alpha_scope = "global",
  orientation = NA,
  pad = TRUE,
  outline.type = "upper",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Coordinate systems

geom_area_fade(), geom_density_fade(), and geom_freqpoly_fade() only support linear gradients. When used with ggplot2::coord_polar() or ggplot2::coord_radial(), they fall back to standard area rendering (equivalent to ggplot2::geom_area()), which means no gradient fill is added. A warning is emitted in this case.

alpha_scope = "global" under faceting

alpha_scope = "global" ties opacity to absolute height across the whole layer, so two ridges / areas / bars of equal height render at equal alpha regardless of which panel they're in. This is meaningful only when panels share a common y scale. Under facet_wrap(scales = "free_y") (or facet_grid(rows = ..., scales = "free")) each panel rescales y independently, so the visual height of a shape no longer reflects its data height; the alpha encoding then conflicts with what the eye reads from the panel size. For comparable alpha across free-y panels you have two options: stick to the default scales = "fixed", or accept that under free scales alpha_scope = "group" is the more honest choice (each shape independently uses its own alpha range).

Legend key under coord_flip

The legend key glyph always shows the canonical (data-axis) fade direction – vertical for the default orientation, horizontal under orientation = "y". Under ggplot2::coord_flip() the rendered geom rotates correctly but the legend key does not: ggplot2's legend builder is coord-independent by design (draw_key has no access to the coord). For a legend key that matches a horizontal layout, prefer aes(y = ...) with auto-detected orientation = "y" over aes(x = ...) + coord_flip().

Orientation

This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the orientation parameter, which can be either "x" or "y". The value gives the axis that the geom should run along, "x" being the default orientation you would expect for the geom.

Aesthetics

geom_area_fade() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P. (2021). "Luminance Masks in R Graphics." Technical Report 2021-04, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/masks/masks.html

Murrell, P. (2022). "Vectorised Pattern Fills in R Graphics." Technical Report 2022-01, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/vecpat/vecpat.html

Murrell, P., Pedersen, T. L., and Skintzos, P. (2023). "Porter-Duff Compositing Operators in R Graphics." Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/compositing/compositing.html

Murrell, P. (2023). "Groups, Compositing Operators, and Affine Transformations in R Graphics." Technical Report 2021-02, Department of Statistics, The University of Auckland. Version 3. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html

See Also

ggplot2::geom_area(), ggplot2::geom_density(), ggplot2::geom_freqpoly().

Examples

library(ggplot2)
df1 <- data.frame(
  g = c("a", "a", "a", "b", "b", "b"),
  x = c(1, 3, 5, 2, 4, 6),
  y = c(2, 5, 1, 3, 6, 7)
)

a <- ggplot(df1, aes(x, y, fill = g)) +
  theme_minimal()

# Default behaviour: opaque at data line, transparent at y = 0
# the outline colour remains unaffected
a + geom_area_fade()

# Change overall opacity
a + geom_area_fade(alpha = .25)

# Keep some opacity at the baseline
a + geom_area_fade(alpha_fade_to = .25)

# Suppress the default upper outline
a + geom_area_fade(outline.type = "none")

# Closed outline (all four edges)
a + geom_area_fade(outline.type = "full")

# Horizontal orientation
a + geom_area_fade(aes(y, x), orientation = "y")

# Disable stat alignment (useful when x values are already aligned)
a + geom_area_fade(stat = "identity")

# Draw upper and lower outlines (no left/right edges)
a + geom_area_fade(outline.type = "both", stat = "identity")

# Use the "alpha_scope" argument to scale the alpha
# value of the gradients separately for each group
df2 <- data.frame(
  g = c("a", "a", "a", "b", "b", "b"),
  x = c(1, 3, 5, 2, 4, 6),
  y = c(1, 2, 1, 9, 10, 8)
)
b <- ggplot(df2, aes(x, y, fill = g)) +
  theme_minimal()

# With alpha_scope = "group", each group uses the alpha range independently
b + geom_area_fade(
  alpha_scope = "group",
  position = "identity"
  )

# Compare with the default where small groups appear washed out
# next to dominant groups, especially when position = "identity"
b + geom_area_fade(
  alpha_scope = "global", # default
  position = "identity"
  )

# Negative values are supported too:
# the gradient fades towards y = 0 from both sides
d <- ggplot(df2, aes(x, y - mean(y))) +
  theme_minimal()
d + geom_area_fade()

# Overwrite both fill and colour
d + geom_area_fade(
  fill = "#0833F5",
  colour = "#d77e7b",
  outline.type = "lower"
  )

# A 2D-gradient is produced when fill is mapped to a variable
# this may not work on all graphic devices, see vignette for details
d + geom_area_fade(
  aes(fill = y),
  colour = "#333333",
  outline.type = "both"
  )

# Basic density curve: opaque at the peak, fully transparent at the baseline.
ggplot(diamonds, aes(carat)) +
  geom_density_fade()

# Map the values to y to flip the orientation
ggplot(diamonds, aes(y = carat)) +
  geom_density_fade()

# `alpha_fade_to` controls the alpha at the baseline.
# The default `0` is fully transparent; raise it to keep some
# opacity at the floor.
ggplot(diamonds, aes(carat)) +
  geom_density_fade(alpha_fade_to = 0.2)

# Multiple groups via `fill`. With the default `alpha_scope = "global"`
# the tallest peak in the layer reaches full opacity; shorter peaks fade
# in proportion. `xlim()` trims the long tails for clarity.
ggplot(diamonds, aes(depth, fill = cut)) +
  geom_density_fade() +
  xlim(55, 70)

# Switch to `alpha_scope = "group"` so every
# area hits full opacity independently
ggplot(diamonds, aes(depth, fill = cut)) +
  geom_density_fade(alpha_scope = "group") +
  xlim(55, 70)

# You can use position = "fill" to produce a conditional density estimate
ggplot(diamonds, aes(carat, after_stat(count), fill = cut)) +
  geom_density_fade(position = "fill")

# Basic frequency polygon with fading gradient
ggplot(faithful, aes(waiting)) +
  geom_freqpoly_fade(
    colour = "#3b528b",
    bins = 20
  ) +
  theme_minimal()

# Rather than stacking histograms, compare frequency polygons
ggplot(iris, aes(Sepal.Length, fill = Species, colour = Species)) +
  geom_freqpoly_fade(
    alpha = 0.8,
    position = "identity",
    bins = 20
  ) +
  scale_fill_viridis_d() +
  scale_colour_viridis_d() +
  theme_minimal()

Description

geom_catenary() draws a catenary curve (hanging chain) between successive points. geom_arch() draws an inverted catenary curve and is hence intended for people living on the southern hemisphere.

The shape follows the catenary equation: $\ y = a\ \cosh \ \!\bigl(\frac{x - h}{a}\bigr) + v$.

Usage

geom_catenary(
  mapping = NULL,
  data = NULL,
  stat = "catenary",
  position = "identity",
  ...,
  chain_length = NULL,
  sag = NULL,
  chainLength = lifecycle::deprecated(),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_arch(
  mapping = NULL,
  data = NULL,
  stat = "arch",
  position = "identity",
  ...,
  arch_length = NULL,
  arch_height = NULL,
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_catenary(
  mapping = NULL,
  data = NULL,
  geom = "catenary",
  position = "identity",
  ...,
  chain_length = NULL,
  sag = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_arch(
  mapping = NULL,
  data = NULL,
  geom = "arch",
  position = "identity",
  ...,
  arch_length = NULL,
  arch_height = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Aesthetics

geom_catenary() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

See Also

The catenary equation is described at https://en.wikipedia.org/wiki/Catenary.

Examples

library(ggplot2)

df <- data.frame(x = seq_len(4), y = c(1, 1, 0, 2))

# Basic usage
p <- ggplot(df, aes(x, y)) + ylim(-3, NA) + geom_point(size = 3)
p + geom_catenary()

# Catenary with sag = 2, considered from lowest point of each segment
# recycled, if only a one value is provided
p + geom_catenary(sag = 2)
p + geom_catenary(sag = c(2, 1, 1))

# If sag and chain_length are provided for same segment(s), sag wins
p + geom_catenary(sag = c(2, 1, NA), chain_length = 10)

# Arch with height = 2, considered from highest point of each segment
p + geom_arch(arch_height = c(2, 1, 1))

# Rice house, see https://en.wikipedia.org/wiki/Rice_House,_Eltham
rice_house <- data.frame(x = c(0, 1.5, 2.5, 3.5, 5), y = c(0, 1, 1, 1, 0))
ggplot(rice_house, aes(x, y)) +
  geom_arch(arch_height = .15, lwd = 2) +
  geom_segment(aes(xend = x, yend = 0)) +
  geom_hline(yintercept = 0, colour = "forestgreen", linewidth = 3) +
  coord_equal()

Description

Use Chaikin's corner-cutting algorithm smooth sharp corners of a path.

Usage

geom_chaikin(
  mapping = NULL,
  data = NULL,
  stat = "chaikin",
  position = "identity",
  ...,
  mode = "open",
  iterations = 5,
  ratio = 0.25,
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_chaikin(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  ...,
  mode = "open",
  iterations = 5,
  ratio = 0.25,
  closed = lifecycle::deprecated(),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Chaikin's corner cutting algorithm iteratively turns a jagged path into a smooth path.

The recursion formula starts from two vertices A and B, which represent a single corner of your path. From this, the algorithm derives two new points: one at the specified ratio when going from point A to point B, and one when going from B to A in the opposite direction. By default, a ratio of 0.25 results in two points: the first at 25% of the way from point A to point B and the other at 75% of the way from A to B. Those new points form a smoother path. Then the algorithm applies the same rule to each pair of new points. The rule is applied iterations times. The maximum number of iterations is 10, default is 5.

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Aesthetics

geom_chaikin() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Chaikin, G. M. (1974). An algorithm for high-speed curve generation. Computer Graphics and Image Processing, 3(4), 346–349. doi:10.1016/0146-664X(74)90028-8

See Also

The smoothr package offers tools to smooth and tidy spatial features

Examples

library(ggplot2)
set.seed(42)
dat <- data.frame(
  x = seq.int(10),
  y = sample(15:30, 10)
)

p1 <- ggplot(dat, aes(x, y)) +
  geom_line(linetype = "12")

p1 +
  geom_chaikin()

p1 +
  geom_chaikin(iterations = 1)

triangle <- data.frame(x = c(0, 0, 1), y = c(0, 1, 1))
p2 <- ggplot(triangle, aes(x, y)) +
  geom_path(linetype = "12") +
  coord_equal()

# Ratio lets you control the cutting amount
p2 + geom_chaikin(ratio = .1)
p2 + geom_chaikin(ratio = .5)

# Mode controls whether the result is an open or closed shape
p2 + geom_chaikin(mode = "open")   # default
p2 + geom_chaikin(mode = "closed")

Description

geom_col_fade() and geom_bar_fade() draw bar charts like ggplot2::geom_col() / ggplot2::geom_bar() but with options to add an alpha gradient that fades from opaque at the peak of each bar to transparent at its baseline; and rounded corners are supported via grid::roundrectGrob(), controlled by the radius argument.

Usage

geom_col_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "stack",
  ...,
  alpha_fade_to = 0,
  alpha_scope = "bar",
  orientation = NA,
  radius = grid::unit(0, "pt"),
  pattern = NULL,
  lineend = "butt",
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_bar_fade(
  mapping = NULL,
  data = NULL,
  stat = "count",
  position = "stack",
  ...,
  alpha_fade_to = 0,
  alpha_scope = "bar",
  orientation = NA,
  radius = grid::unit(0, "pt"),
  pattern = NULL,
  lineend = "butt",
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Orientation

This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the orientation parameter, which can be either "x" or "y". The value gives the axis that the geom should run along, "x" being the default orientation you would expect for the geom.

alpha_scope = "global" under faceting

alpha_scope = "global" ties opacity to absolute height across the whole layer, so two ridges / areas / bars of equal height render at equal alpha regardless of which panel they're in. This is meaningful only when panels share a common y scale. Under facet_wrap(scales = "free_y") (or facet_grid(rows = ..., scales = "free")) each panel rescales y independently, so the visual height of a shape no longer reflects its data height; the alpha encoding then conflicts with what the eye reads from the panel size. For comparable alpha across free-y panels you have two options: stick to the default scales = "fixed", or accept that under free scales alpha_scope = "group" is the more honest choice (each shape independently uses its own alpha range).

Legend key under coord_flip

The legend key glyph always shows the canonical (data-axis) fade direction – vertical for the default orientation, horizontal under orientation = "y". Under ggplot2::coord_flip() the rendered geom rotates correctly but the legend key does not: ggplot2's legend builder is coord-independent by design (draw_key has no access to the coord). For a legend key that matches a horizontal layout, prefer aes(y = ...) with auto-detected orientation = "y" over aes(x = ...) + coord_flip().

Aesthetics

geom_col_fade() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P. (2022). "Vectorised Pattern Fills in R Graphics." Technical Report 2022-01, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/vecpat/vecpat.html

See Also

ggplot2::geom_bar() and ggplot2::geom_col() for fully opaque bar charts, geom_histogram_fade() for the histogram chart equivalent.

Examples

library(ggplot2)

df <- data.frame(
  x = c("A", "B", "C", "D", "E"),
  y = c(3, 4, -2, -0.5, 1)
)

ggplot(df, aes(x, y)) +
  geom_col_fade() +
  theme_minimal()

# Rounded bar charts are supported too
ggplot(df, aes(x, y)) +
  geom_col_fade(radius = unit(10, "pt")) +
  theme_minimal()

# Start at 90% opacity and keep some opacity at the baseline
ggplot(df, aes(x, y)) +
  geom_col_fade(
    alpha = 0.9,
    alpha_fade_to = 0.1
  ) +
  theme_minimal()

# Horizontal bars are supported
ggplot(df, aes(y, x)) +
  geom_col_fade() +
  theme_minimal()


# Multiple groups with different alpha scopes
p <- ggplot(diamonds, aes(color, fill = cut)) +
  labs(x = NULL, y = NULL) +
  theme_minimal()

# By default each bar has its own alpha scope
p + geom_bar_fade()

# With alpha_scope = "x", bars at same x aesthetic share same alpha scope
p + geom_bar_fade(alpha_scope = "x")

# With alpha_scope = "fill", alpha is defined by what is mapped to the fill aesthetic
p + geom_bar_fade(alpha_scope = "fill")

# With alpha_scope = "global", the maximum absolute
# value across the whole dataset is fully opaque
p + geom_bar_fade(alpha_scope = "global")

# same examples for position dodge with varying alpha scope:
p + geom_bar_fade(alpha_scope = "bar", position = "dodge")
p + geom_bar_fade(alpha_scope = "x", position = "dodge")
p + geom_bar_fade(alpha_scope = "fill", position = "dodge")
p + geom_bar_fade(alpha_scope = "global", position = "dodge")

# bars can be filled with a pattern instead of a solid colour
p + geom_bar_fade(
position = "dodge",
pattern = hatch(), # default
colour = "#333333"
)

# hatch can be filled with a pattern instead of a solid colour
p + geom_bar_fade(
position = "dodge",
pattern = hatch(angle = 90, style ="crossed", spacing = unit(1.25, "mm")),
colour = "#333333"
)

# Polar coordinates are supported too, if you need it
ggplot(diamonds, aes(x = factor(1), fill = cut)) +
  geom_bar_fade(width = 1) +
  coord_polar(theta = "y") +
  theme_void()

Description

geom_fourier() and stat_fourier() fit a truncated Fourier (discrete Fourier transform, DFT) series to the supplied x/y observations and render the reconstructed smooth curve. The data are first aggregated at duplicate x positions, interpolated to a uniform grid, optionally de-trended, transformed via stats::fft(), and then reconstructed from the requested number of harmonics.

Usage

geom_fourier(
  mapping = NULL,
  data = NULL,
  stat = "fourier",
  position = "identity",
  ...,
  n_harmonics = NULL,
  detrend = NULL,
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_fourier(
  mapping = NULL,
  data = NULL,
  geom = "fourier",
  position = "identity",
  ...,
  n_harmonics = NULL,
  detrend = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Period convention

The DFT treats the input as one period of an infinitely repeating signal. The correct period for $N$ uniformly-spaced samples with spacing $\Delta x$ is $P = N \cdot \Delta x$, not $x_{max} - x_{min}$. Using the latter (a closed interval) implicitly maps the last sample to $t = 1$, which coincides with $t = 0$ of the next period, causing a boundary discontinuity and Gibbs-phenomenon ringing whenever the first and last y values differ. This implementation uses the half-open period.

Detrending

Before the FFT is applied the data can be de-trended so that slow, non-periodic trends do not dominate the low-frequency coefficients:

NULL (default)

No de-trending; the raw signal is transformed.

"lm"

Subtract a global ordinary-least-squares linear fit.

"loess"

Subtract a LOESS smooth. Falls back to "lm" with a message if the group is too small for LOESS (fewer than 4 observations).

The trend is added back before the final curve is returned, so the output is always on the original y-scale.

Nyquist limit

The maximum number of harmonics recoverable from $N$ observations is $\lfloor N/2 \rfloor$. Requesting more triggers a message and the limit is used instead.

Irregular spacing

The input data is linearly interpolated onto a uniform grid before the FFT. If the original x-spacing is highly irregular (e.g. monthly time series data), the interpolation may introduce artefacts in sparse regions. A message is emitted when the coefficient of variation of the x-spacing exceeds 0.5.

Aesthetics

geom_fourier() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

See Also

stats::fft() for the underlying Fast Fourier Transform, lm() and loess() for the optional detrending fits, geom_catenary() and geom_chaikin() for other curve-fitting geoms.

Examples

library(ggplot2)

n <- 50
df1 <- data.frame(
  x = seq(0, 1, length.out = n),
  y = sin(seq(0, 2 * pi, length.out = n)) + rnorm(n, sd = 0.2)
)

# Basic usage - Interpolating fit (all harmonics)
p <- ggplot(df1, aes(x, y)) +
  geom_point(alpha = 0.5)
p + geom_fourier()

# Use 1 harmonic only
p + geom_fourier(n_harmonics = 1)

# De-trending a linearly drifting signal
set.seed(2)
x <- seq(0, 4 * pi, length.out = n)
df2 <- data.frame(
  x = x,
  y = sin(x) + x * 0.3 + rnorm(n, sd = 0.15)
)

ggplot(df2, aes(x, y))  +
geom_point(alpha = 0.35) +
  geom_fourier(aes(colour = "detrend = NULL"), n_harmonics = 3) +
  geom_fourier(aes(colour = "detrend = \"lm\""), n_harmonics = 3,
               detrend = "lm")

# Multiple groups
set.seed(3)
x <- seq(0, 2 * pi, length.out = n/2)
df3 <- rbind(
  data.frame(x = x, y = sin(x) + rnorm(n / 2, sd = 0.2), grp = "sine"),
  data.frame(x = x, y = cos(x) + rnorm(n / 2, sd = 0.2), grp = "cosine")
)

ggplot(df3, aes(x, y, colour = grp)) +
  geom_point(alpha = 0.5) +
  geom_fourier()

# When the data is not uniformly-spaced, the Fourier
# curve will not hit every data point exactly
ggplot(head(economics, 25), aes(date, unemploy)) +
  geom_fourier() +
  geom_point()  +
  geom_curve_fade(
    data = data.frame(
      x    = as.Date("1967-10-01"),
      xend = as.Date("1968-01-01"),
      y    = 2750,
      yend = 2850
    ),
    aes(x = x, xend = xend, y = y, yend = yend),
    arrow = arrow(),
    colour = "tomato"
    )

# ... in extreme cases a warning is emitted
df4 <- data.frame(
  x = c(1:10, 19:20),
  y = sin(seq_len(12))
)

ggplot(df4, aes(x, y)) +
  geom_point() +
  geom_fourier()

Description

geom_gridline() draws horizontal and vertical grid lines as a regular ggplot2 layer, so they appear above bar charts or any other geom in your plot.

The line positions are read directly from the trained scale (via panel_params), and the line properties are read from the theme; so geom_gridline() always matches the grid line positions and properties by default — but you are free to override every property, of course.

This was inspired by Observable Plot's Grid mark: https://observablehq.com/plot/marks/grid#grid-mark.

Usage

geom_gridline(
  mapping = NULL,
  data = NULL,
  grids = "y",
  lines = "major",
  colour = NULL,
  linewidth = NULL,
  linetype = NULL,
  lineend = NULL,
  alpha = NA,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = FALSE,
  ...
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Line properties

By default geom_gridline() inherits each property by walking ggplot2's documented theme chain: panel.grid.major.x (or .y) → panel.grid.major → panel.grid → line so that by default lines look exactly like the grid would. If you blank panel.grid the layer picks up styling from theme(line = ...). Pass an explicit colour to override, see Examples.

Rendering order

geom_gridline() follows a specific Z-order convention to ensure maximum visibility:

1. Major grid lines are always drawn on top of minor grid lines.

2. Y-aesthetic grid lines are drawn on top of X-aesthetic grid lines.

This means the final drawing sequence (from bottom to top) is: Minor X, Minor Y, Major X, Major Y.

See Also

ggplot2::geom_hline(), ggplot2::geom_vline() for fixed reference lines; ggplot2::theme() for controlling the underlying panel grid.

Examples

library(ggplot2)

# Basic example - geom_gridline() is just another layer
# plotted in the order you add them to your ggplot
p <- ggplot(mpg, aes(class)) +
  geom_bar()
p + geom_gridline()

# Note: geom_gridline() does not touch the theme. To draw only the layer's
# lines (no theme grid underneath), blank the panel grid yourself.
bf <- theme_grey()$panel.background@fill
p +
  geom_gridline(linewidth = 0.4, colour = bf) +
  theme_minimal() +
  theme(panel.grid = element_blank())

# Horizontal bars: flip axes, draw gridlines atop x-grid at custom breaks
ggplot(mpg, aes(y = class)) +
  geom_bar() +
  geom_gridline(grids = "x", colour = "tomato", linewidth = 2) +
  scale_x_continuous(breaks = c(5, 10, 20, 40))

# Line properties are inherited from theme
# their positions from the scale
p +
  geom_gridline() +
  scale_y_continuous(breaks = c(10, 20)) +
  theme_gray(paper = "cornsilk", ink = "navy")

# When you explicitly set properties in geom_gridline
# they will overwrite theme properties
p +
  geom_gridline(lines = c("major", "minor")) +
  scale_y_sqrt(breaks = c(10, 20)) +
  theme_gray(paper = "cornsilk", ink = "navy")

Description

Visualise the distribution of a single continuous variable as a histogram with a fading alpha gradient. Counts are drawn with rounded, gradient-filled bars (like geom_col_fade() paired with ggplot2::stat_bin()). Accepts all binning parameters forwarded to ggplot2::stat_bin() (bins, binwidth, center, boundary, ...).

Usage

geom_histogram_fade(
  mapping = NULL,
  data = NULL,
  stat = "bin",
  position = "stack",
  ...,
  binwidth = NULL,
  bins = NULL,
  alpha_fade_to = 0,
  alpha_scope = "bar",
  orientation = NA,
  radius = grid::unit(0, "pt"),
  pattern = NULL,
  lineend = "butt",
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Aesthetics

geom_histogram_fade() understands the same aesthetics as geom_col_fade() (it is GeomHistogramFade, a subclass of GeomColFade, paired with ggplot2::stat_bin()). See ?geom_col_fade for the full aesthetics table.

Orientation

This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the orientation parameter, which can be either "x" or "y". The value gives the axis that the geom should run along, "x" being the default orientation you would expect for the geom.

References

Murrell, P. (2022). "Vectorised Pattern Fills in R Graphics." Technical Report 2022-01, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/vecpat/vecpat.html

See Also

geom_col_fade() / geom_bar_fade() for the bar-chart equivalents, geom_area_fade() for the general area-fade geom, ggplot2::geom_histogram() and ggplot2::geom_freqpoly() for the non-fading originals.

Examples

library(ggplot2)

# By default each bar has its own alpha scope
p <- ggplot(faithful, aes(waiting))
p + geom_histogram_fade()

# when all bars shall share the same alpha scope,
# set alpha_scope = "global"
p +
  geom_histogram_fade(
    alpha_scope = "global",
    alpha = 0.75,
    alpha_fade_to = 0.1,
    radius = unit(3, "pt"),
    colour = "#333333"
  ) +
  theme_minimal()

# Stacked histogram with groups
ggplot(iris, aes(Sepal.Length, fill = Species)) +
  geom_histogram_fade(alpha_fade_to = 0.25) +
  theme_minimal()

# Stacked histogram with groups and global alpha scope
ggplot(iris, aes(Sepal.Length, fill = Species)) +
  geom_histogram_fade(
    alpha_fade_to = 0.25,
    alpha_scope = "global"
  )

# Per-fill scope under position = "dodge": each fill cluster has its own
# alpha range, so the tallest sub-bar in every bin reaches full opacity.
ggplot(iris, aes(Sepal.Width, fill = Species)) +
  geom_histogram_fade(
    position = "dodge",
    bins = 10,
    alpha_scope = "fill"
  )

Description

This geom can be used to plot 45 deg lifelines for a cohort. Lexis diagrams are named after Wilhelm Lexis and used by demographers for more than a century.

Usage

geom_lexis(
  mapping = NULL,
  data = NULL,
  stat = "lexis",
  position = "identity",
  ...,
  point_show = TRUE,
  point_colour = NULL,
  gap_filler = TRUE,
  lineend = "round",
  linejoin = "round",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

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

Arguments

Details

This geom draws 45 deg lines from the start to the end of a 'lifetime'. It is a combination of a segment, and a point. stat_lexis() calculates y and yend for you, so the only required aesthetics are x and xend. Besides y and yend coordinates this geom creates one additional variable called type in the layer data. You might want to map to an aesthetic with ggplot2::after_stat(), see Examples and vignette("ggpointless") for more details.

Rows in your data with either missing x or xend values will be removed because your segments must start and end somewhere.

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Aesthetics

geom_lexis() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

Examples

library(ggplot2)
df1 <- data.frame(
  key = c("A", "B", "B", "C", "D", "E"),
  start = c(0, 1, 6, 5, 6, 9),
  end = c(5, 4, 10, 9, 8, 11)
)
p <- ggplot(df1, aes(x = start, xend = end, colour = key))
p +
  geom_lexis()
p +
  geom_lexis(gap_filler = FALSE)
p +
  geom_lexis(aes(linetype = after_stat(type)),
    point_show = FALSE
  )

# Change point appearance
p + geom_lexis(
  point_colour = "black",
  size = 3,
  shape = 21,
  fill = "white",
  stroke = 1
)

# Missing values will be removed
df2 <- data.frame(
  key = c("A", "B", "B", "C", "D"),
  start = c(0, 1, 7, 5, 6),
  end = c(5, 4, 13, 9, NA)
)
ggplot(df2, aes(x = start, xend = end, colour = key)) +
  geom_lexis()

# Ideally, `x` values should be increasing, unlike
# in the next example
df3 <- data.frame(x = Sys.Date() - 0:2, xend = Sys.Date() + 1:3)
ggplot(df3, aes(x = x, xend = xend)) +
  geom_lexis()

Description

geom_path_fade() connects observations in the order they appear in the data (like ggplot2::geom_path()) and applies a linear alpha gradient so that one or both ends of the path fade to transparent.

geom_line_fade() is identical to geom_path_fade() but sorts observations by x before drawing (like ggplot2::geom_line()).

geom_step_fade() is identical to geom_path_fade() but draws a staircase-step path (like ggplot2::geom_step()). The direction argument controls the step shape: "hv" (horizontal then vertical, the default), "vh" (vertical then horizontal), or "mid" (step at the midpoint).

Usage

geom_path_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  alpha_fade_to = 0,
  fade_direction = "start",
  alpha_mode = "auto",
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_line_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  alpha_fade_to = 0,
  fade_direction = "start",
  alpha_mode = "auto",
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_step_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  alpha_fade_to = 0,
  fade_direction = "start",
  alpha_mode = "auto",
  direction = "hv",
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Rendering modes

The alpha_mode argument controls how the alpha gradient is rendered. All three values compute a target alpha at each vertex from cumulative distance along the path – the fade follows the path regardless of direction or shape.

"auto" (default): pick per sub-path based on vertex count n. n <= 50 -> "gradient" (smooth within-segment fade; protects the common "few thick segments" case). n > 50 -> "step" (stepping is invisible at that density and gradient's per-segment cost grows linearly with n). The threshold is chosen so that worst-case "gradient" render time stays under ~0.4 s per panel. Resolved per sub-path – a multi-group plot can mix modes. Users who want deterministic rendering (snapshots, reproducible builds) should set "step" or "gradient" explicitly.

"step": each segment is drawn inside a viewport clipped to its bisector-cut polygon, carrying a single uniform alpha – the average of its two endpoint alphas. The fade is an illusion created by stepping through discrete alpha values across adjacent segments. Fast (~0.4 s for a 200-point path).

"gradient": each segment's clipped viewport contains a panel-sized rectGrob with its own direction-aligned linearGradient fill. The alpha transitions smoothly within each segment – a real continuous gradient, not a step approximation. Slower (~1 s for 200 points, ~4 s for 1000 points); scales linearly with n and multiplies under facets.

All modes require a device that supports clipping paths (e.g. ragg::agg_png(), grDevices::svg()). On devices that don't, the geom falls back to per-segment segmentsGrob rendering with combined alpha (no linejoin).

The base grDevices::pdf() and grDevices::postscript() devices advertise clipping-path support but have an upstream R heap-corruption bug at dev.off() once enough clipping or gradient operations accumulate (reproducible with pure grid on R 4.5.3). To keep these devices safe the geom routes through the flat per-segment fallback on pdf() / postscript() regardless of alpha_mode. Use grDevices::cairo_pdf() (or ragg::agg_png() / grDevices::svg() for raster/vector output) if you need the smooth-gradient rendering.

The visual difference between "step" and "gradient" is only noticeable with very few, thick segments: in "step" mode each segment is visibly a solid colour, while "gradient" interpolates smoothly within each segment too. At typical point counts (>= ~50) both modes look identical – which is what "auto" exploits.

As a special case, a single-segment path (exactly two observations) is always rendered as a gradient even when alpha_mode = "step", because step mode's per-segment alpha would otherwise collapse the fade to a uniform mid-alpha stroke.

RStudio "Unknown group" warning

On the RStudio plot pane (and any device that caches and replays the rendered grob tree), step-mode rendering may emit grid warnings of the form ⁠Warning in .useGroup(ref, NULL) : Unknown group, N⁠ on repeat draws – typically when the pane is resized and replays a cached tree. The plot itself is correct; the warning is cosmetic noise.

What is happening: step mode uses grid's compositing primitive (groupGrob() with operator "dest.in") to trim the alpha mask onto the polyline. Each draw allocates fresh device-level group IDs. When the plot pane replays a cached grob tree, that tree still references the old IDs while grid's device table has been reset – the lookup fails and grid prints ⁠Unknown group, N⁠. The pixels you see are correct because the composited result was already resolved when the cache was built; grid is just reporting that the replay couldn't repeat the lookup, not that anything is missing on screen.

The warning fires inside grid's drawing machinery after our render code has already returned, so we cannot wrap it in suppressWarnings() from within the package. The only clean alternative would gate the fast compositing path off in RStudio, which makes the interactive plot pane roughly five times slower (~1.5 s -> ~7.5 s on a five-group $\times$ 573-segment dataset) – we judged that the worse trade-off. If the warnings are intolerable for a particular layer, set alpha_mode = "gradient"; gradient mode uses viewport clipping instead of compositing and does not trigger the warning.

Device-independent alternative

A device-independent alternative to this geom is to densify the path before plotting by interpolating x, y with stats::approx() , and a matching alpha column along the path; then pass the result to a plain ggplot2::geom_path(). Because ggplot2 draws each segment between adjacent points with a uniform aesthetic value (see the ggplot2 book, section 4.4), enough interpolated points make the stepping invisible and produce a smooth apparent fade without any compositing:

df <- data.frame(x = c(0, 1, 2), y = c(0, 1, 0))

# Parameterise by cumulative arc length, then densify
arc <- with(df, c(0, cumsum(sqrt(diff(x)^2 + diff(y)^2))))
arc <- arc / max(arc)
grid_pos <- seq(0, 1, length.out = 200)

dense <- data.frame(
  x     = approx(arc, df$x, xout = grid_pos)$y,
  y     = approx(arc, df$y, xout = grid_pos)$y,
  alpha = 1 - grid_pos   # fade towards end
)

ggplot(dense, aes(x, y, alpha = alpha)) +
  geom_path(linewidth = 2) +
  scale_alpha_identity()

The trade-off: this requires manual labour, and it does not generalise to paths with multiple groups or to fade_direction = c("start", "end") without additional bookkeeping. geom_path_fade() handles all of this internally.

Self-crossing paths

When a faded path crosses itself, the pixels at the crossing are rasterised once per overlapping segment, and the per-segment alpha values compound. Where the two strands carry different alphas (one near the faded end, one near the opaque end), the crossing appears noticeably darker than either strand alone.

This behaviour is inherent to how semi-transparent strokes are alpha-blended at the device level, not specific to geom_path_fade() – the same effect appears with ggplot2::geom_path(alpha = 0.5). There is no general workaround at the rendering layer; if a clean intersection matters for your plot, the practical options are:

• Raise alpha_fade_to so the strands at both ends are closer in opacity (smaller delta -> less visible darkening).

• Use a fully opaque stroke (no fade) for paths known to self-cross.

• Restructure the data so the crossing is split across separate layers.

Applies equally to geom_segment_fade() and geom_curve_fade() when two segments / curves overlap at the same pixel.

Aesthetics

geom_path_fade() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P., Pedersen, T. L., and Skintzos, P. (2023). "Porter-Duff Compositing Operators in R Graphics." Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/compositing/compositing.html

Murrell, P. (2023). "Groups, Compositing Operators, and Affine Transformations in R Graphics." Technical Report 2021-02, Department of Statistics, The University of Auckland. Version 3. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html

See Also

geom_line_fade() which sorts by x first, geom_segment_fade() for individual fading segments, ggplot2::geom_path() for the unfaded version.

Examples

library(ggplot2)

# Path that doubles back -- fade follows the drawing order
theta <- seq(1.3, -1.3, length.out = 101)
df_ichthys <- data.frame(
  x = theta^2,
  y = 0.5 * theta * (theta^2 - 1)
)

p <- ggplot(df_ichthys, aes(x, y)) +
  geom_pointless(
    location = c("first", "last"),
    aes(colour = after_stat(location)),
    size = 4
  ) +
  coord_fixed() +
  theme_minimal()

p + geom_path_fade(
    linewidth = 1.5,
    fade_direction = "start" # default
  )

p + geom_path_fade(
    linewidth = 1.5,
    fade_direction = c("start", "end")
  )

# With few thick segments the default `"auto"` picks `"gradient"` for
# you, because at n <= 50 the smoother within-segment fade matters more
# than the (negligible) extra compute time.
df_thick <- data.frame(
  x = c(0, 1, 1.5, 1, 0),
  y = c(0, 0.5, 1, 1.5, 1)
)

p <- ggplot(df_thick, aes(x, y)) +
  coord_equal() +
  theme_minimal()

# Auto -> gradient (n = 5, well below the 50-vertex threshold)
p + geom_path_fade(
  linewidth = 8,
  colour = "#e63946"
  )

# Force `"step"` to see the per-segment stepping for comparison.
p + geom_path_fade(
  linewidth = 8,
  colour = "#e63946",
  alpha_mode = "step"
  )

# Explicit `"gradient"`, in this example, does the same thing
# `"auto"` picked above; for large n (> 200) this gets slow with
# not much gain visually.
p + geom_path_fade(
  linewidth = 8,
  colour = "#e63946",
  alpha_mode = "gradient"
  )

# Using stat_function
ggplot() +
  stat_function(
    alpha = 0.5,
    fun = dnorm,
    n = 100,
    xlim = c(-4, 4),
    geom = "area_fade",
    outline.type = "none" # remove solid outline
  ) +
  # Add fading outline instead
  stat_function(
    fun = dnorm, n = 100,
    xlim = c(-4, 4),
    geom = "path_fade",
    fade_direction = c("start", "end")
  )


nile_df <- data.frame(year = time(datasets::Nile), value = c(datasets::Nile))
ggplot(nile_df, aes(year, value)) +
  geom_line_fade()

# NA values split the path into sub-paths -- just like geom_line().
# The fade is computed over the concatenated arc length of all visible
# pieces, so the alpha just before a gap equals the alpha just after,
# as if the path were "pulled apart" at the NA.
df <- data.frame(x = c(1, 2, 3, 3, 4, 5), y = c(1, 2, NA, 3, 4, 5))

ggplot(df, aes(x, y)) +
  geom_line_fade(alpha_mode = "gradient", linewidth = 2)


# Fading step function
set.seed(42)
d <- data.frame(
  x   = rep(1:10, 2),
  y   = c(cumsum(rnorm(10)), cumsum(rnorm(10))),
  grp = rep(c("a", "b"), each = 10)
)

ggplot(d, aes(x, y, colour = grp)) +
  geom_step_fade(linewidth = 1, direction = "vh")

Description

geom_point_glow() is a version of ggplot2::geom_point() that adds a glow (radial gradient) behind each point.

Usage

geom_point_glow(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  glow_alpha = 0.5,
  glow_colour = NA,
  glow_size = NA,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Coordinate systems

geom_point_glow() works in all coordinate systems. The glow effect remains point-centric and circular in device space, even in non-linear coordinates like ggplot2::coord_polar().

Aesthetics

geom_point_glow() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P. (2022). "Vectorised Pattern Fills in R Graphics." Technical Report 2022-01, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/vecpat/vecpat.html

See Also

ggplot2::geom_point(), grid::radialGradient()

Examples

library(ggplot2)

# Tiny dataset on purpose: each glow point becomes its own
# `grid::radialGradient` pattern, and the example runner accumulates
# patterns from every package example into a single pdf() device.  On
# large pdf runs that pattern cache can trigger an upstream R bug at
# `dev.off()` -- unrelated to your real plots.
df <- head(mtcars, 10)

# Basic usage -- the default glow is 9x the point's `size` aesthetic,
# so it's always visibly larger than the point itself.
ggplot(df, aes(wt, mpg, colour = factor(cyl))) +
  geom_point_glow()


  # Customising the glow: fixed values applied to every point, while
  # point colour is set to transparent
  ggplot(df, aes(wt, mpg)) +
    geom_point_glow(
    colour = "transparent",
    glow_colour = "tomato",
    glow_alpha = .75,
    glow_size = 20
  )

  # Per-point glow: pass a length-N vector for `glow_colour`, `glow_alpha`,
  # or `glow_size`.
  ggplot(df, aes(wt, mpg)) +
    geom_point_glow(glow_colour = rainbow(nrow(df)), glow_size = 15)

  # Use the Geom with another Stat to glow only specific observations:
  ggplot(head(economics), aes(date, uempmed)) +
    geom_line() +
    stat_pointless(
      geom = "PointGlow",
      glow_colour = "tomato",
      glow_size = 10,
      location = c("first", "last")
    )

Description

This is a wrapper around ggplot2::geom_point() with one additional argument: location. This geom aims to emphasise some observations, and is not particularly useful on its own — hence its name — but it shines in conjunction with geom_line() and friends; see Examples.

Usage

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

stat_pointless(
  mapping = NULL,
  data = NULL,
  geom = "point",
  position = "identity",
  ...,
  location = "last",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Details

The location argument allows you to specify which observations should be highlighted. If location is "last", the default, a single point will be plotted at the last non-missing observation. The locations are determined in the order in which they appear in the data – like ggplot2::geom_path() does compared to ggplot2::geom_line().

When a single observation matches multiple location criteria – for example, the last point is also the maximum – it is emitted once with a composite label joined by ", " (e.g. "last, maximum"). The row order in the output – which drives draw order and legend order – follows the order given in location; for "all" the canonical order is "first", "last", "minimum", "maximum". See vignette("ggpointless") for more details.

Aesthetics

geom_pointless() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

See Also

ggplot2::geom_point()

Examples

library(ggplot2)
x <- seq(-pi, pi, length.out = 150)
y <- outer(x, 1:5, FUN = \(x, y) sin(x * y))

df1 <- data.frame(
  x = x,
  y = rowSums(y)
)

# Not terribly useful on its own ...
p <- ggplot(df1, aes(x = x, y = y))
p + geom_pointless()
p + geom_pointless(location = "all")

# ... but in conjunction with geom_line(), hopefully
p <- p + geom_line()
p + geom_pointless(location = "all")
p + geom_pointless(location = c("first", "last"))
p + geom_pointless(location = c("minimum", "maximum"))

# The layer computes one additional variable, 'location',
# that you can map to aesthetics. Pair `colour` with `shape` for redundant
# encoding -- the four roles stay distinguishable in greyscale and under
# colour-vision deficiencies.
p + geom_pointless(
  aes(colour = after_stat(location), shape = after_stat(location)),
  location = "all",
  size = 3
)

# Example with missing first and last observations
set.seed(42)
df2 <- data.frame(x = 1:10, y = c(NA, sample(1:8), NA))
ggplot(df2, aes(x, y)) +
  geom_line() +
  geom_pointless(location = c("first", "last"))

# Change the order in which points are drawn when they overlap
df3 <- data.frame(x = 1:2, y = 1:2)

p <- ggplot(df3, aes(x = x, y = y)) +
  geom_path() +
  coord_equal()

# Same as location = 'all'
p + geom_pointless(aes(colour = after_stat(location)),
  location = c("first", "last", "minimum", "maximum")
) +
  labs(subtitle = "same as location = 'all'")

# Reversed custom order
p + geom_pointless(aes(colour = after_stat(location)),
  location = c("maximum", "minimum", "last", "first")
) +
  labs(subtitle = "custom order")

# Same as location = 'all' again
p + geom_pointless(aes(colour = after_stat(location)),
  location = c("maximum", "minimum", "last", "first", "all")
) +
  labs(subtitle = "same as location = 'all' again")

# Use stat_pointless() with a geom other than "point"
set.seed(42)
df4 <- data.frame(x = 1:10, y = sample(1:10))
ggplot(df4, aes(x, y)) +
  geom_line() +
  geom_pointless(location = c("maximum", "minimum"), size = 3) +
  stat_pointless(
    aes(label = after_stat(y)),
    location = c("maximum", "minimum"),
    geom = "text",
    hjust = -1
  )

# Example using facets
# https://stackoverflow.com/q/29375169
p <- ggplot(economics_long, aes(x = date, y = value)) +
  geom_line() +
  facet_wrap(vars(variable), ncol = 1, scales = "free_y")

p + geom_pointless(
  aes(colour = after_stat(location)),
  location = c("minimum", "maximum"),
  size = 2
  )

Description

geom_rect_fade() draws axis-aligned rectangles and fills each one with a linear gradient that fades one edge to transparent. The direction is controlled by fade_direction. Corners can be rounded via the radius argument, enabling rounded rectangles and smooth-cornered visual elements. The default of ⁠0 pt⁠ produces plain rectangles.

Usage

geom_rect_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  alpha_fade_to = 0,
  fade_direction = "vertical",
  radius = grid::unit(0, "pt"),
  pattern = NULL,
  lineend = "butt",
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2::layer() object that can be added to a ggplot2::ggplot().

Polar coordinates

Under ggplot2::coord_polar() / ggplot2::coord_radial() each rectangle is bent into an annular segment. A radial alpha gradient – transparent at the inner radius, opaque at the outer – is rendered when the fade direction aligns with the radial axis:

• theta = "x" (default) + fade_direction = "vertical": ymin/ymax map to inner/outer radius and fade radially.

• theta = "y" + fade_direction = "horizontal": xmin/xmax map to inner/outer radius and fade radially.

Any other combination (for example theta = "x" with fade_direction = "horizontal") would require an angular / conic gradient, which grid does not yet expose, so the fade is dropped (with a one-time message). A pattern fill still renders – it lives in millimetre space, independent of the fade – clipped to each annular segment at a uniform alpha. Without a pattern, such plots fall back to plain ggplot2::geom_rect(). Rounded corners (radius) are ignored in polar coordinates since arcs do not carry corner geometry.

Patterns

hatch() builds line-hatch fills – diagonal stripes (hatch()), crosshatch (hatch(style = "crossed")), vertical stripes (hatch(90)), grids (hatch(0, style = "crossed")) – at a true visual angle, recoloured to the fill aesthetic and faded with the alpha gradient.

Unlike grid::pattern() tiling – which renders diagonal or wavy lines as disconnected dashes, because each tile is clipped at its own bounds – hatch() draws real parallel lines clipped to the rectangle, so they stay continuous.

For your own continuous hatching beyond straight lines (e.g. wavy lines), build a grid::grob() in "npc" units and pass it as pattern: it is drawn once and clipped to each rectangle, preserving line continuity. For self-contained motifs (dots, small shapes) pass a grid::pattern() object, which tiles cleanly; its stroke colour is recoloured to the fill aesthetic. The article vignette("ggpointless") walks through building a wavy-line grob and injecting it. For a far richer set of patterns and controls, use the ggpattern package by Trevor L. Davis (https://trevorldavis.com/R/ggpattern/).

Legend key under coord_flip

The legend key glyph always shows the canonical (data-axis) fade direction – vertical for the default orientation, horizontal under orientation = "y". Under ggplot2::coord_flip() the rendered geom rotates correctly but the legend key does not: ggplot2's legend builder is coord-independent by design (draw_key has no access to the coord). For a legend key that matches a horizontal layout, prefer aes(y = ...) with auto-detected orientation = "y" over aes(x = ...) + coord_flip().

Aesthetics

geom_rect_fade() understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:

Learn more about setting these aesthetics in vignette("ggplot2-specs").

References

Murrell, P. (2022). "Vectorised Pattern Fills in R Graphics." Technical Report 2022-01, Department of Statistics, The University of Auckland. Version 1. https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/vecpat/vecpat.html

See Also

hatch() for the line-hatch helper. ggplot2::geom_rect() for plain rectangles, geom_col_fade() for bar charts with per-bar gradient scaling and orientation support. The ggpattern package (https://trevorldavis.com/R/ggpattern/) for comprehensive pattern fills.

Examples

library(ggplot2)

# Highlight a time period with a fading rectangle
df_rect <- data.frame(
  xmin = as.Date("1968-03-01"),
  xmax = as.Date("1969-07-01"),
  ymin = -Inf,
  ymax = 2800
)

p <- ggplot(head(economics, 25), aes(date, unemploy)) +
  stat_fourier(geom = "line_fade", fade_direction = "start", alpha_fade_to = 0.2) +
  geom_point(size = 3, alpha = 0.2) +
  theme_minimal()

p +
  geom_rect_fade(
    data = df_rect,
    inherit.aes = FALSE,
    alpha = 0,
    alpha_fade_to = 0.3,
    aes(xmin = xmin, xmax = xmax, ymin = ymin, ymax = ymax)
  )

# Fill with a fading pattern using the string shortcut
p +
  geom_rect_fade(
    data = df_rect,
    inherit.aes = FALSE,
    alpha = 0,
    alpha_fade_to = 0.3,
    aes(xmin = xmin, xmax = xmax, ymin = ymin, ymax = ymax),
    pattern = "crossed"
  )

# Customize the pattern further by calling hatch() directly
p +
  geom_rect_fade(
    data = df_rect,
    inherit.aes = FALSE,
    alpha = 0,
    alpha_fade_to = 0.3,
    aes(xmin = xmin, xmax = xmax, ymin = ymin, ymax = ymax),
    pattern = hatch(angle = 60, style = "parallel", spacing = unit(1, "mm"))
  )

Description

geom_ridgeline_fade() draws ridgeline plots: multiple area shapes stacked at different vertical offsets and adds a vertical alpha gradient that fades from opaque at the peaks to transparent at each ridge's baseline.

The gradient machinery is shared with geom_area_fade(); the difference is that each group's baseline is its own y value rather than zero, enabling the characteristic overlapping-ridges layout.

geom_ridgeline_density_fade() is a convenience wrapper around geom_ridgeline_fade() that uses ggplot2::stat_density() to compute a kernel density estimate, mapping the result to height automatically via aes(height = after_stat(density)). Adjust scale manually so adjacent ridges reach the desired overlap.

geom_ridgeline_freqpoly_fade() and geom_ridgeline_histogram_fade() are the ridgeline counterparts of geom_freqpoly_fade() and geom_histogram_fade(). Both bin the x aesthetic per categorical y baseline; they differ only in how consecutive bins connect: freqpoly draws linear connections between bin midpoints (polyline); histogram draws stepped flat-top rectangles with vertical jumps at the bin edges.

Usage

geom_ridgeline_fade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = NULL,
  ...,
  alpha_fade_to = 0,
  alpha_scope = "group",
  scale = NULL,
  min_height = NULL,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_ridgeline_density_fade(
  mapping = NULL,
  data = NULL,
  stat = "density",
  ...,
  alpha_fade_to = 0,
  alpha_scope = "group",
  scale = NULL,
  min_height = NULL,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_ridgeline_freqpoly_fade(
  mapping = NULL,
  data = NULL,
  position = NULL,
  ...,
  bins = 30,
  binwidth = NULL,
  center = NULL,
  boundary = NULL,
  closed = c("right", "left"),
  pad = TRUE,
  alpha_fade_to = 0,
  alpha_scope = "group",
  scale = NULL,
  min_height = NULL,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_ridgeline_histogram_fade(
  mapping = NULL,
  data = NULL,
  position = NULL,
  ...,
  bins = 30,
  binwidth = NULL,
  center = NULL,
  boundary = NULL,
  closed = c("right", "left"),
  pad = TRUE,
  alpha_fade_to = 0,
  alpha_scope = "group",
  scale = NULL,
  min_height = NULL,
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)