README.Rmd

---
output: github_document
---

[![R build status](https://github.com/SymbolixAU/colourvalues/workflows/R-CMD-check/badge.svg)](https://github.com/SymbolixAU/colourvalues/actions)
[![Codecov test coverage](https://codecov.io/gh/symbolixau/colourvalues/branch/master/graph/badge.svg)](https://app.codecov.io/gh/symbolixau/colourvalues?branch=master)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/colourvalues)](https://CRAN.R-project.org/package=colourvalues)
![downloads](http://cranlogs.r-pkg.org/badges/grand-total/colourvalues)
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/colourvalues)](https://CRAN.R-project.org/package=colourvalues)
[![Github Stars](https://img.shields.io/github/stars/SymbolixAU/colourvalues.svg?style=social&label=Github)](https://github.com/SymbolixAU/colourvalues)

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

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

```