hypervolume (version 3.1.4)

occupancy_to_unshared: Unshared fraction from an occupancy object

Description

The occupancy_to_unshared() function is used to get the unshared fraction of hypervolumes of an object generated with the occupancy routine.

Usage

occupancy_to_unshared(hv_list, method = "all", tol = 1e-10)

Value

A Hypervolume-class or HypervolumeList-class object.

Arguments

hv_list

A HypervolumeList object generated with hypervolume_n_occupancy(), hypervolume_n_occupancy_test(), occupancy_to_union(), occupancy_to_intersection() or occupancy_filter.

method

If all compute the unshared fraction of each hypervolume in hv_list. If pairwise compute the unshared fraction for each pairwise combination of hypervolumes in hv_list.

tol

Set the tolerance for reconstructing whole volume. See details.

Details

Unshared fraction is the fraction of the hypervolume not shared with other hypervolumes. It is calculated from occupancy objects only (check See Also). When method = "all" a HypervolumeList containing the unshared fraction of each hypervolume is returned. When method = "pairwise" an HypervolumeList containing the unshared fraction of the pairwise combination of hypervolumes is returned. Hypervolumes generated when method = "pairwise" include the unshared fraction of both hypervolumes under comparison. The first of the two hypervolumes is assigned with ValueAtRandomPoints equal to 1 while, the second is assigned with ValueAtRandomPoints equal to -1. This is useful when used in combination with occupancy_filter() or hypervolume_to_data_frame().
The occupancy_to_unshared() function attempts to reconstruct the volume of the unshared fraction from the hv_list provided by the user. At first, the volume of the union of hypervolumes is calculated for each hypervolume in hv_list as the the ratio between the total number of random points and the number of random points of the ith hypervolume of hv_list, multiplied by the volume of the ith hypervolume of hv_list. This step results in a number of reconstructed volumes equal to the number of hypervolumes in the jth bootstrapped occupancy_object. Reconstructed volumes are then compared among each other to ensure the consistency of the reconstruction. To do this, the distance among reconstructed volumes is calculated with the dist() function of the stats package. If at least one of the distances is greater than tol the computation is stopped and some suggestions are returned. The volume of the unshared fraction is then calculated as the ratio between the number of random points of the unshared fraction and the total number of random points, multiplied by the volume of the union of hypervolumes.

See Also

hypervolume_n_occupancy, hypervolume_n_occupancy_test, occupancy_to_intersection, occupancy_to_union, occupancy_filter

Examples

if (FALSE) {
data(penguins,package='palmerpenguins')
penguins_no_na = as.data.frame(na.omit(penguins))

# split the dataset on species and sex
penguins_no_na_split = split(penguins_no_na, 
paste(penguins_no_na$species, penguins_no_na$sex, sep = "_"))

# calculate the hypervolume for each element of the splitted dataset
hv_list = mapply(function(x, y) 
  hypervolume_gaussian(x[, c("bill_length_mm", "flipper_length_mm")],
                       samples.per.point=100, name = y), 
                       x = penguins_no_na_split, 
                       y = names(penguins_no_na_split))


# transform the list into an HypervolumeList
hv_list = hypervolume_join(hv_list)

# calculate occupancy based on sex
hv_occupancy_list_sex = hypervolume_n_occupancy(hv_list, 
                          classification = rep(c("female", "male"), 3))
                          
# get hypervolumes with the unshared fraction
hv_occupancy_sex_unshared <- occupancy_to_unshared(hv_occupancy_list_sex)
plot(hv_occupancy_sex_unshared)

# get hypervolumes with the unshared fraction between each pairwise combination of hypervolumes
hv_occupancy_sex_unshared_pw <- occupancy_to_unshared(hv_occupancy_list_sex)

# plot the unshared fraction with ggplot2
require(ggplot2)

# extract data to plot
occupancy_sex_pw_df <- hypervolume_to_data_frame(hv_occupancy_sex_unshared_pw)

ggplot(occupancy_sex_pw_df, aes(bill_length_mm, flipper_length_mm, col = Name)) +
  geom_point() +
  theme_bw()
}