geom_stream: Create a Streamline Plot Layer in ggplot2

In ggvfields: Vector Field Visualizations with 'ggplot2'

Create a Streamline Plot Layer in ggplot2

Description

geom_stream() generates a ggplot2 layer that visualizes data as continuous streams over a temporal variable t. Each stream is defined by the required aesthetics x, y, and t, and optionally grouped by group (or mapped from id). Within each group, data points are automatically ordered by t to form a continuous path.

Usage

geom_stream(
  mapping = NULL,
  data = NULL,
  stat = StatStream,
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  arrow = grid::arrow(angle = 25, length = unit(0.025, "npc"), type = "closed")
)

stat_stream(
  mapping = NULL,
  data = NULL,
  geom = GeomStream,
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  arrow.fill = NULL,
  lineend = "butt",
  linejoin = "round",
  linemitre = 10,
  arrow = grid::arrow(angle = 25, length = unit(0.025, "npc"), type = "closed")
)

Arguments

mapping	A set of aesthetic mappings created by ggplot2::aes(). Required: Must include x, y, and t; additionally, group is used to differentiate streams (if not provided, id will be mapped to group automatically).
data	A data frame or other object, as in grid::layer().
stat	The statistical transformation to use on the data for this layer; defaults to StatStream.
position	Position adjustment, either as a string or the result of a position adjustment function.
...	Other arguments passed to the underlying layers for further customization.
na.rm	Logical. If FALSE (the default), missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	Logical. Should this layer be included in the legends?
inherit.aes	Logical. If FALSE, overrides the default aesthetics rather than combining with them.
arrow.fill	An optional parameter specifying the color of the arrow head. Defaults to NULL and inherets fill/alpha of aes().
lineend	Line end style (round, butt, square).
linejoin	Line join style (round, mitre, bevel).
linemitre	Line mitre limit (number greater than 1).
arrow	An optional grid::arrow() specification to place arrowheads on the streamline.
geom	The geometric object used to render the streamline (only used in stat_stream(); defaults to GeomStream).

Details

There are two variants:

• geom_stream(): A convenient wrapper that sets stat = StatStream and uses ggplot2::GeomPath by default.

• stat_stream(): Provides direct access to the reordering stat (i.e. StatStream) for advanced customization, using GeomStream for drawing.

Value

A ggplot2 layer that can be added to a plot to produce a streamline visualization.

Aesthetics

geom_stream() and stat_stream() understand the following aesthetics (required aesthetics are in bold):

• x: Horizontal position.

• y: Vertical position.

• t: Temporal or ordered variable used to sequence data points.

• group: Grouping variable for multiple streams (automatically mapped from id if absent).

• color: Color of the stream.

• linetype: Type of line used to draw the stream.

• linewidth: Thickness of the stream line.

• alpha: Transparency of the stream.

Details

• Data Ordering: If t is not provided, an error is thrown. When present, points within each group are sorted by t prior to drawing the stream.

• Arrows: The arrow parameter can be used to indicate direction along each stream.

Computed Variables

These are calculated by the 'stat' part of layers and can be accessed with delayed evaluation.

norm

This variable is calculated as the Euclidean distance derived from the ranges of the x and y values. It serves as a normalization factor for vector lengths when the normalize parameter is active.

avg_spd

Represents the average speed, which is defined as the length of the stream divided by the time it took to traverse that distance.

Examples

n <- 25
s <- seq(0, 1, length.out = n+1)[-(n+1)]
df <- data.frame( "t" = s, "x" = cos(2*pi*s), "y" = sin(2*pi*s) )

ggplot(df) +
  geom_stream(aes(x, y, t = t)) +
  coord_equal()

ggplot(df) +
  geom_stream(aes(x, y, t = t, alpha = t), size = 5) +
  coord_equal()

ggplot(df) +
  geom_path(aes(x, y, alpha = t), size = 5) +
  coord_equal()


stream_1 <- data.frame(
  x = c(0, 3),
  y = c(0, 0),
  t = 0:1
)

stream_2 <- data.frame(
  x = c(1, 1),
  y = c(1, 5),
  t = 0:1
)

stream_3 <- data.frame(
  x = c(2, 5),
  y = c(2, 6),
  t = 0:1
)

streams <- rbind(
  cbind(stream_1, id = 1),
  cbind(stream_2, id = 2),
  cbind(stream_3, id = 3)
)

ggplot(stream_1) +
  geom_stream(aes(x = x, y = y, t = t))

# set group aes if multiple vectors
ggplot(streams) +
  geom_stream(aes(x = x, y = y, t = t, group = id))

ggvfields documentation built on April 3, 2025, 9:04 p.m.