README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{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

<!-- badges: start -->
[![](https://img.shields.io/badge/devel%20version-`r as.character(packageVersion('ggcolormeter'))`-gogreen.svg)](https://github.com/yjunechoe/ggcolormeter)
[![R-CMD-check](https://github.com/yjunechoe/ggcolormeter/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/yjunechoe/ggcolormeter/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/yjunechoe/ggcolormeter/branch/main/graph/badge.svg)](https://app.codecov.io/gh/yjunechoe/ggcolormeter?branch=main)
<!-- badges: end -->

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<br><br>
        <span style='color:darkgrey;font-size:12px'>miles per gallon</span>",
      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.