get_relative_volume: Extract the relative volume

Description

The function get_relative_volume() computes the relative volume from objects generated with the occupancy routine.

Usage

get_relative_volume(hv_list, tol = 1e-10)

Value

A named numeric vector with the relative volume of each input hypervolume

Arguments

hv_list: A Hypervolume or HypervolumeList object generated with hypervolume_n_occupancy(), hypervolume_n_occupancy_permute(), hypervolume_n_occupancy_test(), occupancy_to_union(), occupancy_to_intersection(), occupancy_to_unshared(), or occupancy_filter().
tol: Set the tolerance for reconstructing whole volume. See details.

Details

The relative volume is calculated as the ratio between hypervolumes of an HypervolumeList and the volume resulting from the union of hypervolumes in the same HypervolumeList. Relative volumes can be calculated only for HypervolumeList generated with functions hypervolume_n_occupancy(), hypervolume_n_occupancy_test(), hypervolume_n_occupancy_permute(), occupancy_to_union(), occupancy_to_ushared(), occupancy_to_intersection() or occupancy_filter().
The get_relative_volume() function attempts to reconstruct the volume of the union of hypervolumes from hv_list. At first, the volume of the union of hypervolumes is calculated for each hypervolume of 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 hv_list. This step results in a number of reconstructed volumes equal to the number of hypervolumes in hv_list. Reconstructed volumes are then compared 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.

Examples

Run this code

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","bill_depth_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 relative volume
get_relative_volume(hv_occupancy_list_sex)
}