hypervolume (version 3.1.4)

hypervolume_threshold: Thresholds hypervolume and calculates volume quantile statistics (empirical cumulative distribution function)

Description

Thresholds a hypervolume at a given value that can correspond to a quantile of the hypervolume. All random points below the threshold value are removed and the volume is adjusted accordingly. Provides threshold-quantile plots if multiple thresholds are specified (as by default).

Quantiles can be specified to be either of the total volume enclosed by the hypervolume p(proportional to nrow(hv@RandomPoints)), or of the total probability density (proportional to sum(hv@ValueAtRandomPoints)).

Usage

hypervolume_threshold(hv, 
                        thresholds = NULL, 
                        num.thresholds = 20, 
                        quantile.requested = NULL,
                        quantile.requested.type = "volume", 
                        uniform.density = TRUE,
                        plot = TRUE, verbose = TRUE)

Value

A list containing two elements: a HypervolumeList or Hypervolume object corresponding to the hypervolumes at each threshold value, and a dataframe Statistics corresponding to the relevant quantiles and thresholds.

Arguments

hv

An input hypervolume

thresholds

A sequence of probability threshold values. If NULL, defaults to a sequence of length num.thresholds spanning the minimum and maximum probability values in the hypervolume.

num.thresholds

The number of threshold values to use if thresholds=NULL. Otherwise ignored.

quantile.requested

If not NULL, selects a single hypervolume correspondong to the threshold value that comes closest to enclosing the requested quantile fraction of the type quantile.requested.type. Using high values of num.thresholds enables more accurate threshold and quantile selection.

quantile.requested.type

Determines the quantile type: either "volume" or "probability".

uniform.density

Logical value. If TRUE, sets all @ValueAtRandomPoints values to 1 in order to represent thresholded hypervolume as a solid geometrical shape.

plot

Plots a threshold-quantile plot if TRUE. Quantiles are shown for both volume and probability density. This plot is similar to an empirical cumulative distribution function.

verbose

If TRUE, prints diagnostic progress messages.

Details

Hypervolumes constructed using the hypervolume_box method may not always yield quantiles close to the requested value because of the flat shape of the kernel.

Examples

if (FALSE) {
data(penguins,package='palmerpenguins')
penguins_no_na = as.data.frame(na.omit(penguins))
penguins_adelie = penguins_no_na[penguins_no_na$species=="Adelie",
                    c("bill_length_mm","bill_depth_mm","flipper_length_mm")]
  
hv = hypervolume_box(penguins_adelie,name='Adelie')

# get hypervolumes at multiple thresholds
hvlist = hypervolume_threshold(hv, plot=TRUE)
head(hvlist$Statistics)
plot(hvlist$HypervolumesThresholded[[c(1,5,10,15,20)]],
  show.random=TRUE, show.data=FALSE,show.centroid=FALSE)

# get hypervolume for a single low quantile value
plot(hypervolume_threshold(hv, plot=FALSE, verbose=FALSE,
  quantile.requested=0.1,quantile.requested.type="volume")[[1]])
}