occupancy_filter: Subset occupancy hypervolumes

Description

The occupancy_filter() function is used to subset an hypervolume generated with hypervolume_n_occupancy() or hypervolume_n_occupancy_test().

Usage

occupancy_filter(hv, operator = NULL, filter = NULL, tol = 1e-10)

Value

A Hypervolume-class or HypervolumeList-class object.

Arguments

hv: A Hypervolume or HypervolumeList object generated with hypervolume_n_occupancy() or hypervolume_n_occupancy_test().
operator: Binary operator which allow the comparison.
filter: Threshold value to perform the operation.
tol: Set the tolerance for reconstructing whole volume. See details.

Details

The occupancy_filter() function set the occupancy values to 0 based on the user-provided operation. Volume of the hypervolumes are changed accordingly.
When hv is an HypervolumeList, the occupancy_filter() 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 element of hv as the the ratio between the total number of random points and the number of random points of the ith element of hv, multiplied by the volume of the ith element hv. 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.

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))


# set to 0 values lower than 0.35
occupancy_filter(hv_occupancy_list_sex, operator = "<", filter = "0.35")
}