hypervolume (version 3.1.4)

occupancy_to_union: Union of hypervolumes from an occupancy object

Description

The occupancy_to_union() function is used to get the union of hypervolumes of an object generated with hypervolume_n_occupancy().

Usage

occupancy_to_union(hv_list, method = "all", m = 2, 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_intersection(), occupancy_to_unshared() or occupancy_filter().

method

If all compute the union of all the hypervolumes in hv_list. If n_wise compute of the union 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_union() 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_union() function returns a Hypervolume representing the union of all the hypervolumes in hv_list. When method = "n_wise" a HypervolumeList in which each hypervolume represent the union 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_union() function attempts to reconstruct the volume of the union from the hv_list provided by the user. For each hypervolume in hv_list, it calculates the volume of the union as 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.

See Also

hypervolume_n_occupancy, hypervolume_n_occupancy_test, occupancy_to_intersection, 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("female", "male"), 3))
                          
# get the union of all the hypervolumes
hv_occupancy_sex_union <- occupancy_to_union(hv_occupancy_list_sex)
plot(hv_occupancy_sex_union)

}