Percentile.EstimationType (Apache Commons Math 3.6.1 API)

org.apache.commons.math3.stat.descriptive.rank

## Enum Percentile.EstimationType

- java.lang.Object
- - java.lang.Enum<Percentile.EstimationType>
  - - org.apache.commons.math3.stat.descriptive.rank.Percentile.EstimationType

- All Implemented Interfaces:
    Serializable, Comparable<Percentile.EstimationType>
  Enclosing class:
    Percentile

      public static enum Percentile.EstimationType
      extends Enum<Percentile.EstimationType>

  An enum for various estimation strategies of a percentile referred in wikipedia on quantile with the names of enum matching those of types mentioned in wikipedia.

  Each enum corresponding to the specific type of estimation in wikipedia implements the respective formulae that specializes in the below aspects

  - An index method to calculate approximate index of the estimate
  - An estimate method to estimate a value found at the earlier computed index
  - A minLimit on the quantile for which first element of sorted input is returned as an estimate
  - A maxLimit on the quantile for which last element of sorted input is returned as an estimate

  Users can now create `Percentile` by explicitly passing this enum; such as by invoking `Percentile.withEstimationType(EstimationType)`

  References:

  1. Wikipedia on quantile
  2. Hyndman, R. J. and Fan, Y. (1996) Sample quantiles in statistical packages, American Statistician 50, 361–365
  3. R-Manual

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and Description
    `LEGACY` This is the default type used in the `Percentile`.This method has the following formulae for index and estimates \( \begin{align} &index = (N+1)p\ \\ &estimate = x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)
    `R_1` The method R_1 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate= x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ \end{align}\)
    `R_2` The method R_2 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\, \\ &estimate=\frac{x_{\lceil h\,-\,1/2 \rceil} + x_{\lfloor h\,+\,1/2 \rfloor}}{2} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)
    `R_3` The method R_3 has the following formulae for index and estimates \( \begin{align} &index= Np \\ &estimate= x_{\lfloor h \rceil}\, \\ &minLimit = 0.5/N \\ \end{align}\)
    `R_4` The method R_4 has the following formulae for index and estimates \( \begin{align} &index= Np\, \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/N \\ &maxLimit = 1 \\ \end{align}\)
    `R_5` The method R_5 has the following formulae for index and estimates \( \begin{align} &index= Np + 1/2\\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0.5/N \\ &maxLimit = (N-0.5)/N \end{align}\)
    `R_6` The method R_6 has the following formulae for index and estimates \( \begin{align} &index= (N + 1)p \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/(N+1) \\ &maxLimit = N/(N+1) \\ \end{align}\)
    `R_7` The method R_7 implements Microsoft Excel style computation has the following formulae for index and estimates. \( \begin{align} &index = (N-1)p + 1 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)
    `R_8` The method R_8 has the following formulae for index and estimates \( \begin{align} &index = (N + 1/3)p + 1/3 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (2/3)/(N+1/3) \\ &maxLimit = (N-1/3)/(N+1/3) \\ \end{align}\)
    `R_9` The method R_9 has the following formulae for index and estimates \( \begin{align} &index = (N + 1/4)p + 3/8\\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (5/8)/(N+1/4) \\ &maxLimit = (N-3/8)/(N+1/4) \\ \end{align}\)

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `estimate(double[] work, int[] pivotsHeap, double pos, int length, KthSelector selector)` Estimation based on Kth selection.
    `double` | `evaluate(double[] work, double p, KthSelector selector)` Evaluate method to compute the percentile for a given bounded array.
    `protected double` | `evaluate(double[] work, int[] pivotsHeap, double p, KthSelector selector)` Evaluate method to compute the percentile for a given bounded array using earlier computed pivots heap. This basically calls the `index` and then `estimate` functions to return the estimated percentile value.
    `protected abstract double` | `index(double p, int length)` Finds the index of array that can be used as starting index to `estimate` percentile.
    `static Percentile.EstimationType` | `valueOf(String name)` Returns the enum constant of this type with the specified name.
    `static Percentile.EstimationType[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class java.lang.Enum

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### LEGACY

          public static final Percentile.EstimationType LEGACY

      This is the default type used in the `Percentile`.This method has the following formulae for index and estimates
      \( \begin{align} &index = (N+1)p\ \\ &estimate = x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

    - #### R_1

          public static final Percentile.EstimationType R_1

      The method R_1 has the following formulae for index and estimates
      \( \begin{align} &index= Np + 1/2\, \\ &estimate= x_{\lceil h\,-\,1/2 \rceil} \\ &minLimit = 0 \\ \end{align}\)

    - #### R_2

          public static final Percentile.EstimationType R_2

      The method R_2 has the following formulae for index and estimates
      \( \begin{align} &index= Np + 1/2\, \\ &estimate=\frac{x_{\lceil h\,-\,1/2 \rceil} + x_{\lfloor h\,+\,1/2 \rfloor}}{2} \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

    - #### R_3

          public static final Percentile.EstimationType R_3

      The method R_3 has the following formulae for index and estimates
      \( \begin{align} &index= Np \\ &estimate= x_{\lfloor h \rceil}\, \\ &minLimit = 0.5/N \\ \end{align}\)

    - #### R_4

          public static final Percentile.EstimationType R_4

      The method R_4 has the following formulae for index and estimates
      \( \begin{align} &index= Np\, \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/N \\ &maxLimit = 1 \\ \end{align}\)

    - #### R_5

          public static final Percentile.EstimationType R_5

      The method R_5 has the following formulae for index and estimates
      \( \begin{align} &index= Np + 1/2\\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0.5/N \\ &maxLimit = (N-0.5)/N \end{align}\)

    - #### R_6

          public static final Percentile.EstimationType R_6

      The method R_6 has the following formulae for index and estimates
      \( \begin{align} &index= (N + 1)p \\ &estimate= x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 1/(N+1) \\ &maxLimit = N/(N+1) \\ \end{align}\)

      Note: This method computes the index in a manner very close to the default Commons Math Percentile existing implementation. However the difference to be noted is in picking up the limits with which first element (p<1(N+1)) and last elements (p>N/(N+1))are done. While in default case; these are done with p=0 and p=1 respectively.

    - #### R_7

          public static final Percentile.EstimationType R_7

      The method R_7 implements Microsoft Excel style computation has the following formulae for index and estimates.
      \( \begin{align} &index = (N-1)p + 1 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = 0 \\ &maxLimit = 1 \\ \end{align}\)

    - #### R_8

          public static final Percentile.EstimationType R_8

      The method R_8 has the following formulae for index and estimates
      \( \begin{align} &index = (N + 1/3)p + 1/3 \\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (2/3)/(N+1/3) \\ &maxLimit = (N-1/3)/(N+1/3) \\ \end{align}\)

      As per Ref [2,3] this approach is most recommended as it provides an approximate median-unbiased estimate regardless of distribution.

    - #### R_9

          public static final Percentile.EstimationType R_9

      The method R_9 has the following formulae for index and estimates
      \( \begin{align} &index = (N + 1/4)p + 3/8\\ &estimate = x_{\lfloor h \rfloor} + (h - \lfloor h \rfloor) (x_{\lfloor h \rfloor + 1} - x_{\lfloor h \rfloor}) \\ &minLimit = (5/8)/(N+1/4) \\ &maxLimit = (N-3/8)/(N+1/4) \\ \end{align}\)

  - ### Method Detail

    - #### values

          public static Percentile.EstimationType[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (Percentile.EstimationType c : Percentile.EstimationType.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static Percentile.EstimationType valueOf(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `IllegalArgumentException` - if this enum type has no constant with the specified name
        `NullPointerException` - if the argument is null

    - #### index

          protected abstract double index(double p,
                     int length)

      Finds the index of array that can be used as starting index to `estimate` percentile. The calculation of index calculation is specific to each `Percentile.EstimationType`.
      Parameters:
        `p` - the pth quantile
        `length` - the total number of array elements in the work array
      Returns:
        a computed real valued index as explained in the wikipedia

    - #### estimate

          protected double estimate(double[] work,
                        int[] pivotsHeap,
                        double pos,
                        int length,
                        KthSelector selector)

      Estimation based on Kth selection. This may be overridden in specific enums to compute slightly different estimations.
      Parameters:
        `work` - array of numbers to be used for finding the percentile
        `pos` - indicated positional index prior computed from calling `index(double, int)`
        `pivotsHeap` - an earlier populated cache if exists; will be used
        `length` - size of array considered
        `selector` - a `KthSelector` used for pivoting during search
      Returns:
        estimated percentile

    - #### evaluate

          protected double evaluate(double[] work,
                        int[] pivotsHeap,
                        double p,
                        KthSelector selector)

      Evaluate method to compute the percentile for a given bounded array using earlier computed pivots heap.
      This basically calls the `index` and then `estimate` functions to return the estimated percentile value.
      Parameters:
        `work` - array of numbers to be used for finding the percentile
        `pivotsHeap` - a prior cached heap which can speed up estimation
        `p` - the pth quantile to be computed
        `selector` - a `KthSelector` used for pivoting during search
      Returns:
        estimated percentile
      Throws:
        `OutOfRangeException` - if p is out of range
        `NullArgumentException` - if work array is null

    - #### evaluate

          public double evaluate(double[] work,
                        double p,
                        KthSelector selector)

      Evaluate method to compute the percentile for a given bounded array. This basically calls the `index` and then `estimate` functions to return the estimated percentile value. Please note that this method does not make use of cached pivots.
      Parameters:
        `work` - array of numbers to be used for finding the percentile
        `p` - the pth quantile to be computed
        `selector` - a `KthSelector` used for pivoting during search
      Returns:
        estimated percentile
      Throws:
        `OutOfRangeException` - if length or p is out of range
        `NullArgumentException` - if work array is null

Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.