Title:	Perceptual Analysis, Visualization and Organization of Spectral Colour Data
Version:	2.9.0
Description:	A cohesive framework for the spectral and spatial analysis of colour described in Maia, Eliason, Bitton, Doucet & Shawkey (2013) <doi:10.1111/2041-210X.12069> and Maia, Gruson, Endler & White (2019) <doi:10.1111/2041-210X.13174>.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	http://pavo.colrverse.com, https://github.com/rmaia/pavo/
BugReports:	https://github.com/rmaia/pavo/issues
Depends:	R (≥ 3.5.0)
Imports:	cluster, future.apply, geometry(≥ 0.4.0), lightr(≥ 1.0), magick, farver, plot3D, progressr, sf, viridisLite
Suggests:	alphashape3d, imager, knitr, mapproj, rgl, rmarkdown, testthat(≥ 2.99.0), vdiffr, digest
VignetteBuilder:	knitr
Config/Needs/website:	pkgdown
Encoding:	UTF-8
Language:	en-GB
RoxygenNote:	7.2.3
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2023-09-24 09:43:04 UTC; twhite
Author:	Thomas White [aut, cre], Rafael Maia [aut], Hugo Gruson [aut], John Endler [aut], Chad Eliason [aut], Pierre-Paul Bitton [aut]
Maintainer:	Thomas White <thomas.white026@gmail.com>
Repository:	CRAN
Date/Publication:	2023-09-24 10:10:02 UTC

pavo: Perceptual Analysis, Visualization and Organization of Spectral Colour Data

Description

A cohesive framework for the spectral and spatial analysis of colour described in Maia, Eliason, Bitton, Doucet & Shawkey (2013) doi:10.1111/2041-210X.12069 and Maia, Gruson, Endler & White (2019) doi:10.1111/2041-210X.13174.

Author(s)

Maintainer: Thomas White thomas.white026@gmail.com (ORCID)

Authors:

• Rafael Maia rafa.maia@gmail.com (ORCID)

• Hugo Gruson hugo.gruson+R@normalesup.org (ORCID)

• John Endler john.endler@deakin.edu.au

• Chad Eliason cme16@zips.uakron.edu

• Pierre-Paul Bitton bittonp@uwindsor.ca (ORCID)

See Also

Useful links:

• http://pavo.colrverse.com

• https://github.com/rmaia/pavo/

• Report bugs at https://github.com/rmaia/pavo/issues

Run an adjacency and boundary strength analysis

Description

Calculate summary variables from the adjacency (Endler 2012) and boundary-strength (Endler et al. 2018) analyses, along with overall pattern contrast (Endler & Mielke 2005).

Usage

adjacent(
  classimg,
  xpts = NULL,
  xscale = NULL,
  bkgID = NULL,
  polygon = NULL,
  exclude = c("none", "background", "object"),
  coldists = NULL,
  hsl = NULL
)

Arguments

Details

You can customise the type of parallel processing used by this function with the future::plan() function. This works on all operating systems, as well as high performance computing (HPC) environment. Similarly, you can customise the way progress is shown with the progressr::handlers() functions (progress bar, acoustic feedback, nothing, etc.)

Value

a data frame of summary variables:

• 'k': The number of user-specified colour and/or luminance classes.

• 'N': The grand total (sum of diagonal and off-diagonal) transitions.

• 'n_off': The total off-diagonal transitions.

• 'p_i': The overall frequency of colour class i.

• 'q_i_j': The frequency of transitions between all colour classes i and j, such that sum(q_i_j) = 1.

• 't_i_j': The frequency of off-diagonal (i.e. class-change transitions) transitions i and j, such that sum(t_i_j) = 1.

• 'm': The overall transition density (mean transitions), in units specified in the argument xscale.

• 'm_r': The row-wise transition density (mean row transitions), in user-specified units.

• 'm_c': The column-wise transition density (mean column transitions), in user-specified units.

• 'A': The transition aspect ratio (< 1 = wide, > 1 = tall).

• 'Sc': Simpson colour class diversity, Sc = 1/(sum(p_i^2)). If all colour and luminance classes are equal in relative area, then Sc = k.

• 'St': Simpson transition diversity, St = 1/sum(t_i_j^2).

• 'Jc': Simpson colour class diversity relative to its achievable maximum. Jc = Sc/k.

• 'Jt': Simpson transition diversity relative to its achievable maximum. Jt = St/(k*(k-1)/2).

• 'B': The animal/background transition ratio, or the ratio of class-change transitions entirely within the focal object and those involving the object and background, B = sum(O_a_a / O_a_b).

• 'Rt': Ratio of animal-animal and animal-background transition diversities, Rt = St_a_a / St_a_b.

• 'Rab': Ratio of animal-animal and background-background transition diversities, Rt = St_a_a / St_b_b.

• ⁠'m_dS', 's_dS', 'cv_dS'⁠: weighted mean, sd, and coefficient of variation of the chromatic boundary strength.

• ⁠'m_dL', 's_dL', 'cv_dL'⁠: weighted mean, sd, and coefficient of variation of the achromatic boundary strength.

• ⁠'m_hue', 's_hue', 'var_hue'⁠: circular mean, sd, and variance of overall pattern hue (in radians).

• ⁠'m_sat', 's_sat', 'cv_sat'⁠: weighted mean, sd, and coefficient variation of overall pattern saturation.

• ⁠'m_lum', 's_lum', 'cv_lum'⁠: weighted mean, sd, and coefficient variation of overall pattern luminance.

Author(s)

Thomas E. White thomas.white026@gmail.com

References

Endler, J. A. (2012). A framework for analysing colour pattern geometry: adjacent colours. Biological Journal Of The Linnean Society, 107(2), 233-253.

Endler, J. A., Cole G., Kranz A. (2018). Boundary Strength Analysis: Combining color pattern geometry and coloured patch visual properties for use in predicting behaviour and fitness. Methods in Ecology and Evolution, 9(12), 2334-2348.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

See Also

classify(), summary.rimg(), procimg()

Examples

# Set a seed, for reproducibility
set.seed(153)

# Run the adjacency analysis on a single image of a butterfly
papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))
papilio_class <- classify(papilio, kcols = 4)
papilio_adj <- adjacent(papilio_class, xscale = 100)

# Expand on the above, by including (fake) color distances and hsl values
# of colour elements in the image

# Generate fake color distances
distances <- data.frame(
  c1 = c(1, 1, 1, 2, 2, 3),
  c2 = c(2, 3, 4, 3, 4, 4),
  dS = c(5.3, 3.5, 5.7, 2.9, 6.1, 3.2),
  dL = c(5.5, 6.6, 3.3, 2.2, 4.4, 6.6)
)

# Generate some fake hue, saturation, luminance values
hsl_vals <- data.frame(
  patch = seq_len(4),
  hue = c(1.5, 2.2, 1.0, 0.5),
  lum = c(10, 5, 7, 3),
  sat = c(3.5, 1.1, 6.3, 1.3)
)

# Run the full analysis, including the white background's ID
papilio_adj <- adjacent(papilio_class,
  xscale = 100, bkgID = 1,
  coldists = distances, hsl = hsl_vals
)

# Run an adjacency analysis on multiple images.
# First load some images of coral snake colour patterns
snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))

# Automatically colour-classify the coral snake patterns
snakes_class <- classify(snakes, kcols = 3)

# Run the adjacency analysis, with varying real-world scales for each image
snakes_adj <- adjacent(snakes_class, xpts = 120, xscale = c(50, 55))

Plot aggregated reflectance spectra

Description

Combines and plots spectra (by taking the average and the standard deviation, for example) according to an index or a vector of identities.

Usage

aggplot(
  rspecdata,
  by = NULL,
  FUN.center = mean,
  FUN.error = sd,
  lcol = NULL,
  shadecol = NULL,
  alpha = 0.2,
  legend = FALSE,
  ...
)

Arguments

Value

Plot containing the lines and shaded areas of the groups of spectra.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Chad Eliason cme16@zips.uakron.edu

References

Montgomerie R (2006) Analyzing colors. In: Hill G, McGraw K (eds) Bird coloration. Harvard University Press, Cambridge, pp 90-147.

Examples

# Load reflectance data
data(sicalis)

# Create grouping variable based on spec names
bysic <- gsub("^ind[0-9].", "", names(sicalis)[-1])

# Plot using various error functions and options
aggplot(sicalis, bysic)
aggplot(sicalis, bysic, FUN.error = function(x) quantile(x, c(0.0275, 0.975)))
aggplot(sicalis, bysic, shadecol = spec2rgb(sicalis), lcol = 1)
aggplot(sicalis, bysic, lcol = 1, FUN.error = function(x) sd(x) / sqrt(length(x)))

Aggregate reflectance spectra

Description

Combines spectra (by taking the average, for example) according to an index or a vector of identities.

Usage

aggspec(rspecdata, by = NULL, FUN = mean, trim = TRUE)

Arguments

Value

A data frame of class rspec containing the spectra after applying the aggregating function.

Author(s)

Chad Eliason cme16@zips.uakron.edu

References

Montgomerie R (2006) Analyzing colors. In: Hill G, McGraw K (eds) Bird coloration. Harvard University Press, Cambridge, pp 90-147.

Examples

data(teal)

# Average every two spectra
teal.sset1 <- aggspec(teal, by = 2)
plot(teal.sset1)

# Create factor and average spectra by levels 'a' and 'b'
ind <- rep(c("a", "b"), times = 6)
teal.sset2 <- aggspec(teal, by = ind)

plot(teal.sset2)

Convert data to an rimg object

Description

Converts an array of RGB values, a cimg object, or a magick-image object, to an rimg object.

Usage

as.rimg(object, name = "img")

## Default S3 method:
as.rimg(object, name = "img")

## S3 method for class 'cimg'
as.rimg(object, name = "img")

is.rimg(object)

Arguments

Value

an object of class rimg for use in further pavo functions

a logical value indicating whether the object is of class rimg

Author(s)

Thomas E. White thomas.white026@gmail.com

Hugo Gruson hugo.gruson+R@normalesup.org

Examples

# Generate some fake image data
fake <- array(c(
  as.matrix(rep(c(0.2, 0.4, 0.6), each = 250)),
  as.matrix(rep(c(0.4, 0.7, 0.8), each = 250)),
  as.matrix(rep(c(0.6, 0.1, 0.2), each = 250))
),
dim = c(750, 750, 3)
)

# Inspect it
head(fake)

# Determine if is an rimg object
is.rimg(fake)

# Convert to rimg object and check again
fake2 <- as.rimg(fake)
is.rimg(fake2)

Convert data to an rspec object

Description

Converts data frames or matrices containing spectral data to rspec object

Usage

as.rspec(
  object,
  whichwl = NULL,
  interp = TRUE,
  lim = NULL,
  exceed.range = TRUE
)

is.rspec(object)

Arguments

Value

an object of class rspec for use in further pavo functions

a logical value indicating whether the object is of class rspec

Author(s)

Chad Eliason cme16@zips.uakron.edu

Examples

# Generate some fake reflectance data
fakedat <- data.frame(wl = 300:700, refl1 = rnorm(401), refl2 = rnorm(401))
head(fakedat)

# Determine if is rspec object
is.rspec(fakedat)

# Convert to rspec object
fakedat2 <- as.rspec(fakedat)
is.rspec(fakedat2)
head(fakedat2)

Plot reference axes in a static tetrahedral colourspace

Description

Plots reference x, y and z arrows showing the direction of the axes in a static tetrahedral colourspace plot.

Usage

axistetra(
  x = 0,
  y = 1.3,
  size = 0.1,
  arrowhead = 0.05,
  col = par("fg"),
  lty = par("lty"),
  lwd = par("lwd"),
  label = TRUE,
  adj.label = list(x = c(0.003, 0), y = c(0.003, 0.003), z = c(0, 0.003)),
  label.cex = 1,
  label.col = NULL
)

Arguments

Value

axistetra adds reference arrows showing the direction of the 3-dimensional axes in a static tetrahedral colourspace plot.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Examples

data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
plot(tcs.sicalis)
axistetra()

Default background and illuminant data

Description

Default background and illuminant data

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Endler, J. (1993). The Color of Light in Forests and Its Implications. Ecological Monographs, 63, 1-27.

Bootstrap colour distance confidence intervals

Description

Uses a bootstrap procedure to generate confidence intervals for the mean colour distance between two or more samples of colours

Usage

bootcoldist(vismodeldata, by, boot.n = 1000, alpha = 0.95, raw = FALSE, ...)

Arguments

Details

You can customise the type of parallel processing used by this function with the future::plan() function. This works on all operating systems, as well as high performance computing (HPC) environment. Similarly, you can customise the way progress is shown with the progressr::handlers() functions (progress bar, acoustic feedback, nothing, etc.)

Value

a matrix including the empirical mean and bootstrapped confidence limits for dS (and dL if achromatic = TRUE), or a data.frame of raw bootstraped dS (and dL if achromatic = TRUE) values equal in length to boot.n.

References

Maia, R., White, T. E., (2018) Comparing colors using visual models. Behavioral Ecology, ary017 doi:10.1093/beheco/ary017

Examples

# Run the receptor-noise limited model, using the visual phenotype
# of the blue tit
data(sicalis)
vm <- vismodel(sicalis, achromatic = "bt.dc", relative = FALSE)
gr <- gsub("ind..", "", rownames(vm))
bootcoldist(vm, by = gr, n = c(1, 2, 2, 4), weber = 0.1, weber.achro = 0.1)

# Run the same again, though as a simple colourspace model
data(sicalis)
vm <- vismodel(sicalis, achromatic = "bt.dc")
space <- colspace(vm)
gr <- gsub("ind..", "", rownames(space))
bootcoldist(space, by = gr)

# Estimate bootstrapped colour-distances for a more 'specialised' model,
# like the colour hexagon
data(flowers)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, achromatic = "l", bkg = "green"
)
flowers.hex <- colspace(vis.flowers, space = "hexagon")
pop_group <- c(rep("pop_1", nrow(flowers.hex) / 2), rep("pop_2", nrow(flowers.hex) / 2))
bootcoldist(flowers.hex, by = pop_group)

Categorical fly-visual model

Description

Applies the categorical colour vision model of Troje (1993)

Usage

categorical(vismodeldata)

Arguments

Value

Object of class colspace consisting of the following columns:

• ⁠R7p, R7y, R8p, R8y⁠: the quantum catch data used to calculate the remaining variables.

• ⁠x, y⁠: cartesian coordinates in the categorical colour space.

• r.vec: the r vector (saturation, distance from the center).

• h.theta: angle theta (in radians), a continuous measure of stimulus hue.

• category: fly-colour category. One of ⁠p-y-⁠, ⁠p-y+⁠, ⁠p+y-⁠, ⁠p+y+⁠.

Author(s)

Thomas White thomas.white026@gmail.com

References

Troje N. (1993). Spectral categories in the learning behaviour of blowflies. Zeitschrift fur Naturforschung C, 48, 96-96.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "musca", achromatic = "md.r1")
cat.flowers <- colspace(vis.flowers, space = "categorical")

Plot the categorical colour vision model

Description

Produces a plot based on Troje's (1993) categorical colour model.

Usage

catplot(catdata, labels = TRUE, labels.cex = 0.9, ...)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Troje N. (1993). Spectral categories in the learning behaviour of blowflies. Zeitschrift fur Naturforschung C, 48, 96-96.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, qcatch = "Qi", visual = "musca", achro = "none", relative = TRUE)
cat.flowers <- colspace(vis.flowers, space = "categorical")
plot(cat.flowers)

CIE colour spaces

Description

Calculates coordinates and colorimetric variables that represent reflectance spectra in either the CIEXYZ (1931), CIELAB (1971), or CIELCh (1971) colourspaces.

Usage

cie(
  vismodeldata,
  space = c("XYZ", "LAB", "LCh"),
  visual = c("cie2", "cie10"),
  illum = c("D65", "bluesky", "forestshade")
)

Arguments

Value

Object of class colspace containing:

• ⁠X, Y, Z⁠: Tristimulus values.

• ⁠x, y, z⁠: Cartesian coordinates, when using space = XYZ.

• ⁠L, a, b⁠: Lightness, L, and colour-opponent a (redness-greenness) and b (yellowness-blueness) values, in a Cartesian coordinate space. Returned when using space = LAB.

• ⁠L, a, b, C, h⁠: Lightness, L, colour-opponent a (redness-greenness) and b (yellowness-blueness) values, as well as chroma C and hue-angle h (degrees), the latter of which are cylindrical representations of a and b from the CIELAB model. Returned when using space = LCh.

Author(s)

Thomas White thomas.white026@gmail.com

References

Smith T, Guild J. (1932) The CIE colorimetric standards and their use. Transactions of the Optical Society, 33(3), 73-134.

Westland S, Ripamonti C, Cheung V. (2012). Computational colour science using MATLAB. John Wiley & Sons.

Stockman, A., & Sharpe, L. T. (2000). Spectral sensitivities of the middle- and long-wavelength sensitive cones derived from measurements in observers of known genotype. Vision Research, 40, 1711-1737.

CIE (2006). Fundamental chromaticity diagram with physiological axes. Parts 1 and 2. Technical Report 170-1. Vienna: Central Bureau of the Commission Internationale de l Eclairage.

Examples

# Load floral reflectance spectra
data(flowers)

# Estimate quantum catches, using the cie10-degree viewer matching function
vis.flowers <- vismodel(flowers, visual = "cie10", illum = "D65", vonkries = TRUE, relative = FALSE)

# Model floral spectra in the CIEXYZ space
flowers.ciexyz <- colspace(vis.flowers, space = "ciexyz")

# Model floral spectra in the CIELab space
flowers.cielab <- colspace(vis.flowers, space = "cielab")

# Model floral spectra in the CIELch space
flowers.cielch <- colspace(vis.flowers, space = "cielch")

CIE plot

Description

Plot a CIE (XYZ, LAB, or LCH) chromaticity diagram.

Usage

cieplot(
  ciedata,
  mono = TRUE,
  out.lwd = NULL,
  out.lcol = "black",
  out.lty = 1,
  theta = 45,
  phi = 10,
  r = 1e+06,
  zoom = 1,
  box = FALSE,
  ciebg = TRUE,
  ...
)

Arguments

Author(s)

Thomas E. White thomas.white026@gmail.com

Rafael Maia rm72@zips.uakron.edu

References

Smith T, Guild J. (1932) The CIE colorimetric standards and their use. Transactions of the Optical Society, 33(3), 73-134.

Westland S, Ripamonti C, Cheung V. (2012). Computational colour science using MATLAB. John Wiley & Sons.

Stockman, A., & Sharpe, L. T. (2000). Spectral sensitivities of the middle- and long-wavelength sensitive cones derived from measurements in observers of known genotype. Vision Research, 40, 1711-1737.

CIE (2006). Fundamental chromaticity diagram with physiological axes. Parts 1 and 2. Technical Report 170-1. Vienna: Central Bureau of the Commission Internationale de l Eclairage.

Examples

# Load floral reflectance spectra
data(flowers)

# CIEXYZ
# Estimate quantum catches, using the cie10-degree viewer matching function
vis.flowers <- vismodel(flowers, visual = "cie10", illum = "D65", vonkries = TRUE, relative = FALSE)

# Run the ciexyz model
xyz.flowers <- colspace(vis.flowers, space = "ciexyz")

# Visualise the floral spectra in a ciexyz chromaticity diagram
plot(xyz.flowers)

# CIELAB
# Using the quantum catches above, instead model the spectra in the CIELab
# space
lab.flowers <- colspace(vis.flowers, space = "cielab")

# And plot in Lab space
plot(lab.flowers)

Identify colour classes in an image for adjacency analyses

Description

Classify image pixels into discrete colour classes.

Usage

classify(
  imgdat,
  method = c("kMeans", "kMedoids"),
  kcols = NULL,
  refID = NULL,
  interactive = FALSE,
  plotnew = FALSE,
  col = "red",
  ...
)

Arguments

Details

You can customise the type of parallel processing used by this function with the future::plan() function. This works on all operating systems, as well as high performance computing (HPC) environment. Similarly, you can customise the way progress is shown with the progressr::handlers() functions (progress bar, acoustic feedback, nothing, etc.)

Value

A matrix, or list of matrices, of class rimg containing the colour class classifications ID at each pixel location. The RGB values corresponding to cluster centres (i.e. colour classes) are stored as object attributes.

Note

Since the kmeans process draws on random numbers to find initial cluster centres when interactive = FALSE, use set.seed() if reproducible cluster ID's are desired between runs.

Author(s)

Thomas E. White thomas.white026@gmail.com

See Also

stats::kmeans

Examples

# Single image
papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))
papilio_class <- classify(papilio, kcols = 4)

# Multiple images, with interactive classification and a reference image
snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))
if (interactive()) {
  snakes_class <- classify(snakes, refID = "snake_01", interactive = TRUE)
}

Color opponent coding model

Description

Calculates coordinates and colorimetric variables that represent reflectance spectra in the color opponent coding model of hymenopteran vision.

Usage

coc(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• s, m, l: the quantum catch data used to calculate the remaining variables.

• x, y: coordinates for the points in coc space

• r.vec: the r vector (saturation, distance from the center using a city-block metric).

Author(s)

Thomas White thomas.white026@gmail.com

References

Backhaus W. (1991). Color opponent coding in the visual system of the honeybee. Vision Research, 31, 1381-1397.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "apis", qcatch = "Ei", relative = FALSE, vonkries = TRUE)
coc.flowers <- colspace(vis.flowers, space = "coc")

Plot the colour opponent coding diagram

Description

Produces a plot based on the colour opponent coding diagram of Backhaus (1991).

Usage

cocplot(
  cocdata,
  labels = TRUE,
  labels.cex = 0.9,
  tick.loc = c(-12, -9, -6, -3, 3, 6, 9, 12),
  achro = FALSE,
  achrosize = 0.8,
  achrocol = "grey",
  square = TRUE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Backhaus W. (1991). Color opponent coding in the visual system of the honeybee. Vision Research, 31, 1381-1397.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "apis", qcatch = "Ei", relative = FALSE, vonkries = TRUE)
coc.flowers <- colspace(vis.flowers, space = "coc")
plot(coc.flowers)

Colour distances

Description

Calculates colour distances. When data are the result of vismodel(), it applies the receptor-noise model of Vorobyev et al. (1998) to calculate colour distances with noise based on relative photoreceptor densities. It also accepts colspace() data in which case unweighted Euclidean distances, CIE2000 distances (cielab and cielch only), or Manhattan distances (coc model only) are returned.

Usage

coldist(
  modeldata,
  noise = c("neural", "quantum"),
  subset = NULL,
  achromatic = FALSE,
  qcatch = NULL,
  n = c(1, 2, 2, 4),
  weber = 0.1,
  weber.ref = "longest",
  weber.achro = 0.1
)

Arguments

Value

A data frame containing up to 4 columns. The first two (⁠patch1, patch2⁠) refer to the two colors being contrasted; dS is the chromatic contrast (delta S) and dL is the achromatic contrast (delta L). Units of dS JND's in the receptor-noise model, unweighted Euclidean distances in colorspace models, and Manhattan distances in the colour-opponent-coding space. Units of dL vary, and are either simple contrast, Weber contrast, or Michelson contrast, as indicated by the output message.

Note on previous versions

Generic di- tri- and tetra-chromatic colspace objects were previously passed through the receptor-noise limited model to return noise-weighted Euclidean distances. This behaviour has been amended, and generic spaces now return unweighted Euclidean distances. Equivalent results to the former behaviour can be attained by sending the results of vismodel() directly to coldist() , as previously, which also offers greater flexibility and reliability. Thus coldist() now returns unweighted Euclidean distances for colspace objects (with the exception of Manhattan distances for the coc space, and CIE2000, distances for CIELab and CIELCh spaces), and noise-weighted Euclidean distances for vismodel objects.

Author(s)

Thomas E. White thomas.white026@gmail.com

Rafael Maia rm72@zips.uakron.edu

References

Vorobyev, M., Osorio, D., Bennett, A., Marshall, N., & Cuthill, I. (1998). Tetrachromacy, oil droplets and bird plumage colours. Journal Of Comparative Physiology A-Neuroethology Sensory Neural And Behavioral Physiology, 183(5), 621-633.

Hart, N. S. (2001). The visual ecology of avian photoreceptors. Progress In Retinal And Eye Research, 20(5), 675-703.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Olsson, P., Lind, O., & Kelber, A. (2015) Bird colour vision: behavioural thresholds reveal receptor noise. Journal of Experimental Biology, 218, 184-193.

Lind, O. (2016) Colour vision and background adaptation in a passerine bird, the zebra finch (Taeniopygia guttata). Royal Society Open Science, 3, 160383.

Olsson, P., Lind, O., & Kelber, A. (2017) Chromatic and achromatic vision: parameter choice and limitations for reliable model predictions. Behavioral Ecology, doi:10.1093/beheco/arx133

Examples

# Dichromat
data(flowers)
vis.flowers <- vismodel(flowers, visual = "canis", relative = FALSE)
didist.flowers <- coldist(vis.flowers, n = c(1, 2))

# Trichromat
vis.flowers <- vismodel(flowers, visual = "apis", relative = FALSE)
tridist.flowers <- coldist(vis.flowers, n = c(1, 2, 1))

# Trichromat, colour-hexagon model (euclidean distances)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei",
  relative = FALSE, vonkries = TRUE, achromatic = "l", bkg = "green"
)
hex.flowers <- colspace(vis.flowers, space = "hexagon")
hexdist.flowers <- coldist(hex.flowers)

# Trichromat, colour-opponent-coding model (manhattan distances)
vis.flowers <- vismodel(flowers, visual = "apis", qcatch = "Ei", relative = FALSE, vonkries = TRUE)
coc.flowers <- colspace(vis.flowers, space = "coc")
hexdist.flowers <- coldist(coc.flowers)

# Tetrachromat
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv", relative = FALSE)
tetradist.sicalis.n <- coldist(vis.sicalis)

Convert coldist to distance matrix

Description

Converts a coldist() output into a distance matrix where samples are rows and columns.

Usage

coldist2mat(coldistres)

Arguments

Value

A list containing one or two matrices, for dS and dL, depending if the original object had dS and dL columns

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Maia, R., White, T. E., (2018) Comparing colors using visual models. Behavioral Ecology, ary017 doi:10.1093/beheco/ary017

Examples

data(flowers)
vis.flowers <- vismodel(flowers, achromatic = "l")
cd.flowers <- coldist(vis.flowers, achromatic = TRUE)
coldist2mat(cd.flowers)[["dS"]]
coldist2mat(cd.flowers)[["dL"]]

Model spectra in a colorspace

Description

Models reflectance spectra in a colorspace. For information on plotting arguments and graphical parameters, see plot.colspace().

Usage

colspace(
  vismodeldata,
  space = c("auto", "di", "tri", "tcs", "hexagon", "coc", "categorical", "ciexyz",
    "cielab", "cielch", "segment"),
  qcatch = NULL,
  ...
)

Arguments

Author(s)

Rafael Maia rm72@zips.uakron.edu

Thomas White thomas.white026@gmail.com

References

Smith T, Guild J. (1932) The CIE colorimetric standards and their use. Transactions of the Optical Society, 33(3), 73-134.

Westland S, Ripamonti C, Cheung V. (2012). Computational colour science using MATLAB. John Wiley & Sons.

Chittka L. (1992). The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. Journal of Comparative Physiology A, 170(5), 533-543.

Chittka L, Shmida A, Troje N, Menzel R. (1994). Ultraviolet as a component of flower reflections, and the colour perception of Hymenoptera. Vision research, 34(11), 1489-1508.

Troje N. (1993). Spectral categories in the learning behaviour of blowflies. Zeitschrift fur Naturforschung C, 48, 96-96.

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

Backhaus W. (1991). Color opponent coding in the visual system of the honeybee. Vision Research, 31, 1381-1397.

Endler, J. A. (1990) On the measurement and classification of color in studies of animal color patterns. Biological Journal of the Linnean Society, 41, 315-352.

Examples

data(flowers)

# Model a dichromat viewer in a segment colourspace
vis.flowers <- vismodel(flowers, visual = "canis")
di.flowers <- colspace(vis.flowers, space = "di")

# Model a honeybee viewer in the colour hexagon
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, achromatic = "l", bkg = "green"
)
hex.flowers <- colspace(vis.flowers, space = "hexagon")

# Model a trichromat (the honeybee) in a Maxwell triangle
vis.flowers <- vismodel(flowers, visual = "apis")
tri.flowers <- colspace(vis.flowers, space = "tri")
plot(tri.flowers)

# Model a tetrachromat (the Blue Tit) in a tetrahedral colourspace
vis.flowers <- vismodel(flowers, visual = "bluetit")
tcs.flowers <- colspace(vis.flowers, space = "tcs")

# Model a housefly in the 'categorical' colourspace
vis.flowers <- vismodel(flowers, visual = "musca", achro = "md.r1")
cat.flowers <- colspace(vis.flowers, space = "categorical")

Plot a dichromat segment

Description

Produces a dichromat segment plot.

Usage

diplot(
  didata,
  labels = TRUE,
  achro = TRUE,
  achrocol = "grey",
  achrosize = 0.8,
  labels.cex = 1,
  out.lwd = 1,
  out.lcol = "black",
  out.lty = 1,
  square = TRUE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "canis")
di.flowers <- colspace(vis.flowers, space = "di")
plot(di.flowers)

Dichromatic colour space

Description

Calculates coordinates and colorimetric variables that represent reflectance spectra in a dichromatic colour space.

Usage

dispace(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• s, l: the quantum catch data used to calculate the remaining variables.

• x: the coordinate of the stimulus along a segment

• r.vec: the r vector (saturation, distance from the center).

Author(s)

Thomas White thomas.white026@gmail.com

References

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "canis")
di.flowers <- colspace(vis.flowers, space = "di")

Plot spectral curves

Description

Plots one or multiple spectral curves in the same graph to rapidly compare groups of spectra.

Usage

explorespec(
  rspecdata,
  by = NULL,
  scale = c("equal", "free"),
  legpos = "topright",
  ...
)

Arguments

Value

Spectral curve plots

Note

Number of plots presented per page depends on the number of graphs produced.

Author(s)

Pierre-Paul Bitton bittonp@uwindsor.ca

Examples

data(sicalis)
explorespec(sicalis, 3)
explorespec(sicalis, 3, ylim = c(0, 100), legpos = c(500, 80))

Compute the \alpha^* value

Description

Compute the \alpha^* value

Usage

find_astar(coords)

Arguments

Value

The \alpha^* value as defined in Gruson (2020).

References

Gruson H. (2020). Estimation of colour volumes as concave hypervolumes using \alpha-shapes. Methods in Ecology and Evolution, 11(8), 955-963 doi:10.1111/2041-210X.13398

See Also

alphashape3d::ashape3d()

Reflectance spectra from a suite of native Australian flowers, collected around Cairns, Queensland.

Description

Dataset containing reflectance measurements from 36 native Australian angiosperm species, indicated by column names.

Usage

data(flowers)

Format

An object of class rspec (inherits from data.frame) with 401 rows and 37 columns.

Author(s)

Thomas White thomas.white026@gmail.com

References

Dalrymple, R., L., Kemp, D. J., Flores-Moreno, H., Laffan, S. W., White, T. E., Hemmings, F. A., Tindall, M. L., & Moles, A. T. (2015). Birds, butterflies and flowers in the tropics are not more colourful than those at higher latitudes. Global Ecology and Biogeography, 24(12), 1424-1432. doi:10.1111/geb.12368

White, T. E., Dalrymple, R. L., Herberstein, M. E., & Kemp, D. J. (2017). The perceptual similarity of orb-spider prey lures and flowers colours. Evolutionary Ecology, 31(1), 1-20. doi:10.1007/s10682-016-9876-x

Dalrymple, R. L., Flores-Moreno, H., Kemp, D. J., White, T. E., Laffan, S. W., Hemmings, F. A., Tindall, M. L., & Moles, A. T. (2018). Abiotic and biotic predictors of macroecological patterns in bird and butterfly coloration. Ecological Monographs, 88(2), 204-224.

Import image data

Description

Finds and imports PNG, JPEG, and/or BMP images.

Usage

getimg(imgpath = getwd(), subdir = FALSE, subdir.names = FALSE, max.size = 1)

Arguments

Value

a image, or list of images, of class rimg, for use in further pavo functions.

Author(s)

Thomas E. White thomas.white026@gmail.com

Examples

# Single image
papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))

# Multiple images
snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))

Import spectra files

Description

Finds and imports spectra files from a folder. Currently works for reflectance files generated in Ocean Optics SpectraSuite (USB2000, USB4000 and Jaz spectrometers), CRAIC software (after exporting) and Avantes (before or after exporting).

Usage

getspec(
  where = getwd(),
  ext = "txt",
  lim = c(300, 700),
  decimal = ".",
  sep = NULL,
  subdir = FALSE,
  subdir.names = FALSE,
  ignore.case = TRUE
)

Arguments

Details

You can customise the type of parallel processing used by this function with the future::plan() function. This works on all operating systems, as well as high performance computing (HPC) environment. Similarly, you can customise the way progress is shown with the progressr::handlers() functions (progress bar, acoustic feedback, nothing, etc.)

Value

A data frame, of class rspec, containing individual imported spectral files as columns. Reflectance values are interpolated to the nearest wavelength integer.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Hugo Gruson hugo.gruson+R@normalesup.org

References

Gruson H, White TE, Maia R (2019) lightr: import spectral data and metadata in R. Journal of Open Source Software, 4(43), 1857, doi:10.21105/joss.01857.

See Also

lightr::lr_get_spec() for a more flexible version of this function (e.g. uninterpolated wavelengths), and lightr::lr_get_metadata() for the retrieval and import of spectral metadata. See https://docs.ropensci.org/lightr/ for the complete, and up-to-date, list of supported file formats.

Examples

# Import and inspect example spectral data with a range of set to 400-700nm.
rspecdata <- getspec(system.file("testdata", package = "lightr"), ext = "ttt", lim = c(400, 700))
head(rspecdata)

Colour hexagon

Description

Calculates coordinates and colourimetric variables that represent reflectance spectra in the hymenopteran colour hexagon.

Usage

hexagon(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• s, m, l: the quantum catch data used to calculate the remaining variables

• x, y: cartesian coordinates in the colour hexagon.

• h.theta: hue angle theta (in degrees), with 0-degrees at the 1200 angle, increasing clockwise.

• r.vec: the r vector (saturation, distance from the center).

• sec.fine: fine 'hue sector', wherein the full hexagon is composed of 36 10-degree sectors, with 0-degrees at the 1200 angle.

• sec.coarse: coarse 'hue sector', wherein the full hexagon is composed of five sectors: blue, bluegreen, green, uvgreen, uv, and uvblue.

Author(s)

Thomas White thomas.white026@gmail.com

References

Chittka L. (1992). The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. Journal of Comparative Physiology A, 170(5), 533-543.

Chittka L, Shmida A, Troje N, Menzel R. (1994). Ultraviolet as a component of flower reflections, and the colour perception of Hymenoptera. Vision research, 34(11), 1489-1508.

Examples

data(flowers)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, achromatic = "l", bkg = "green"
)
flowers.hex <- colspace(vis.flowers, space = "hexagon")

Plot a colour hexagon

Description

Produces a colour hexagon plot.

Usage

hexplot(
  hexdata,
  achro = TRUE,
  labels = TRUE,
  sectors = c("none", "fine", "coarse"),
  sec.col = "grey",
  out.lwd = 1,
  out.lty = 1,
  out.lcol = "black",
  labels.cex = 1,
  achrosize = 0.8,
  achrocol = "grey",
  square = TRUE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Chittka L. (1992). The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. Journal of Comparative Physiology A, 170(5), 533-543.

Chittka L, Shmida A, Troje N, Menzel R. (1994). Ultraviolet as a component of flower reflections, and the colour perception of Hymenoptera. Vision research, 34(11), 1489-1508.

Examples

data(flowers)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, achromatic = "l", bkg = "green"
)
hex.flowers <- colspace(vis.flowers, space = "hexagon")
plot(hex.flowers)

Convert images between class rimg and cimg or magick-image

Description

Conveniently convert single objects of class rimg to class cimg (from the package imager) or magick-image (from the package magick), both of which contains a suite of useful image-processing capabilities.

Usage

rimg2cimg(image)

rimg2magick(image)

Arguments

Value

an image of the specified class

Note

Attributes (e.g. scales, color-classes) will not be preserved following conversion from class rimg, so it's best to use early in the analysis workflow.

Author(s)

Thomas E. White thomas.white026@gmail.com

Hugo Gruson hugo.gruson+R@normalesup.org

Examples

papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))

# Convert from class rimg to cimg
if (requireNamespace("imager", quiety = TRUE)) {
  papilio_cimg <- rimg2cimg(papilio)
  class(papilio_cimg)
}


# Convert from class rimg to magick-image
papilio_magick <- rimg2magick(papilio)
class(papilio_magick)

Converts between irradiance and photon (quantum) flux

Description

Some spectrometers will give illuminant values in units of irradiance (μWatt.cm^-2), but physiological models require illuminants in units of photon (quantum) flux (μmol.s^-1.m^-2). The functions irrad2flux() and flux2irrad() allows for easy conversion of rspec objects between these units.

Usage

irrad2flux(rspecdata)

flux2irrad(rspecdata)

Arguments

Value

a converted rspec object.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Test if object is of class 'colspace'

Description

Test if object is of class 'colspace'

Usage

is.colspace(object)

Arguments

Value

a logical value indicating whether the object is of class colspace

See Also

colspace()

Test if object is of class 'vismodel'

Description

Test if object is of class 'vismodel'

Usage

is.vismodel(object)

Arguments

Value

a logical value indicating whether the object is of class vismodel.

See Also

vismodel()

Convert JND distances into perceptually-corrected Cartesian coordinates

Description

Converts a coldist() output into Cartesian coordinates that are perceptually-corrected (i.e. noise-weighted Euclidean distances)

Usage

jnd2xyz(
  coldistres,
  center = TRUE,
  rotate = TRUE,
  rotcenter = c("mean", "achro"),
  ref1 = "l",
  ref2 = "u",
  axis1 = c(1, 1, 0),
  axis2 = c(0, 0, 1)
)

Arguments

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Pike, T.W. (2012). Preserving perceptual distances in chromaticity diagrams. Behavioral Ecology, 23, 723-728.

Maia, R., White, T. E., (2018) Comparing colors using visual models. Behavioral Ecology, ary017 doi:10.1093/beheco/ary017

Examples

# Load floral reflectance spectra
data(flowers)

# Estimate quantum catches visual phenotype of a Blue Tit
vis.flowers <- vismodel(flowers, visual = 'bluetit')

# Estimate noise-weighted colour distances between all flowers
cd.flowers <- coldist(vis.flowers)

# Convert points to Cartesian coordinates in which Euclidean distances are
# noise-weighted.
jnd2xyz(cd.flowers)

Perceptually-corrected chromaticity diagrams

Description

Plot options for jnd2xyz objects.

Usage

jndplot(
  x,
  arrow = c("relative", "absolute", "none"),
  achro = FALSE,
  arrow.labels = TRUE,
  arrow.col = "darkgrey",
  arrow.p = 1,
  labels.cex = 1,
  margin = "recommended",
  square = TRUE,
  ...
)

Arguments

Value

Creates a plot, details of the plot depend on the input data.

Note

the arrow argument accepts three options:

• "relative": With this option, arrows will be made relative to the data. Arrows will be centered on the data centroid, and will have an arbitrary length of half the average pairwise distance between points, which can be scaled with the arrow.p argument.

• "absolute": With this option, arrows will be made to reflect the visual system underlying the data. Arrows will be centered on the achromatic point in colourspace, and will have length equal to the distance to a monochromatic point (i.e. a colour that stimulates approximately 99.9% of that receptor alone). Arrows can still be scaled using the arrow.p argument, in which case they cannot be interpreted as described.

• "none": no arrows will be included.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Pike, T.W. (2012). Preserving perceptual distances in chromaticity diagrams. Behavioral Ecology, 23, 723-728.

Examples

# Load floral reflectance spectra
data(flowers)

# Estimate quantum catches visual phenotype of a Blue Tit
vis.flowers <- vismodel(flowers, visual = 'bluetit')

# Estimate noise-weighted colour distances between all flowers
cd.flowers <- coldist(vis.flowers)

# Convert points to Cartesian coordinates in which Euclidean distances are
# noise-weighted.
propxyz <- jnd2xyz(cd.flowers)

# Plot the floral spectra in 'noise-corrected' space
plot(propxyz)

Rotate Cartesian coordinates obtained from jnd2xyz()

Description

Rotate Cartesian coordinates obtained from jnd2xyz()

Usage

jndrot(
  jnd2xyzres,
  center = c("mean", "achro"),
  ref1 = "l",
  ref2 = "u",
  axis1 = c(1, 1, 0),
  axis2 = c(0, 0, 1)
)

Arguments

Author(s)

Rafael Maia rm72@zips.uakron.edu

Examples

# Load floral reflectance spectra
data(flowers)

# Estimate quantum catches visual phenotype of a Blue Tit
vis.flowers <- vismodel(flowers, visual = 'bluetit')

# Estimate noise-weighted colour distances between all flowers
cd.flowers <- coldist(vis.flowers)

# Convert points to Cartesian coordinates in which Euclidean distances are
# noise-weighted, before rotating them about the data centroid
jndrot(jnd2xyz(cd.flowers))

Add legend to a static tetrahedral colourspace

Description

Adds a legend to a static tetrahedral colourspace plot.

Usage

legendtetra(x = 0.8, y = 1.2, ...)

Arguments

Value

legendtetra() adds a legend to a static tetrahedral colourspace plot. for additional information on which arguments are necessary and how they are used, see legend().

Author(s)

Rafael Maia rm72@zips.uakron.edu

Examples

data(sicalis)

vis_sicalis <- vismodel(sicalis)
tcs_sicalis <- colspace(vis_sicalis)

cols <- c("#1B9E77", "#D95F02", "#7570B3")
plot(tcs_sicalis, col = cols)
legendtetra(
  legend = c("Crown", "Throat", "Breast"),
  col = cols, pch = 16
)

Merge two rspec objects

Description

Merges two rspec objects into a single rspec object.

Usage

## S3 method for class 'rspec'
merge(x, y, ...)

Arguments

Value

an object of class rspec for use with pavo functions. Will use by = "wl" if unspecified, or automatically append wl to the by argument if one is specified.

Author(s)

Chad Eliason cme16@zips.uakron.edu

See Also

as.rspec(), aggspec()

Examples

# Load angle-resolved reflectance data for a green-winged teal, and
# split it in two
data(teal)
teal1 <- teal[, c(1, 2:5)]
teal2 <- teal[, c(1, 6:13)]

# Merge the two split datasets back into one, with a shared 'wl' column
teal.mer <- merge(teal1, teal2, by = "wl")

# Examine the results, and compare the original to the (identical)
# reconstructed version
plot(teal.mer)
plot(teal)
identical(teal.mer, teal)

# Or an equivalent method, which also allows for the merging of more than one rspec
# object at a time (simply add further objects to the list())
teal.mer2 <- do.call(merge, list(teal1, teal2))

# Check equivalence
identical(teal.mer2, teal)

Peak shape descriptors

Description

Calculates height, location and width of peak at the reflectance midpoint (FWHM). Note: bounds should be set wide enough to incorporate all minima in spectra. Smoothing spectra using procspec() is also recommended.

Usage

peakshape(
  rspecdata,
  select = NULL,
  lim = NULL,
  plot = TRUE,
  ask = FALSE,
  absolute.min = FALSE,
  ...
)

Arguments

Value

a data frame containing column names (id); peak height (max value, B3), location (hue, H1) and full width at half maximum (FWHM), as well as half widths on left (HWHM.l) and right side of peak (HWHM.r). Incl.min column indicates whether user-defined bounds incorporate the actual minima of the spectra. Function will return a warning if not.

Author(s)

Chad Eliason cme16@zips.uakron.edu

Rafael Maia rm72@zips.uakron.edu

Hugo Gruson hugo.gruson+R@normalesup.org

See Also

procspec()

Examples

data(teal)

peakshape(teal, select = 3)
peakshape(teal, select = 10)

# Use wavelength bounds to narrow in on peak of interest
peakshape(teal, select = 10, lim = c(400, 550))

Plot spectra in a colourspace

Description

Plots reflectance spectra in the appropriate colourspace.

Usage

## S3 method for class 'colspace'
plot(x, ...)

Arguments

Value

A colourspace plot appropriate to the input data.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Thomas White thomas.white026@gmail.com

Chad Eliason cme16@zips.uakron.edu

References

Smith T, Guild J. (1932) The CIE colorimetric standards and their use. Transactions of the Optical Society, 33(3), 73-134.

Westland S, Ripamonti C, Cheung V. (2012). Computational colour science using MATLAB. John Wiley & Sons.

Chittka L. (1992). The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. Journal of Comparative Physiology A, 170(5), 533-543.

Chittka L, Shmida A, Troje N, Menzel R. (1994). Ultraviolet as a component of flower reflections, and the colour perception of Hymenoptera. Vision research, 34(11), 1489-1508.

Troje N. (1993). Spectral categories in the learning behaviour of blowflies. Zeitschrift fur Naturforschung C, 48, 96-96.

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

Backhaus W. (1991). Color opponent coding in the visual system of the honeybee. Vision Research, 31, 1381-1397.

Endler, J. A. (1990) On the measurement and classification of color in studies of animal color patterns. Biological Journal of the Linnean Society, 41, 315-352.

See Also

plot(), points.colspace()

Examples

data(flowers)
data(sicalis)

# Dichromat
vis.flowers <- vismodel(flowers, visual = "canis")
di.flowers <- colspace(vis.flowers, space = "di")
plot(di.flowers)

# Colour hexagon
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, achromatic = "l", bkg = "green"
)
hex.flowers <- colspace(vis.flowers, space = "hexagon")
plot(hex.flowers, sectors = "coarse")

# Tetrahedron (static)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
plot(tcs.sicalis)


# Tetrahedron (interactive)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
tcsplot(tcs.sicalis, size = 0.005)

## Add points to interactive tetrahedron
patch <- rep(c("C", "T", "B"), 7)
tcs.crown <- subset(tcs.sicalis, "C")
tcs.breast <- subset(tcs.sicalis, "B")
tcsplot(tcs.crown, col = "blue")
tcspoints(tcs.breast, col = "red")

## Plot convex hull in interactive tetrahedron
tcsplot(tcs.sicalis, col = "blue", size = 0.005)
tcsvol(tcs.sicalis)

Plot unprocessed or colour-classified images

Description

Plot unprocessed or colour-classified image data. If the images are in a list, they will be stepped through one by one.

Usage

## S3 method for class 'rimg'
plot(x, axes = TRUE, col = NULL, ...)

Arguments

Value

an image plot.

Author(s)

Thomas E. White thomas.white026@gmail.com

Examples

papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))
plot(papilio)

papilio_class <- classify(papilio, kcols = 4)
plot(papilio_class)


# Multiple images
snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))
plot(snakes)

snakes_class <- classify(snakes, kcols = 3)
plot(snakes_class)

Plot spectra

Description

Plots reflectance spectra in different arrangements.

Usage

## S3 method for class 'rspec'
plot(
  x,
  select = NULL,
  type = c("overlay", "stack", "heatmap"),
  varying = NULL,
  n = 100,
  labels = FALSE,
  labels.stack = NULL,
  labels.cex = 1,
  wl.guide = TRUE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

Hugo Gruson hugo.gruson+R@normalesup.org

Chad Eliason cme16@zips.uakron.edu

See Also

spec2rgb(), image(), plot()

Examples

# Load angle-resolved reflectance data for a green-winged teal
data(teal)

# Create an overlay plot (default)
plot(teal)

# Create an stacked spectral plot
plot(teal, type = "stack")

# Create a reflectance heatmap
plot(teal, type = "heatmap")

Plot absorbance spectra from sensmodel()

Description

Plot absorbance spectra from sensmodel()

Usage

## S3 method for class 'sensmod'
plot(
  x,
  select = NULL,
  type = c("overlay", "stack", "heatmap"),
  varying = NULL,
  n = 100,
  labels = FALSE,
  labels.stack = NULL,
  labels.cex = 1,
  wl.guide = TRUE,
  ...
)

Arguments

See Also

plot.rspec(), sensmodel()

Examples

# Blue tit visual system based on Hart et al (2000)
bluesens <- sensmodel(c(371, 448, 502, 563),
  beta = FALSE,
  lambdacut = c(330, 413, 507, 572),
  oiltype = c("T", "C", "Y", "R"), om = TRUE
)
plot(bluesens)

# Alternatively, you can specify your own ylab
plot(bluesens, ylab = "absor.")

Plot loess smoothed curves

Description

Plots spectral curves with various levels of loess smoothing to help decide which loess parameters are best for subsequently smoothing the data (e.g. via procspec()).

Usage

plotsmooth(
  rspecdata,
  minsmooth = 0.05,
  maxsmooth = 0.2,
  curves = 5,
  specnum = "ALL",
  ask = TRUE
)

Arguments

Value

Series of plot with curves processed with varying level of loess smoothing

Author(s)

Pierre-Paul Bitton bittonp@uwindsor.ca

See Also

procspec()

Examples

# Load reflectance spectra
data(sicalis)

# Visualise the spectral reflectance curves across a range of smoothing levels
plotsmooth(sicalis, minsmooth = 0.05, maxsmooth = 0.1, curves = 7, specnum = 6)

Plot points in a colourspace

Description

Add points to a colourspace plot

Usage

## S3 method for class 'colspace'
points(x, ...)

Arguments

Value

points.colspace adds points to a colourspace plot.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Thomas White thomas.white026@gmail.com

See Also

plot.colspace()

Process images

Description

Specify scales, resize, and/or define focal objects within images.

Usage

procimg(
  image,
  resize = NULL,
  rotate = NULL,
  scaledist = NULL,
  outline = FALSE,
  reclass = NULL,
  smooth = FALSE,
  iterations = 1L,
  col = "red",
  obj_dist = NULL,
  obj_width = NULL,
  eye_res = NULL,
  plotnew = FALSE,
  ...
)

Arguments

Value

an image, or list of images, for use in further pavo functions.

Note

There are several caveats that should be considered when using the AcuityView algorithm. First and foremost, the converted image is not what the animal actually sees. For example, it does not account for edge enhancement and other processing by the retina and brain that may alter an image. It does, however, show what spatial information can be detected and then processed by the visual system. Second, the converted image is static, which does not allow one to assess how movement may reveal the presence of an otherwise indiscernible object. Third, AcuityView makes several assumptions about the Modulation Transfer Function (MTF), which describes how the optical system affects image contrast as a function of the level of detail. These assumptions include that the MTF is constant over the region of the retina that views the scene, is circularly symmetrical, and is wavelength independent. For a full discussion and details, please do read Caves & Johnsen (2018).

Author(s)

Thomas E. White thomas.white026@gmail.com

References

Caves, E. M., & Johnsen, S. (2018). AcuityView: An r package for portraying the effects of visual acuity on scenes observed by an animal. Methods in Ecology and Evolution, 9(3), 793-797 doi:10.1111/2041-210X.12911.

Chaikin, G. 1974. An algorithm for high speed curve generation. Computer Graphics and Image Processing 3, 346-349.

Examples

if (interactive()) {
  # Interactively add a scale to a single image
  papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))
  papilio <- procimg(papilio, scaledist = 10)

  # Interactively assign individual scales to each image,
  # after slightly reducing their size (to 90% of original).
  snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))
  snakes <- procimg(snakes, scaledist = c(10, 14), resize = 90)

  # Model the appearance of a butterfly given the reduced visual acuity of another
  # animal viewer as per the AcuityView algorithm. Here our butterfly is 60 cm away,
  # the image width is 10 cm, and the minimum resolvable angle of the viewer is 0.2-degrees.
  tiger <- getimg(system.file("testdata/images/tiger.png", package = "pavo"))
  tiger_acuity <- procimg(tiger, obj_dist = 60, obj_width = 10, eye_res = 0.2)
}

Process spectra

Description

Applies normalization and/or smoothing to spectra for further analysis or plotting.

Usage

procspec(
  rspecdata,
  opt = c("none", "smooth", "maximum", "minimum", "bin", "sum", "center"),
  fixneg = c("none", "addmin", "zero"),
  span = 0.25,
  bins = 20
)

Arguments

Value

A data frame of class rspec with the processed data.

Author(s)

Chad Eliason cme16@zips.uakron.edu

References

Cuthill, I., Bennett, A. T. D., Partridge, J. & Maier, E. 1999. Plumage reflectance and the objective assessment of avian sexual dichromatism. The American Naturalist, 153, 183-200.

Montgomerie R. 2006. Analyzing colors. In Hill, G.E, and McGraw, K.J., eds. Bird Coloration. Volume 1 Mechanisms and measurements. Harvard University Press, Cambridge, Massachusetts.

White, T. E., Dalrymple, R. L., Noble D. W. A., O'Hanlon, J. C., Zurek, D. B., Umbers, K. D. L. 2015. Reproducible research in the study of biological coloration. Animal Behaviour, 106, 51-57.

See Also

loess.smooth(), plotsmooth()

Examples

data(teal)
plot(teal, select = 10)

# Smooth data to remove noise
teal.sm <- procspec(teal, opt = "smooth", span = 0.25)
plot(teal.sm, select = 10)

# Normalize to max of unity
teal.max <- procspec(teal, opt = c("max"))
plot(teal.max, select = 10)

2D projection of a tetrahedral colourspace

Description

Produces a 2D projection plot of points in a tetrahedral colour space

Adds points to a tetrahedral colorspace projection

Usage

projplot(tcsdata, ...)

projpoints(tcsdata, ...)

Arguments

Value

projplot() creates a 2D plot of color points projected from the tetrahedron to its encapsulating sphere, and is ideal to visualize differences in hue.

projpoints() creates points in a projection color space plot produced by projplot().

Note

projplot() uses the Mollweide projection, and not the Robinson projection, which has been used in the past. Among other advantages, the Mollweide projection preserves area relationships within latitudes without distortion.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Examples

data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
projplot(tcs.sicalis, pch = 16, col = setNames(rep(seq_len(3), 7), rep(c("C", "T", "B"), 7)))

Plot the segment-analysis model

Description

Produces a plot based on Endler's (1990) segment analysis.

Usage

segplot(
  segdata,
  labels = TRUE,
  lab.cex = 0.9,
  out.lwd = 1,
  out.lty = 1,
  out.lcol = "black",
  tick.loc = c(-1, -0.5, 0.5, 1),
  square = TRUE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Endler, J. A. (1990) On the measurement and classification of colour in studies of animal colour patterns. Biological Journal of the Linnean Society, 41, 315-352.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "segment", achromatic = "all")
seg.flowers <- colspace(vis.flowers, space = "segment")
plot(seg.flowers)

Segment classification

Description

Calculates segment classification measures as defined in Endler (1990).

Usage

segspace(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• S1, S2, S3, S4: the relative reflectance at each of the four segments.

• LM, MS: segment scores

• C, H, B: 'chroma', 'hue' (degrees), and 'brightness' in the segment classification space

Author(s)

Thomas E. White thomas.white026@gmail.com

Pierre-Paul Bitton bittonp@uwindsor.ca

References

Endler, J. A. (1990) On the measurement and classification of colour in studies of animal colour patterns. Biological Journal of the Linnean Society, 41, 315-352.

Examples

data(sicalis)
vis.sic <- vismodel(sicalis, visual = "segment", achromatic = "all")
seg.sic <- colspace(vis.sic, space = "segment")

Retrieve or plot in-built spectral sensitivity data

Description

Retrieve (as an rspec object) or plot pavo's in-built spectral sensitivity data.

Usage

sensdata(
  visual = c("none", "all", "avg.uv", "avg.v", "bluetit", "ctenophorus", "star", "pfowl",
    "apis", "canis", "cie2", "cie10", "musca", "drosophila", "habronattus",
    "rhinecanthus"),
  achromatic = c("none", "all", "bt.dc", "ch.dc", "st.dc", "md.r1", "dm.r1", "ra.dc",
    "cf.r"),
  illum = c("none", "all", "bluesky", "D65", "forestshade"),
  trans = c("none", "all", "bluetit", "blackbird"),
  bkg = c("none", "all", "green"),
  plot = FALSE,
  ...
)

Arguments

Value

An object of class rspec (when plot = FALSE), containing a wavelength column "wl" and spectral data binned at 1 nm intervals from 300-700 nm.

Author(s)

Thomas E. White thomas.white026@gmail.com

Rafael Maia rm72@zips.uakron.edu

References

Sharkey, C. R., Blanco, J., Leibowitz, M. M., Pinto-Benito, D., & Wardill, T. J. (2020). The spectral sensitivity of Drosophila photoreceptors. Scientific reports, 10(1), 1-13.

Examples

# Plot the honeybee's receptors
sensdata(visual = "apis", ylab = "Absorbance", plot = TRUE)

# Plot the average UV vs V avian receptors
sensdata(visual = c("avg.v", "avg.uv"), ylab = "Absorbance", plot = TRUE)

# Retrieve the CIE colour matching functions as an rspec object
ciedat <- sensdata(visual = c("cie2", "cie10"))

Modeling spectral sensitivity

Description

Models spectral sensitivity (with oil droplets; optional) based on peak cone sensitivity according to the models of Govardovskii et al. (2000) and Hart & Vorobyev (2005).

Usage

sensmodel(
  peaksens,
  range = c(300, 700),
  lambdacut = NULL,
  Bmid = NULL,
  oiltype = NULL,
  beta = TRUE,
  om = NULL,
  integrate = TRUE,
  sensnames = NULL
)

Arguments

Value

A data frame of class rspec containing each cone model as a column.

Author(s)

Pierre-Paul Bitton bittonp@uwindsor.ca

Chad Eliason cme16@zips.uakron.edu

References

Govardovskii VI, Fyhrquist N, Reuter T, Kuzmin DG and Donner K. 2000. In search of the visual pigment template. Visual Neuroscience 17:509-528, doi:10.1017/S0952523800174036

Hart NS, and Vorobyev M. 2005. Modeling oil droplet absorption spectra and spectral sensitivities of bird cone photoreceptors. Journal of Comparative Physiology A. 191: 381-392, doi:10.1007/s00359-004-0595-3

Hart NS, Partridge JC, Cuthill IC, Bennett AT (2000) Visual pigments, oil droplets, ocular media and cone photoreceptor distribution in two species of passerine bird: the blue tit (Parus caeruleus L.) and the blackbird (Turdus merula L.). J Comp Physiol A 186:375-387, doi:10.1007/s003590050437

Examples

# Blue tit visual system based on Hart et al (2000)
bluesens <- sensmodel(c(371, 448, 502, 563),
  beta = FALSE,
  lambdacut = c(330, 413, 507, 572),
  oiltype = c("T", "C", "Y", "R"), om = TRUE
)

# Danio aequipinnatus based on Govardovskii et al. (2000)
daniosens <- sensmodel(c(357, 411, 477, 569))

Spectral curves from three body regions of stripe-tailed yellow finch (Sicalis citrina) males

Description

Dataset containing reflectance measurements from 3 body parts ("C": crown, "B": breast, "T": throat) from seven male stripe-tailed yellow finches (Sicalis citrina)

Usage

data(sicalis)

Format

An object of class rspec (inherits from data.frame) with 401 rows and 22 columns.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Simulate a spectrum

Description

Simulate a naturalistic reflectance, radiance, irradiance, or transmission spectrum. Curves may have sigmoidal (s-shaped) and/or Gaussian (bell-shaped) features. Multiple Gaussian and sigmoidal curves can be combined in a single spectrum, to simulate more complex spectral functions.

Usage

simulate_spec(
  wl_inflect = NULL,
  wl_peak = NULL,
  width_sig = 20,
  width_gauss = 70,
  skew_gauss = 0,
  xlim = c(300, 700),
  ylim = c(0, 100)
)

Arguments

Value

An object of class rspec.

Author(s)

Thomas White thomas.white026@gmail.com

Hugo Gruson hugo.gruson+R@normalesup.org

References

Azzalini A (1985). A class of distributions which includes the normal ones. Scan. J. Stat. 171-178.

Examples

# Single ideal 'grey' reflectance spectrum, with 50% reflectance across 300 - 700 nm.
reflect0 <- simulate_spec(ylim = c(0, 50))

# Single sigmoidal spectrum, with a low-to-high inflection at 550 nm.
reflect1 <- simulate_spec(wl_inflect = 550)

# Single Gaussian spectrum, with a peak at 400 nm
reflect2 <- simulate_spec(wl_peak = 400)

# Combination of both Gaussian (with peak at 340 nm) and sigmoidal (with inflection
# at 560 nm)
reflect3 <- simulate_spec(wl_inflect = 560, wl_peak = 340)

# Double-Gaussian peaks of differing widths
reflect4 <- simulate_spec(wl_peak = c(340, 560), width_gauss = c(12, 40))

# Complex spectrum with single sigmoidal peak and multi-Gaussian peaks
reflect5 <- simulate_spec(wl_inflect = 575, wl_peak = c(340, 430), width_gauss = c(20, 60))

# Simulate a set of Gaussian reflectance curves with peaks varying between 400-600nm
# in increments of 10, then combine into a single rspec object, and plot the result
peaks <- seq(400, 600, 10)  # Peak locations
reflectances <- lapply(seq_along(peaks), function(x) simulate_spec(wl_peak = peaks[x]))  # Simulate
reflectances <- Reduce(merge, reflectances)  # Combine
plot(reflectances)  # Plot

# Simulate a set of Gaussian reflectance curves with a single peak at 500 nm, but
# with maximum reflectance varying from 30 to 90% in 10% increments, then combine
# into a single rspec object, and plot the result
ymax <- lapply(seq(30, 90, 10), function(x) c(0, x))  # Varying reflectance maxima
reflectances2 <- lapply(ymax, function(x) simulate_spec(wl_peak = 500, ylim = x))  # Simulate
reflectances2 <- Reduce(merge, reflectances2)  # Combine
plot(reflectances2)  # Plot

# To simulate non-reflectance spectra (like irradiances or radiances), it's often useful
# to explore more 'extreme' parameters. Here's a simple example which simulates
# natural daylight, as represented by the D65 standard daylight spectrum.
D65_real <- procspec(sensdata(illum = 'D65'), opt = 'smooth')  # Official D65 daylight spectrum
D65_sim <- simulate_spec(wl_peak = 400,
                         width_gauss = 1300,
                         skew_gauss = 10,
                         ylim = c(0, 1))  # Simulated D65
cor.test(D65_real$D65, D65_sim$spec_p400)  # >0.99 correlation
plot(merge(D65_real, D65_sim), lty = 1:2, ylab = 'Irradiance (%)')  # Merge and plot the two spectra

Spectrum to rgb colour conversion

Description

Calculates rgb values from spectra based on human colour matching functions.

Usage

spec2rgb(rspecdata, alpha = 1)

Arguments

Value

A character vector consisting of hexadecimal colour values for passing to further plotting functions.

Author(s)

Hugo Gruson hugo.gruson+R@normalesup.org

Chad Eliason cme16@zips.uakron.edu

References

CIE(1932). Commission Internationale de l'Eclairage Proceedings, 1931. Cambridge: Cambridge University Press.

Examples

data(teal)
spec2rgb(teal)

# Plot data using estimated perceived colour
plot(teal, col = spec2rgb(teal), type = "overlay")

Subset rspec, vismodel, and colspace objects

Description

Subsets various object types based on a given vector or grep partial matching of data names.

Usage

## S3 method for class 'rspec'
subset(x, subset, ...)

## S3 method for class 'colspace'
subset(x, subset, ...)

## S3 method for class 'vismodel'
subset(x, subset, ...)

Arguments

Value

a subsetted object of the same class as the input object.

Note

if more than one value is given to subset, any spectra that matches either condition will be included. It's a union, not an intersect.

Author(s)

Chad Eliason cme16@zips.uakron.edu

Examples

data(sicalis)
vis.sicalis <- vismodel(sicalis)
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")

# Subset all 'crown' patches (C in file names)
head(subset(sicalis, "C"))
head(subset(sicalis, c("B", "C")))
head(subset(sicalis, "T", invert = TRUE))
subset(vis.sicalis, "C")
subset(tcs.sicalis, "C")[, seq_len(5)]

Colourspace data summary

Description

Returns the attributes of colspace objects.

Usage

## S3 method for class 'colspace'
summary(object, by = NULL, ...)

Arguments

Value

returns all attributes of the data as mapped to the selected colourspace, including options specified when calculating the visual model. Also return the default data.frame summary, except when the object is the result of tcspace(), in which case the following variables are output instead:

• ⁠centroid.u, .s, .m, .l⁠ the centroids of usml coordinates of points.

• c.vol the total volume occupied by the points, computed with a convex hull.

• rel.c.vol volume occupied by the points (convex hull volume) relative to the tetrahedron volume.

• colspan.m the mean hue span.

• colspan.v the variance in hue span.

• huedisp.m the mean hue disparity.

• huedisp.v the variance in hue disparity.

• mean.ra mean saturation.

• max.ra maximum saturation achieved by the group of points.

• a.vol colour volume computed with \alpha-shapes.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Gruson H. (2020). Estimation of colour volumes as concave hypervolumes using \alpha-shapes. Methods in Ecology and Evolution, 11(8), 955-963 doi:10.1111/2041-210X.13398

Examples

# Colour hexagon
data(flowers)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, bkg = "green"
)
flowers.hex <- hexagon(vis.flowers)
summary(flowers.hex)

# Tetrahedral model
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
csp.sicalis <- colspace(vis.sicalis)
summary(csp.sicalis, by = rep(c("C", "T", "B"), 7))

Image summary

Description

Returns the attributes of, and optionally plots, an image.

Usage

## S3 method for class 'rimg'
summary(object, plot = FALSE, axes = TRUE, col = NULL, ...)

Arguments

Value

Either the RGB values of the k-means centres from the colour-classified image, or a plot of both the image and specified colours (when plot = TRUE).

Author(s)

Thomas E. White thomas.white026@gmail.com

Examples

papilio <- getimg(system.file("testdata/images/butterflies/papilio.png", package = "pavo"))
papilio_class <- classify(papilio, kcols = 4)
summary(papilio_class)

# Plot the colour-classified image alongside the colour class palette
summary(papilio_class, plot = TRUE)

# Multiple images
snakes <- getimg(system.file("testdata/images/snakes", package = "pavo"))
snakes_class <- classify(snakes, kcols = 3)
summary(snakes_class, plot = TRUE)

Colourimetric variables

Description

Calculates all 23 colourimetric variables reviewed in Montgomerie (2006).

Usage

## S3 method for class 'rspec'
summary(object, subset = FALSE, lim = NULL, wlmin = NULL, wlmax = NULL, ...)

Arguments

Value

A data frame containing either 23 or 5 (subset = TRUE) variables described in Montgomerie (2006) with spectra name as row names. The colorimetric variables calculated by this function are described in Montgomerie (2006) with corrections included in the README CLR file from the May 2008 distribution of the CLR software. Authors should reference both this package,Montgomerie (2006), and the original reference(s). Description and notes on the measures:

B1 (Total brightness): Sum of the relative reflectance over the entire spectral range (area under the curve). Frequently used but should be discouraged because values are difficult to compare across studies (B2 is preferred). REF 1-3, 7, 9-11, 13

B2 (Mean brightness): Mean relative reflectance over the entire spectral range. This is preferred to B1 since values are easier to compare across studies. REF 4, 12

B3 (Intensity): Maximum relative reflectance (Reflectance at wavelength of maximum reflectance). Note that may be sensitive to noise near the peak. REF 1, 5, 6

S1 (Chroma): Relative contribution of a spectral range to the total brightness (B1) S1 is arbitrarily divided in 6 measures of chroma based on the wavelength ranges normally associated with specific hues. The values are calculated using the following ranges: S1U (UV, if applicable): lambda min-400nm; S1V (Violet) lambda min-415nm; S1B (Blue) 400nm-510nm; S1G (Green) 510nm-605nm; S1Y (Yellow) 550nm-625nm; S1R (Red) 605nm-lambda max. REF 2, 7, 8, 11-13

S2 (Spectral saturation): Rmax/Rmin This measure is sensitive to spectral noise. Proper interpretation of this value may be difficult for spectra with multiple peaks in the range of interest. REF 1

S3 (Chroma): Reflectance over the Rmax +- 50nm range divided by B1. Values for peaks within 50nm of either the minimum or maximum range of the data will not be comparable since the area under the curve for the area of interest will not always be based on the same wavelength range. Therefore, S3 should be interpreted with caution for peaks in the UV or Red range. REF 11

S4 (Spectral purity): |bmaxneg| , calculated by approximating the derivative of the spectral curve. As such, it is very sensitive to noise and should only be considered when data is adequately smoothed. NAs are returned for curves which do not, at any range of wavelength, decrease in intensity. Therefore, reflectance curves for brown and red surfaces, for example, should not generate a values. REF 1

S5 (Chroma): Similar in design to segment classification measures (see Montgomerie 2006 for details). REF 10

S6 (Contrast): Rmax - Rmin. Because it uses both Rmin and Rmax, this measure may be sensitive to spectral noise. REF 5, 6

S7 (Spectral saturation): Difference between the relative reflectance before and after the wavelength at which reflectance is halfway between its minimum (Rmin) and its maximum (Rmax). Somewhat sensitive to noise and can be misleading when more than one maxima and/or minima are present. REF 3, 9

S8 (Chroma): (Rmax - Rmin)/B2. Because it uses both Rmin and Rmax, this measure may be sensitive to spectral noise. REF 3, 13

S9 (Carotenoid chroma): (R700 - R450)/R700. Should only be used when the colour of the surface is clearly due to carotenoid pigmentation and R450 is lower than R700. Could be sensitive to noise. REF 8

S10 (Peaky chroma): (Rmax - Rmin)/B2 x |bmaxneg|. Should be used with properly smoothed curves. REF 7

H1 (Peak wavelength, hue): Wavelength of maximum reflectance. May be sensitive to noise and may be variable if there is more than one maxima. REF 1, 2, 4, 6, 7, 10-13

H2 (Hue): Wavelength at bmaxneg. Should be calculated using smoothed data. REF 2, 13

H3 (Hue): Wavelength at Rmid. Sensitive to noisy spectra and may be variable if there are more than one maxima and minima. REF 3, 9, 13

H4 (Hue): Similar in design to segment classification measures see Montgomerie (2006) for details. REF 10

H5 (Hue): Wavelength at bmax. Sensitive to noise and may be variable if there is more than one maxima and minima. REF 5

Note

If minimum wavelength is over 400, UV chroma is not computed.

Variables which compute bmax and bmaxneg should be used with caution, for they rely on smoothed curves to remove noise, which would otherwise result in spurious results. Make sure chosen smoothing parameters are adequate.

Smoothing affects only B3, S2, S4, S6, S10, H2, and H5 calculation. All other variables can be reliably extracted using non-smoothed data.

Author(s)

Thomas E. White thomas.white026@gmail.com

Pierre-Paul Bitton bittonp@windsor.ca

Rafael Maia rm72@zips.uakron.edu

References

Montgomerie R. 2006. Analyzing colors. In Hill, G.E, and McGraw, K.J., eds. Bird Coloration. Volume 1 Mechanisms and measurements. Harvard University Press, Cambridge, Massachusetts.

References describing variables:

1- Andersson, S. 1999. Morphology of uv reflectance in a whistling-thrush: Implications for the study of structural colour signalling in birds. Journal of Avian Biology 30:193-204.

2- Andersson, S., J. Ornborg, and M. Andersson. 1998. Ultraviolet sexual dimorphism and assortative mating in blue tits. Proceedings of the Royal Society B 265:445-450.

3- Andersson, S., S. Pryke, J. Ornborg, M. Lawes, and M. Andersson. 2002. Multiple receivers, multiple ornaments, and a trade-off between agonistic and epigamic signaling in a widowbird. American Naturalist 160:683-691.

4- Delhey, K., A. Johnsen, A. Peters, S. Andersson, and B. Kempenaers. 2003. Paternity analysis reveals opposing selection pressures on crown coloration in the blue tit (Parus caeruleus). Proceedings of the Royal Society B 270:2057-2063.

5- Keyser, A. and G. Hill. 1999. Condition-dependent variation in the blue-ultraviolet coloration of a structurally based plumage ornament. Proceedings of the Royal Society B 266:771-777.

6- Keyser, A.J. and G. Hill. 2000. Structurally based plumage coloration is an honest signal of quality in male blue grosbeaks. Behavioural Ecology 11:202-209.

7- Ornborg, J., S. Andersson, S. Griffith, and B. Sheldon. 2002. Seasonal changes in a ultraviolet structural colour signal in blue tits, Parus caeruleus. Biological Journal of the Linnean Society 76:237-245.

8- Peters, A., A. Denk, K. Delhey, and B. Kempenaers. 2004. Carotenoid-based bill colour as an indicator of immunocompetence and sperm performance in male mallards. Journal of Evolutionary Biology 17:1111-1120.

9- Pryke, S., M. Lawes, and S. Andersson. 2001. Agonistic carotenoid signalling in male red-collared widowbirds: Aggression related to the colour signal of both the territory owner and model intruder. Animal Behaviour 62:695-704.

10- Saks, L., K. Mcgraw, and P. Horak. 2003. How feather colour reflects its carotenoid content. Functional Ecology 17:555-561.

11- Shawkey, M., A. Estes, L. Siefferman, and G. Hill. 2003. Nanostructure predicts intraspecific variation in ultraviolet-blue plumage colour. Proceedings of the Royal Society B 270:1455-1460.

12- Siefferman, L. and G. Hill. 2005. UV-blue structural coloration and competition for nestboxes in male eastern bluebirds. Animal Behaviour 69:67-72.

13- Smiseth, P., J. Ornborg, S. Andersson, and T. Amundsen. 2001. Is male plumage reflectance correlated with paternal care in bluethroats? Behavioural Ecology 12:164-170.

Examples

# Load data
data(sicalis)

# Calculate and display all spectral summary variables
summary(sicalis)

# Calculate only subset of B2, S8 and H1 as per Andersson (1999)
summary(sicalis, subset = TRUE)

# Calculate user-specified subset of B1 and H4
summary(sicalis, subset = c("B1", "H4"))

Visual model summary

Description

Returns the attributes used when calculating a visual model using vismodel()

Usage

## S3 method for class 'vismodel'
summary(object, ...)

Arguments

Value

Returns all attributes chosen when calculating the visual model, as well as the default data.frame summary

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Vorobyev, M., Osorio, D., Bennett, A., Marshall, N., & Cuthill, I. (1998). Tetrachromacy, oil droplets and bird plumage colours. Journal Of Comparative Physiology A-Neuroethology Sensory Neural And Behavioral Physiology, 183(5), 621-633.

Hart, N. S. (2001). The visual ecology of avian photoreceptors. Progress In Retinal And Eye Research, 20(5), 675-703.

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Examples

data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
summary(vis.sicalis)

Tetrahedral colourspace

Description

Calculates coordinates and colorimetric variables that represent reflectance spectra in the avian tetrahedral color space.

Usage

tcspace(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• u, s, m, l: the quantum catch data used to calculate the remaining variables. NOTE: even if visual system is of type V-VIS, the output column will be labeled u.

• u.r, s.r, m.r, l.r: relative cone stimulation, for a given hue, as a function of saturation. See Stoddard & Prum (2008) for details.

• x, y, z: cartesian coordinates for the points in the tetrahedral color space.

• h.theta, h.phi: angles theta and phi, in radians, determining the hue of the color.

• r.vec: the r vector (saturation, distance from the achromatic center).

• r.max: the maximum r vector achievable for the colour's hue.

• r.achieved: the relative r distance from the achromatic center, in relation to the maximum distance achievable (r.vec/r.max).

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Examples

data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")

Interactive plot of a tetrahedral colourspace

Description

Produces an interactive 3D plot of a tetrahedral colourspace using OpenGL capabilities.

Plots points in a tetrahedral colour space

Usage

tcsplot(
  tcsdata,
  size = 0.02,
  alpha = 1,
  col = "black",
  vertexsize = 0.02,
  achro = TRUE,
  achrosize = 0.01,
  achrocol = "grey",
  lwd = 1,
  lcol = "lightgrey",
  new = FALSE,
  hspin = FALSE,
  vspin = FALSE,
  floor = TRUE,
  gamut = FALSE
)

tcspoints(tcsdata, size = 0.02, col = "black", alpha = 1)

tcsvol(
  tcsdata,
  type = c("convex", "alpha"),
  avalue = "auto",
  col = "black",
  alpha = 0.2,
  grid.alpha = 1,
  grid = TRUE,
  fill = TRUE,
  lwd = 1
)

Arguments

Value

tcsplot() creates a 3D plot using functions of the package rgl, based on openGL capabilities. Plot is interactive and can be manipulated with the mouse (left button: rotate along 'z' axis; right button: rotate along 'x' axis; third button: zoom).

tcspoints() adds points to the plot. Points are currently plotted only as spheres to maintain export capabilities.

tcsvol() creates a 3D colour volume within a tcsplot object.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Examples

# For plotting
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
tcsplot(tcs.sicalis, size = 0.005)
rgl::rgl.postscript("testplot.pdf", fmt = "pdf")
rgl::rgl.snapshot("testplot.png")

# For adding points
patch <- rep(c("C", "T", "B"), 7)
tcs.crown <- subset(tcs.sicalis, "C")
tcs.breast <- subset(tcs.sicalis, "B")
tcsplot(tcs.crown, col = "blue")
tcspoints(tcs.breast, col = "red")

# For plotting convex hull
tcsplot(tcs.sicalis, col = "blue", size = 0.005)
tcsvol(tcs.sicalis)

Angle-resolved reflectance data for the iridescent wing patch of a male green-winged teal (Anas carolinensis)

Description

Dataset containing reflectance measurements from the wing patch of a single male at different incident angles (15-75 degrees in 5-degree increments).

Usage

data(teal)

Format

An object of class rspec (inherits from data.frame) with 401 rows and 13 columns.

Author(s)

Chad Eliason cme16@zips.uakron.edu

Plot a static tetrahedral colorspace

Description

Produces a static 3D tetrahedral plot.

Usage

tetraplot(
  tcsdata,
  theta = 45,
  phi = 10,
  perspective = FALSE,
  range = c(1, 2),
  r = 1e+06,
  zoom = 1,
  achro = TRUE,
  achro.col = "grey",
  achro.size = 1,
  achro.line = FALSE,
  achro.lwd = 1,
  achro.lty = 3,
  tetrahedron = TRUE,
  vert.cex = 1,
  vert.range = c(1, 2),
  out.lwd = 1,
  out.lcol = "darkgrey",
  type = "p",
  labels = FALSE,
  gamut = FALSE,
  ...
)

Arguments

Value

tetraplot() creates a non-interactive 3D plot.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Thomas White thomas.white026@gmail.com

Chad Eliason cme16@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Examples

# For plotting
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
plot(tcs.sicalis)

Default ocular transmission data

Description

Default ocular transmission data

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Hart, N. S., Partridge, J. C., Cuthill, I. C., Bennett, A. T. D. (2000). Visual pigments, oil droplets, ocular media and cone photoreceptor distribution in two species of passerine

Plot a Maxwell triangle

Description

Produces a Maxwell triangle plot.

Usage

triplot(
  tridata,
  labels = TRUE,
  achro = TRUE,
  achrocol = "grey",
  achrosize = 0.8,
  labels.cex = 1,
  out.lwd = 1,
  out.lcol = "black",
  out.lty = 1,
  square = TRUE,
  gamut = FALSE,
  ...
)

Arguments

Author(s)

Thomas White thomas.white026@gmail.com

References

Maxwell JC. (1970). On color vision. In: Macadam, D. L. (ed) Sources of Color Science. Cambridge, MIT Press, 1872 - 1873.

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

MacLeod DIA, Boynton RM. (1979). Chromaticity diagram showing cone excitation by stimuli of equal luminance. Journal of the Optical Society of America, 69, 1183-1186.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "apis")
tri.flowers <- colspace(vis.flowers, space = "tri")
plot(tri.flowers)

Trichromatic colour space

Description

Calculates coordinates and colourimetric variables that represent reflectance spectra in a trichromatic chromaticity space.

Usage

trispace(vismodeldata)

Arguments

Value

A data frame of class colspace consisting of the following columns:

• s, m, l: the quantum catch data used to calculate the remaining variables.

• x, y: cartesian coordinates for the points in the Maxwell triangle.

• h.theta: angle theta, in radians, determining the hue of the colour.

• r.vec: the r vector (saturation, distance from the center).

Author(s)

Thomas E. White thomas.white026@gmail.com

References

Maxwell JC. (1970). On color vision. In: Macadam, D. L. (ed) Sources of Color Science. Cambridge, MIT Press, 1872 - 1873.

Kelber A, Vorobyev M, Osorio D. (2003). Animal colour vision - behavioural tests and physiological concepts. Biological Reviews, 78, 81 - 118.

MacLeod DIA, Boynton RM. (1979). Chromaticity diagram showing cone excitation by stimuli of equal luminance. Journal of the Optical Society of America, 69, 1183-1186.

Examples

data(flowers)
vis.flowers <- vismodel(flowers, visual = "apis", achromatic = "l")
tri.flowers <- colspace(vis.flowers, space = "tri")

vertex for the tetrahedral color space

Description

internal data for plotting devices.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Visual models

Description

Calculates quantum catches at each photoreceptor. Both raw and relative values can be returned, for use in a suite of colourspace and non-colourspace models.

Usage

vismodel(
  rspecdata,
  visual = c("avg.uv", "avg.v", "bluetit", "ctenophorus", "star", "pfowl", "apis",
    "canis", "cie2", "cie10", "musca", "drosophila", "segment", "habronattus",
    "rhinecanthus"),
  achromatic = c("none", "bt.dc", "ch.dc", "st.dc", "md.r1", "dm.r1", "ra.dc", "cf.r",
    "ml", "l", "all"),
  illum = c("ideal", "bluesky", "D65", "forestshade"),
  trans = c("ideal", "bluetit", "blackbird"),
  qcatch = c("Qi", "fi", "Ei"),
  bkg = c("ideal", "green"),
  vonkries = FALSE,
  scale = 1,
  relative = TRUE
)

Arguments

Value

An object of class vismodel containing the photon catches for each of the photoreceptors considered. Information on the parameters used in the calculation are also stored and can be called using the summary.vismodel() function.

Note

Built-in visual, achromatic, illum, bkg and trans are only defined on the 300 to 700nm wavelength range. If you wish to work outside this range, you will need to provide your own data.

Author(s)

Thomas E. White thomas.white026@gmail.com

Rafael Maia rm72@zips.uakron.edu

References

Vorobyev, M., Osorio, D., Bennett, A., Marshall, N., & Cuthill, I. (1998). Tetrachromacy, oil droplets and bird plumage colours. Journal Of Comparative Physiology A-Neuroethology Sensory Neural And Behavioral Physiology, 183(5), 621-633.

Hart, N. S., Partridge, J. C., Cuthill, I. C., Bennett, A. T. D. (2000). Visual pigments, oil droplets, ocular media and cone photoreceptor distribution in two species of passerine bird: the blue tit (Parus caeruleus L.) and the blackbird (Turdus merula L.). Journal of Comparative Physiology A, 186, 375-387.

Hart, N. S. (2001). The visual ecology of avian photoreceptors. Progress In Retinal And Eye Research, 20(5), 675-703.

Barbour H. R., Archer, M. A., Hart, N. S., Thomas, N., Dunlop, S. A., Beazley, L. D, Shand, J. (2002). Retinal characteristics of the Ornate Dragon Lizard, Ctenophorus ornatus.

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Chittka L. (1992). The colour hexagon: a chromaticity diagram based on photoreceptor excitations as a generalized representation of colour opponency. Journal of Comparative Physiology A, 170(5), 533-543.

Stockman, A., & Sharpe, L. T. (2000). Spectral sensitivities of the middle- and long-wavelength sensitive cones derived from measurements in observers of known genotype. Vision Research, 40, 1711-1737.

CIE (2006). Fundamental chromaticity diagram with physiological axes. Parts 1 and 2. Technical Report 170-1. Vienna: Central Bureau of the Commission Internationale de l' Eclairage.

Neitz, J., Geist, T., Jacobs, G.H. (1989) Color vision in the dog. Visual Neuroscience, 3, 119-125.

Sharkey, C. R., Blanco, J., Leibowitz, M. M., Pinto-Benito, D., & Wardill, T. J. (2020). The spectral sensitivity of Drosophila photoreceptors. Scientific reports, 10(1), 1-13.

See Also

sensdata() to retrieve or plot in-built spectral sensitivity data used in vismodel()

Examples

# Dichromat (dingo)
data(flowers)
vis.dingo <- vismodel(flowers, visual = "canis")
di.dingo <- colspace(vis.dingo, space = "di")

# Trichromat (honeybee)
data(flowers)
vis.bee <- vismodel(flowers, visual = "apis")
tri.bee <- colspace(vis.bee, space = "tri")

# Tetrachromat (blue tit)
data(sicalis)
vis.bluetit <- vismodel(sicalis, visual = "bluetit")
tcs.bluetit <- colspace(vis.bluetit, space = "tcs")

# Tetrachromat (starling), receptor-noise model
data(sicalis)
vis.star <- vismodel(sicalis, visual = "star", achromatic = "bt.dc", relative = FALSE)
dist.star <- coldist(vis.star, achromatic = TRUE)

# Estimate quantum catches using a custom trichromatic visual phenotype
custom <- sensmodel(c(330, 440, 550))
names(custom) <- c("wl", "s", "m", "l")
vis.custom <- vismodel(flowers, visual = custom)
tri.custom <- colspace(vis.custom, space = "tri")

Animal visual systems data

Description

Internal data for visual model calculations.

Author(s)

Rafael Maia rm72@zips.uakron.edu

References

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Plot a tetrahedral colour space

Description

Produces a 3D colour volume in tetrahedral colour space when plotting a non-interactive tetrahedral plot.

Usage

vol(
  tcsdata,
  type = c("convex", "alpha"),
  avalue = "auto",
  alpha = 0.2,
  grid = TRUE,
  fill = TRUE,
  new = FALSE,
  ...
)

Arguments

Value

vol() creates a 3D colour volume within a static tetrahedral plot.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Hugo Gruson

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Stoddard, M. C., & Stevens, M. (2011). Avian vision and the evolution of egg color mimicry in the common cuckoo. Evolution, 65(7), 2004-2013.

Maia, R., White, T. E., (2018) Comparing colors using visual models. Behavioral Ecology, ary017 doi:10.1093/beheco/ary017

Gruson H. (2020). Estimation of colour volumes as concave hypervolumes using \alpha-shapes. Methods in Ecology and Evolution, 11(8), 955-963 doi:10.1111/2041-210X.13398

Examples

# For plotting
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
tcs.sicalis <- colspace(vis.sicalis, space = "tcs")
plot(tcs.sicalis)

# Convex hull
vol(tcs.sicalis, type = "convex")

# Alpha-shape
if (require("alphashape3d")) {
  vol(tcs.sicalis, type = "alpha", avalue = 1)
}

Colour volume overlap

Description

Calculates the overlap between the volumes defined by two sets of points in cartesian space.

Usage

voloverlap(
  colsp1,
  colsp2,
  type = c("convex", "alpha"),
  avalue = "auto",
  plot = FALSE,
  interactive = FALSE,
  col = c("blue", "red", "darkgrey"),
  fill = FALSE,
  new = TRUE,
  nsamp = 1000,
  psize = 0.001,
  lwd = 1,
  ...
)

Arguments

Value

Calculates the overlap between the volumes defined by two set of points in colourspace. The volume from the overlap is then given relative to:

• vsmallest the volume of the overlap divided by the smallest of that defined by the the two input sets of colour points. Thus, if one of the volumes is entirely contained within the other, this overlap will be vsmallest = 1.

• vboth the volume of the overlap divided by the combined volume of both input sets of colour points. If type = "alpha", If used, the output will be different:

• ⁠s_in1, s_in2⁠ the number of sampled points that fall within each of the volumes individually.

• s_inboth the number of sampled points that fall within both volumes.

• s_ineither the number of points that fall within either of the volumes.

• psmallest the proportion of points that fall within both volumes divided by the number of points that fall within the smallest volume.

• pboth the proportion of points that fall within both volumes divided by the total number of points that fall within both volumes.

Note

Stoddard & Stevens (2011) originally obtained the volume overlap through Monte Carlo simulations of points within the range of the volumes, and obtaining the frequency of simulated values that fall inside the volumes defined by both sets of colour points.

Stoddard & Stevens (2011) also return the value of the overlap relative to one of the volumes (in that case, the host species). However, for other applications this value may not be what one expects to obtain if (1) the two volumes differ considerably in size, or (2) one of the volumes is entirely contained within the other. For this reason, we also report the volume relative to the union of the two input volumes, which may be more adequate in most cases.

Author(s)

Rafael Maia rm72@zips.uakron.edu

Hugo Gruson hugo.gruson+R@normalesup.org

References

Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage color in a tetrahedral color space: A phylogenetic analysis of new world buntings. The American Naturalist, 171(6), 755-776.

Stoddard, M. C., & Stevens, M. (2011). Avian vision and the evolution of egg color mimicry in the common cuckoo. Evolution, 65(7), 2004-2013.

Maia, R., White, T. E., (2018) Comparing colors using visual models. Behavioral Ecology, ary017 doi:10.1093/beheco/ary017

Gruson H. (2020). Estimation of colour volumes as concave hypervolumes using \alpha-shapes. Methods in Ecology and Evolution, 11(8), 955-963 doi:10.1111/2041-210X.13398

Examples

data(sicalis)
tcs.sicalis.C <- subset(colspace(vismodel(sicalis)), "C")
tcs.sicalis.T <- subset(colspace(vismodel(sicalis)), "T")
tcs.sicalis.B <- subset(colspace(vismodel(sicalis)), "B")

# Convex hull volume
voloverlap(tcs.sicalis.T, tcs.sicalis.B, type = "convex")
voloverlap(tcs.sicalis.T, tcs.sicalis.C, type = "convex", plot = TRUE)
voloverlap(tcs.sicalis.T, tcs.sicalis.C, type = "convex", plot = TRUE, col = seq_len(3))

# Alpha-shape volume
if (require("alphashape3d")) {
  voloverlap(tcs.sicalis.T, tcs.sicalis.B, type = "alpha", avalue = 1)
}