R/RcppExports.R

In depthR: Multivariate Depth Functions for General Dimension

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Mahalanobis Depth
#'
#' Computes the Mahalanobis depth of one or more query points with respect
#' to a reference distribution estimated from \code{data}.
#'
#' @details
#' Mahalanobis depth is defined as
#' \deqn{D(x, F) = \frac{1}{1 + (x - \mu)^\top \Sigma^{-1} (x - \mu)}}
#' where \eqn{\mu} and \eqn{\Sigma} are the mean vector and covariance matrix
#' of \eqn{F}, estimated from \code{data}.
#'
#' Note: The deepest point under this depth function is the mean vector, not
#' a robust generalization of the median. Mahalanobis depth is included here
#' as a computationally trivial baseline and for comparison purposes.
#' For a genuine depth function, prefer \code{simplicial_depth} or
#' \code{tukey_depth}.
#'
#' @param x Numeric matrix of query points (m x d), or a numeric vector
#'   of length d for a single query point.
#' @param data Numeric matrix of reference data (n x d). Used to estimate
#'   the mean and covariance.
#' @param mu Optional numeric vector of length d. If supplied, overrides the
#'   mean estimated from \code{data}.
#' @param sigma Optional numeric matrix (d x d). If supplied, overrides the
#'   covariance estimated from \code{data}. Must be positive definite.
#'
#' @return Numeric vector of depth values in (0, 1], one per query point.
#'   A value of 1 indicates the query point coincides with the center (mean).
#'   Values decrease toward 0 as points move away from the center.
#'
#' @examples
#' \donttest{
#' set.seed(42)
#' data <- matrix(rnorm(200), nrow = 100, ncol = 2)
#' x    <- matrix(c(0, 0, 3, 3), nrow = 2, byrow = TRUE)
#' mahalanobis_depth(x, data)
#' }
#'
#' @keywords internal
.mahalanobis_depth_cpp <- function(x, data, mu = NULL, sigma = NULL) {
    .Call(`_depthR_mahalanobis_depth_cpp`, x, data, mu, sigma)
}

#' Depth-Based Outlyingness
#'
#' Converts depth values to outlyingness scores via O(x) = 1/D(x) - 1,
#' so that depth 1 maps to outlyingness 0 and depth approaching 0 maps
#' to outlyingness approaching infinity.
#'
#' @param depths Numeric vector of depth values in (0, 1].
#' @return Numeric vector of outlyingness values in [0, inf).
#'
#' @export
depth_outlyingness <- function(depths) {
    .Call(`_depthR_depth_outlyingness`, depths)
}

#' Projection Depth
#'
#' Computes the projection depth of one or more query points with respect
#' to a reference distribution estimated from \code{data}, using an adaptive
#' random projection approximation.
#'
#' @details
#' Projection depth is defined via the Stahel-Donoho outlyingness measure:
#' \deqn{O(x, F) = \sup_{u \neq 0} \frac{|u^\top x - \mathrm{med}(u^\top F)|}
#'                                        {\mathrm{MAD}(u^\top F)}}
#' \deqn{PD(x, F) = \frac{1}{1 + O(x, F)}}
#' where med and MAD are the median and median absolute deviation of the
#' projected distribution. The supremum is approximated by the maximum over
#' random unit vector projections.
#'
#' @param x Numeric matrix of query points (m x d), or a numeric vector
#'   of length d for a single query point.
#' @param data Numeric matrix of reference data (n x d).
#' @param tol Convergence tolerance for the adaptive stopping rule. Default
#'   0.01.
#' @param batch_size Number of random projections per batch. Default 100.
#' @param min_batches Minimum batches before checking convergence. Default 5.
#' @param patience Consecutive stable batches required to declare convergence.
#'   Default 3.
#' @param seed Integer random seed for reproducibility. Default 42.
#'
#' @return Numeric vector of depth values in (0, 1], one per query point.
#'
#' @references
#' Zuo, Y. & Serfling, R. (2000). General notions of statistical depth
#' function. \emph{Annals of Statistics}, 28(2), 461--482.
#'
#' Stahel, W. A. (1981). Robuste Schätzungen: infinitesimale Optimalität
#' und Schätzungen von Kovarianzmatrizen. PhD thesis, ETH Zürich.
#'
#' @keywords internal
.projection_depth_cpp <- function(x, data, tol = 0.01, batch_size = 100L, min_batches = 5L, patience = 3L, seed = 42L) {
    .Call(`_depthR_projection_depth_cpp`, x, data, tol, batch_size, min_batches, patience, seed)
}

#' Liu Simplicial Depth
#'
#' Computes the simplicial depth of one or more query points with respect
#' to a reference distribution estimated from \code{data}, using an adaptive
#' Monte Carlo approximation.
#'
#' @details
#' Simplicial depth of a point x with respect to distribution F is defined as
#' the probability that a random simplex formed by d+1 independent draws from
#' F contains x:
#' \deqn{SD(x, F) = P(x \in S[X_1, \ldots, X_{d+1}])}
#' where \eqn{S[X_1, \ldots, X_{d+1}]} denotes the closed simplex with
#' vertices \eqn{X_1, \ldots, X_{d+1}}.
#'
#' This is estimated by sampling random simplices from the empirical
#' distribution and checking containment via barycentric coordinates.
#' The adaptive stopping rule uses the Bernoulli standard error to determine
#' when the estimate has converged.
#'
#' @param x Numeric matrix of query points (m x d), or a numeric vector
#'   of length d for a single query point.
#' @param data Numeric matrix of reference data (n x d). Must have at least
#'   d+1 rows.
#' @param tol Relative standard error tolerance for the stopping rule.
#'   Default 0.05 (5\%).
#' @param batch_size Number of random simplices per batch. Default 200.
#' @param min_batches Minimum number of batches before checking convergence.
#'   Default 3.
#' @param max_batches Maximum number of batches regardless of convergence.
#'   Acts as a hard cap on computation time. Default 20.
#' @param seed Integer random seed for reproducibility. Default 42.
#'
#' @return Numeric vector of depth values in [0, 1], one per query point.
#'
#' @references
#' Liu, R. Y. (1990). On a notion of data depth based on random simplices.
#' \emph{Annals of Statistics}, 18(1), 405--414.
#'
#' @keywords internal
.simplicial_depth_cpp <- function(x, data, tol = 0.05, batch_size = 200L, min_batches = 3L, max_batches = 20L, seed = 42L) {
    .Call(`_depthR_simplicial_depth_cpp`, x, data, tol, batch_size, min_batches, max_batches, seed)
}

#' Spatial Depth
#'
#' Computes the spatial depth of one or more query points with respect
#' to a reference distribution estimated from \code{data}.
#'
#' @details
#' Spatial depth is defined as:
#' \deqn{SD(x, F) = 1 - \left\| E\left[ \frac{x - X}{\|x - X\|} \right] \right\|}
#' where the expectation is over \eqn{X \sim F}. It is estimated by the
#' sample mean of unit vectors pointing from each data point toward x.
#'
#' Unlike other depth functions in this package, spatial depth has a
#' closed-form sample estimate and requires no Monte Carlo approximation.
#' This makes it extremely fast even at large n and d.
#'
#' Spatial depth is not affine invariant but is orthogonally invariant,
#' and has been found to work well in high dimensions where affine
#' invariant methods can be computationally prohibitive.
#'
#' @param x Numeric matrix of query points (m x d), or a numeric vector
#'   of length d for a single query point.
#' @param data Numeric matrix of reference data (n x d).
#'
#' @return Numeric vector of depth values in [0, 1], one per query point.
#'   A value of 1 indicates perfect centrality (the spatial median).
#'   Values decrease toward 0 as points move away from the center.
#'
#' @references
#' Vardi, Y. & Zhang, C.-H. (2000). The multivariate L1-median and
#' associated data depth. \emph{Proceedings of the National Academy of
#' Sciences}, 97(4), 1423--1426.
#'
#' Serfling, R. (2006). Depth functions in nonparametric multivariate
#' inference. \emph{DIMACS Series in Discrete Mathematics}, 72, 1--16.
#'
#' @keywords internal
.spatial_depth_cpp <- function(x, data) {
    .Call(`_depthR_spatial_depth_cpp`, x, data)
}

#' Tukey (Halfspace) Depth
#'
#' Computes the Tukey halfspace depth of one or more query points with respect
#' to a reference distribution estimated from \code{data}, using an adaptive
#' random projection approximation.
#'
#' @param x Numeric matrix of query points (m x d), or a numeric vector
#'   of length d for a single query point.
#' @param data Numeric matrix of reference data (n x d).
#' @param tol Convergence tolerance. Default 0.01.
#' @param batch_size Number of random projections per batch. Default 100.
#' @param min_batches Minimum batches before checking convergence. Default 5.
#' @param patience Consecutive stable batches to declare convergence. Default 3.
#' @param seed Integer random seed for reproducibility. Default 42.
#'
#' @return Numeric vector of depth values in [0, 0.5], one per query point.
#'
#' @keywords internal
.tukey_depth_cpp <- function(x, data, tol = 0.01, batch_size = 100L, min_batches = 5L, patience = 3L, seed = 42L) {
    .Call(`_depthR_tukey_depth_cpp`, x, data, tol, batch_size, min_batches, patience, seed)
}