get_occupancy_stats: Stats from occupancy objects

Description

Functions get_occupancy_stats() and get_occupancy_stats_bootstrap() return the results of a function applied to hypervolumes generated with hypervolume_n_occupancy(), hypervolume_n_occupancy_bootstrap(), hypervolume_n_occupancy_permute() or hypervolume_n_occupancy_test().

Usage

get_occupancy_stats(hv, FUN, remove_zeroes = TRUE)
get_occupancy_stats_bootstrap(path,
                              FUN,
                              remove_zeroes = TRUE,
                              method = "pairwise",
                              res_type = "summary",
                              verbose = TRUE,
                              cores = 1)

Value

Either a vector, a matrix or a data.frame with the results of the applied function.

Arguments

hv: A Hypervolume or HypervolumeList object generated with hypervolume_n_occupancy(), hypervolume_n_occupancy_bootstrap(), hypervolume_n_occupancy_permute() or hypervolume_n_occupancy_test().
FUN: The function to be applied.
remove_zeroes: Remove zeroes before the calculation. See Details.
path: A path to a directory of bootstrapped hypervolumes obtained with hypervolume_n_occupancy_bootstrap().
method: If all returns the results for each hypervolume. If pairwise returns the results for all the pairwise comparisons of individual hypervolumes.
res_type: It can be raw or pairwise. See details.
verbose: Logical value; print diagnostic output if TRUE.
cores: Number of logical cores to use while generating permuted hypervolumes. If parallel backend already registered to doParallel, function will use that backend and ignore the argument in cores.

Details

The get_occupancy_stats() and get_occupancy_stats_bootstrap() functions take ValueAtRandomPoints of each hypervolume as input to FUN (e.g. mean, median).
The get_occupancy_stats_bootstrap() function applies the function to bootstrapped occupancy objects generated with hypervolume_n_occupancy_bootstrap(). If res_type = "raw" raw values of the applied functions are returned for each occupancy object in path, only when method = "all". If res_type = "summary" the mean value as well as the standard deviation, median, minimum, maximum, 2.5% and 97.5% quantiles, skewness and kurtosis are returned either for individual hypervolumes (method = "all") or pairwise comparisons (method = "pairwise").
The get_occupancy_stats() and get_occupancy_stats_bootstrap() functions remove occupancy values equal to 0 by default. These values are generated during the occupancy routine when a random point is included in some groups of hypervolumes but not in others. A tipical usage of get_occupancy_stats() or get_occupancy_stats_bootstrap() should remove zeroes before applying a function (the default).

Examples

Run this code

if (FALSE) {

##### single occupancy object #####
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))


# calculate the mean occupancy value
get_occupancy_stats(hv_occupancy_list_sex, mean)

##### bootstrapped occupancy objects #####

# bootstrap input hypervolumes
hv_boot = hypervolume_n_resample(name = "example", hv_list = hv_list,  n = 9)

# calculate occupancy on bootstrapped hypervolumes
hv_boot_occ = hypervolume_n_occupancy_bootstrap(hv_boot, name = "example_occ",
                                  classification = rep(c("female", "male"), 3))

# calculate summary statistics for pairwise comparisons
get_occupancy_stats_bootstrap(hv_boot_occ, FUN = mean)

}