randomTukeyDepth.hh

Go to the documentation of this file.

#ifndef NPSTAT_RANDOMTUKEYDEPTH_HH_
#define NPSTAT_RANDOMTUKEYDEPTH_HH_
 
/*!
// \file randomTukeyDepth.hh
//
// \brief Implementation of Tukey depth using random directions and/or
//        directions from the center of the cloud to the sample points
//
// Author: I. Volobouev
//
// March 2023
*/
 
#include "npstat/nm/Matrix.hh"
#include "npstat/rng/AbsRandomGenerator.hh"
 
// For a detailed description of the random Tukey depth concept, see
// Cuesta-Albertos, J. A. and Nieto-Reyes, A., "The random Tukey depth",
// Computational Statistics & Data Analysis 52, 11 (July 2008), 4979-4988.
namespace npstat {
    /**
    // Random Tukey depth calculated within the sample.
    // Function arguments are as follows:
    //
    // sample   should be dimensioned n x d, where d is the
    //          point dimensionality and n is the sample size.
    //
    // rng      random number generator in 1 or d dimensions.
    //
    // covmat   should be dimensioned d x d. The random directions
    //          will be generated by a multivariate normal
    //          distribution with this covariance matrix.
    //
    // nRandom  is the number of random directions to generate.
    //          In addition to random directions, the ordering
    //          will also be perfomed according to the marginals.
    //
    // depth    this array will be filled with depth values
    //          on exit (in the same order of points as in
    //          the "sample" argument).
    //
    // nDepth   is the length of the "depth" array. Should be
    //          at least as large as the sample size.
    //
    // usePointDirections  if this argument is set to "true",
    //                     directions from the center of the
    //                     cloud to each sample point will also
    //                     be utilized in the depth calculation.
    //
    // The CPU time used by this function will scale as
    // O(nRandom*n*log(n)) if "usePointDirections" is false.
    // If "usePointDirections" is true, another step will
    // be added that scales as O(n^2*log(n)).
    */
    template<typename Real>
    void randomTukeyDepth1(const Matrix<Real>& sample,
                           AbsRandomGenerator& rng,
                           const Matrix<double>& covmat,
                           unsigned nRandom,
                           double* depth, unsigned nDepth,
                           bool usePointDirections = false);
 
    /**
    // Random Tukey depth for each point in a sample calculated
    // using another (reference) sample. Function arguments are
    // as follows:
    //
    // sample   should be dimensioned n x d, where d is the
    //          point dimensionality and n is the sample size.
    //
    // refSample  the depth of each point in the "sample" argument
    //            will be defined with respect to this "reference"
    //            sample. The size of this sample should normally
    //            be substantialy larger than n.
    //
    // rng      random number generator in 1 or d dimensions.
    //
    // covmat   should be dimensioned d x d. The random directions
    //          will be generated by a multivariate normal
    //          distribution with this covariance matrix.
    //
    // nRandom  is the number of random directions to generate.
    //          In addition to random directions, the ordering
    //          will also be perfomed according to the marginals.
    //
    // depth    this array will be filled with depth values
    //          on exit (in the same order of points as in
    //          the "sample" argument).
    //
    // nDepth   is the length of the "depth" array. Should be
    //          at least as large as the "sample" size.
    //
    // usePointDirections  if this argument is set to "true",
    //                     directions from the center of the
    //                     "refSample" cloud to each point of
    //                     the "sample" will also be utilized
    //                     in the depth calculation.
    //
    // Assuming that the size of the reference sample is m,
    // the CPU time used by this function will scale as
    // O(nRandom*(m+n)*log(m)) if "usePointDirections" is false.
    // If "usePointDirections" is true, another step will
    // be added that scales as O(n*(m+n)*log(m)).
    */
    template<typename Real1, typename Real2>
    void randomTukeyDepth2(const Matrix<Real1>& sample,
                           const Matrix<Real2>& refSample,
                           AbsRandomGenerator& rng,
                           const Matrix<double>& covmat,
                           unsigned nRandom,
                           double* depth, unsigned nDepth,
                           bool usePointDirections = false);
}
 
#include "npstat/stat/randomTukeyDepth.icc"
 
#endif // NPSTAT_RANDOMTUKEYDEPTH_HH_