Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://teunbrand.github.io/ggarrow/
ggplot2 extension: more options for drawing arrows
https://teunbrand.github.io/ggarrow/
ggplot-extension ggplot2 ggplot2-geom rstats
Last synced: 3 days ago
JSON representation
ggplot2 extension: more options for drawing arrows
- Host: GitHub
- URL: https://teunbrand.github.io/ggarrow/
- Owner: teunbrand
- License: other
- Created: 2022-10-19T15:34:44.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-05T20:41:04.000Z (5 months ago)
- Last Synced: 2024-07-13T11:22:49.943Z (4 months ago)
- Topics: ggplot-extension, ggplot2, ggplot2-geom, rstats
- Language: R
- Homepage: https://teunbrand.github.io/ggarrow/
- Size: 15.3 MB
- Stars: 50
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
fig.align = "center",
out.width = "80%",
dev = "ragg_png",
dpi = 132
)
```
# ggarrow 
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://github.com/teunbrand/ggarrow/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/teunbrand/ggarrow?branch=main)
[](https://CRAN.R-project.org/package=ggarrow)
The goal of ggarrow is to draw arrows in [{ggplot2}](https://ggplot2.tidyverse.org/). It is a [{ggplot2} extension](https://exts.ggplot2.tidyverse.org/gallery/) package that focusses on specialised geometry layers to expand the toolkit of arrows.
## Installation
You can install ggarrow from CRAN
``` r
install.packages("ggarrow")
```
You can install the development version of ggarrow from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("teunbrand/ggarrow")
```
## Arrows
They're made for pointing at things. The workhorse functionality is in the `geom_arrow()` function that, unsurprisingly, draws arrows.
### Basic arrows
```{r basic_example}
library(ggarrow)
p <- ggplot(whirlpool(5), aes(x, y, colour = group)) +
coord_equal() +
guides(colour = "none")
p + geom_arrow()
```
### Variable width
Arrows, in contrast to vanilla lines, can have variable widths.
```{r variable_width}
p + geom_arrow(aes(linewidth = I(arc))) # Identity scale for linewidth
```
### Inner arrows
Besides varying linewidths, there is also an option to place arrows along the path.
You could draw arbitrarily many of these, but I doubt that will look pretty.
```{r middle_arrows}
p + geom_arrow(arrow_mid = "head_wings", mid_place = c(0.25, 0.5, 0.75))
```
### Ornament styles
You can also tweak what the arrows should look like.
The example below is a bit verbose, but gives an impression of the available options by combining different styles of arrow heads and what are termed 'arrow fins'.
```{r, show_ornaments}
p + geom_arrow(aes(arrow_head = group, arrow_fins = group), linewidth = 2) +
scale_arrow_head_discrete(values = list(
"head_wings",
arrow_head_wings(offset = 20, inset = 70),
arrow_head_line(lineend = "parallel"),
arrow_head_line(45, lineend = "round"),
"head_minimal"
), guide = "none") +
scale_arrow_fins_discrete(values = list(
"fins_feather",
arrow_fins_feather(indent = 0, outdent = 0, height = 1),
"fins_line",
arrow_fins_line(90),
"fins_minimal"
), guide = "none")
```
There are some other geoms that mimic bread-and-butter ggplot2 layers, such as `geom_arrow_segment()` and `geom_arrow_curve()`, that add the same arrow functionality on top of the `geom_segment()` and `geom_curve()` layers.
### Chains
Aside from these, there is also `geom_arrow_chain()`, which has no equivalent in vanilla ggplot2. It adds arrows in between points, and dodges the endpoints a bit so that they don't seem to touch. In the example below, we can see that we can dodge points of different sizes.
```{r arrow_chain}
t <- seq(0, 2 * pi, length.out = 11)
l <- rep(c(1, 0.4), length.out = 11)
df <- data.frame(
x = cos(t) * l,
y = sin(t) * l,
size = l
)
ggplot(df, aes(x, y, size = size)) +
geom_point(colour = 2) +
geom_arrow_chain() +
coord_equal()
```
### Theme elements
Because arrows are almost drop-in replacements for lines, I also included `element_arrow()` as a theme element. With function, you can set any line element in the theme to an arrow, with similar customisation options as the layers.
```{r theme_elements}
p + geom_arrow() +
theme(
axis.line.x = element_arrow(
arrow_head = "head_wings", linewidth_head = 1.5, linewidth_fins = 0
),
axis.line.y = element_arrow(arrow_head = "head_line"),
axis.ticks.length = unit(0.4, "cm"),
axis.ticks.x = element_arrow(linewidth_fins = 0, linewidth_head = 2),
axis.ticks.y = element_arrow(arrow_fins = "head_line"),
panel.grid.major = element_arrow(
linewidth_head = 5, linewidth_fins = 0,
resect_head = 5, resect_fins = 5, lineend = "round"
),
panel.grid.minor = element_arrow(
linewidth_head = 0, linewidth_fins = 5
)
)
```
## Limitations
The current limitation is that variable width paths don't lend themselves well to jagged paths with short segments. This is because I had to implement linejoins for variable width paths and I barely have high-school level understanding of trigonometry. Consequently, the linejoins look bad with short jagged segments.
```{r jagged}
ggplot(economics, aes(date, unemploy)) +
geom_arrow(aes(linewidth = date))
```
The best advice I can give for the jagged linejoins is to smooth the data beforehand.
```{r smoothed}
ggplot(economics, aes(date, unemploy)) +
geom_arrow(
stat = "smooth", formula = y ~ x, method = "loess", span = 0.05,
aes(linewidth = after_stat(x))
)
```
A second limitation is that you cannot use variable widths with different linetypes.
## Dependency statement
The {ggarrow} package largely takes on the same dependencies as {ggplot2} to keep it on the lightweight side. However, this package wouldn't work at all without the {polyclip} dependency, which is the only one outside {ggplot2}'s imports.
## Related work
Of course, the {grid} package, on which {ggplot2} is build upon, offers some options for arrows.
The [{arrowheadr}](https://github.com/wjschne/arrowheadr) package provides some great extensions for arrowheads.
The [{vwlines}](https://cran.r-project.org/package=vwline) package that handles variable widths lines much more graciously than this package.
Both the [{gggenes}](https://wilkox.org/gggenes/) and [{gggenomes}](https://thackl.github.io/gggenomes/) packages use arrows in a domain-specific context.
For vector field visualisation, there is the [{ggquiver}](http://pkg.mitchelloharawild.com/ggquiver/) package.
The [{ggarchery}](https://github.com/mdhall272/ggarchery) package also provides extended options for the `geom_segment()` parametrisation of lines.