geom_stream_field {ggvfields} | R Documentation |
Create a Stream Field Layer in ggplot2
Description
geom_stream_field()
creates a ggplot2 layer that integrates a user-defined
vector field function f(x, y) \to (dx, dy)
over a grid of seed points
within a specified domain. The function numerically integrates the field
starting from these seeds, producing streamlines that visualize the flow.
This is useful for visualizing vector fields, flow patterns, or trajectories,
such as in fluid dynamics or gradient fields.
Usage
geom_stream_field(
mapping = NULL,
data = NULL,
stat = StatStreamField,
position = "identity",
...,
na.rm = FALSE,
show.legend = NA,
inherit.aes = FALSE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
args = list(),
max_it = 1000L,
tol = sqrt(.Machine$double.eps),
T = NULL,
L = NULL,
center = TRUE,
type = "stream",
normalize = TRUE,
tail_point = FALSE,
eval_point = FALSE,
grid = NULL,
method = "rk4",
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = grid::arrow(angle = 30, length = unit(0.02, "npc"), type = "closed")
)
stat_stream_field(
mapping = NULL,
data = NULL,
geom = GeomStream,
position = "identity",
...,
na.rm = FALSE,
show.legend = NA,
inherit.aes = TRUE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
args = list(),
max_it = 1000,
tol = sqrt(.Machine$double.eps),
T = NULL,
L = NULL,
center = TRUE,
type = "stream",
normalize = TRUE,
tail_point = FALSE,
eval_point = FALSE,
grid = NULL,
method = "rk4",
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = grid::arrow(angle = 30, length = unit(0.02, "npc"), type = "closed")
)
geom_stream_field2(
mapping = NULL,
data = NULL,
stat = StatStreamField,
position = "identity",
...,
na.rm = FALSE,
show.legend = NA,
inherit.aes = FALSE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
args = list(),
max_it = 1000,
tol = sqrt(.Machine$double.eps),
L = NULL,
center = FALSE,
type = "stream",
tail_point = TRUE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
method = "rk4"
)
stat_stream_field2(
mapping = NULL,
data = NULL,
geom = GeomStream,
position = "identity",
...,
na.rm = FALSE,
show.legend = NA,
inherit.aes = FALSE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
args = list(),
max_it = 1000,
tol = sqrt(.Machine$double.eps),
L = NULL,
center = FALSE,
type = "stream",
tail_point = TRUE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
method = "rk4"
)
Arguments
mapping |
A set of aesthetic mappings created by |
data |
A data frame or other object, as in |
stat |
The statistical transformation to use on the data (default: StatStreamField). |
position |
Position adjustment, either as a string or the result of a position adjustment function. |
... |
Other arguments passed to |
na.rm |
Logical. If |
show.legend |
Logical. Should this layer be included in the legends? |
inherit.aes |
Logical. If |
fun |
A function of two variables, |
xlim |
Numeric vector of length 2 specifying the domain limits in the
|
ylim |
Numeric vector of length 2 specifying the domain limits in the
|
n |
Integer or two-element numeric vector specifying the grid resolution
(number of seed points) along each axis. Defaults to |
args |
A list of additional arguments passed to |
max_it |
|
tol |
|
T |
Numeric. When |
L |
Numeric. Maximum arc length for each streamline. When |
center |
Logical. If |
type |
Character. Either |
normalize |
Logical.
When |
tail_point |
Logical. If |
eval_point |
Logical. If |
grid |
A data frame containing precomputed grid points for seed
placement. If |
method |
Character. Integration method (e.g. |
lineend |
Line end style (round, butt, square). |
linejoin |
Line join style (round, mitre, bevel). |
linemitre |
Line mitre limit (number greater than 1). |
arrow |
A |
geom |
The geometric object used to render the streamlines (defaults to GeomStream). |
Value
A ggplot2 layer that computes and renders streamlines over the specified domain.
Aesthetics
geom_stream_field()
(and its stat variant) inherit
aesthetics from GeomStream and understand the following:
-
x
: x-coordinate of the seed point. -
y
: y-coordinate of the seed point. -
color
: Color, typically used to represent computed statistics (e.g. average speed). -
linetype
: Type of line used to draw the streamlines. -
linewidth
: Thickness of the streamlines. -
alpha
: Transparency of the streamlines.
Details
The streamlines are generated by numerically integrating
the vector field defined by fun(x, y)
. When normalize = TRUE
,
integration stops once the cumulative arc length reaches L
; otherwise,
integration runs until time T
is reached. If both T
and L
are
provided in incompatible combinations, one parameter is ignored. The
computed paths are rendered by GeomStream.
Computed Variables
The following variables are computed internally by StatStreamField during the integration of the vector field:
- avg_spd
For vector fields, this is computed as the total arc length divided by the integration time, providing an estimate of the average speed. It is used to scale the vector lengths when mapping
length = after_stat(norm)
.- t
The integration time at each computed point along a streamline.
- d
The distance between consecutive points along the computed path.
- l
The cumulative arc length along the streamline, calculated as the cumulative sum of
d
.
Examples
f <- function(u) c(-u[2], u[1])
# the basic usage involves providing a fun, xlim, and ylim
ggplot() + geom_stream_field(fun = f, xlim = c(-1,1), ylim = c(-1,1))
# if unspecified, xlim and ylim default to c(-1,1). we use this in what
# follows to focus on other parts of the code
ggplot() + geom_stream_field(fun = f)
ggplot() + geom_stream_field(fun = f, center = FALSE)
ggplot() + geom_stream_field(fun = f, normalize = FALSE)
ggplot() + geom_stream_field(fun = f, normalize = FALSE, center = FALSE)
# run systems until specified lengths
ggplot() + geom_stream_field(fun = f, normalize = TRUE, L = .8)
ggplot() + geom_vector_field(fun = f, normalize = TRUE, L = .3)
ggplot() + geom_vector_field(fun = f, normalize = FALSE, L = 2)
# run systems for specified times
ggplot() + geom_stream_field(fun = f, normalize = FALSE, T = .1)
# tail and eval points
ggplot() + geom_stream_field(fun = f, tail_point = TRUE)
ggplot() + geom_stream_field(fun = f, eval_point = TRUE)
# changing the grid of evaluation
ggplot() + geom_stream_field(fun = f)
ggplot() + geom_stream_field(fun = f, grid = "hex")
ggplot() + geom_stream_field(fun = f, grid = "hex", n = 5)
ggplot() + geom_stream_field(fun = f, n = 5)
ggplot() + geom_stream_field(fun = f, xlim = c(-5, 5)) + coord_equal()
ggplot() + geom_stream_field(fun = f, xlim = c(-5, 5), n = c(21, 11)) + coord_equal()
ggplot() + geom_stream_field(fun = f)
ggplot() + geom_stream_field(fun = f, grid = grid_hex(c(-1,1), c(-1,1), .2))
# using other ggplot2 tools
f <- efield_maker()
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2))
ggplot() +
geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2)) +
scale_color_viridis_c(trans = "log10")
ggplot() +
geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2)) +
scale_color_viridis_c(trans = "log10") +
coord_equal()
# other vector fields
f <- function(u) u
ggplot() + geom_stream_field(fun = f, xlim = c(-1,1), ylim = c(-1,1))
f <- function(u) c(2,1)
ggplot() + geom_stream_field(fun = f, xlim = c(-1,1), ylim = c(-1,1))
# neat examples
f <- function(u) {
x <- u[1]; y <- u[2]
c(y, y*(-x^2 - 2*y^2 + 1) - x)
}
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2))
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2), type = "vector")
f <- function(u) {
x <- u[1]; y <- u[2]
c(y, x - x^3)
}
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2))
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2),
grid = grid_hex(c(-2,2), c(-2,2), .35))
f <- function(u) {
x <- u[1]; y <- u[2]
c(x^2 - y^2, x^2 + y^2 - 2)
}
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2))
ggplot() + geom_stream_field(fun = f, xlim = c(-2,2), ylim = c(-2,2),
grid = grid_hex(c(-2,2), c(-2,2), .35))
ggplot() +
geom_stream_field(fun = f, aes(alpha = after_stat(t)), xlim = c(-2,2), ylim = c(-2,2)) +
scale_alpha(range = c(0,1))
ggplot() +
geom_stream_field(
fun = f, xlim = c(-1,1), ylim = c(-1,1),
linewidth = .75, arrow = arrow(length = unit(0.015, "npc"))
)