|
| 1 | +#' @name palette-recommendations |
| 2 | +#' @title Recommendations for colour palettes |
| 3 | +#' @description |
| 4 | +#' For the purposes of these recommendations, we define a palette as a function |
| 5 | +#' that either takes an `n` argument for the number of desired output colours or |
| 6 | +#' a `value` argument between 0-1 representing how far along a gradient output |
| 7 | +#' colours should be. The palette then returns a number of colours equal to `n` |
| 8 | +#' or `length(x)`. |
| 9 | +#' |
| 10 | +#' The convention in the scales package is to name functions that generate |
| 11 | +#' palettes (palette factories) with the `pal_`-prefix. The benefit of |
| 12 | +#' factories is that you can easily parameterise palettes, for example giving |
| 13 | +#' options for how a palette should be constructed. |
| 14 | +#' |
| 15 | +#' In the example below `pal_aurora()` is a palette factory parameterised by |
| 16 | +#' a `direction` argument. |
| 17 | +#' |
| 18 | +#' ```r |
| 19 | +#' pal_aurora <- function(direction = 1) { |
| 20 | +#' colours <- c("palegreen", "deepskyblue", "magenta") |
| 21 | +#' if (sign(direction) == -1) { |
| 22 | +#' colours <- rev(colours) |
| 23 | +#' } |
| 24 | +#' pal_manual(colours, type = "colour") |
| 25 | +#' } |
| 26 | +#' |
| 27 | +#' class(pal_aurora()) |
| 28 | +#' #> [1] "pal_discrete" "scales_pal" "function" |
| 29 | +#' ``` |
| 30 | +#' |
| 31 | +#' It is recommended that a palette factory returns a function with either the |
| 32 | +#' `pal_discrete` or `pal_continuous` class. If your factory constructs a |
| 33 | +#' plain vector of colours, then `pal_manual(type = "colour")` or |
| 34 | +#' `pal_gradient_n()` are useful to return a classed palette for this common |
| 35 | +#' use case. |
| 36 | +#' |
| 37 | +#' When your inner palette function does not return a defined vector of colours, |
| 38 | +#' it is recommended to use `new_discrete_palette` and `new_continuous_palette` |
| 39 | +#' instead and supplement the additional `type` and `na_safe`/`nlevels` |
| 40 | +#' properties. This should allow easy translation between discrete and |
| 41 | +#' continuous palettes. |
| 42 | +#' |
| 43 | +#' ```r |
| 44 | +#' pal_random <- function() { |
| 45 | +#' fun <- function(n) { |
| 46 | +#' sample(colours(distinct = TRUE), size = n) |
| 47 | +#' } |
| 48 | +#' new_discrete_palette(fun, type = "colour", nlevels = length(colours())) |
| 49 | +#' } |
| 50 | +#' ``` |
| 51 | +#' |
| 52 | +#' If you don't have parameterised palettes, but also if you have palette |
| 53 | +#' factories, it is encouraged to export an (inner) palette function or |
| 54 | +#' plain colour vector. This is in addition to exporting the palette factory. |
| 55 | +#' Exporting this makes it easy for users to specify for example |
| 56 | +#' `as_continuous_pal(mypackage::aurora)`. |
| 57 | +#' |
| 58 | +#' ``` |
| 59 | +#' #' @export |
| 60 | +#' aurora <- pal_aurora() |
| 61 | +#' |
| 62 | +#' # or: |
| 63 | +#' |
| 64 | +#' #' @export |
| 65 | +#' aurora <- c("palegreen", "deepskyblue", "magenta") |
| 66 | +#' ``` |
| 67 | +#' |
| 68 | +#' Lastly, for testing purposes we encourage that your palettes can be |
| 69 | +#' interpreted both as discrete palette, but also a continuous palette. |
| 70 | +#' To test for this, you can test the output of `as_discrete_pal()` and |
| 71 | +#' `as_continuous_pal()`. |
| 72 | +#' |
| 73 | +#' ```r |
| 74 | +#' test_that("pal_aurora can be discrete or continuous", { |
| 75 | +#' |
| 76 | +#' my_pal <- pal_aurora() |
| 77 | +#' colours <- c("palegreen", "deepskyblue", "magenta") |
| 78 | +#' |
| 79 | +#' expect_equal(as_discrete_pal(my_pal)(3), colours) |
| 80 | +#' expect_equal(as_continuous_pal(my_pal)(c(0, 0.5, 1)), alpha(colours, NA)) |
| 81 | +#' |
| 82 | +#' }) |
| 83 | +#' ``` |
| 84 | +#' @seealso [palette utilities][new_continuous_palette] |
| 85 | +NULL |
| 86 | + |
1 | 87 | # Constructors ------------------------------------------------------------ |
2 | 88 |
|
3 | 89 | #' Constructors for palettes |
|
28 | 114 | #' For `palette_nlevels()` a single integer. For `palette_na_safe()` a boolean. |
29 | 115 | #' For `palette_type()` a string. |
30 | 116 | #' @export |
| 117 | +#' @seealso [palette recommendations][palette-recommendations] |
31 | 118 | #' |
32 | 119 | #' @examples |
33 | 120 | #' # Creating a new discrete palette |
|