BRIL

BRIL (Bootstrap and Refine Iterative Locator) is an R package for multivariate mode estimate.

The BRIL algorithm estimate the main mode through three principal steps:

  • BOOTSTRAP: a recursive depth (or convex body minimizers) trimming to locate a first estimate.
  • REFINE: a two-pass outliers filtering, the first relying on euclidean distances to the first estimate and unimodality tests, the second on robust distances and multinormality tests.
  • ITERATE: after removing the samples selected in the REFINE step from the global distribution, the same process is reapplied, the first mode corresponding to the iteration with the largest number of samples.

To browse and test this package in an online RStudio environment, follow the link below:

Binder

To cite this package, please refer to:

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

Installation

To install BRIL from the GitHub repository, add first the remotes package if missing.

install.packages("remotes")

Then proceed to the installation of the BRIL package and its dependencies using the install_github function from remotes.

remotes::install_github("adrienbrilhault/BRIL", subdir = "pkg")


Note: As of May 2022, the OjaNP package - one of of BRIC’s dependencies - has been removed from the main CRAN repository. If missing, install it manually with the following command, and then launch the BRIC package installation again:

remotes::install_github("cran/OjaNP", subdir = "pkg")


Documentation

The package documentation is available in BRIL-manual.pdf, at adrienbrilhault.github.io/BRIL/, and directly in the R environment with the help commands.

# main documentation page
help(package = "BRIL")

# bril() function help
?BRIL::bril()


Example

If missing, install the mvtnorm package from CRAN with the command install.packages("mvtnorm"). Then try the following example, which creates a sample multivariate mixture, and estimates its main mode.

library(BRIL)
library(mvtnorm)

XY <- rbind(
  rmvnorm(300, c(0,0), diag(2)*3-1),
  rmvnorm(100, c(15,20), diag(2)),
  rmvnorm(150, c(-10,15), diag(2)*2-0.5),
  rmvnorm(200, c(5,5), diag(2)*200)
)

res <- bril(XY)

print(res)
plot(res)


Complementary code and data

This repository, beyond the R package itself (in the folder pkg), provides the datasets et complementary materials related to the article “Brilhault A, Neuenschwander S, Rios R - A New Robust Multivariate Mode Estimator for Eye-tracking Calibration - 2022”

Datasets

The real-world datasets used in the article, consisting of eye-tracking calibrations, are provided in data/eyeTrackingCalibrations.Rdata, with an illustrative video. They contain the x and y positions recorded from the eye-tracker in each trial, with their corresponding metadata, which includes the following attributes:

  • session: subject name and session identifier,
  • trial: trial number within the session,
  • nTrials: total number of trials in the session,
  • duration: duration of trials in the session (in ms),
  • target: id of the calibration target displayed during the trial,
  • nTargets: number of calibration targets in the session.

The table groundTruth provides the manually annotated reference coordinates for each of the calibration targets in every session. The labelling procedure, shown in this video, is described in the article, and its code available in data/groundTruthLabeling.R.

The three datasets presented in the article as Set1, Set2, and Set3 (with low, medium, and high contamination) correspond to the sessions juj011a00; ded00800, and ded005a01, respectively.

Additional code

The benchmarks folder of the repository contains a series of additional scripts and materials used in our study, as for instance:

Illustrative notebooks

To run these notebooks interactively in JupyterLab, follow this link:

Binder