hypervolume (version 3.1.4)

occupancy_to_intersection: Get the intersection of an occupancy object

Description

The occupancy_to_intersection() function is used to get the intersection of hypervolumes of an object generated with the occupancy routine.

Usage

occupancy_to_intersection(hv_list, method = "all", m = 2, tol = 1e-10)

Value

A Hypervolume-class or HypervolumeList-class object.

Arguments

hv_list

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

method

If all compute the intersection among all the hypervolumes in hv_list. If n_wise compute the intersection for each n_wise combination of hypervolumes in hv_list.

m

Number of elements to choose. Default to 2 (pairwise comparisons). This argument is ignored when method is set to all.

tol

Set the tolerance for reconstructing whole volume. See details.

Details

The occupancy_to_intersection() function takes as input a HypervolumeList generated with an occupancy function (check See Also) and returns a Hypervolume or HypervolumeList depending on method. When method = "all" the occupancy_to_intersection() function returns a Hypervolume representing the intersection of all the hypervolumes in hv_list. When method = "n_wise" a HypervolumeList in which each hypervolume represent the intersection of a combination of the hypervolumes in hv_list is returned. The number of hypervolumes for each combination is set with the argument m. Argument m can not be higher than the number of hypervolumes in hv_list and lower than 2.
The occupancy_to_intersection() function attempts to reconstruct the volume of the intersection 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 intersection is then calculated as the ratio between the number of random points of the intersection 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_union, occupancy_to_unshared, 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("Adelie", "Chinstrap", "Gentoo"), 2))

# get the hypervolume of intersection
hv_occupancy_sex_intersection <- occupancy_to_intersection(hv_occupancy_list_sex)
plot(hv_occupancy_sex_intersection)

# get hypervolumes with the intersection among 3 or 2 combinations of hypervolumes
hv_occ_sex_intersection_3 <- occupancy_to_intersection(hv_occupancy_list_sex,
                                                       method = "n_wise",
                                                       m = 3)
hv_occ_intersection_2 <- occupancy_to_intersection(hv_occupancy_list_sex,
                                                   method = "n_wise",
                                                   m = 2)

}