pavo (version 2.0.0)

voloverlap: Color volume overlap

Description

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

Usage

voloverlap(tcsres1, tcsres2, plot = FALSE, interactive = FALSE,
  col = c("blue", "red", "darkgrey"), fill = FALSE, new = TRUE,
  montecarlo = FALSE, nsamp = 1000, psize = 0.001, lwd = 1, ...)

Arguments

tcsres1, tcsres2

(required) data frame, possibly a result from the colspace function, containing values for the 'x', 'y' and 'z' coordinates as columns (labeled as such)

plot

logical. Should the volumes and points be plotted? (defaults to FALSE)

interactive

logical. If TRUE, uses the rgl engine for interactive plotting; if FALSE then a static plot is generated.

col

a vector of length 3 with the colors for (in order) the first volume, the second volume, and the overlap.

fill

logical. should the two volumes be filled in the plot? (defaults to FALSE)

new

logical. Should a new plot window be called? If FALSE, volumes and their overlap are plotted over the current plot (defaults to TRUE).

montecarlo

logical. If TRUE, Monte Carlo simulation is used instead of exact solution (not recommended; defaults to FALSE)

nsamp

if montecarlo = TRUE, determines the number of points to be sampled.

psize

if montecarlo = TRUE and plot = TRUE, sets the size to plot the points used in the Monte Carlo simulation.

lwd

if plot = TRUE, sets the line width for volume grids.

...

additional arguments passed to the plot. See vol

Value

Calculates the overlap between the volumes defined by two set of points in colorspace. 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 color 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 color points.

The Monte Carlo solution is available mostly for legacy and benchmarking, and is not recommended (see notes). 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.

If the Monte Carlo solution is used, a number of points much greater than the default should be considered (Stoddard & Stevens(2011) use around 750,000 points, but more or fewer might be required depending on the degree of overlap).

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.

Villeger, S., Novack-Gottshall, P. M., & Mouillot, D. (2011). The multidimensionality of the niche reveals functional diversity changes in benthic marine biotas across geological time. Ecology Letters, 14(6), 561-568.

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

Examples

# NOT RUN {
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')
voloverlap(tcs.sicalis.T, tcs.sicalis.B)
voloverlap(tcs.sicalis.T, tcs.sicalis.C, plot = T)
voloverlap(tcs.sicalis.T, tcs.sicalis.C, plot = T, col = 1:3) 
# }
# NOT RUN {
# }