org.apache.commons.math3.stat

## Class 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.

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.

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.
`meanDifference(double[],double[])`
`public static double[] normalize(double[] sample)`
`sample` - Sample to normalize.