https://github.com/yjunechoe/ggcolormeter
A ggplot2 color/fill legend guide extension in the style of a dashboard meter
https://github.com/yjunechoe/ggcolormeter
ggplot2 package
Last synced: 7 months ago
JSON representation
A ggplot2 color/fill legend guide extension in the style of a dashboard meter
- Host: GitHub
- URL: https://github.com/yjunechoe/ggcolormeter
- Owner: yjunechoe
- License: other
- Created: 2022-06-13T08:46:02.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-23T14:00:14.000Z (almost 2 years ago)
- Last Synced: 2024-07-17T09:55:47.927Z (over 1 year ago)
- Topics: ggplot2, package
- Language: R
- Homepage: https://yjunechoe.github.io/ggcolormeter/
- Size: 5.13 MB
- Stars: 18
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
- awesome-ggplot2 - ggcolormeter
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
dev.args = list(png = list(type = "cairo")),
fig.retina = 2
)
```
# ggcolormeter
[)`-gogreen.svg)](https://github.com/yjunechoe/ggcolormeter)
[](https://github.com/yjunechoe/ggcolormeter/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/yjunechoe/ggcolormeter?branch=main)
The `{ggcolormeter}` package provides a single function [`guide_colormeter()`](https://yjunechoe.github.io/ggcolormeter/reference/guide_colormeter.html), which is a `{ggplot2}` color/fill legend **guide extension** in the style of a dashboard meter.
## Installation
```{r, eval=FALSE}
install.packages("ggcolormeter")
# or
remotes::install_github("yjunechoe/ggcolormeter")
```
## Simple usage
```{r simple-usage}
library(ggplot2)
library(ggcolormeter)
theme_set(theme_classic())
p <- ggplot(mtcars, aes(drat, hp)) +
geom_point(aes(color = mpg))
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter()
)
```
# Colormeter guide theme components
The colormeter guide has argument families for styling 5 distinct components of the guide:
1) [Size and aspect](https://github.com/yjunechoe/ggcolormeter#1-size-and-aspect)
2) [Arc](https://github.com/yjunechoe/ggcolormeter#2-arc)
3) [Label](https://github.com/yjunechoe/ggcolormeter#3-label)
4) [Dashboard](https://github.com/yjunechoe/ggcolormeter#4-dashboard)
5) [Frame](https://github.com/yjunechoe/ggcolormeter#5-frame)
Position of these theme elements is relative to the [guide-internal coordinate system](https://yjunechoe.github.io/ggcolormeter/reference/legend-coords.html), which you can inspect with the `debug = TRUE` argument.
## 1) Size and aspect
The colormeter legend is a bit pecular in that its size doesn't expand with more keys: the colormeter has a fixed size and shape, and its elements are packed inside it.
You can primarily control the size of the legend with `legend_size` and `aspect.ratio`
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
legend_size = unit(3, "cm"),
aspect.ratio = .8
)
)
```
Note that the usual legend background is still present and different from the dashboard circle:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
legend_size = unit(3, "cm"),
aspect.ratio = .8
)
) +
theme(legend.background = element_rect(color = "red", fill = "pink"))
```
Most of the time you'd want to remove this legend background, as the dashboard serves that purpose:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
)
) +
theme(
legend.position = c(.85, .75),
legend.background = element_blank()
)
```
## 2) Arc
```{r}
formals(guide_colormeter)[grepl("arc", names(formals(guide_colormeter)))]
```
Non-positional aesthetic arguments for the color arc:
```{r arc-theme}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
arc_width = 1/6, # thinner arcs
arc_gap = 1/3, # bigger gaps
arc_rounding = 0.03 # rounded corners
)
)
```
By default, label and dashboard radii are derived from `arc_radius`:
```{r arc-radius}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
arc_radius = 1.2
)
)
```
You can use `arc_range` to set the start and end angles of the color meter, which may yield different shapes:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(5), # half the arcs
guide = guide_colormeter(
arc_range = c(-pi/2, 0) # quarter circle
)
)
```
The defaults aren't great for when you change from the dashboard shape. Some manual adjustments may be desirable:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(5),
guide = guide_colormeter(
arc_range = c(-pi/2, 0),
title_position = c(-.2, .2), # moves title left and up from center
legend_padding = grid::unit(0.7, "lines") # pads relative to legend label
)
)
```
## 3) Label
```{r}
formals(guide_colormeter)[grepl("label", names(formals(guide_colormeter)))]
```
By default, the dashboard radius is derived from `label_radius`:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
label_radius = 1.5
)
)
```
Like `ggplot2::guide_colorsteps()`, the argument `show.limits` controls labeling the limits of the scale:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
label_radius = 1.3,
show.limits = TRUE
)
)
```
## 4) Dashboard
```{r}
formals(guide_colormeter)[grepl("dashboard", names(formals(guide_colormeter)))]
```
`dashboard_radius` controls the radius of just the dashboard circle
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
dashboard_radius = 1.2,
)
)
```
By default, the dashboard is clipped to the legend boundary, which can be turned off:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
title = "mpg
miles per gallon",
clip_dashboard = FALSE
)
) +
theme(legend.title = ggtext::element_markdown(vjust = -.6))
```
Non-positional aesthetic arguments for the dashboard:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
dashboard_fill = "skyblue",
dashboard_color = "steelblue",
dashboard_linetype = 5,
dashboard_linewidth = 4
)
)
```
## 5) Frame
```{r}
formals(guide_colormeter)[grepl("frame", names(formals(guide_colormeter)))]
```
Frames simply decorate the color arcs/bars:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(
frame_color = "black",
frame_linewidth = .3
)
)
```
## Miscellaneous
Set `debug = TRUE` to inspect the internal legend coordinate system (for deciding on `dashboard_radius`, `arc_width`, `title_position`, etc.):
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(10),
guide = guide_colormeter(debug = TRUE)
)
```
Puttings labels inside the arc:
```{r}
p +
scale_color_viridis_c(
option = "inferno",
breaks = scales::breaks_pretty(5),
guide = guide_colormeter(
arc_width = 0.1,
label_radius = .7,
aspect.ratio = 1.1,
dashboard_color = NA
)
) +
theme(legend.position = c(.85, .75))
```
## Acknowledgments
- Thomas Lin Pedersen for [`{ggforce}`](https://github.com/thomasp85/ggforce), whose several unexported functions are used in this package.