Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/SymbolixAU/colourvalues
R library for assigning colours to values
https://github.com/SymbolixAU/colourvalues
colours palettes r rcpp viridis
Last synced: 3 months ago
JSON representation
R library for assigning colours to values
- Host: GitHub
- URL: https://github.com/SymbolixAU/colourvalues
- Owner: SymbolixAU
- Created: 2018-09-03T10:44:56.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-01-02T04:02:07.000Z (10 months ago)
- Last Synced: 2024-05-02T05:01:22.608Z (6 months ago)
- Topics: colours, palettes, r, rcpp, viridis
- Language: C++
- Homepage: https://symbolixau.github.io/colourvalues/
- Size: 4.8 MB
- Stars: 47
- Watchers: 6
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.Rmd
Awesome Lists containing this project
- jimsghstars - SymbolixAU/colourvalues - R library for assigning colours to values (C++)
README
---
output: github_document
---
[](https://github.com/SymbolixAU/colourvalues/actions)
[](https://app.codecov.io/gh/symbolixau/colourvalues?branch=master)
[](https://CRAN.R-project.org/package=colourvalues)
[](https://CRAN.R-project.org/package=colourvalues)
[](https://github.com/SymbolixAU/colourvalues)
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#",
fig.path = "man/figures/README-",
out.width = "100%",
out.height = 200
)
library(colourvalues)
```
# colourvalues
```{r, echo = FALSE}
bar_plot <- function(df) {
barplot( height = df[["a"]], col = df[["col"]], border = NA, space = 0, yaxt = 'n')
}
df <- data.frame(a = 10, x = 1:256)
df$col <- colour_values(df$x, palette = "viridis")
bar_plot( df )
```
---
### What does it do?
It maps viridis colours (by default) to values, and quickly!
**Note** It does not perform a 1-to-1 mapping of a palette to values. It interpolates the colours from a given palette.
### Why did you build it?
I'm aware there are other methods for mapping colours to values. And which do it quick too. But I can never remember them, and I find the interfaces a bit cumbersome. For example, `scales::col_numeric(palette = viridisLite::viridis(5), domain = range(1:5))(1:5)`.
I wanted **one** function which will work on **one** argument.
```{r}
colour_values(1:5)
colour_values(letters[1:5])
```
I also want it available at the `src` (C/C++) level for linking to other packages.
---
### Why do you spell colour with a 'u'?
Because it's correct, and [R tells us to](https://developer.R-project.org/Rds.html)
> For consistency, aim to use British (rather than American) spelling
But don't worry, `color_values(1:5)` works as well
---
### How do I install it?
From CRAN
```{r, eval=FALSE}
install.packages("colourvalues")
```
Or install the development version from [GitHub](https://github.com/SymbolixAU/colourvalues) with:
```r
# install.packages("devtools")
devtools::install_github("SymbolixAU/colourvalues")
```
---
### How can I make use of it in my package?
**Rcpp**
All functions are written in `Rcpp`. I have exposed some of them in header files so you can "link to" them in your package.
For example, the `LinkingTo` section in `DESCRIPTION` will look something like
```yaml
LinkingTo:
Rcpp,
colourvalues
```
And in a **c++** source file so you can `#include` the API header
```cpp
#include "colourvalues/api.hpp"
// [[Rcpp::depends(colourvalues)]]
```
And call
```cpp
// return hex colours
colourvalues::api::colour_values_hex()
// return RGP matrix
colourvalues::api::colour_values_rgb()
```
**R**
If you're not using `Rcpp`, just `Import` this package like you would any other.
## Do you have any examples?
Of course!
#### 256 numbers mapped to a colour
```{r}
bar_plot <- function(df) {
barplot( height = df[["a"]], col = df[["col"]], border = NA, space = 0, yaxt = 'n')
}
df <- data.frame(a = 10, x = 1:256)
df$col <- colour_values(df$x, palette = "viridis")
bar_plot( df )
```
#### 5000 numbers on a non-linear scale
```{r}
df <- data.frame(a = 10, x = c((1:5000)**3))
df$col <- colour_values(df$x, palette = "viridis")
bar_plot( df )
```
#### 1000 random numbers
```{r}
df <- data.frame(a = 10, x = rnorm(n = 1000))
df$col <- colour_values(df$x, palette = "inferno")
bar_plot( df )
```
Eurgh!
```{r}
df <- df[with(df, order(x)), ]
bar_plot( df )
```
That's better!
---
## Are there only viridis palettes?
No, you can chose one from
```{r}
colour_palettes()
```
And you can use `show_colours()` to view them all. Here's what some of them look like
```{r}
show_colours( colours = colour_palettes(c("viridis", "colorspace")))
```
## Do I have to use the in-built palettes?
No, you can use your own specified as a matrix of red, green and blue columns in the range [0,255]
```{r}
n <- 100
m <- grDevices::colorRamp(c("red", "green"))( (1:n)/n )
df <- data.frame(a = 10, x = 1:n)
df$col <- colour_values(df$x, palette = m)
bar_plot( df )
```
## Do you support 'alpha' values
Yep. Either supply a single alpha value for all the colours
```{r}
## single alpha value for all colours
df <- data.frame(a = 10, x = 1:255)
df$col <- colour_values(df$x, alpha = 50)
bar_plot( df )
```
Or use a vector of values the same length as `x`
```{r}
df <- data.frame(a = 10, x = 1:300, y = rep(c(1:50, 50:1), 3) )
df$col <- colour_values(df$x, alpha = df$y)
bar_plot( df )
```
Or include the alpha value as a 4th column in the palette matrix
```{r}
n <- 100
m <- grDevices::colorRamp(c("red", "green"))( (1:n)/n )
## alpha values
m <- cbind(m, seq(0, 255, length.out = 100))
df <- data.frame(a = 10, x = 1:n)
df$col <- colour_values(df$x, palette = m)
bar_plot( df )
```
## Some of my plotting functions don't support alpha, can I exclude it?
Yep. Set `include_alpha = FALSE`
```{r}
colour_values(1:5, include_alpha = F)
colour_values_rgb(1:5, include_alpha = F)
```
## Can I get a summary of colours to use in a legend?
Yes, for numeric values use the `n_summaries` argument to specify the number of summary values you'd like
```{r}
colour_values(1:10, n_summaries = 3)
```
You can also specify the number of digits you'd like returned in the summary
```{r}
colour_values(rnorm(n = 10), n_summaries = 3, digits = 2)
```
You can also use `format = FALSE` if you don't want the summary values formatted.
```{r}
dte <- seq(as.Date("2018-01-01"), as.Date("2018-02-01"), by = 1)
colour_values(dte, n_summaries = 3)
colour_values(dte, n_summaries = 3, format = F)
```
For categorical values use `summary = TRUE` to return a uniqe set of the values, and their associated colours
```{r}
colour_values(sample(letters, size = 50, replace = T), summary = T)
```
### I see you support lists, but how does it work?
Basically, it's the same as un-listing the list to create a vector of all the values, then colouring them.
So if your list contains different types, it will coerce all values to the same type and colour them.
But it returns a list of the same structure.
For example,
```{r}
l <- list( x = 1:5, y = list(z = letters[1:5] ) )
colour_values( l )
x <- c( 1:5, letters[1:5] )
colour_values( x )
```
What it doesn't do is treat each list element independently. For this you would use
```{r}
lapply( l, colour_values )
```
---
### What's the performance like?
**10 million numeric values**
```{r, out.height=400}
library(microbenchmark)
library(scales)
library(viridisLite)
n <- 1e7
df <- data.frame(x = rnorm(n = n))
m <- microbenchmark(
colourvalues = { colourvalues::colour_values(x = df$x) },
scales = { col_numeric(palette = rgb(subset(viridis.map, opt=="D")[, 1:3]), domain = range(df$x))(df$x) },
times = 25
)
m
```
**1 million characters (26 unique values)**
```{r, out.height=400}
library(microbenchmark)
library(scales)
library(viridisLite)
n <- 1e6
x <- sample(x = letters, size = n, replace = TRUE)
df <- data.frame(x = x)
m <- microbenchmark(
colourvalues = { x <- colourvalues::colour_values(x = df$x) },
scales = { y <- col_factor(palette = rgb(subset(viridis.map, opt=="D")[, 1:3]), domain = unique(df$x))(df$x) },
times = 25
)
m
```