1 Package Overview

pavo is an R package developed with the goal of establishing a flexible and integrated workflow for working with spectral and spatial colour data. It includes functions that take advantage of new data classes to work seamlessly from importing raw spectra and images, to visualisation and analysis. It provides flexible ways to input spectral data from a variety of equipment manufacturers, process these data, extract variables, and produce publication-quality figures.

pavo was written with the following workflow in mind:

  1. Organise data by importing and processing spectral and image data (e.g., to remove noise, negative values, smooth curves, etc.).
  2. Analyse the resulting files, using spectral analyses of shape (hue, saturation, brightness), visual models based on perceptual data, and/or spatial adjacency and boundary strength analyses.
  3. Visualise the output, with multiple options provided for exploration and analysis.
A non-exhaustive overview of the colour-pattern analysis workflow in pavo, as of version 2.0, displaying some key functions at each stage.

Figure 1.1: A non-exhaustive overview of the colour-pattern analysis workflow in pavo, as of version 2.0, displaying some key functions at each stage.

In the remaining chapters we begin by detailing the importing, processing and visualisation of spectral and image data, before moving on to discussion of the many analyses that pavo allows. Our hope is to demonstrate the flexibility of pavo, and to provide a cohesive, reproducible workflow for colour pattern analysis within R. As always, the development version of pavo can be found on github, while the stable release is available via CRAN.

1.1 Classes and Attributes

To enable the comprehensive workflow of pavo, we’ve implemented an expanded class system. Spectra will be of class rspec as long as we use one of pavo’s spectral import or processing functions, or explicitly convert an object using as.rspec(). Similarly, images will be of class rimg when imported via getimg(), or if converted using as.rimg(). The results of vismodel() are objects of class vismodel and the results of colspace() are, unsurprisingly, objects of class colspace. Most of these classes inherit from data.frame, and contain a suite of attributes that describe the object’s characteristics (e.g. options used in visual modelling such as the selected visual system and illuminant, and properties of the modelled colourspace). These are easily viewed using the summary function (on any rspec, rimg, vismodel, or colspace object), which will return the attributes and summary data (where appropriate) in a readable format.

1.2 Suggestions and Assistance

For suggestions, assistance and/or bug reports, we suggest getting in touch via the colRverse discussion board. It requires a github account, however, so if you don’t have and/or want one the feel free to just email Tom and we’ll get back to you as soon as possible. If you have a bug to report, we’d appreciate it if you could also include a reproducible example when possible. Users familiar with GitHub may prefer to open an issue on the project’s github page, or to make a pull-request directly.

1.3 Citation of methods implemented in pavo

Most of the methods implemented in pavo have been thoroughly described in their original publications, to which users should refer for details and interpretation. For reflectance shape variables (“objective colourimetrics”) and their particular relation to signal production and perception, see Andersson and Prager (2006) and Montgomerie (2006). Visual models based on photon catches and receptor noise are detailed in Vorobyev et al. (1998) and Vorobyev et al. (1998), and photoreceptor sensitivity curve estimation in Govardovskii et al. (2000) and Hart and Vorobyev (2005). For tetrahedral colourspace model implementations and variable calculations, see Endler and Mielke (2005) and Stoddard and Prum (2008), and for colour volume overlap see Stoddard and Prum (2008) and Stoddard and Stevens (2011). Adjacency and boundary strength analyses are described in Endler (2012) and Endler, Cole, and Kranz (2018), while overall pattern contrast is detailed in Endler and Mielke (2005). Users of the functions that apply these methods must cite the original sources as appropriate, along with pavo itself:

citation(package = "pavo")
To cite the package pavo in publications please use:

  Maia R, Gruson H, Endler JA, White TE (2019). "pavo 2: new
  tools for the spectral and spatial analysis of colour in
  R." _Methods in Ecology and Evolution_, *10*(7).
  doi:10.1111/2041-210X.13174
  <https://doi.org/10.1111/2041-210X.13174>.

A BibTeX entry for LaTeX users is

  @Article{,
    title = {pavo 2: new tools for the spectral and spatial analysis of colour in R},
    author = {Rafael Maia and Hugo Gruson and John A. Endler and Thomas E. White},
    journal = {Methods in Ecology and Evolution},
    year = {2019},
    volume = {10},
    number = {7},
    page = {1097-1107},
    doi = {10.1111/2041-210X.13174},
  }

1.4 Acknowledgements

We would like to thank Matthew D. Shawkey and Stephanie M. Doucet for insights and support, and Jarrod D. Hadfield and Mary Caswell Stoddard for sharing code that helped us develop some of pavo’s capabilities.