Creating a colour palette package

Adding package metadata

At this point we can add important metadata about what our package does in DESCRIPTION with usethis::use_package():

use_description(
  fields = list(
    Title = "Sunset Colour Palettes",
    `Authors@R` = 
      'person("First", "Last", , "first.last@example.com", c("aut", "cre"))',
    Description = paste0(
      "Colour palettes inspired by sunsets in the Canadian Prairies. ",
      "Built using the 'palettes' package, which provides methods for ",
      "printing, formatting, casting and coercion, extraction and updating ",
      "of components, plotting, colour mixing arithmetic, and colour ",
      "interpolation."
    ),
    URL = "https://github.com/user/repo",
    BugReports = "https://github.com/user/repo/issues"
  )
)

Choosing a license

Because our package will primarily contain colour palette data, not code, we recommend choosing a Creative Commons license:

• For minimal restrictions choose the CC0 license with usethis::use_cc0_license()
• To require attribution when your colour palettes are used, choose the CC BY license with usethis::use_ccby_license()

For sunsets we choose the CC0 license with usethis::use_cc0_license():

use_cc0_license()

Creating colour palettes

Colour palette packages made with palettes are examples of so-called “data packages”—they exist solely for the purpose of distributing colour palettes created with pal_palette(), along with their documentation.

To make it easy to update or reproduce our colour palettes, we first set up a data-creating script that includes the code used to create them with usethis::use_data_raw():

use_data_raw(name = "sunset_palettes")

For the sunsets package our final script for creating colour palettes looks like this:

library(palettes)

# Discrete palettes -----------------------------------------------------------
sunset_palettes_discrete <- pal_palette(
  light = c("#dc8951", "#4E8AC9", "#F5D06D", "#69ca97", "#c978b5"),
  dark = c("#EE6720", "#0792C9", "#E4B854", "#24B079", "#9A4F80")
)

plot(sunset_palettes_discrete)

usethis::use_data(sunset_palettes_discrete, overwrite = TRUE)

# Sequential palettes ---------------------------------------------------------
sunset_palettes_sequential <- pal_palette(
  orange = pal_ramp(pal_colour(c("#EE6720", "#FBE0D1")), n = 7),
  blue   = pal_ramp(pal_colour(c("#0792C9", "#C1D1EB")), n = 7),
  yellow = pal_ramp(pal_colour(c("#E4B854", "#FFECC8")), n = 7),
  green  = pal_ramp(pal_colour(c("#24B079", "#C9EBD7")), n = 7),
  purple = pal_ramp(pal_colour(c("#9A4F80", "#ECCCE2")), n = 7)
)

plot(sunset_palettes_sequential)

usethis::use_data(sunset_palettes_sequential, overwrite = TRUE)

# All palettes ----------------------------------------------------------------
sunset_palettes <- c(
  sunset_palettes_sequential,
  sunset_palettes_discrete
)

plot(sunset_palettes)

usethis::use_data(sunset_palettes, overwrite = TRUE)

This demonstrates three important points about making colour palettes:

• Palettes can be created manually, as in the “discrete palettes” section
• Palettes can be made programmatically, as in the “sequential palettes” section
• Multiple palette objects can coerced together, as in the “all palettes” section

To store these colour palettes and make them available to users of our package, we save them as .rda files in the data/ directory with usethis::use_data().

Attaching the palettes package

Our colour palettes in data/ are always effectively exported, which can be seen by running devtools::load_all() then running sunset_palettes in the console. However, to make the functions from palettes available to users of sunsets, we need to add palettes as a dependency and attach it at runtime. We can add the necessary text to DESCRIPTION with usethis::use_package():

usethis::use_package("palettes", "Depends")

We use Depends instead of Imports because sunsets is designed to be used in conjunction with palettes and is not useful without it. This is a valid exception to the general advice to always use Imports.

We also need to import palettes in our package’s NAMESPACE for its methods to be available when sunsets is loaded but not attached (i.e., sunsets::my_fun()). To import palettes in our package’s NAMESPACE, we create a basic package-level documentation script in R/ where we will import palettes with usethis::use_package_doc():

use_package_doc()

Then in R/sunsets-package.R we write roxygen2 blocks to document our colour palettes, and run devtools::document() when we’re finished. For the sunsets package our documentation looks like this:

#' @keywords internal
"_PACKAGE"

#' Internal palettes methods
#'
#' @import palettes
#' @keywords internal
#' @name sunsets-palettes
NULL

Documenting colour palettes

Our colour palettes in data/ are always effectively exported, but we still need to document them. To document our colour palettes, we create a script in R/ where we will document the names of our colour palettes with usethis::use_r():

usethis::use_r("palettes")

You can name the script anything you like, but we suggest “palettes” if all your colour palette documentation will be in a single file.

Then in R/palettes.R we write roxygen2 blocks to document our colour palettes, and run devtools::document() when we’re finished. For the sunsets package our documentation looks like this:

#' Sunset palettes
#'
#' Palettes inspired by sunsets in the Canadian Prairies.
#'
#' @format ## `sunset_palettes`
#' An object of class `palettes_palette` with `r length(sunset_palettes)`
#' colour palettes. Use `names(sunset_palettes)` to return all palette names.
#' @source <https://github.com/mccarthy-m-g/sunsets>
#' @author [Michael McCarthy](https://github.com/mccarthy-m-g)
#' @seealso [pal_palette()], [pal_colour()]
#' @examples
#' # Get all palettes by name.
#' names(sunset_palettes)
#'
#' # Plot all palettes.
#' plot(sunset_palettes)
"sunset_palettes"

#' @rdname sunset_palettes
#' @format ## `sunset_palettes_discrete`
#' An object of class `palettes_palette` with
#' `r length(sunset_palettes_discrete)` discrete colour palettes.
#'  Use `names(sunset_palettes_discrete)` to return all palette names.
"sunset_palettes_discrete"

#' @rdname sunset_palettes
#' @format ## `sunset_palettes_sequential`
#' An object of class `palettes_palette` with
#' `r length(sunset_palettes_sequential)` sequential colour palettes.
#'  Use `names(sunset_palettes_sequential)` to return all palette names.
"sunset_palettes_sequential"

Adding README.md and NEWS.md

You now have a package that is ready to submit to CRAN. But before you do, you should update two important documentation files:

• README.md, which describes what the package does
• NEWS.md, which describes what’s changed since the previous version

See the Documentation chapter in R Packages by Hadley Wickham and Jenny Bryan for advice on writing these files.

If you want to include printed colour previews of your colour palettes in README.md like there are in palettes’ README.md, you will need to write a README.Rmd file that uses the asciicast knitr engine. For a working example, refer to the code in palettes’ README.Rmd file.

Optionally, you might also consider adding vignettes or a pkgdown website to your package.