Assigns Colours to Values (original) (raw)

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.

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

For consistency, aim to use British (rather than American) spelling

But don’t worry, [color_values(1:5)](reference/colour%5Fvalues.html) works as well

How do I install it?

From CRAN

Or install the development version from GitHub with:

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

And in a c++ source file so you can #include a header and use the available functions

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

5000 numbers on a non-linear scale

1000 random numbers

Eurgh!

That’s better!

Are there only viridis palettes?

No, you can chose one from

And you can use [show_colours()](reference/show%5Fcolours.html) to view them all. Here’s what some of them look like

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]

Do you support ‘alpha’ values

Yep. Either supply a single alpha value for all the colours

Or use a vector of values the same length as x

Or include the alpha value as a 4th column in the palette matrix

Some of my plotting functions don’t support alpha, can I exclude it?

Yep. Set include_alpha = FALSE

colour_values(1:5, include_alpha = F)
# [1] "#440154" "#3B528B" "#21908C" "#5DC963" "#FDE725"
colour_values_rgb(1:5, include_alpha = F)
#      [,1] [,2] [,3]
# [1,]   68    1   84
# [2,]   59   82  139
# [3,]   33  144  140
# [4,]   93  201   99
# [5,]  253  231   37

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

You can also specify the number of digits you’d like returned in the summary

You can also use format = FALSE if you don’t want the summary values formatted.

For categorical values use summary = TRUE to return a uniqe set of the values, and their associated colours

What’s the performance like?

10 million numeric values

1 million characters (26 unique values)