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 1244107 2012-02-14 16:17:55Z erans $

- - ### 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[]` | `normalize(double[] sample)` Normalize (standardize) the series, so in the end it is having 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)

      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:
        `IllegalArgumentException` - if the array is null

    - #### sum

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### sumSq

          public 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.

      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:
        `IllegalArgumentException` - if the array is null

    - #### sumSq

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### product

          public static double product(double[] values)

      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:
        `IllegalArgumentException` - if the array is null

    - #### product

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### sumLog

          public 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.

      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:
        `IllegalArgumentException` - if the array is null

    - #### sumLog

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### mean

          public static double mean(double[] values)

      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:
        `IllegalArgumentException` - if the array is null

    - #### mean

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### geometricMean

          public static double geometricMean(double[] values)

      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:
        `IllegalArgumentException` - if the array is null

    - #### geometricMean

          public 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.

      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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### variance

          public static double variance(double[] values)

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### variance

          public 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.

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - 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)

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### variance

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

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### populationVariance

          public static double populationVariance(double[] values)

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### populationVariance

          public 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.

      See `Variance` for details on the computing algorithm.

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

      Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - 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)

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### populationVariance

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

      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 `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### max

          public static double max(double[] values)

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

      Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### max

          public 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.

      Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### min

          public static double min(double[] values)

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

      Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null

    - #### min

          public 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.

      Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the array is null or the array index parameters are not valid

    - #### percentile

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

      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:
        `IllegalArgumentException` - if `values` is null or p is invalid

    - #### percentile

          public 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.

      - Returns `Double.NaN` if `length = 0`
      - Returns (for any value of `p`) `values[begin]` if `length = 1`
      - Throws `IllegalArgumentException` 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:
        `IllegalArgumentException` - if the parameters are not valid or the input array is null

    - #### sumDifference

          public 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]).
      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)

      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)

      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 series, so in the end it is having a mean of 0 and a standard deviation of 1.
      Parameters:
        `sample` - Sample to normalize.
      Returns:
        normalized (standardized) sample.
      Since:
        2.2

Copyright © 2003-2012 The Apache Software Foundation. All Rights Reserved.