Bootstrap colour distance confidence intervals

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

vismodeldata: (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.
by: (required) a numeric or character vector indicating the group to which each row from the object belongs to.
boot.n: number of bootstrap replicates (defaults to 1000)
alpha: the confidence level for the confidence intervals (defaults to 0.95)
raw: should the full set of bootstrapped distances (equal in length to boot.n) be returned, instead of the summary distances and CI's? Defaults to FALSE.
...: other arguments to be passed to coldist(). Must at minimum include n and weber. See coldist() for details.

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.

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.)

References

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

Examples

# \donttest{
# 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)
#> Calculating noise-weighted Euclidean distances and noise-weighted luminance contrasts
#>      dS.mean    dS.lwr   dS.upr   dL.mean    dL.lwr   dL.upr
#> B-C 4.626548 2.8682623 7.004432 7.4677171 5.7063244 9.326239
#> B-T 1.741764 0.2046389 5.015957 0.2340913 0.0339413 1.654701
#> C-T 6.110519 3.9313140 8.542214 7.2336258 5.4298695 9.082158

# 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)
#> Quantum catch are relative, distances may not be meaningful
#> Calculating unweighted Euclidean distances and Weber luminance contrast
#>        dS.mean      dS.lwr     dS.upr    dL.mean     dL.lwr    dL.upr
#> B-C 0.08873222 0.058389224 0.12301039 1.11017675 0.76080437 1.5235194
#> B-T 0.02510854 0.005450728 0.07263973 0.02368528 0.00213318 0.1647769
#> C-T 0.11208967 0.081727034 0.14513597 1.06135304 0.71634168 1.4956300

# 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)
#> Calculating unweighted Euclidean distances and simple luminance contrast
#>               dS.mean    dS.lwr    dS.upr   dL.mean    dL.lwr   dL.upr
#> pop_1-pop_2 0.0736203 0.0205342 0.2000373 0.9016919 0.7219518 1.054019
# }