Bootstrap and Refine Iterative Locator

Source: R/bril.R

Robust Estimate of Mode in Multivariate Distribution

bril(
  data,
  maxIterations = NULL,
  minUnassigned = 0.1,
  method = "Projection",
  alpha = 0.5,
  testUnimodal = "DIP",
  threshUnimodal = 0.05,
  distUnimodal = "Euclidean",
  testNormal = "Mardia",
  threshNormal = 0.05,
  distNormal = "MCD",
  trimmedPerFilteringIteration = 1,
  exitWhenUnimodal = FALSE,
  debug = FALSE,
  warnings = FALSE
)

Arguments

data

Matrix of numerical values containing the observations (one per row, with two columns for X and Y coordinates)
maxIterations

Maximum number of iterations performed by the algorithm (set to NULL or 0 for unlimited number)
minUnassigned

Numerical value between 0 and 1 (default: 0.1), providing the proportion of unassigned samples from data below which the algorithm will terminate
method

Method to use. Valid options are "MCD" and "MVE" for convex body minimizers, or "L2", "Lui", "Mahalanobis", "Oja", "Projection" (default), "Spatial" and "Tukey" for depth functions
alpha

Proportion of samples trimmed at each iteration of the recursive median estimate (numerical value between 0 and 1, default: 0.5), see median_rec()
testUnimodal

Statistical test used for unimodality. Valid options are "DIP" only, see filter_outliers()
threshUnimodal

Threshold of significance for the unimodality test (numerical value between 0 and 1, default: 0.05)
distUnimodal

Distance metric used for ordering the samples in the unimodal filtering. Valid options are "Euclidean" (default), or "MCD", "MVE", and "OGK" for robust distances. "Euclidean" is strongly advised for unimodality tests.
testNormal

Statistical test used for normality. Valid options are "Mardia" (default), "Kurtosis", "Skewness", "KS", "KS-adj", "Shapiro", "Lillie" and "Chisq", see filter_outliers()
threshNormal

Threshold of significance for the normality test (numerical value between 0 and 1, default: 0.05)
distNormal

Distance metric used for ordering the samples in the normal filtering. Valid options are "Euclidean", or "MCD" (default), "MVE", and "OGK" for robust distances. Robust distances are strongly advised for normality tests.
trimmedPerFilteringIteration

Number of samples trimmed at each iteration of the unimodality and normality filtering (default: 1), see filter_outliers()
exitWhenUnimodal

Logical value. TRUE will terminate the execution of the algorithm as soon as an unimodal subset is encountered on the start of a global iteration. FALSE (default) will let that last iteration proceed before terminating
debug

Logical value. TRUE will compute all p.values in the filtering steps (even after they exceed the selection threshold, see plot.BRIL.Filtering())
warnings

Logical value, to display the warnings and errors caught

Value

The function returns an S3 object of type BRIL containing the following values:

call

Parameters of the call (contains data, maxIterations, minUnassigned, method, alpha, testUnimodal, threshUnimodal, distUnimodal, testNormal, threshNormal, distNormal, trimmedPerFilteringIteration, and exitWhenUnimodal)

iterations

A list with every global iteration of the algorithm, each containing the two filtering procedures performed: filteringUnimodal and filteringNormal (both being S3 object of class BRIL.Filtering, see filter_outliers())

nbClusters

Number of groups encountered

labels

Labels of the groups encountered (corresponding to the number of the iteration they were identified in)

clustersCenters

Matrix containing the coordinates of the centers of each group (row-wise)

clustersSizes

Array with the number of samples in each group

mainCluster

Index of the group identified as main mode

mode

Coordinates of the main mode

References

Adrien Brilhault, Sergio Neuenschwander, and Ricardo Rios - A New Robust Multivariate Mode Estimator for Eye-tracking Calibration - Behavior Research Methods, 2022 - rdcu.be/cI9Pf

See also

plot.BRIL(), print.BRIL(), filter_outliers(), median_rec(), median_mv(), depth_values()

Examples


# Create a sample distribution and run bril() function
XY <- rbind(
  mvtnorm::rmvnorm(300, c(0, 0), diag(2) * 3 - 1),
  mvtnorm::rmvnorm(100, c(15, 20), diag(2)),
  mvtnorm::rmvnorm(150, c(-10, 15), diag(2) * 2 - 0.5),
  mvtnorm::rmvnorm(200, c(5, 5), diag(2) * 200)
)

res <- bril(XY, debug = TRUE)
print(res)

#> 
#> => Results for bril() using method "Projection" (alpha=0.5), DIP Unimodality Test (> 0.05), and Mardia Normality test (> 0.05)
#>    750 samples: 3 clusters identified (sizes 311, 157, 105), and 177 samples unassigned
#> 
#> Mode:
#> [1]  0.2010784 -0.0902806
#> 
#> 
#> Clusters Sizes:
#> [1] 311 157 105
#> 
#> 
#> Clusters Centers:
#>            [,1]       [,2]
#> [1,]  0.2010784 -0.0902806
#> [2,] -9.8754989 15.0017539
#> [3,] 15.0869077 19.9320447
#> 
#> 
#> Labels:
#>   [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#>  [38] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#>  [75] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [112] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [149] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [186] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [223] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [260] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [297] 1 1 1 1 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3
#> [334] 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3
#> [371] 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2
#> [408] 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
#> [445] 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
#> [482] 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 0 2 2 2 2 2 2 2 2 2 2 2 2
#> [519] 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 0 0 0 0 0
#> [556] 0 0 0 1 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1
#> [593] 3 0 0 0 0 0 0 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 3 0 0 0 0 0 0 0 0 2
#> [630] 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2
#> [667] 1 0 0 1 0 0 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 2 0 2 0 0 0 0 0 0 0 0 0 0 0 0 0
#> [704] 0 0 0 2 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 3 0 0 0 2 0 0 0 0 0 0 0 0 0
#> [741] 0 0 2 0 0 0 0 0 3 0
#> 
#> 

# Plot the mode and groups encountered
plot(res)


# Plot the different iterations (interactive)
if (FALSE) {
plot(res, contents = "iterations", asp = 1)
}

# See ?plot.BRIL() for other plotting examples