An introduction to pavo 1.0
Rafael Maia, Thomas White, Chad Eliason, Pierre-Paul Bitton
2016-12-05
Introduction
We are happy to introduce the stable release of pavo 1.0, which — among other things — includes a suite of new analysis and visualisation tools to make working with color data simpler and more intuitive than ever.
While we have made improvements that will expedite data organisation, the most significant developments in 1.0 relate to the analysis and visualisation of color data. This includes greater flexibility in the initial visual modelling process, and a host of new colorspace models and associated plotting options which are accessable through a simplified workflow. Below we will provide an overview of the main new features introduced in 1.0 in an example workflow.
A Quick Guide For Familiar Users
We detail the changes and additions to the package below, but frequent users should be aware of the following main changes:
vismodelcan now incorporate wavelength-dependent transmission (such as from ocular media or turbid environment) and hyperbolic transformation of quantum catches. It also includes several new build-in visual systems.- the new
colspacefunction replaces the oldtcsfunction, and expands colorspace calculations by incorporating a series of different di-, tri- and tetrachromatic colorspaces. - there are now
plotoptions that work directly withcolspaceresults, including a static tetrahedral plot, which is more convenient when producing publication-quality figures. - the
coldistfunction has undergone significant changes to its imput arguments. Mainly, instead of specifying the single-cone noisevand then1, n2, n3andn4relative cone densities, users now (a) specify the desired weber fraction for the reference cone using the argumentweber, (b) which cone to be used as the reference cone with the argumentweber.ref, and (c) a single vector with the relative cone densities through thenargument. Explanations for these changes follow below. The achromatic Weber fraction can now also be specified separately through theweber.achroargument. - besides the familiar distances in JND for receptor noise models,
coldistnow also calculates color distances for the other colorspaces available throughcolspace: Euclidean distances in the hexagon, cielab and categorical spaces, and manhattan (city-bloc) distances in the color-opponent-coding space. getspecnow has a fast algorithm that speeds up importing spectra. The fast version will only work when all files have the same format.getspecattempts to use it first, and if it fails, it will switch to the old algorithm. (the slow version can also be chosen with the argumentfast=FALSE)
New flowers Dataset
data(flowers) is a new example dataset consisting of reflectance spectra from 36 Australian angiosperm species. which we’ll use to illustrate many of the new features in this document.
data(flowers)
flowercols <- spec2rgb(flowers)
head(flowers[1:4])## wl Goodenia_heterophylla Goodenia_geniculata Goodenia_gracilis
## 1 300 1.7426387 1.918962 0.3638354
## 2 301 1.5724849 1.872966 0.3501921
## 3 302 1.4099808 1.828019 0.3366520
## 4 303 1.2547709 1.784152 0.3231911
## 5 304 1.1064997 1.741398 0.3097854
## 6 305 0.9648117 1.699792 0.2964107plot(flowers, lwd = 2, col = flowercols)
The flower dataset
Visual Modelling
Visual Phenotypes
pavo 1.0introduced several new di-, tri- and tetrachromatic visual systems, to accompany the suite of new models. The full complement of included systems are accessable via thevismodel()argumentvisual:avg.uvaverage ultraviolet-sensitive avian (tetrachromat)avg.vaverage violet-sensitive avian (tetrachromat)bluetitThe blue tit Cyanistes caeruleus (tetrachromat)starThe starling Sturnus vulgaris (tetrachromat)pfowlThe peafowl Pavo cristatus (tetrachromat)apisThe honeybee Apis mellifera (trichromat)canisThe canid Canis familiaris (dichromat)muscaThe housefly Musca domestica (tetrachromat)cie22-degree color matching functions for CIE models of human color vision (trichromat)cie1010-degree color matching functions for CIE models of human color vision (trichromat)
As in previous versions, the individual sensitivity functions can be accessed via a call to vissyst, and visualised using plot. For example:
plot(vissyst[, c('wl', grep('musca|md', names(vissyst), value = TRUE))], main = 'Musca domestica', ylab = 'Absorbance', lwd = 2)
The visual sensitivities of the muscoid fly Musca domestica.
The vismodel Function and Receptor-Noise Limited Model
Incorporating transmission into visual models. The vismodel function is the first point of contact for visual modelling, as it estimates raw or relative photoreceptor stimulation. In 1.0, we’ve introduced a new argument, trans, which allows for the explicit modelling of the effects of light transmission (e.g. through noisy environments or ocular filters). The argument defaults to ideal (i.e. no effect), though we can also use the built-in options of bluetit or blackbird to model the ocular transmission of blue tits/blackbirds, or specify a user-defined vector containing transmission spectra.
plot(transmissiondata, lwd = 2, ylab = 'Transmission', main = 'Ocular transmission', col = c('red', 'blue'))
Transmission example: Ocular transmission for the blue tit (red) and blackbird (blue) retinas.
Hyperbolic transformation of quantum catches. Some of the default options for existing arguments have been expanded, such as the visual and achromatic arguments as outlined above. A significant new inclusion is the qcatch = 'Ei' option, which specifies the hyperbolic transformation of quantum catches according to:
\[E_i = \frac{Q_i}{Q_i + 1}\]
Where Ei is the ’excitation value` for photoreceptor i, and Qi is the raw quantum catch of said photoreceptor. The transformation is a simplification of the Michaelis–Menton photoreceptor equation (Backhaus and Menzel 1987; Dowling 1987), and is particularly common in models of Hymenopteran vision we’ll see below (Backhaus and Menzel 1987; Backhaus 1991; Chittka 1992).
Modelling and Plotting colorspaces
The New colspace and plot Functions
The most significant structural changes in 1.0 involve the workflow for visual modelling, particular as regards the use of colorspaces. Previously, for example, we might use vismodel to model photoreceptor stimulation to an avian viewer, tcs to convert the data to points in a tetrahedral colorspace, and tcsplot to visualise the data. In 1.0 these, and all other, colorspace modelling and plotting options are now wrapped into the new colspace and plot functions. For modelling in colorspace, a typical workflow might use:
vismodelto estimate photoreceptor quantum catches. The assumptions of many colorspace models may differ dramatically, so be sure to select options that are appropriate for your intended use.
colspaceto convert the results ofvismodel(or user-provided quantum catches) into points in a given colorspace, specified with thespaceargument. If nospaceargument is provided,colspacewill automatically select the di-, tri- or tetrahedral colorspace, depending on the nature of the input data. The result ofcolspacewill be an object of classcolspace(that inherits fromdata.frame; see the ‘Under-the-hood’ section below), and will contain the location of stimuli in the selected space along with any associated color variables.plotthe output.plotwill automatically select the appropriate visualisation based on the inputcolspaceobject, and will also accept various graphical parameters depending on the colorspace (see?plot.colspaceand links therein for details) .
examples are featured in detail below.
New Di-, Tri-, and Tetrachromatic Spaces
pavo 1.0’s new workflow expands modeling and visualization capabilities of di- and trichromatic spaces, uniting these approaches in a cohesive workflow. As with most colorspace models, we first estimate relative quantum catches with various assumptions by using the vismodel function, before converting each set of values to a location in colorspace by using the space argument in colspace (the function can also be set to try to detect the dimensionality of the colorspace automatically). For di- tri- and tetrechromatic spaces, colspace calculates the coordinates of stimuli as:
Dichromats: \[x = \frac{1}{\sqrt{2}}(Q_l - Q_s)\]
Trichromats: \[x = \frac{1}{\sqrt{2}}(Q_l - Q_m)\] \[y = \frac{\sqrt{2}}{\sqrt{3}}(Q_s - \frac{Q_l + Q_m}{2})\]
Tetrachromats: \[x = \frac{1}{\sqrt{2}}(Q_l - Q_m)\] \[y = \frac{\sqrt{2}}{\sqrt{3}}(Q_s - \frac{Q_l + Q_m}{2})\] \[z = \frac{\sqrt{3}}{2}(Q_u - \frac{Q_l + Q_m + Q_s}{3})\]
Where Qu, Qs, Qm, and Ql refer to quantum catch estimates for UV-, short, medium-, and long-wavelength photoreceptors, respectively.
For a dichromatic example, we can model our floral reflectance data using the visual system of the domestic dog Canis familiaris, which has two cones with maximal sensitivity near 440 and 560 nm.
vis.flowers <- vismodel(flowers, visual = 'canis')
di.flowers <- colspace(vis.flowers, space = 'di')
head(di.flowers)## s l x r.vec
## Goodenia_heterophylla 0.52954393 0.4704561 -0.04178143 0.04178143
## Goodenia_geniculata 0.25430150 0.7456985 0.34747015 0.34747015
## Goodenia_gracilis 0.01747832 0.9825217 0.68238870 0.68238870
## Xyris_operculata 0.39433933 0.6056607 0.14942675 0.14942675
## Eucalyptus_sp 0.40628552 0.5937145 0.13253229 0.13253229
## Faradaya_splendida 0.23166580 0.7683342 0.37948187 0.37948187The output contains values for the relative stimulation of shot- and long-wavelength sensitive photoreceptors associated with each flower, along with its single coordinate in dichromatic space and its r.vector (distance from the origin). To visualise where these points lie, we can simply plot them on a segment.
plot(di.flowers, col = flowercols) 
Flowers in a dichromatic colorspace, as modelled according to a canid visual system.
For our trichromatic viewer we can use the honeybee Apis melifera, one of the most significant and widespread pollinators. We’ll also transform our quantum catches according to Fechner’s law by specifying qcatch = 'fi', and will model photoreceptor stimulation under bright conditions by scaling our illuminant with the scale argument.
vis.flowers <- vismodel(flowers, visual = 'apis', qcatch = 'fi', scale = 10000)
tri.flowers <- colspace(vis.flowers, space = 'tri')
head(tri.flowers)## s m l x
## Goodenia_heterophylla 0.2680609 0.3692102 0.3627289 -0.004583018
## Goodenia_geniculata 0.2271455 0.3674126 0.4054419 0.026890830
## Goodenia_gracilis 0.1123462 0.3278566 0.5597972 0.164006728
## Xyris_operculata 0.1255093 0.4303017 0.4441890 0.009819783
## Eucalyptus_sp 0.2516894 0.3676007 0.3807098 0.009269542
## Faradaya_splendida 0.2538901 0.3503816 0.3957283 0.032064975
## y h.theta r.vec
## Goodenia_heterophylla -0.07994212 -1.628063 0.08007338
## Goodenia_geniculata -0.13005300 -1.366901 0.13280399
## Goodenia_gracilis -0.27065282 -1.026001 0.31646668
## Xyris_operculata -0.25453138 -1.532236 0.25472073
## Eucalyptus_sp -0.09999295 -1.478359 0.10042168
## Faradaya_splendida -0.09729766 -1.252450 0.10244509As in the case of our dichromat, the output contains relative photoreceptor stimulations, coordinates in the Maxwell triangle, a well as the ‘hue angle’ h.theta and distance from the origin (r.vec).
plot(tri.flowers, pch = 21, bg = flowercols) 
Floral reflectance in a Maxwell triangle, considering a honeybee visual system.
Finally, we’ll draw on the blue tit’s visual system to model our floral reflectance spectra in a tetrahedral space, again using log-transformed quantum catches and assuming bright viewing conditions.
vis.flowers <- vismodel(flowers, visual = 'bluetit', qcatch = 'fi', scale = 10000)
tetra.flowers <- colspace(vis.flowers, space = 'tcs')
head(tetra.flowers)## u s m l u.r
## Goodenia_heterophylla 0.22743747 0.2659589 0.2524136 0.2541900 -0.02256253
## Goodenia_geniculata 0.16252473 0.2721544 0.2827981 0.2825228 -0.08747527
## Goodenia_gracilis 0.04286461 0.2442994 0.3504364 0.3623997 -0.20713539
## Xyris_operculata 0.17663054 0.2709700 0.2642600 0.2881394 -0.07336946
## Eucalyptus_sp 0.21185426 0.2609393 0.2636990 0.2635074 -0.03814574
## Faradaya_splendida 0.18442467 0.2557585 0.2786359 0.2811809 -0.06557533
## s.r m.r l.r x
## Goodenia_heterophylla 0.015958946 0.002413584 0.004189995 -0.007206981
## Goodenia_geniculata 0.022154388 0.032798126 0.032522752 0.006349301
## Goodenia_gracilis -0.005700643 0.100436369 0.112399664 0.072321372
## Xyris_operculata 0.020970028 0.014259992 0.038139435 0.010514071
## Eucalyptus_sp 0.010939334 0.013699024 0.013507382 0.001572602
## Faradaya_splendida 0.005758476 0.028635925 0.031180928 0.015568009
## y z h.theta h.phi
## Goodenia_heterophylla -0.005417065 -0.02256253 -2.4970419 -1.190641
## Goodenia_geniculata 0.003860489 -0.08747527 0.5462942 -1.486052
## Goodenia_gracilis 0.033295437 -0.20713539 0.4314537 -1.203832
## Xyris_operculata -0.010815014 -0.07336946 -0.7995067 -1.368039
## Eucalyptus_sp 0.001043454 -0.03814574 0.5858214 -1.521361
## Faradaya_splendida 0.007188605 -0.06557533 0.4325862 -1.315029
## r.vec r.max r.achieved
## Goodenia_heterophylla 0.02429718 0.2692205 0.0902501
## Goodenia_geniculata 0.08779031 0.2509004 0.3499011
## Goodenia_gracilis 0.22190997 0.2678320 0.8285416
## Xyris_operculata 0.07490385 0.2552283 0.2934778
## Eucalyptus_sp 0.03819240 0.2503058 0.1525830
## Faradaya_splendida 0.06778025 0.2584061 0.2623013As in previous versions of pavo, tetrahedral data (now via colspace(space = 'tcs')) may be visualised in an interactive plot by using tcsplot, along with the accessory functions tcspoints and tcsvol for adding points and convex hulls, respectively. Version 1.0, however, now also includes a static tetrahedral plot, based on functionality from the package scatterplot3d. As with other colorspace plots there are a number of associated graphical options, though the view option is particularly useful in this case, as it controls the orientation of the tetrahedron by specifying a viewing angle from 0 to 360 (in degrees).
Two additional new functions may help with tetrahedral colorspace plotting:
axistetrafunction can be used to draw arrows showing the direction and magnitude of distortion of x, y and z in the tetrahedral plot.legendtetraallows you to add a legend to a plot.
par(mfrow = c(1, 2), pty = 's')
plot(tetra.flowers, view = 30, pch = 21, bg = flowercols)
legendtetra(x = -2.8, y = 0.2, z = 1.1, legend = 'flowers', pch = 19, col = 'black', bty = 'n')
axistetra(x = 1.4, y = 0.2, z = 0.4, size = c(0.25, 0.15, 0.1), adj.label = c(0.06, 0.08, 0.07))
axistetra(x = 1.4, y = 0.2, z = -0.4, size = 0.2, label = FALSE)
plot(tetra.flowers, view=60, scale.y = 0.6, pch = 21, bg = flowercols)
axistetra(x = 0.6, y = 0.2, z = 0.5, size = c(0.2, 0.2, 0.15), adj.label = c(0.07, 0.12, 0.07))
axistetra(x = 0.6, y = 0.2, z = -0.5, size = 0.2, label = FALSE)
Flowers in a tetrahedral colorspace, with varied orientations and perspectives, modelled using the visual phenotype of the blue tit. Top arrows show direction of axes, and bottom arrows of equal length shows differences in perspective and distortion.
The Color Hexagon
The hexagon color space of Chittka (1992) is a generalised color-opponent model of hymenopteran vision that has found extremely broad use, particularly in studies of bee-flower interactions. It’s also often broadly applied across hymenopteran species, because the photopigments underlying trichromatic vision in Hymenoptera appear to be quite conserved (Briscoe and Chittka 2001). What’s particularly useful is that color distances within the hexagon have been extensively validated against behaviour, and thus offer a relatively reliable measure of perceptual distance (Chittka 1992; e.g. Dyer et al. 2008; Avarguès-Weber et al. 2010).
In the hexagon, photoreceptor quantum catches are typically hyperbolically transformed (and pavo will return a warning if the transform is not selected), and vonkries correction is often used used to model photoreceptor adaptation to a vegetation background. This can all now be specified in vismodel. including the optional use of a ‘green’ vegetation background. Note that although this is a colorspace model, we specific relative = FALSE to return raw (albeit transformed) quantum catches, as required for the model (Chittka 1992).
vis.flowers <- vismodel(flowers, visual = 'apis', qcatch = 'Ei', relative = FALSE, vonkries = TRUE, achro = 'l', bkg = 'green')We can then apply the hexagon model in colspace, which will convert our photoreceptor ‘excitation values’ to coordinates in the hexagon according to:
\[x = \frac{\sqrt{3}}{2(E_g = E_{uv})}\]
\[y = E_b - 0.5(E_{uv} + E_g)\]
hex.flowers <- colspace(vis.flowers, space = 'hexagon')
head(hex.flowers)## s m l x
## Goodenia_heterophylla 0.086435155 0.37464448 0.2383065 0.1315245
## Goodenia_geniculata 0.040686930 0.38653516 0.4575212 0.3609891
## Goodenia_gracilis 0.001709545 0.02738349 0.3148769 0.2712109
## Xyris_operculata 0.002844880 0.26835909 0.2170078 0.1854705
## Eucalyptus_sp 0.074047589 0.42777802 0.3725662 0.2585247
## Faradaya_splendida 0.074604645 0.32783502 0.4358825 0.3128758
## y h.theta r.vec sec.fine sec.coarse
## Goodenia_heterophylla 0.21227364 31.78230 0.2497174 30 bluegreen
## Goodenia_geniculata 0.13743110 69.15781 0.3862647 60 bluegreen
## Goodenia_gracilis -0.13090974 115.76596 0.3011523 110 green
## Xyris_operculata 0.15843274 49.49537 0.2439267 40 bluegreen
## Eucalyptus_sp 0.20447114 51.65899 0.3296111 50 bluegreen
## Faradaya_splendida 0.07259145 76.93771 0.3211865 70 bluegreenAgain, the output includes the photoreceptor excitation values for short- medium- and long-wave sensitive photoreceptors, x and y coordinates, and measures of hue and saturation for each stimulus. The hegaon model also outputs two additoinal measures of of subjective ‘bee-hue’; sec.fine and sec.coarse. sec.fine describes the location of stimuli within one of 36 ‘hue sectors’ that are specified by radially dissecting the hexagon in 10-degree increments. sec.coarse follows a similar principle, though here the hexagon is divided into only five ‘bee-hue’ sectors: UV, UV-blue, blue, blue-green, green, and UV-green (Chittka et al. 1994; Dyer et al. 2012). These can easily be visualised by specifying sectors = 'coarse or sectors = 'fine' in a call to plot after modelling.
plot(hex.flowers, sectors = 'coarse', pch = 21, bg = flowercols)
Flowers as modelled in the hymenopteran color hexagon of Chittka (1992), overlain with coarse bee-hue sectors.
The Color Opponent Coding (COC) Space
The color opponent coding (coc) space is an earlier hymenopteran visual model (Backhaus 1991) which, although now seldom used in favour of the hexagon, may prove useful for comparative work. While the initial estimation of photoreceptor excitation is similar to that in the hexagon, the coc subsequently specifies A and B coordinates based on empirically-derived weights for the output from each photoreceptor:
\[A = -9.86E_g + 7.70E_b + 2.16E_g\] \[B = -5.17E_g + 20.25E_b - 15.08E_g\]
Where Ei is the excitation value (quantum catch) in photoreceptor i.
vis.flowers <- vismodel(flowers, visual = 'apis', qcatch = 'Ei', relative = FALSE, vonkries = TRUE, bkg = 'green')
coc.flowers <- colspace(vis.flowers, space = 'coc')
head(coc.flowers)## s m l x
## Goodenia_heterophylla 0.086435155 0.37464448 0.2383065 2.5472539
## Goodenia_geniculata 0.040686930 0.38653516 0.4575212 3.5633933
## Goodenia_gracilis 0.001709545 0.02738349 0.3148769 0.8741309
## Xyris_operculata 0.002844880 0.26835909 0.2170078 2.5070514
## Eucalyptus_sp 0.074047589 0.42777802 0.3725662 3.3685245
## Faradaya_splendida 0.074604645 0.32783502 0.4358825 2.7302341
## y r.vec
## Goodenia_heterophylla 3.5460185 6.093272
## Goodenia_geniculata 0.7175661 4.280959
## Goodenia_gracilis -4.2026664 5.076797
## Xyris_operculata 2.1470857 4.654137
## Eucalyptus_sp 2.6613811 6.029906
## Faradaya_splendida -0.3201549 3.050389The A and B coordinates are designated x and y in the output of coc for consistency, and while the model includes a measure of saturation in r.vec, it contains no associated measure of hue.
plot(coc.flowers, pch = 21, bg = flowercols, yaxt='n') 
Flowers in the color-opponent-coding space of Backhaus (1991), as modelling according to the honeybee.
CIE Spaces
The CIE (International Commission on Illumination) colorspaces are a suite of models of human color vision and perception. pavo 1.0 now includes two of the most commonly used: the foundational 1931 CIE XYZ space, and the more modern, perceptually calibrated CIE LAB space. Tristimulus values in XYZ space are calculated as:
\[X = k\int_{300}^{700}{R(\lambda)I(\lambda)\bar{x}(\lambda)d\lambda}\] \[Y = k\int_{300}^{700}{R(\lambda)I(\lambda)\bar{y}(\lambda)d\lambda}\] \[Z = k\int_{300}^{700}{R(\lambda)I(\lambda)\bar{z}(\lambda)d\lambda}\]
where x, y, and z are the trichromatic color matching functions for a ‘standard colorimetric viewer’. These functions are designed to describe an average human’s chromatic response within a specified viewing arc in the fovea (to account for the uneven distribution of cones across eye). pavo includes both the CIE 2-degree and the modern 10-degree standard observer, which can be selected in the visual option in the vismodel function. In these equations, k is the normalising factor
\[k = \frac{100}{\int_{300}^{700}{I(\lambda)\bar{y}(\lambda)d\lambda}}\]
and the chromaticity coordinates of stimuli are calculated as
\[x = \frac{X}{X + Y + Z}\] \[y = \frac{Y}{X + Y + Z}\] \[z = \frac{Z}{X + Y + Z} = 1 - x - y\]
For modelling in both XYZ and LAB spaces, here we’ll use the CIE 10-degree standard observer, and assume a D65 ‘standard daylight’ illuminant. Again, although they are colorspace models, we need to set relative = FALSE to return raw quantum catch estimates, vonkries = TRUE to account for the required normalising factor (as above), and achromatic = 'none' since there is no applicable way to estimate luminance in the CIE models. As with all models that have particular requirements, vismodel will output warnings and/or errors if unusual or non-standard arguments are specified.
vis.flowers <- vismodel(flowers, visual = 'cie10', illum = 'D65', vonkries = TRUE, relative = FALSE, achromatic = 'none')ciexyz.flowers <- colspace(vis.flowers, space = 'ciexyz')
head(ciexyz.flowers)## X Y Z x y
## Goodenia_heterophylla 0.2074305 0.2067084 0.3013614 0.2899097 0.2889005
## Goodenia_geniculata 0.6472803 0.6752456 0.4240380 0.3706021 0.3866137
## Goodenia_gracilis 0.5153064 0.4587957 0.0153714 0.5207885 0.4636766
## Xyris_operculata 0.2884446 0.2353124 0.2224271 0.3865595 0.3153544
## Eucalyptus_sp 0.4431842 0.4470468 0.4019893 0.3429634 0.3459524
## Faradaya_splendida 0.6636975 0.6553481 0.2869075 0.4132733 0.4080743
## z
## Goodenia_heterophylla 0.42118974
## Goodenia_geniculata 0.24278414
## Goodenia_gracilis 0.01553492
## Xyris_operculata 0.29808613
## Eucalyptus_sp 0.31108420
## Faradaya_splendida 0.17865248The output is simply the tristimulus values and chromaticity coordinates of stimuli, and we can visualise our results (along with a line connecting monochromatic loci, by default) by calling
plot(ciexyz.flowers, pch = 21, bg = flowercols) 
Floral reflectance in the CIEXYZ human visual model. Note that this space is not perceptually calibrated, so we cannot make inferences about the similarity or differences of colors based on their relative location.
The Lab space is a more recent development, and is a color-opponent model that attempts to mimic the nonlinear responses of the human eye. The Lab space is also calibrated (unlike the XYZ space) such that Euclidean distances between points represent relative perceptual distances. This means that two stimuli that are farther apart in Lab space should be percieved as more different that two closer points. As the name suggests, the dimensions of the Lab space are Lightness (i.e. subjective brightness), along with two color-opponent dimensions designated a and b. The colspace function, when space = cielab, simply converts points from the XYZ model according to:
\[L = 116\left(\frac{Y}{Y_n}\right)^\frac{1}{3} \;\; if \;\; \frac{Y}{Y_n} > 0.008856\] \[L = 903.3\left(\frac{Y}{Y_n}\right) \;\; if \;\; \frac{Y}{Y_n} \leq 0.008856\]
\[a = 500\left(f\left(\frac{X}{X_n}\right) - f\left(\frac{Y}{Y_n}\right)\right)\]
\[b = 500\left(f\left(\frac{Y}{Y_n}\right) - f\left(\frac{Z}{Z_n}\right)\right)\]
where
\[f(x) = x^\frac{1}{3} \;\; if \;\; x > 0.008856\] \[f(x) = 7.787(x) + \frac{16}{116} \;\; if \;\; x \leq 0.008856\]
Here, \(X_n, Y_n, Z_n\) are neutral point values to model visual adaptation, calculated as:
\[X_n = \int_{300}^{700}{R_n(\lambda)I(\lambda)\bar{x}(\lambda)d\lambda}\] \[Y_n = \int_{300}^{700}{R_n(\lambda)I(\lambda)\bar{y}(\lambda)d\lambda}\] \[Z_n = \int_{300}^{700}{R_n(\lambda)I(\lambda)\bar{z}(\lambda)d\lambda}\]
when \(R_n(\lambda)\) is a perfect diffuse reflector (i.e. 1).
cielab.flowers <- colspace(vis.flowers, space = 'cielab')
head(cielab.flowers)## X Y Z L a
## Goodenia_heterophylla 0.2074305 0.2067084 0.3013614 1.691253 0.091908831
## Goodenia_geniculata 0.6472803 0.6752456 0.4240380 5.524744 -0.778898966
## Goodenia_gracilis 0.5153064 0.4587957 0.0153714 3.753788 2.157990123
## Xyris_operculata 0.2884446 0.2353124 0.2224271 1.925286 1.966170677
## Eucalyptus_sp 0.4431842 0.4470468 0.4019893 3.657660 0.005744138
## Faradaya_splendida 0.6636975 0.6553481 0.2869075 5.361946 0.507048199
## b
## Goodenia_heterophylla -2.4336189
## Goodenia_geniculata 1.9981497
## Goodenia_gracilis 6.1991586
## Xyris_operculata -0.6289287
## Eucalyptus_sp -0.8295538
## Faradaya_splendida 4.1517115Our output now contains the tristimulus XYZ values, as well as their Lab counterparts, which are coordinates in the Lab space. These can also be visualised in three-dimensional Lab space by calling plot:
plot(cielab.flowers, pch = 21, bg = flowercols) 
CIELAB.
Categorical Fly colorspace
The categorical color vision model of Troje (1993) is a model of dipteran vision, based on behavioural data from the blowfly Lucilia sp. It assumes the involvement of all four dipteran photoreceptor classes (R7 & R8 ‘pale’ and ‘yellow’ subtypes), and further posits that color vision is based on two specific opponent mechanisms (R7p - R8p, and R7y - R8y). The model assumes that all colors are perceptually grouped into one of four color categories, and that flies are unable to distinguish between colors that fall within the same category.
We’ll use the visual systems of the mudcoid fly Musca domestica, and will begin by estimating linear (i.e. untransformed) quantum catches for each of the four photoreceptors (Troje 1993).
vis.flowers <- vismodel(flowers, qcatch = 'Qi', visual = 'musca', achro = 'none', relative = TRUE)Our call to colspace will then simply estimate the location of stimuli in the categorical space as the difference in relative stimulation between ‘pale’ (R7p - R8p) and ‘yellow’ (R7y - R8y) photoreceptor pairs:
\[x = R7_p - R8_p\]
\[y = R7_y - R8_y\]
cat.flowers <- colspace(vis.flowers, space = 'categorical')
head(cat.flowers)## R7p R7y R8p R8y
## Goodenia_heterophylla 0.036748525 0.18750232 0.4831894 0.2925597
## Goodenia_geniculata 0.014425754 0.08432394 0.4234800 0.4777703
## Goodenia_gracilis 0.008460324 0.02696304 0.1702152 0.7943614
## Xyris_operculata 0.008614719 0.12477105 0.4972701 0.3693441
## Eucalyptus_sp 0.023808699 0.14355472 0.4468683 0.3857682
## Faradaya_splendida 0.025364796 0.09511658 0.3602082 0.5193104
## x y category r.vec
## Goodenia_heterophylla -0.4464409 -0.1050574 p-y- 0.4586355
## Goodenia_geniculata -0.4090543 -0.3934464 p-y- 0.5675609
## Goodenia_gracilis -0.1617549 -0.7673984 p-y- 0.7842608
## Xyris_operculata -0.4886554 -0.2445731 p-y- 0.5464431
## Eucalyptus_sp -0.4230596 -0.2422135 p-y- 0.4874904
## Faradaya_splendida -0.3348434 -0.4241939 p-y- 0.5404262And it is simply the signs of these differences that define the four possible fly-color categories (p+y+, p-y+, p+y-, p-y-), which we can see in the associated plot.
plot(cat.flowers, pch = 21, bg = flowercols) 
Flowers in the categorical colorspace of Troje (1993).
Changes to coldist
Argument Changes to coldist
The coldist function has undergone significant changes in pavo 1.0, both internally and to its user interface. For one, it now accepts both vismodel and coldist objects, and will return distances in units that are appropriate for a given input. If we input a vismodel object for the purpose of receptor-noise modelling, the output will contain weighted Euclidean distances in units of JND’s (as was the case in previous versions). In contrast, if we input a colspace object, the output units will vary depending on the selected space. If we use the hexagon, for example, and specify the honeybee’s long (‘green’) photoreceptor for the estimation of achromatic contrasts:
# Model flower colours according to a honeybee
vis.flowers <- vismodel(flowers, visual = 'apis', qcatch = 'Ei', relative = FALSE, vonkries = TRUE, achro = 'l', bkg = 'green')
hex.flowers <- colspace(vis.flowers, space = 'hexagon')
# Estimate color distances. No need to specify relative receptor densities, noise etc.,
# which only apply in the case of receptor-noise modelling
dist.flowers <- coldist(hex.flowers)
head(dist.flowers)## patch1 patch2 dS dL
## 1 Goodenia_heterophylla Goodenia_geniculata 0.2413616 -0.2192147
## 2 Goodenia_heterophylla Goodenia_gracilis 0.3705228 -0.0765704
## 3 Goodenia_heterophylla Xyris_operculata 0.0762169 0.0212987
## 4 Goodenia_heterophylla Eucalyptus_sp 0.1272397 -0.1342596
## 5 Goodenia_heterophylla Faradaya_splendida 0.2289092 -0.1975760
## 6 Goodenia_heterophylla Gaultheria_hispida 0.1691932 -0.1186296the chromatic constrasts dS and achromatic contrasts dL are expressed as Euclidean distances in the hexagon (i.e. “hexagon units”; Chittka 1992). If we had instead used the color-oppoonent coding space, the units would have been city-bloc distances. The output units for each space are listed in the documentation for coldist, and of course the original publications remain the most authoritative source of information.
The most important change to coldist is that some of its arguments have changed, with implications for receptor-noise modelling. In pavo 1.0, coldist requires the empirically estimated value for the Weber fraction to be entered, instead of the single cone noise-to-signal ratio (the v argument in previous versions of pavo). Further, instead of separately entering n1, n2, n3 and n4, coldist now has a single argument n, and a vector of relative cone abundances is the required input. Finally, the argument weber.ref specifies which cone to use as the reference cone for the desired Weber fraction.
The noise-to-signal ratio is then calculated based on the empirically estimated Weber fraction for the reference cone type (which must also be specified), and applied to the remaining cone types. This is largely to avoid confusion between empirically estimated values for the Weber fraction and the noise-to-signal ratio, which are common in the literature. It was also made to demand less of the user, who used to have to calculate what value of v to use given the desired Weber fraction and relative cone abundances.
So, for example, the code below used in previous versions of pavo:
data(sicalis)
vis.sicalis <- vismodel(sicalis, relative = FALSE)
JND.sicalis <- coldist(vis.sicalis, n1 = 1, n2 = 2, n3 = 2, n4 = 4, v = 0.2)in pavo 1.0 would be:
data(sicalis)
vis.sicalis <- vismodel(sicalis, relative = FALSE)
JND.sicalis <- coldist(vis.sicalis, n = c(1, 2, 2, 4), weber = 0.1, weber.ref = 4)
head(JND.sicalis)## patch1 patch2 dS dL
## 1 ind1.C ind1.T 3.5206558 6.653493
## 2 ind1.C ind1.B 1.4452940 7.980093
## 3 ind1.C ind2.C 0.6797948 3.389606
## 4 ind1.C ind2.T 10.5195704 7.199048
## 5 ind1.C ind2.B 2.7180185 6.341610
## 6 ind1.C ind3.C 3.2067444 4.542846or alternatively, weber.ref can be simply set to “longest”:
data(sicalis)
vis.sicalis <- vismodel(sicalis, relative = FALSE)
JND.sicalis <- coldist(vis.sicalis, n = c(1, 2, 2, 4), weber = 0.1, weber.ref = 'longest')
head(JND.sicalis)## patch1 patch2 dS dL
## 1 ind1.C ind1.T 3.5206558 6.653493
## 2 ind1.C ind1.B 1.4452940 7.980093
## 3 ind1.C ind2.C 0.6797948 3.389606
## 4 ind1.C ind2.T 10.5195704 7.199048
## 5 ind1.C ind2.B 2.7180185 6.341610
## 6 ind1.C ind3.C 3.2067444 4.542846coldist now also accepts a weber.achro argument so that the value for the Weber fraction to be used to calculate achromatic contrast can be input independently of the cone ratios.
Color Distances in N-Dimensions
As a result of the changes in the input of relative cone abundances and the internal calculation functions used in coldist, the function is not limited to di-, tri- or tetrachromatic visual systems. coldist has been generalised, and can now calculate color distances for n-dimensional visual phenotypes. This means there is no limit on the dimensionality of visual systems that may be input, which may prove useful for modelling nature’s extremes (e.g. butterflies, mantis shrimp) or for simulation-based work. Naturally, since these calculations aren’t largely implemented elsewhere, we recommend caution and validation of results prior to publication.
# Create an arbitrary visual phenotype with 10 photoreceptors
fakemantisshrimp <- sensmodel(c(325, 350, 400, 425, 450, 500, 550, 600, 650, 700), beta = FALSE, integrate = FALSE)
# Convert to percentages, just to color the plot
fakemantisshrimp.colors <- fakemantisshrimp * 100
fakemantisshrimp.colors[, 'wl'] <- fakemantisshrimp[, 'wl']
plot(fakemantisshrimp, col = spec2rgb(fakemantisshrimp.colors), lwd = 2, ylab = 'Absorbance')
Visual system of a pretend mantis shrimp with 10 cones
# Run visual model and calculate color distances
vm.fms <- vismodel(flowers, visual = fakemantisshrimp, relative = FALSE, achro = FALSE)
JND.fms <- coldist(vm.fms, n = c(1, 1, 2, 2, 3, 3, 4, 4, 5, 5))## Warning: achro=TRUE but visual model was calculated with achro= "none" ;
## achromatic contrast not calculated.head(JND.fms)## patch1 patch2 dS
## 1 Goodenia_heterophylla Goodenia_geniculata 16.297557
## 2 Goodenia_heterophylla Goodenia_gracilis 48.390309
## 3 Goodenia_heterophylla Xyris_operculata 30.760482
## 4 Goodenia_heterophylla Eucalyptus_sp 6.044184
## 5 Goodenia_heterophylla Faradaya_splendida 15.901435
## 6 Goodenia_heterophylla Gaultheria_hispida 11.188246Classes and Attributes
To enable the improved workflow and new features in pavo 1.0, we’ve expanded the underlying class system. As in previous versions, spectra will be of class rspec as long as we use one of pavo’s spectral import or processing funcitons, or explicitly convert an object using as.rspec. The results of vismodel are now objects of class vismodel and the results of colspace are, unsurprisingly, objects of class colspace. Both of these classes inherit from data.frame, and contain a suite of attributes that describe the object’s characteristics (e.g. options used in visual modelling such as the selected visual system and illuminant, and properties of the modelled colorspace). These are easily viewed using the summary function (on any rspec, vismodel, or colspace object), which will return the attributes and summary data (where appropriate) in a readable format.
Concluding Thoughts, and Further Assistance
We hope that we have piqued your interest in pavo 1.0 by illustrating some of its exciting new features. Although many of the changes are significant (and breaking), we feel the package is in its most useful form yet, which will also act as a solid foundation for expansion in the future. As always, we appreciate your interest in pavo, and are happy to hear from you.
For suggestions, assistance and/or bug reports, we suggest getting in touch via ‘gitter’ at https://gitter.im/r-pavo/help, which is essentially a public chat room for all things pavo. If you have a bug to report, we’d appreciate it if you could also include a reproducible example when possible. Users familiar with git may prefer to open an issue on the project’s github page, or to make a pull-request directly.
References
Avarguès-Weber, A., M. G. de Brito Sanchez, M. Giurfa, and A. G. Dyer. 2010. Aversive reinforcement improves visual discrimination learning in free-flying honeybees. PLoS One 5:e15370.
Backhaus, W. 1991. Color opponent coding in the visual system of the honeybee. Vision research 31:1381–1397.
Backhaus, W., and R. Menzel. 1987. Color distance derived from a receptor model of color vision in the honeybee. Biological Cybernetics 55:321–331.
Briscoe, A. D., and L. Chittka. 2001. The evolution of color vision in insects. Annual review of entomology 46:471–510.
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:533–542.
Chittka, L., A. Shmida, N. Troje, and R. Menzel. 1994. Ultraviolet as a component of flower reflections, and the colour perception of hymenoptera. Vision research 34:1489–1508.
Dowling, J. E. 1987. The retina: An approachable part of the brain. Harvard University Press.
Dyer, A. G., S. Boyd-Gerny, S. McLoughlin, M. G. P. Rosa, V. Simonov, and B. B. M. Wong. 2012. Parallel evolution of angiosperm colour signals: Common evolutionary pressures linked to hymenopteran vision. Proceedings of the Royal Society B-Biological Sciences 279:3606–3615.
Dyer, A. G., J. Spaethe, and S. Prack. 2008. Comparative psychophysics of bumblebee and honeybee colour discrimination and object detection. Journal of Comparative Physiology A 194:617–627.
Troje, N. 1993. Spectral categories in the learning behaviour of blowflies. Zeitschrift fur Naturforschung C 48:96–96.