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, v, n1, n2,
  n3, n4)

Arguments

modeldata	(required) quantum catch colour data. Can be the result from vismodel, or colspace. Data may also be independently calculated quantum catches, in the form of a data frame with columns representing photoreceptors.
noise	how the noise will be calculated. (Ignored for colspace objects if model is not a receptor noise model (i.e. hexagon, colour-opponent-coding, categorical, segment, and cie models)): neural: 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.
subset	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.
achromatic	Logical. If TRUE, last column of the data frame is used to calculate the achromatic contrast, with noise based on the Weber fraction given by the argument weber.achro. If the data are from the hexagon model (i.e. colspace(space = 'hexagon')), it instead returns simple long (or 'green') receptor contrast.
qcatch	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 law (the signal of the receptor channel is proportional to the logarithm of the quantum catch)
n	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 if model is not a receptor noise model (i.e. hexagon, colour-opponent-coding, categorical, and cie models).
weber	The Weber fraction 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 of the cone classes. 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 if model is not a receptor noise model (i.e. hexagon, colour-opponent-coding, categorical, segment, and cie models).
weber.ref	the cone class used to obtain the empirical estimate of the Weber fraction used for the weber argument. By default, n4 is used, representing the LWS cone for Leiothrix lutea. Ignored for colspace objects if model is not a receptor noise model (i.e. hexagon, colour-opponent-coding, categorical, segment, and cie models).
weber.achro	the Weber fraction to be used to calculate achromatic contrast, when achromatic = TRUE. Defaults to 0.1. Ignored for colspace objects if model is not a receptor noise model (i.e. hexagon, colour-opponent-coding, categorical, segment, and cie models).
n1, n2, n3, n4, v	deprecated arguments. see below.

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 are JND's in the receptor-noise model, euclidean distances in the categorical and segment space, manhattan distances in the color-opponent-coding space, green-receptor contrast in the hexagon, and lightness (L) contrast in the cielab model.

Note on previous versions

previous versions of coldist calculated receptor noise using the arguments v for the individual cone noise-to-signal ratio and n1,n2,n3,n4 for the relative cone densities. These arguments have been replaced by weber and n, which takes a vector of relative cone densities. weber.ref allows the user to specify which receptor to use as the reference to obtain the desired Weber fraction, and coldist calculates internally the value of v to be used when calculating the Weber fraction for the remaining cones.

This allows a more explicit choice of Weber fraction, without the need to find the right value of v to use in order to obtain the desired signal-to-noise ratio. Furthermore, by allowing n to be entered as a vector, coldist can now handle visual systems with more than four photoreceptors.

In addition, the achromatic noise is calculated based on the weber.achro argument directly, and not based on v and n4 as before.

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

# NOT RUN {
# 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, color-hexagon model (euclidean distances)
vis.flowers <- vismodel(flowers, visual = 'apis', qcatch = 'Ei',
                        relative = FALSE, vonkries = TRUE, achro = 'l', bkg = 'green')
hex.flowers <- colspace(vis.flowers, space = 'hexagon')
hexdist.flowers <- coldist(hex.flowers)

# Trichromat, color-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)

# This will also work, but give you several warnings you shouldn't ignore!!
col.sicalis <- colspace(vis.sicalis)
tetradist.sicalis.n <- coldist(col.sicalis)

tetradist.sicalis.q <- coldist(vis.sicalis, noise = 'quantum')
# }