There are a few ways in which one can tweak the display of arrow ornaments in ggarrow. This vignette goes through a few methods for making new arrow ornaments, from basic xy-coordinates to function factories and using the ornaments in scales.
New ornaments
In principle, extending ornaments is as straightforward as being able
to construct a polygon in an xy-coordinate matrix with x as
the first column and y as the second column.
my_ornament <- function(n = 5) {
t <- seq(0, 2 * pi, length.out = n * 2 + 1)[-(n * 2 + 1)]
l <- rep(c(1, 0.4), length.out = length(t))
cbind(
x = cos(t) * l,
y = sin(t) * l
)
}We can inspect the coordinates of our new ornament. It is ggarrow’s convention that the line joins the ornament at the (0,0) coordinate. Also, the tip of the ornament is expected to be at the (1,0) coordinate.
orn <- my_ornament(5)
plot_ornament(orn)
You can now use your ornament as the arrow_head,
arrow_fins and arrow_mid arguments. It just
listens to the usual arguments like length_{head/fins/mid},
resect_{head/fins} and mid_place and scales
with the line width (if the length is not an absolute unit).
ggplot(data = data.frame(x = c(0, 1)), aes(x = x)) +
geom_arrow(aes(y = c(1, 3)), arrow_head = orn, resect = unit(2, "cm")) +
geom_arrow(aes(y = c(2, 2)), arrow_fins = orn, length_fins = unit(1, "cm")) +
geom_arrow(aes(y = c(3, 1)), arrow_mid = orn, mid_place = c(0.33, 0.66),
linewidth = 2)
Ornament factories
Sometimes, you might want to know more about the context in which you’re drawing the ornament than can’t be known before plotting. For example, let’s say we wanted to add half the star we made above an arrowhead. When doing this it is immediately clear that the connection with the line looks awful.
half_star <- orn[orn[, "y"] >= 0, ]
ggplot(data.frame(x = c(0, 1), y = c(1, 1)), aes(x, y)) +
geom_arrow(arrow_head = half_star, linewidth = 3)
If we know the linewidth in advance, you might nudge it manually.
Because the default length_head is 4 and the we set the
linewidth is 3, the arrowhead will get a size of 3 * 4 = 12 mm.
magic_number <- 0.7528125
half_star[, "y"] <- half_star[, "y"] - (1.5/12) * magic_number
ggplot(data.frame(x = c(0, 1), y = c(1, 1)), aes(x, y)) +
geom_arrow(arrow_head = half_star, linewidth = 3)
The way to solve this, is to use a function factory. This method is much more involved, so be forewarned. First, if we just write a function that does as we did before, you might notice a tiny star at the end of the line as a few pixels.
half_star <- function(n = 5) {
ornament <- my_ornament(n)
function(...) {
half <- ornament[ornament[, "y"] >= 0, ]
half
}
}
ggplot(data.frame(x = c(0, 1), y = c(1, 1)), aes(x, y)) +
geom_arrow(arrow_head = half_star(5), linewidth = 3)
That is because the output of the function factory gets interpreted
as millimetres. To be responsive to what length_head is
being passed around, you should multiply your output with the length.
length is one of the parameters that the function produced
by the factory can receive. Doing this gives more reasonable output, but
we can now see that the half-star extends beyond the path’s end.
half_star <- function(n = 5) {
ornament <- my_ornament(n)
function(length, ...) {
half <- ornament[ornament[, "y"] >= 0, ]
half * length
}
}
ggplot(data.frame(x = c(0, 1), y = c(1, 1)), aes(x, y)) +
geom_arrow(arrow_head = half_star(5), linewidth = 3)
To control how much the line should be cut back, you can set the ‘resect’ attribute on your output. For this shape, we should probably resect the line by exactly the length parameter we get. Now the alignment looks as it should.
half_star <- function(n = 5) {
ornament <- my_ornament(n)
function(length, ...) {
half <- ornament[ornament[, "y"] >= 0, ]
half <- half * length
attr(half, "resect") <- length
half
}
}
ggplot(data.frame(x = c(0, 1), y = c(1, 1)), aes(x, y)) +
geom_arrow(arrow_head = half_star(5), linewidth = 3)
Lastly, to fix the actual problem we were trying to solve, we can
nudge the y-coordinates by half the linewidth. width is a
parameter the produced function can receive that represents the line
width. Now, it looks like it should.
half_star <- function(n = 5) {
ornament <- my_ornament(n)
function(length, width, ...) {
half <- ornament[ornament[, "y"] >= 0, ]
half <- half * length
half[, "y"] <- half[, "y"] - 0.5 * width
attr(half, "resect") <- length
half
}
}
df <- expand.grid(x = c(0, 1), width = 1:4)
ggplot(df, aes(x, width, linewidth = I(width), group = width)) +
geom_arrow(arrow_head = half_star(5)) +
ylim(0, 5)
Besides width and length, the inner
function can also receive resect. Because functionality
might be expanded in the future, the last argument to the inner function
should be ....
Scales
The discrete scales in ggarrow can take a mixed list of things that may define an arrow. That way, you can just put your own ornaments in a list to have it become part of the scale.
p <- ggplot(whirlpool(5), aes(x, y, group = group)) +
coord_equal()
p + geom_arrow(aes(arrow_head = group), resect = 5) +
scale_arrow_head_discrete(
values = list("head_wings", orn, "fins_feather", orn, "cup"),
)
If you start your function name with the arrow_-prefix,
the ornament can be automatically found if available in the global
environment.
arrow_star <- function(n = 5) {
my_ornament(round(n))
}
p + geom_arrow(aes(arrow_head = group), resect = 1) +
scale_arrow_head_discrete(
values = c("head_wings", "star", "fins_feather", "star", "cup"),
)
While not always very easy to figure out, as different arrowheads are
discrete, one can in theory also apply a continuous scale to
arrows. Please note that I sneaked in a round() in the
function above, this is so that we can demonstrate a continuous scale
with the star.
If we have something about our arrowhead that may vary in number,
like an angle, or some size or in this example, the number of points on
a star (though not truly continuous), we can use
scale_arrow_head_continuous() to map our variable to the
arrowhead. We should give the function we created as the
generator argument. The variable part of our function
argument should be provided as map_arg, and the range of
values it can take on should be provided as range.
p + geom_arrow(aes(arrow_head = as.integer(group)), resect = 5) +
scale_arrow_head_continuous(
generator = arrow_star, map_arg = "n",
range = c(3, 7)
)