{"id":13706664,"url":"https://github.com/SymbolixAU/colourvalues","last_synced_at":"2025-05-05T23:31:26.269Z","repository":{"id":56935412,"uuid":"147190723","full_name":"SymbolixAU/colourvalues","owner":"SymbolixAU","description":"R library for assigning colours to values","archived":false,"fork":false,"pushed_at":"2025-04-19T01:31:17.000Z","size":5044,"stargazers_count":45,"open_issues_count":4,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-19T10:49:28.955Z","etag":null,"topics":["colours","palettes","r","rcpp","viridis"],"latest_commit_sha":null,"homepage":"https://symbolixau.github.io/colourvalues/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SymbolixAU.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-03T10:44:56.000Z","updated_at":"2025-04-19T01:31:20.000Z","dependencies_parsed_at":"2024-01-02T05:19:48.910Z","dependency_job_id":"9db016b3-e069-4ed3-bae6-6d239f024c32","html_url":"https://github.com/SymbolixAU/colourvalues","commit_stats":{"total_commits":268,"total_committers":7,"mean_commits":"38.285714285714285","dds":0.2649253731343284,"last_synced_commit":"dfc75685389ebcfcbac15dccbbd0c024c2854117"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SymbolixAU%2Fcolourvalues","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SymbolixAU%2Fcolourvalues/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SymbolixAU%2Fcolourvalues/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SymbolixAU%2Fcolourvalues/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SymbolixAU","download_url":"https://codeload.github.com/SymbolixAU/colourvalues/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252593046,"owners_count":21773397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["colours","palettes","r","rcpp","viridis"],"created_at":"2024-08-02T22:01:04.393Z","updated_at":"2025-05-05T23:31:24.032Z","avatar_url":"https://github.com/SymbolixAU.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n[![R build status](https://github.com/SymbolixAU/colourvalues/workflows/R-CMD-check/badge.svg)](https://github.com/SymbolixAU/colourvalues/actions)\n[![Codecov test coverage](https://codecov.io/gh/symbolixau/colourvalues/branch/master/graph/badge.svg)](https://app.codecov.io/gh/symbolixau/colourvalues?branch=master)\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/colourvalues)](https://CRAN.R-project.org/package=colourvalues)\n![downloads](http://cranlogs.r-pkg.org/badges/grand-total/colourvalues)\n[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/colourvalues)](https://CRAN.R-project.org/package=colourvalues)\n[![Github Stars](https://img.shields.io/github/stars/SymbolixAU/colourvalues.svg?style=social\u0026label=Github)](https://github.com/SymbolixAU/colourvalues)\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\",\n  out.height = 200\n)\n\nlibrary(colourvalues)\n```\n\n# colourvalues\n\n```{r, echo = FALSE}\nbar_plot \u003c- function(df) {\n  barplot( height = df[[\"a\"]], col = df[[\"col\"]], border = NA, space = 0, yaxt = 'n')\n}\ndf \u003c- data.frame(a = 10, x = 1:256)\ndf$col \u003c- colour_values(df$x, palette = \"viridis\")\nbar_plot( df )\n```\n\n---\n\n### What does it do?\n\nIt maps viridis colours (by default) to values, and quickly!\n\n**Note** It does not perform a 1-to-1 mapping of a palette to values. It interpolates the colours from a given palette.\n\n### Why did you build it?\n\nI'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)`.\n\nI wanted **one** function which will work on **one** argument. \n\n```{r}\ncolour_values(1:5)\ncolour_values(letters[1:5])\n```\n\nI also want it available at the `src` (C/C++) level for linking to other packages. \n\n---\n\n### Why do you spell colour with a 'u'?\n\nBecause it's correct, and [R tells us to](https://developer.R-project.org/Rds.html)\n\n\u003e For consistency, aim to use British (rather than American) spelling\n\nBut don't worry, `color_values(1:5)` works as well\n\n---\n\n### How do I install it?\n\nFrom CRAN\n\n```{r, eval=FALSE}\ninstall.packages(\"colourvalues\")\n```\n\nOr install the development version from [GitHub](https://github.com/SymbolixAU/colourvalues) with:\n\n```r\n# install.packages(\"devtools\")\ndevtools::install_github(\"SymbolixAU/colourvalues\")\n```\n\n---\n\n### How can I make use of it in my package?\n\n**Rcpp**\n\nAll functions are written in `Rcpp`. I have exposed some of them in header files so you can \"link to\" them in your package.\n\nFor example, the `LinkingTo` section in `DESCRIPTION` will look something like\n\n```yaml\nLinkingTo: \n    Rcpp,\n    colourvalues\n```\n\nAnd in a **c++** source file so you can `#include` the API header\n\n```cpp\n#include \"colourvalues/api.hpp\"\n// [[Rcpp::depends(colourvalues)]]\n```\n\nAnd call \n\n```cpp\n// return hex colours\ncolourvalues::api::colour_values_hex()\n\n// return RGP matrix\ncolourvalues::api::colour_values_rgb()\n```\n\n**R**\n\nIf you're not using `Rcpp`, just `Import` this package like you would any other.\n\n## Do you have any examples?\n\nOf course!\n\n\n#### 256 numbers mapped to a colour\n\n```{r}\nbar_plot \u003c- function(df) {\n  barplot( height = df[[\"a\"]], col = df[[\"col\"]], border = NA, space = 0, yaxt = 'n')\n}\ndf \u003c- data.frame(a = 10, x = 1:256)\ndf$col \u003c- colour_values(df$x, palette = \"viridis\")\nbar_plot( df )\n```\n\n#### 5000 numbers on a non-linear scale\n\n```{r}\ndf \u003c- data.frame(a = 10, x = c((1:5000)**3))\ndf$col \u003c- colour_values(df$x, palette = \"viridis\")\nbar_plot( df )\n```\n\n#### 1000 random numbers\n\n```{r}\ndf \u003c- data.frame(a = 10, x = rnorm(n = 1000))\ndf$col \u003c- colour_values(df$x, palette = \"inferno\")\nbar_plot( df )\n```\n\nEurgh!\n\n```{r}\ndf \u003c- df[with(df, order(x)), ]\nbar_plot( df )\n```\n\nThat's better!\n\n\n---\n\n## Are there only viridis palettes?\n\nNo, you can chose one from \n\n```{r}\ncolour_palettes()\n```\n\nAnd you can use `show_colours()` to view them all. Here's what some of them look like\n\n```{r}\nshow_colours( colours = colour_palettes(c(\"viridis\", \"colorspace\")))\n```\n\n\n## Do I have to use the in-built palettes?\n\nNo, you can use your own specified as a matrix of red, green and blue columns in the range [0,255]\n\n```{r}\nn \u003c- 100\nm \u003c- grDevices::colorRamp(c(\"red\", \"green\"))( (1:n)/n )\ndf \u003c- data.frame(a = 10, x = 1:n)\ndf$col \u003c- colour_values(df$x, palette = m)\nbar_plot( df )\n```\n\n\n## Do you support 'alpha' values\n\nYep. Either supply a single alpha value for all the colours\n\n```{r}\n## single alpha value for all colours\ndf \u003c- data.frame(a = 10, x = 1:255)\ndf$col \u003c- colour_values(df$x, alpha = 50)\nbar_plot( df )\n```\n\nOr use a vector of values the same length as `x`\n\n```{r}\ndf \u003c- data.frame(a = 10, x = 1:300, y = rep(c(1:50, 50:1), 3) )\ndf$col \u003c- colour_values(df$x, alpha = df$y)\nbar_plot( df )\n```\n\n\nOr include the alpha value as a 4th column in the palette matrix\n\n```{r}\nn \u003c- 100\nm \u003c- grDevices::colorRamp(c(\"red\", \"green\"))( (1:n)/n )\n## alpha values\nm \u003c- cbind(m, seq(0, 255, length.out = 100))\ndf \u003c- data.frame(a = 10, x = 1:n)\ndf$col \u003c- colour_values(df$x, palette = m)\nbar_plot( df )\n```\n\n## Some of my plotting functions don't support alpha, can I exclude it?\n\nYep. Set `include_alpha = FALSE`\n\n```{r}\ncolour_values(1:5, include_alpha = F)\ncolour_values_rgb(1:5, include_alpha = F)\n```\n\n## Can I get a summary of colours to use in a legend?\n\nYes, for numeric values use the `n_summaries` argument to specify the number of summary values you'd like\n\n```{r}\ncolour_values(1:10, n_summaries = 3)\n```\n\nYou can also specify the number of digits you'd like returned in the summary\n\n```{r}\ncolour_values(rnorm(n = 10), n_summaries = 3, digits = 2)\n```\n\nYou can also use `format = FALSE` if you don't want the summary values formatted.\n\n```{r}\ndte \u003c- seq(as.Date(\"2018-01-01\"), as.Date(\"2018-02-01\"), by = 1)\ncolour_values(dte, n_summaries = 3)\n\ncolour_values(dte, n_summaries = 3, format = F)\n```\n\n\nFor categorical values use `summary = TRUE` to return a uniqe set of the values, and their associated colours\n\n```{r}\ncolour_values(sample(letters, size = 50, replace = T), summary = T)\n```\n\n### I see you support lists, but how does it work?\n\nBasically, it's the same as un-listing the list to create a vector of all the values, then colouring them.\n\nSo if your list contains different types, it will coerce all values to the same type and colour them.\n\nBut it returns a list of the same structure. \n\nFor example,\n\n```{r}\n\nl \u003c- list( x = 1:5, y = list(z = letters[1:5] ) )\ncolour_values( l )\n\nx \u003c- c( 1:5, letters[1:5] )\ncolour_values( x )\n\n```\n\nWhat it doesn't do is treat each list element independently. For this you would use \n\n```{r}\nlapply( l, colour_values ) \n```\n\n\n\n---\n\n### What's the performance like?\n\n\n\n**10 million numeric values**\n\n```{r, out.height=400}\nlibrary(microbenchmark)\nlibrary(scales)\nlibrary(viridisLite)\n\nn \u003c- 1e7\ndf \u003c- data.frame(x = rnorm(n = n))\n\nm \u003c- microbenchmark(\n  colourvalues = { colourvalues::colour_values(x = df$x) },\n  scales = { col_numeric(palette = rgb(subset(viridis.map, opt==\"D\")[, 1:3]), domain = range(df$x))(df$x) },\n  times = 25\n)\nm\n\n```\n\n\n**1 million characters (26 unique values)**\n\n```{r, out.height=400}\nlibrary(microbenchmark)\nlibrary(scales)\nlibrary(viridisLite)\n\nn \u003c- 1e6\nx \u003c- sample(x = letters, size = n, replace = TRUE)\ndf \u003c- data.frame(x = x)\n\nm \u003c- microbenchmark(\n  colourvalues = { x \u003c- colourvalues::colour_values(x = df$x) },\n  scales = { y \u003c- col_factor(palette = rgb(subset(viridis.map, opt==\"D\")[, 1:3]), domain = unique(df$x))(df$x) },\n  times = 25\n)\nm\n\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSymbolixAU%2Fcolourvalues","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSymbolixAU%2Fcolourvalues","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSymbolixAU%2Fcolourvalues/lists"}