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 1416643 2012-12-03 19:37:14Z tn $

### Field Summary

Fields
`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

Constructors
`private` `StatUtils()` Private Constructor

### Method Summary

Methods
`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 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`

### 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)
                      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