org.apache.commons.math3.stat
Class StatUtils

java.lang.Object
  extended by 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 $

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[] 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 pth percentile of the values in the values array.
static double percentile(double[] values, int begin, int length, double p)
          Returns an estimate of the pth percentile of the values in the values array, starting with the element in (0-based) position begin in the array and including length values.
static double populationVariance(double[] values)
          Returns the population variance of the entries in the input array, or Double.NaN if the array is empty.
static double populationVariance(double[] values, double mean)
          Returns the population variance of the entries in the input array, using the precomputed mean value.
static double populationVariance(double[] values, double mean, int begin, int length)
          Returns the population variance of the entries in the specified portion of the input array, using the precomputed mean value.
static double populationVariance(double[] values, int begin, int length)
          Returns the population variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double product(double[] values)
          Returns the product of the entries in the input array, or Double.NaN if the array is empty.
static double product(double[] values, int begin, int length)
          Returns the product of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double sum(double[] values)
          Returns the sum of the values in the input array, or Double.NaN if the array is empty.
static double sum(double[] values, int begin, int length)
          Returns the sum of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double sumDifference(double[] sample1, double[] sample2)
          Returns the sum of the (signed) differences between corresponding elements of the input arrays -- i.e., sum(sample1[i] - sample2[i]).
static double sumLog(double[] values)
          Returns the sum of the natural logs of the entries in the input array, or Double.NaN if the array is empty.
static double sumLog(double[] values, int begin, int length)
          Returns the sum of the natural logs of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double sumSq(double[] values)
          Returns the sum of the squares of the entries in the input array, or Double.NaN if the array is empty.
static double sumSq(double[] values, int begin, int length)
          Returns the sum of the squares of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double variance(double[] values)
          Returns the variance of the entries in the input array, or Double.NaN if the array is empty.
static double variance(double[] values, double mean)
          Returns the variance of the entries in the input array, using the precomputed mean value.
static double variance(double[] values, double mean, int begin, int length)
          Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value.
static double variance(double[] values, int begin, int length)
          Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
static double varianceDifference(double[] sample1, double[] sample2, double meanDifference)
          Returns the variance of the (signed) differences between corresponding elements of the input arrays -- i.e., var(sample1[i] - sample2[i]).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

sum

public static double sum(double[] values)
                  throws MathIllegalArgumentException
Returns the sum of the values in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the input array is null.

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

sum

public static double sum(double[] values,
                         int begin,
                         int length)
                  throws MathIllegalArgumentException
Returns the sum of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

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

sumSq

public static double sumSq(double[] values)
                    throws MathIllegalArgumentException
Returns the sum of the squares of the entries in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the array is null.

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

sumSq

public static double sumSq(double[] values,
                           int begin,
                           int length)
                    throws MathIllegalArgumentException
Returns the sum of the squares of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

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

product

public static double product(double[] values)
                      throws MathIllegalArgumentException
Returns the product of the entries in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the array is null.

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

product

public static double product(double[] values,
                             int begin,
                             int length)
                      throws MathIllegalArgumentException
Returns the product of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

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

sumLog

public static double sumLog(double[] values)
                     throws MathIllegalArgumentException
Returns the sum of the natural logs of the entries in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the array is null.

See SumOfLogs.

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

sumLog

public static double sumLog(double[] values,
                            int begin,
                            int length)
                     throws MathIllegalArgumentException
Returns the sum of the natural logs of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

See SumOfLogs.

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

mean

public static double mean(double[] values)
                   throws MathIllegalArgumentException
Returns the arithmetic mean of the entries in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the array is null.

See Mean for details on the computing algorithm.

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

mean

public static double mean(double[] values,
                          int begin,
                          int length)
                   throws MathIllegalArgumentException
Returns the arithmetic mean of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

See Mean for details on the computing algorithm.

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

geometricMean

public static double geometricMean(double[] values)
                            throws MathIllegalArgumentException
Returns the geometric mean of the entries in the input array, or Double.NaN if the array is empty.

Throws IllegalArgumentException if the array is null.

See GeometricMean for details on the computing algorithm.

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

geometricMean

public static double geometricMean(double[] values,
                                   int begin,
                                   int length)
                            throws MathIllegalArgumentException
Returns the geometric mean of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

Throws IllegalArgumentException if the array is null.

See GeometricMean for details on the computing algorithm.

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

variance

public static double variance(double[] values)
                       throws MathIllegalArgumentException
Returns the variance of the entries in the input array, or Double.NaN if the array is empty.

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

See Variance for details on the computing algorithm.

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

Throws MathIllegalArgumentException if the array is null.

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

variance

public static double variance(double[] values,
                              int begin,
                              int length)
                       throws MathIllegalArgumentException
Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

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

See Variance for details on the computing algorithm.

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

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

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

variance

public static double variance(double[] values,
                              double mean,
                              int begin,
                              int length)
                       throws MathIllegalArgumentException
Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns Double.NaN if the designated subarray is empty.

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

See Variance for details on the computing algorithm.

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

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

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

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

variance

public static double variance(double[] values,
                              double mean)
                       throws MathIllegalArgumentException
Returns the variance of the entries in the input array, using the precomputed mean value. Returns Double.NaN if the array is empty.

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

See Variance for details on the computing algorithm.

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

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

Throws MathIllegalArgumentException if the array is null.

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

populationVariance

public static double populationVariance(double[] values)
                                 throws MathIllegalArgumentException
Returns the population variance of the entries in the input array, or Double.NaN if the array is empty.

See Variance for details on the formula and computing algorithm.

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

Throws MathIllegalArgumentException if the array is null.

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

populationVariance

public static double populationVariance(double[] values,
                                        int begin,
                                        int length)
                                 throws MathIllegalArgumentException
Returns the population variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

See Variance for details on the computing algorithm.

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

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

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

populationVariance

public static double populationVariance(double[] values,
                                        double mean,
                                        int begin,
                                        int length)
                                 throws MathIllegalArgumentException
Returns the population variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns Double.NaN if the designated subarray is empty.

See Variance for details on the computing algorithm.

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

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

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

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

populationVariance

public static double populationVariance(double[] values,
                                        double mean)
                                 throws MathIllegalArgumentException
Returns the population variance of the entries in the input array, using the precomputed mean value. Returns Double.NaN if the array is empty.

See Variance for details on the computing algorithm.

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

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

Throws MathIllegalArgumentException if the array is null.

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

max

public static double max(double[] values)
                  throws MathIllegalArgumentException
Returns the maximum of the entries in the input array, or Double.NaN if the array is empty.

Throws MathIllegalArgumentException if the array is null.

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.

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.

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.

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 pth percentile of the values in the values array.

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 pth percentile of the values in the values array, starting with the element in (0-based) position begin in the array and including length values.

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


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