Class StatUtils
-
Method Summary
Modifier and TypeMethodDescriptionstatic double
geometricMean
(double... values) Returns the geometric mean of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double
max
(double... values) Returns the maximum of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double
mean
(double... values) Returns the arithmetic mean of the entries in the input array, orDouble.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, orDouble.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, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double[]
mode
(double... sample) Returns the sample mode(s).static double[]
mode
(double[] sample, int begin, int length) Returns the sample mode(s).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 thep
th percentile of the values in thevalues
array.static double
percentile
(double[] values, int begin, int length, double p) Returns an estimate of thep
th percentile of the values in thevalues
array, starting with the element in (0-based) positionbegin
in the array and includinglength
values.static double
populationVariance
(double... values) Returns the population variance of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double
product
(double... values) Returns the product of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double
sum
(double... values) Returns the sum of the values in the input array, orDouble.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, orDouble.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, orDouble.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, orDouble.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, orDouble.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, orDouble.NaN
if the designated subarray is empty.static double
variance
(double... values) Returns the variance of the entries in the input array, orDouble.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, orDouble.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]).
-
Method Details
-
sum
Returns the sum of the values in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.Throws
IllegalArgumentException
if the array is null.- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
Returns the sum of the squares of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.Throws
IllegalArgumentException
if the array is null.- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
Returns the product of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.Throws
IllegalArgumentException
if the array is null.- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
Returns the sum of the natural logs of the entries in the input array, orDouble.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, orDouble.NaN
if the designated subarray is empty.Throws
IllegalArgumentException
if the array is null.See
SumOfLogs
.- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
Returns the arithmetic mean of the entries in the input array, orDouble.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, orDouble.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 arraybegin
- index of the first array element to includelength
- 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
Returns the geometric mean of the entries in the input array, orDouble.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, orDouble.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 arraybegin
- index of the first array element to includelength
- 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
Returns the variance of the entries in the input array, orDouble.NaN
if the array is empty.This method returns the bias-corrected sample variance (using
n - 1
in the denominator). UsepopulationVariance(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, orDouble.NaN
if the designated subarray is empty.This method returns the bias-corrected sample variance (using
n - 1
in the denominator). UsepopulationVariance(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 arraybegin
- index of the first array element to includelength
- 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. ReturnsDouble.NaN
if the designated subarray is empty.This method returns the bias-corrected sample variance (using
n - 1
in the denominator). UsepopulationVariance(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 arraymean
- the precomputed mean valuebegin
- index of the first array element to includelength
- 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
Returns the variance of the entries in the input array, using the precomputed mean value. ReturnsDouble.NaN
if the array is empty.This method returns the bias-corrected sample variance (using
n - 1
in the denominator). UsepopulationVariance(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 arraymean
- 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
Returns the population variance of the entries in the input array, orDouble.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, orDouble.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 arraybegin
- index of the first array element to includelength
- 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. ReturnsDouble.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 arraymean
- the precomputed mean valuebegin
- index of the first array element to includelength
- 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. ReturnsDouble.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 arraymean
- 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
Returns the maximum of the entries in the input array, orDouble.NaN
if the array is empty.Throws
MathIllegalArgumentException
if the array is null.- The result is
NaN
iff all values areNaN
(i.e.NaN
values have no impact on the value of the statistic). - If any of the values equals
Double.POSITIVE_INFINITY
, the result isDouble.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
- The result is
-
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, orDouble.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 areNaN
(i.e.NaN
values have no impact on the value of the statistic). - If any of the values equals
Double.POSITIVE_INFINITY
, the result isDouble.POSITIVE_INFINITY.
- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
- The result is
-
min
Returns the minimum of the entries in the input array, orDouble.NaN
if the array is empty.Throws
MathIllegalArgumentException
if the array is null.- The result is
NaN
iff all values areNaN
(i.e.NaN
values have no impact on the value of the statistic). - If any of the values equals
Double.NEGATIVE_INFINITY
, the result isDouble.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
- The result is
-
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, orDouble.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 areNaN
(i.e.NaN
values have no impact on the value of the statistic). - If any of the values equals
Double.NEGATIVE_INFINITY
, the result isDouble.NEGATIVE_INFINITY.
- Parameters:
values
- the input arraybegin
- index of the first array element to includelength
- 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
- The result is
-
percentile
Returns an estimate of thep
th percentile of the values in thevalues
array.- Returns
Double.NaN
ifvalues
has length0
- Returns (for any value of
p
)values[0]
ifvalues
has length1
- Throws
IllegalArgumentException
ifvalues
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 valuesp
- the percentile value to compute- Returns:
- the percentile value or Double.NaN if the array is empty
- Throws:
MathIllegalArgumentException
- ifvalues
is null or p is invalid
- Returns
-
percentile
public static double percentile(double[] values, int begin, int length, double p) throws MathIllegalArgumentException Returns an estimate of thep
th percentile of the values in thevalues
array, starting with the element in (0-based) positionbegin
in the array and includinglength
values.- Returns
Double.NaN
iflength = 0
- Returns (for any value of
p
)values[begin]
iflength = 1
- Throws
MathIllegalArgumentException
ifvalues
is null,begin
orlength
is invalid, orp
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 valuesp
- the percentile to computebegin
- the first (0-based) element to include in the computationlength
- 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
- Returns
-
sumDifference
public static double sumDifference(double[] sample1, double[] sample2) throws MathIllegalArgumentException 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 arraysample2
- the second array- Returns:
- sum of paired differences
- Throws:
MathIllegalArgumentException
- if the arrays do not have the same (positive) length.MathIllegalArgumentException
- if the sample arrays are empty.
-
meanDifference
public static double meanDifference(double[] sample1, double[] sample2) throws MathIllegalArgumentException 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 arraysample2
- the second array- Returns:
- mean of paired differences
- Throws:
MathIllegalArgumentException
- if the arrays do not have the same (positive) length.MathIllegalArgumentException
- if the sample arrays are empty.
-
varianceDifference
public static double varianceDifference(double[] sample1, double[] sample2, double meanDifference) throws MathIllegalArgumentException 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 arraysample2
- the second arraymeanDifference
- the mean difference between corresponding entries- Returns:
- variance of paired differences
- Throws:
MathIllegalArgumentException
- if the arrays do not have the same length.MathIllegalArgumentException
- if the arrays length is less than 2.- See Also:
-
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.
-
mode
Returns the sample mode(s).The mode is the most frequently occurring value in the sample. If there is a unique value with maximum frequency, this value is returned as the only element of the output array. Otherwise, the returned array contains the maximum frequency elements in increasing order.
For example, if
sample
is {0, 12, 5, 6, 0, 13, 5, 17}, the returned array will have length two, with 0 in the first element and 5 in the second.NaN values are ignored when computing the mode - i.e., NaNs will never appear in the output array. If the sample includes only NaNs or has length 0, an empty array is returned.
- Parameters:
sample
- input data- Returns:
- array of array of the most frequently occurring element(s) sorted in ascending order.
- Throws:
MathIllegalArgumentException
- if the indices are invalid or the array is null
-
mode
public static double[] mode(double[] sample, int begin, int length) Returns the sample mode(s).The mode is the most frequently occurring value in the sample. If there is a unique value with maximum frequency, this value is returned as the only element of the output array. Otherwise, the returned array contains the maximum frequency elements in increasing order.
For example, if
sample
is {0, 12, 5, 6, 0, 13, 5, 17}, the returned array will have length two, with 0 in the first element and 5 in the second.NaN values are ignored when computing the mode - i.e., NaNs will never appear in the output array. If the sample includes only NaNs or has length 0, an empty array is returned.
- Parameters:
sample
- input databegin
- index (0-based) of the first array element to includelength
- the number of elements to include- Returns:
- array of array of the most frequently occurring element(s) sorted in ascending order.
- Throws:
MathIllegalArgumentException
- if the indices are invalid or the array is null
-