Compute colour volume overlap in 3D with alphashapes

overlap3d(
colsp1,
colsp2,
avalue = "auto",
plot = FALSE,
interactive = TRUE,
col = c("blue", "red", "darkgrey"),
fill = FALSE,
new = TRUE,
nsamp = 1000,
psize = 0.001,
lwd = 1,
...
)

## Arguments

colsp1 (required) data frame, possibly a result from the colspace() function, containing values for the 'x', 'y' (and possibly 'z') coordinates as columns (labeled as such) (required) data frame, possibly a result from the colspace() function, containing values for the 'x', 'y' (and possibly 'z') coordinates as columns (labeled as such) if type = alpha, the alpha parameter values for colsp1 and colsp2 respectively to compute the alphashapes. Can be a numeric of length one if the same value is used in both cases. avalue = "auto" (default) finds and use the α* value as defined in Gruson (2020). logical. Should the volumes and points be plotted? (defaults to FALSE). This only works for tetrahedral colourspaces at the moment. logical. If TRUE, uses the rgl engine for interactive plotting; if FALSE then a static plot is generated. a vector of length 3 with the colours for (in order) the first volume, the second volume, and the overlap. logical. should the two volumes be filled in the plot? (defaults to FALSE) logical. Should a new plot window be called? If FALSE, volumes and their overlap are plotted over the current plot (defaults to TRUE). if type = "alpha", the number of points to be sampled for the Monte Carlo computation. Stoddard & Stevens(2011) use around 750,000 points, but more or fewer might be required depending on the degree of overlap. if type = "alpha" and plot = TRUE, sets the size to plot the points used in the Monte Carlo computation. if plot = TRUE, sets the line width for volume grids. additional arguments passed to the plot. See vol()

## Value

a data.frame with the following columns:

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

## References

Gruson H. 2020. Estimation of colour volumes as concave hypervolumes using α‐shapes. Methods in Ecology and Evolution, early view doi: 10.1111/2041-210X.13398

## Examples

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")
# \donttest{
pavo:::overlap3d(tcs.sicalis.T, tcs.sicalis.B, avalue = 1)#>           vol1         vol2 s_in1 s_in2 s_inboth s_ineither psmallest
#> 1 5.183721e-06 6.231493e-06     5    10        1         14       0.2
#>        pboth
#> 1 0.07142857pavo:::overlap3d(tcs.sicalis.T, tcs.sicalis.C, plot = TRUE, avalue = c(0.1, 0.12))#>   vol1         vol2 s_in1 s_in2 s_inboth s_ineither psmallest pboth
#> 1    0 4.684183e-06     0     4        0          4       NaN     0pavo:::overlap3d(tcs.sicalis.T, tcs.sicalis.C, plot = TRUE, col = seq_len(3), avalue = 0.1)#>   vol1         vol2 s_in1 s_in2 s_inboth s_ineither psmallest pboth
#> 1    0 4.684183e-06     0     6        0          6       NaN     0# }