## org.apache.commons.math.stat
Class StatUtils

    java.lang.Object
      org.apache.commons.math.stat.StatUtils

    public final class StatUtils

extends java.lang.Object

StatUtils provides static methods for computing statistics based on data stored in double[] arrays.

Version:
  $Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $

Field Summary
`private static GeometricMean` `GEOMETRIC_MEAN` geometric mean
`private static UnivariateStatistic` `MAX` max
`private static UnivariateStatistic` `MEAN` mean
`private static UnivariateStatistic` `MIN` min
`private static Percentile` `PERCENTILE` percentile
`private static UnivariateStatistic` `PRODUCT` prod
`private static UnivariateStatistic` `SUM` sum
`private static UnivariateStatistic` `SUM_OF_LOGS` sumLog
`private static UnivariateStatistic` `SUM_OF_SQUARES` sumSq
`private static Variance` `VARIANCE` variance

Constructor Summary
`private` `StatUtils()` Private Constructor

Method Summary
`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` `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` `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`

Field Detail

### SUM

    private static final UnivariateStatistic SUM

  sum

### SUM_OF_SQUARES

    private static final UnivariateStatistic SUM_OF_SQUARES

  sumSq

### PRODUCT

    private static final UnivariateStatistic PRODUCT

  prod

### SUM_OF_LOGS

    private static final UnivariateStatistic SUM_OF_LOGS

  sumLog

### MIN

    private static final UnivariateStatistic MIN

  min

### MAX

    private static final UnivariateStatistic MAX

  max

### MEAN

    private static final UnivariateStatistic MEAN

  mean

### VARIANCE

    private static final Variance VARIANCE

  variance

### PERCENTILE

    private static final Percentile PERCENTILE

  percentile

### GEOMETRIC_MEAN

    private static final GeometricMean GEOMETRIC_MEAN

  geometric mean

Constructor Detail

### StatUtils

    private StatUtils()

  Private Constructor

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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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.

  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:
    `java.lang.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.

  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:
    `java.lang.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.

  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:
    `java.lang.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.

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

### sumDifference

    public static double sumDifference(double[] sample1,
                                       double[] sample2)
                                throws java.lang.IllegalArgumentException

  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:
    `java.lang.IllegalArgumentException` - if the arrays do not have the same (positive) length

### meanDifference

    public static double meanDifference(double[] sample1,
                                        double[] sample2)
                                 throws java.lang.IllegalArgumentException

  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:
    `java.lang.IllegalArgumentException` - if the arrays do not have the same (positive) length

### varianceDifference

    public static double varianceDifference(double[] sample1,
                                            double[] sample2,
                                            double meanDifference)
                                     throws java.lang.IllegalArgumentException

  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:
    `java.lang.IllegalArgumentException` - if the arrays do not have the same length or their common length is less than 2.
  See Also:
    `meanDifference(double[],double[])`

Copyright (c) 2003-2011 Apache Software Foundation