StatUtils (Apache Commons Math 3.3 API)

org.apache.commons.math3.stat

## Class StatUtils

- java.lang.Object
- - org.apache.commons.math3.stat.StatUtils

-     public final class StatUtils
      extends Object

  StatUtils provides static methods for computing statistics based on data stored in double[] arrays.
  Version:
    $Id: StatUtils.java 1505931 2013-07-23 08:37:39Z luc $

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static double` | `geometricMean(double[] values)` Returns the geometric mean of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `geometricMean(double[] values, int begin, int length)` Returns the geometric mean of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `max(double[] values)` Returns the maximum of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `max(double[] values, int begin, int length)` Returns the maximum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `mean(double[] values)` Returns the arithmetic mean of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `mean(double[] values, int begin, int length)` Returns the arithmetic mean of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `meanDifference(double[] sample1, double[] sample2)` Returns the mean of the (signed) differences between corresponding elements of the input arrays -- i.e., sum(sample1[i] - sample2[i]) / sample1.length.
    `static double` | `min(double[] values)` Returns the minimum of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `min(double[] values, int begin, int length)` Returns the minimum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double[]` | `mode(double[] sample)` Returns the sample mode(s).
    `static double[]` | `mode(double[] sample, int begin, int length)` Returns the sample mode(s).
    `static double[]` | `normalize(double[] sample)` Normalize (standardize) the sample, so it is has a mean of 0 and a standard deviation of 1.
    `static double` | `percentile(double[] values, double p)` Returns an estimate of the `p`th percentile of the values in the `values` array.
    `static double` | `percentile(double[] values, int begin, int length, double p)` Returns an estimate of the `p`th percentile of the values in the `values` array, starting with the element in (0-based) position `begin` in the array and including `length` values.
    `static double` | `populationVariance(double[] values)` Returns the population variance of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `populationVariance(double[] values, double mean)` Returns the population variance of the entries in the input array, using the precomputed mean value.
    `static double` | `populationVariance(double[] values, double mean, int begin, int length)` Returns the population variance of the entries in the specified portion of the input array, using the precomputed mean value.
    `static double` | `populationVariance(double[] values, int begin, int length)` Returns the population variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `product(double[] values)` Returns the product of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `product(double[] values, int begin, int length)` Returns the product of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `sum(double[] values)` Returns the sum of the values in the input array, or `Double.NaN` if the array is empty.
    `static double` | `sum(double[] values, int begin, int length)` Returns the sum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `sumDifference(double[] sample1, double[] sample2)` Returns the sum of the (signed) differences between corresponding elements of the input arrays -- i.e., sum(sample1[i] - sample2[i]).
    `static double` | `sumLog(double[] values)` Returns the sum of the natural logs of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `sumLog(double[] values, int begin, int length)` Returns the sum of the natural logs of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `sumSq(double[] values)` Returns the sum of the squares of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `sumSq(double[] values, int begin, int length)` Returns the sum of the squares of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `variance(double[] values)` Returns the variance of the entries in the input array, or `Double.NaN` if the array is empty.
    `static double` | `variance(double[] values, double mean)` Returns the variance of the entries in the input array, using the precomputed mean value.
    `static double` | `variance(double[] values, double mean, int begin, int length)` Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value.
    `static double` | `variance(double[] values, int begin, int length)` Returns the variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
    `static double` | `varianceDifference(double[] sample1, double[] sample2, double meanDifference)` Returns the variance of the (signed) differences between corresponding elements of the input arrays -- i.e., var(sample1[i] - sample2[i]).

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### sum

          public static double sum(double[] values)
                            throws MathIllegalArgumentException

      Returns the sum of the values in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the input array is null.

      Parameters:
        `values` - array of values to sum
      Returns:
        the sum of the values or `Double.NaN` if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### sum

          public static double sum(double[] values,
                   int begin,
                   int length)
                            throws MathIllegalArgumentException

      Returns the sum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the sum of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### sumSq

          public static double sumSq(double[] values)
                              throws MathIllegalArgumentException

      Returns the sum of the squares of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the array is null.

      Parameters:
        `values` - input array
      Returns:
        the sum of the squared values or `Double.NaN` if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### sumSq

          public static double sumSq(double[] values,
                     int begin,
                     int length)
                              throws MathIllegalArgumentException

      Returns the sum of the squares of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the sum of the squares of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### product

          public static double product(double[] values)
                                throws MathIllegalArgumentException

      Returns the product of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
      Returns:
        the product of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### product

          public static double product(double[] values,
                       int begin,
                       int length)
                                throws MathIllegalArgumentException

      Returns the product of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the product of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### sumLog

          public static double sumLog(double[] values)
                               throws MathIllegalArgumentException

      Returns the sum of the natural logs of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `SumOfLogs`.

      Parameters:
        `values` - the input array
      Returns:
        the sum of the natural logs of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### sumLog

          public static double sumLog(double[] values,
                      int begin,
                      int length)
                               throws MathIllegalArgumentException

      Returns the sum of the natural logs of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `SumOfLogs`.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the sum of the natural logs of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### mean

          public static double mean(double[] values)
                             throws MathIllegalArgumentException

      Returns the arithmetic mean of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `Mean` for details on the computing algorithm.

      Parameters:
        `values` - the input array
      Returns:
        the mean of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### mean

          public static double mean(double[] values,
                    int begin,
                    int length)
                             throws MathIllegalArgumentException

      Returns the arithmetic mean of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `Mean` for details on the computing algorithm.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the mean of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### geometricMean

          public static double geometricMean(double[] values)
                                      throws MathIllegalArgumentException

      Returns the geometric mean of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `GeometricMean` for details on the computing algorithm.

      Parameters:
        `values` - the input array
      Returns:
        the geometric mean of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### geometricMean

          public static double geometricMean(double[] values,
                             int begin,
                             int length)
                                      throws MathIllegalArgumentException

      Returns the geometric mean of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `IllegalArgumentException` if the array is null.

      See `GeometricMean` for details on the computing algorithm.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the geometric mean of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### variance

          public static double variance(double[] values)
                                 throws MathIllegalArgumentException

      Returns the variance of the entries in the input array, or `Double.NaN` if the array is empty.

      This method returns the bias-corrected sample variance (using `n - 1` in the denominator). Use `populationVariance(double[])` for the non-bias-corrected population variance.

      See `Variance` for details on the computing algorithm.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
      Returns:
        the variance of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### variance

          public static double variance(double[] values,
                        int begin,
                        int length)
                                 throws MathIllegalArgumentException

      Returns the variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      This method returns the bias-corrected sample variance (using `n - 1` in the denominator). Use `populationVariance(double[], int, int)` for the non-bias-corrected population variance.

      See `Variance` for details on the computing algorithm.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the variance of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### variance

          public static double variance(double[] values,
                        double mean,
                        int begin,
                        int length)
                                 throws MathIllegalArgumentException

      Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns `Double.NaN` if the designated subarray is empty.

      This method returns the bias-corrected sample variance (using `n - 1` in the denominator). Use `populationVariance(double[], double, int, int)` for the non-bias-corrected population variance.

      See `Variance` for details on the computing algorithm.

      The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      Parameters:
        `values` - the input array
        `mean` - the precomputed mean value
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the variance of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### variance

          public static double variance(double[] values,
                        double mean)
                                 throws MathIllegalArgumentException

      Returns the variance of the entries in the input array, using the precomputed mean value. Returns `Double.NaN` if the array is empty.

      This method returns the bias-corrected sample variance (using `n - 1` in the denominator). Use `populationVariance(double[], double)` for the non-bias-corrected population variance.

      See `Variance` for details on the computing algorithm.

      The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
        `mean` - the precomputed mean value
      Returns:
        the variance of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### populationVariance

          public static double populationVariance(double[] values)
                                           throws MathIllegalArgumentException

      Returns the population variance of the entries in the input array, or `Double.NaN` if the array is empty.

      See `Variance` for details on the formula and computing algorithm.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
      Returns:
        the population variance of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### populationVariance

          public static double populationVariance(double[] values,
                                  int begin,
                                  int length)
                                           throws MathIllegalArgumentException

      Returns the population variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      See `Variance` for details on the computing algorithm.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the population variance of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### populationVariance

          public static double populationVariance(double[] values,
                                  double mean,
                                  int begin,
                                  int length)
                                           throws MathIllegalArgumentException

      Returns the population variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns `Double.NaN` if the designated subarray is empty.

      See `Variance` for details on the computing algorithm.

      The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      Parameters:
        `values` - the input array
        `mean` - the precomputed mean value
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the population variance of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### populationVariance

          public static double populationVariance(double[] values,
                                  double mean)
                                           throws MathIllegalArgumentException

      Returns the population variance of the entries in the input array, using the precomputed mean value. Returns `Double.NaN` if the array is empty.

      See `Variance` for details on the computing algorithm.

      The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.

      Returns 0 for a single-value (i.e. length = 1) sample.

      Throws `MathIllegalArgumentException` if the array is null.

      Parameters:
        `values` - the input array
        `mean` - the precomputed mean value
      Returns:
        the population variance of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### max

          public static double max(double[] values)
                            throws MathIllegalArgumentException

      Returns the maximum of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `MathIllegalArgumentException` if the array is null.

      - The result is `NaN` iff all values are `NaN` (i.e. `NaN` values have no impact on the value of the statistic).
      - If any of the values equals `Double.POSITIVE_INFINITY`, the result is `Double.POSITIVE_INFINITY.`
      Parameters:
        `values` - the input array
      Returns:
        the maximum of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### max

          public static double max(double[] values,
                   int begin,
                   int length)
                            throws MathIllegalArgumentException

      Returns the maximum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      - The result is `NaN` iff all values are `NaN` (i.e. `NaN` values have no impact on the value of the statistic).
      - If any of the values equals `Double.POSITIVE_INFINITY`, the result is `Double.POSITIVE_INFINITY.`
      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the maximum of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### min

          public static double min(double[] values)
                            throws MathIllegalArgumentException

      Returns the minimum of the entries in the input array, or `Double.NaN` if the array is empty.

      Throws `MathIllegalArgumentException` if the array is null.

      - The result is `NaN` iff all values are `NaN` (i.e. `NaN` values have no impact on the value of the statistic).
      - If any of the values equals `Double.NEGATIVE_INFINITY`, the result is `Double.NEGATIVE_INFINITY.`
      Parameters:
        `values` - the input array
      Returns:
        the minimum of the values or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if the array is null

    - #### min

          public static double min(double[] values,
                   int begin,
                   int length)
                            throws MathIllegalArgumentException

      Returns the minimum of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

      Throws `MathIllegalArgumentException` if the array is null or the array index parameters are not valid.

      - The result is `NaN` iff all values are `NaN` (i.e. `NaN` values have no impact on the value of the statistic).
      - If any of the values equals `Double.NEGATIVE_INFINITY`, the result is `Double.NEGATIVE_INFINITY.`
      Parameters:
        `values` - the input array
        `begin` - index of the first array element to include
        `length` - the number of elements to include
      Returns:
        the minimum of the values or Double.NaN if length = 0
      Throws:
        `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### percentile

          public static double percentile(double[] values,
                          double p)
                                   throws MathIllegalArgumentException

      Returns an estimate of the `p`th percentile of the values in the `values` array.

      - Returns `Double.NaN` if `values` has length `0`
      - Returns (for any value of `p`) `values[0]` if `values` has length `1`
      - Throws `IllegalArgumentException` if `values` is null or p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

      See `Percentile` for a description of the percentile estimation algorithm used.

      Parameters:
        `values` - input array of values
        `p` - the percentile value to compute
      Returns:
        the percentile value or Double.NaN if the array is empty
      Throws:
        `MathIllegalArgumentException` - if `values` is null or p is invalid

    - #### percentile

          public static double percentile(double[] values,
                          int begin,
                          int length,
                          double p)
                                   throws MathIllegalArgumentException

      Returns an estimate of the `p`th percentile of the values in the `values` array, starting with the element in (0-based) position `begin` in the array and including `length` values.

      - Returns `Double.NaN` if `length = 0`
      - Returns (for any value of `p`) `values[begin]` if `length = 1`
      - Throws `MathIllegalArgumentException` if `values` is null , `begin` or `length` is invalid, or `p` is not a valid quantile value (p must be greater than 0 and less than or equal to 100)

      See `Percentile` for a description of the percentile estimation algorithm used.

      Parameters:
        `values` - array of input values
        `p` - the percentile to compute
        `begin` - the first (0-based) element to include in the computation
        `length` - the number of array elements to include
      Returns:
        the percentile value
      Throws:
        `MathIllegalArgumentException` - if the parameters are not valid or the input array is null

    - #### sumDifference

          public static double sumDifference(double[] sample1,
                             double[] sample2)
                                      throws DimensionMismatchException,
                                             NoDataException

      Returns the sum of the (signed) differences between corresponding elements of the input arrays -- i.e., sum(sample1[i] - sample2[i]).
      Parameters:
        `sample1` - the first array
        `sample2` - the second array
      Returns:
        sum of paired differences
      Throws:
        `DimensionMismatchException` - if the arrays do not have the same (positive) length.
        `NoDataException` - if the sample arrays are empty.

    - #### meanDifference

          public static double meanDifference(double[] sample1,
                              double[] sample2)
                                       throws DimensionMismatchException,
                                              NoDataException

      Returns the mean of the (signed) differences between corresponding elements of the input arrays -- i.e., sum(sample1[i] - sample2[i]) / sample1.length.
      Parameters:
        `sample1` - the first array
        `sample2` - the second array
      Returns:
        mean of paired differences
      Throws:
        `DimensionMismatchException` - if the arrays do not have the same (positive) length.
        `NoDataException` - if the sample arrays are empty.

    - #### varianceDifference

          public static double varianceDifference(double[] sample1,
                                  double[] sample2,
                                  double meanDifference)
                                           throws DimensionMismatchException,
                                                  NumberIsTooSmallException

      Returns the variance of the (signed) differences between corresponding elements of the input arrays -- i.e., var(sample1[i] - sample2[i]).
      Parameters:
        `sample1` - the first array
        `sample2` - the second array
        `meanDifference` - the mean difference between corresponding entries
      Returns:
        variance of paired differences
      Throws:
        `DimensionMismatchException` - if the arrays do not have the same length.
        `NumberIsTooSmallException` - if the arrays length is less than 2.
      See Also:
        `meanDifference(double[],double[])`

    - #### normalize

          public static double[] normalize(double[] sample)

      Normalize (standardize) the sample, so it is has a mean of 0 and a standard deviation of 1.
      Parameters:
        `sample` - Sample to normalize.
      Returns:
        normalized (standardized) sample.
      Since:
        2.2

    - #### mode

          public static double[] mode(double[] sample)
                               throws MathIllegalArgumentException

      Returns the sample mode(s). The mode is the most frequently occurring value in the sample. If there is a unique value with maximum frequency, this value is returned as the only element of the output array. Otherwise, the returned array contains the maximum frequency elements in increasing order. For example, if `sample` is {0, 12, 5, 6, 0, 13, 5, 17}, the returned array will have length two, with 0 in the first element and 5 in the second.

      NaN values are ignored when computing the mode - i.e., NaNs will never appear in the output array. If the sample includes only NaNs or has length 0, an empty array is returned.

      Parameters:
        `sample` - input data
      Returns:
        array of array of the most frequently occurring element(s) sorted in ascending order.
      Throws:
        `MathIllegalArgumentException` - if the indices are invalid or the array is null
      Since:
        3.3

    - #### mode

          public static double[] mode(double[] sample,
                      int begin,
                      int length)

      Returns the sample mode(s). The mode is the most frequently occurring value in the sample. If there is a unique value with maximum frequency, this value is returned as the only element of the output array. Otherwise, the returned array contains the maximum frequency elements in increasing order. For example, if `sample` is {0, 12, 5, 6, 0, 13, 5, 17}, the returned array will have length two, with 0 in the first element and 5 in the second.

      NaN values are ignored when computing the mode - i.e., NaNs will never appear in the output array. If the sample includes only NaNs or has length 0, an empty array is returned.

      Parameters:
        `sample` - input data
        `begin` - index (0-based) of the first array element to include
        `length` - the number of elements to include
      Returns:
        array of array of the most frequently occurring element(s) sorted in ascending order.
      Throws:
        `MathIllegalArgumentException` - if the indices are invalid or the array is null
      Since:
        3.3

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