TukeyRegion {TukeyRegion}

Computation of the Tukey Region

Description

Computes the Tukey depth trimmed region for a given depth level.

Usage

TukeyRegion(data, depth, method = "bfs",
  trgFacets = FALSE, checkInnerPoint = TRUE,
  retHalfspaces = TRUE, retHalfspacesNR = FALSE,
  retInnerPoint = FALSE, retVertices = FALSE,
  retFacets = FALSE, retVolume = FALSE, retBarycenter = FALSE,
  halfspaces = matrix(0), innerPoint = numeric(1),
  verbosity = 0L)

Arguments

data

data set for which the Tukey region shall be computed, a matrix having > 2 columns and more rows than columns.

depth

depth of the Tukey region, an integer between 1 and the half of the number of rows in data.

method

the method to use to compute the Tukey region, a string containing "bfs", or "cmb", or "bf", see ‘Details’, "bfs" by default.

trgFacets

whether to triangulate facets, logical, FALSE by default. In this case no facet ridges are plotted, see ‘Value’.

checkInnerPoint

whether to check correctness of the inner point in case it is provided, logical, TRUE by default.

retHalfspaces

whether to return all found halfspaces, logical, TRUE by default.

retHalfspacesNR

whether to return non-redundant halfspaces, logical, FALSE by default.

retInnerPoint

whether to return inner point, logical, FALSE by default.

retVertices

whether to return vertices, logical, FALSE by default.

retFacets

whether to return facets, logical, FALSE by default.

retVolume

whether to return volume, logical, FALSE by default.

retBarycenter

whether to return the region's barycenter, logical, FALSE by default.

halfspaces

halfspaces defining the Tukey region by their intersection, a matrix with number of columns equal to space dimension and where each row corresponds to a halfspace defined by three point numbers in data.

innerPoint

inner point, a vector of length equal to dimension.

verbosity

level of details to print during execution, integer, from 0 (= print nothing) to 2 (= print all details).

Details

The function computes the Tukey region (upper-level set of the Tukey depth function) for n points in the Euclidean d-variate space contained in data at the depth value depth.

Three methods are implemented: Method "bfs" is the most efficient, it starts with an initial set of ridges and traverses all facets using the breadth-first search algorithm. Method "cmb" considers all subspaces spanned by combinations of d - 1 points, projects data onto their orthogonal complements (planes), and searches for bivariate quantiles these planes. Method "bf" employs the brute-force strategy by checking all halfspaces defined by hyperplanes containing d points from data. If d = 2, method "bf" is used. See Liu, Mosler, and Mozharovskyi (2019) for details on algorithms.

The function proceeds in three main steps. Step 1: Calculate all the halfspaces defining Tukey region in their intersection. Many of them are usually redundant. Step 2: Find the inner point of the Tukey region, i.e. a point which lies simultaneously in all the before calculated halfspaces. If such a point does not exist neither does the Tukey region exist for this depth level. The algorithm stops and returns FALSE in the field innerPointFound. If the inner point has been found, the algorithm proceeds to Step 3: Filter the halfspaces leaving only those containing the facets of the Tukey region. Step 3 provides infirmation to compute vertices, facets, volume, and barycenter of the Tukey region.

halfspaces and/or innerPoint can be provided as function arguments.

The function tries to fulfill all the requirements indicated by the input flags. Step 1 is performed anyway (even if retHalfspaces is unset, which means the halfspaces just should not be output, except they are provided by the argument halfspaces). If any further ret...-flag is set Step 2 is performed, except retHalfspacesNR is unset and the argument innerPoint provided. If any of retVertices, retFacets, retVolume, retBarycenter is set, Step 3 is performed.

The region can be visualized in 2- and 3-dimensional space by plot(...), general information can be printed by print(...), statistics can be summarized by summary(...).

Value

The function returns an object of class TukeyRegion with fields specified by ret...-flags in the arguments:

data

the input data set.

depth

chosen depth level.

halfspacesFound

whether at least one of the determining Tukey region halfspaces has been found.

halfspaces

if requested, halfspaces defining the Tukey region by their intersection, a matrix with number of columns equal to space dimension and where each row corresponds to a halfspace defined by three point numbers in data.

innerPointFound

a logical indicating whether an inner point of the region has been found. If FALSE then the region of the given depth does not exist. If the field is absent then the inner point has not been requested by the input arguments.

innerPoint

coordinates of a point inside of the Tukey region. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

halfspacesNR

non-redundant halfspaces (i.e. those containing Tukey region's facets), a matrix with number of columns equal to space dimension and where each row corresponds to a halfspace defined by three point numbers in data. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

vertices

vertices of the Tukey region, a matrix with number of columns equal to space dimension and where each row represents vertex coordinates. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments. If field facets is returned, this field is returned as well.

triangulated

a logical repeating the trgFacets input argument. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

facets

facets of the Tukey region. If input argument trgFacets is set, then this is a list where each element is an array enumerating numbers of the rows in field vertices; their number for each facet can vary. If input argument trgFacets is unset, then this is a matrix with each row corresponding to a triangulated facet, and no facets' ridges reconstruction is performed. So it cannot be visualized. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

volume

volume of the Tukey region. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

barycenter

the barycenter of the Tukey region. If the field is absent then either no halfspaces or no inner point have been found or facet computation has not been requested by the input arguments.

numRidges

number of used ridges.

Author(s)

Pavlo Mozharovskyi <[e-mail]>

References

Liu, X., Mosler, K., and Mozharovskyi, P. (2019). Fast computation of Tukey trimmed regions and median in dimension p > 2. Journal of Computational and Graphical Statistics, 28, 682-697.

See Also

TukeyMedian

Examples

# Load required packages
require(TukeyRegion)
require(MASS)
# Generate data
set.seed(1)
X <- mvrnorm(500, rep(0, 3),
  matrix(c(1, 1, 1, 1, 2, 2, 1, 2, 4), nrow = 3))
# Compute the Tukey region
Tr <- TukeyRegion(X, 10, "bfs",
  retFacets = TRUE, retVolume = TRUE, retBarycenter = TRUE)
summary(Tr)
# Visualize the Tukey region
plot(Tr)