geom_gradient_field {ggvfields} | R Documentation |
Create a Gradient Field Layer in ggplot2
Description
These functions provide convenient ggplot2 layers for drawing gradient fields
by computing the gradient of a scalar field. A user-defined function (fun
)
specifies the behavior of the scalar field by taking a numeric vector of
length 2 (representing (x, y)
) and returning a single numeric value.
The underlying StatStreamField computes the gradient via numerical
differentiation (using numDeriv::grad()
) and GeomStream renders the
resulting vectors.
Usage
geom_gradient_field(
mapping = NULL,
data = NULL,
stat = StatStreamField,
position = "identity",
...,
na.rm = FALSE,
show.legend = TRUE,
inherit.aes = TRUE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
max_it = 1000,
T = NULL,
L = NULL,
center = TRUE,
type = "vector",
normalize = TRUE,
tail_point = FALSE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = grid::arrow(angle = 30, length = grid::unit(0.02, "npc"), type = "closed")
)
stat_gradient_field(
mapping = NULL,
data = NULL,
geom = GeomStream,
position = "identity",
...,
na.rm = FALSE,
show.legend = TRUE,
inherit.aes = TRUE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
max_it = 1000,
T = NULL,
L = NULL,
center = TRUE,
type = "vector",
normalize = TRUE,
tail_point = FALSE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = grid::arrow(angle = 30, length = grid::unit(0.02, "npc"), type = "closed")
)
geom_gradient_field2(
mapping = NULL,
data = NULL,
stat = StatStreamField,
position = "identity",
...,
na.rm = FALSE,
show.legend = TRUE,
inherit.aes = TRUE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
max_it = 1000,
T = NULL,
L = NULL,
center = FALSE,
type = "stream",
normalize = TRUE,
tail_point = TRUE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = NULL
)
stat_gradient_field2(
mapping = NULL,
data = NULL,
geom = GeomStream,
position = "identity",
...,
na.rm = FALSE,
show.legend = TRUE,
inherit.aes = TRUE,
fun,
xlim = NULL,
ylim = NULL,
n = 11,
max_it = 1000,
T = NULL,
L = NULL,
center = FALSE,
type = "stream",
normalize = TRUE,
tail_point = TRUE,
eval_point = FALSE,
grid = NULL,
lineend = "butt",
linejoin = "round",
linemitre = 10,
arrow = NULL
)
Arguments
mapping |
A set of aesthetic mappings created by |
data |
A data frame containing the input data. |
stat |
The statistical transformation to use on the data for this layer. Defaults to StatStreamField. |
position |
Position adjustment, either as a string or the result of a position adjustment function. |
... |
Other arguments passed on to |
na.rm |
Logical. If |
show.legend |
Logical. Should this layer be included in the legends? |
inherit.aes |
Logical. If |
fun |
A function that defines the scalar field. It should take a numeric
vector of length 2 (representing |
xlim |
Numeric vector of length two. Specifies the limits of the x-axis
domain. Defaults to |
ylim |
Numeric vector of length two. Specifies the limits of the y-axis
domain. Defaults to |
n |
Integer. Grid resolution specifying the number of seed points along
each axis. Higher values produce a denser gradient field. Defaults to |
max_it |
Integer. Maximum number of integration steps allowed when
computing the gradient stream. Defaults to |
T |
Numeric. Time increment used for numerical integration when
|
L |
Numeric. Target length for the gradient vectors or streamlines. When
|
center |
Logical. If |
type |
Character. Specifies the type of field to compute: use |
normalize |
Logical. If |
tail_point |
Logical. If |
eval_point |
Logical. If |
grid |
A data frame containing precomputed grid points for seed
placement. If |
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 streamline (only used in
|
Details
Two variants are provided:
-
geom_gradient_field() uses a default mapping that sets
color = after_stat(norm)
. -
geom_gradient_field2() uses a default mapping that sets
length = after_stat(norm)
(withcolor
unmapped by default).
Value
A ggplot2 layer that computes and plots a gradient field by numerically differentiating a scalar field.
Aesthetics
geom_gradient_field()
and geom_gradient_field2()
understand the following aesthetics (required aesthetics are in bold):
-
x
: The x-coordinate of the seed point. -
y
: The y-coordinate of the seed point. -
color
: In geom_gradient_field, the color of the gradient vector. In geom_gradient_field2, color is not mapped by default. -
length
: In geom_gradient_field2, the computed vector norm. -
size
,linetype
,alpha
: Additional aesthetics to control appearance.
Computed Variables
The following variables are computed internally by StatStreamField when generating the gradient field from a scalar function:
- norm
The Euclidean norm of the gradient vector, calculated as
\sqrt{fx^2 + fy^2}
. This value is used, by default, for mapping color or scaling arrow lengths in the visualization.- avg_spd
This variable may represent an average speed computed from the gradient magnitude. In the default mapping for geom_gradient_field, the color aesthetic is mapped to
after_stat(avg_spd)
.
Examples
Si <- matrix(c(1, 0.75, 0.75, 1), nrow = 2)
f <- function(u) exp(-as.numeric(u %*% solve(Si) %*% u) / 2) / (2 * pi * det(Si))
ggplot() +
geom_gradient_field(fun = f, xlim = c(-3, 3), ylim = c(-3, 3))
df <- expand.grid(x = seq(-3, 3, 0.1), y = seq(-3, 3, 0.1)) |>
transform(fxy = apply(cbind(x, y), 1, f))
ggplot() +
geom_raster(aes(x, y, fill = fxy), data = df) +
geom_gradient_field(fun = f, xlim = c(-3, 3), ylim = c(-3, 3)) +
coord_equal()
fxy <- function(x, y) apply(cbind(x,y), 1, f)
ggplot() +
ggdensity::geom_hdr_fun(fun = fxy, xlim = c(-3,3), ylim = c(-3,3)) +
geom_gradient_field(fun = f, xlim = c(-3,3), ylim = c(-3,3)) +
coord_equal()
library("ggdensity")
fxy <- function(x, y) apply(cbind(x, y), 1, f)
fxy(1, 2)
f(1:2)
ggplot() +
geom_hdr_fun(fun = fxy, xlim = c(-3, 3), ylim = c(-3, 3)) +
geom_gradient_field(fun = f, xlim = c(-3, 3), ylim = c(-3, 3)) +
coord_equal()