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.
(required) quantum catch colour data. Can be the result from
vismodel() for noise-weighted Euclidean distances, or colspace() for
unweighted (typically) Euclidean distances. Data may also be independently
calculated quantum catches, in the form of a data frame with columns
representing photoreceptors.
how the noise will be calculated (ignored for colspace
objects):
neural (default): noise is proportional to the Weber fraction and is
independent of the intensity of the signal received (i.e. assumes bright
conditions).
quantum: noise is the sum of the neural noise and receptor noise, and
is thus proportional to the Weber fraction and inversely proportional to
the intensity of the signal received (the quantum catches).
Note that the quantum option will only work with objects of
class vismodel.
If only some of the comparisons should be returned, a character vector of length 1 or 2 can be provided, indicating which samples are desired. The subset vector must match the labels of the input samples, but partial matching (and regular expressions) are supported.
Logical. If TRUE, last column of the data frame is used
to calculate the achromatic contrast, the form of which will depend on the
input data and will be indicated by a message during execution. For
noise-weighted distances, noise is based on the Weber fraction given by the
argument weber.achro.
if the object is of class vismodel or colspace, this
argument is ignored. If the object is a data frame of quantal catches from
another source, this argument is used to specify what type of quantum catch
is being used, so that the noise can be calculated accordingly: * Qi:
Quantum catch for each photoreceptor * fi: Quantum catch according to
Fechner's law (the signal of the receptor channel is proportional to the
logarithm of the quantum catch)
photoreceptor densities for the cones used in visual modeling. must
have same length as number of columns (excluding achromatic receptor if
used; defaults to the Pekin robin Leiothrix lutea densities:
c(1,2,2,4)). Ignored for colspace objects.
The Weber fraction(s) to be used (often also referred to as
receptor noise, or e). The noise-to-signal ratio v is unknown, and
therefore must be calculated based on the empirically estimated Weber
fraction of one or (more rarely) all the cone classes. When noise is only
known for one receptor, as is typical, v is then applied to estimate the
Weber fraction of the other cones. By default, the value of 0.1 is used
(the empirically estimated value for the LWS cone from Leiothrix lutea).
See Olsson et al. 2017 for a review of published values in the literature.
Ignored for colspace objects.
the cone class used to obtain the empirical estimate of the
Weber fraction used for the weber argument, if a single value is
specified. By default, n4 is used, representing the LWS cone for
Leiothrix lutea. Ignored for colspace objects.
the Weber fraction to be used to calculate achromatic
contrast, when achromatic = TRUE. Defaults to 0.1. Ignored for colspace
objects.
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.
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.
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
# \donttest{
# Dichromat
data(flowers)
vis.flowers <- vismodel(flowers, visual = "canis", relative = FALSE)
didist.flowers <- coldist(vis.flowers, n = c(1, 2))
#> Calculating noise-weighted Euclidean distances
# Trichromat
vis.flowers <- vismodel(flowers, visual = "apis", relative = FALSE)
tridist.flowers <- coldist(vis.flowers, n = c(1, 2, 1))
#> Calculating noise-weighted Euclidean distances
# 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)
#> Calculating unweighted Euclidean distances
# 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)
#> Calculating Manhattan distances
# Tetrachromat
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv", relative = FALSE)
tetradist.sicalis.n <- coldist(vis.sicalis)
#> Calculating noise-weighted Euclidean distances
# }