Class StatUtils
- java.lang.Object
-
- org.apache.commons.math4.legacy.stat.StatUtils
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static doublegeometricMean(double[] values)Returns the geometric mean of the entries in the input array, orDouble.NaNif the array is empty.static doublegeometricMean(double[] values, int begin, int length)Returns the geometric mean of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublemax(double[] values)Returns the maximum of the entries in the input array, orDouble.NaNif the array is empty.static doublemax(double[] values, int begin, int length)Returns the maximum of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublemean(double[] values)Returns the arithmetic mean of the entries in the input array, orDouble.NaNif the array is empty.static doublemean(double[] values, int begin, int length)Returns the arithmetic mean of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublemeanDifference(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 doublemin(double[] values)Returns the minimum of the entries in the input array, orDouble.NaNif the array is empty.static doublemin(double[] values, int begin, int length)Returns the minimum of the entries in the specified portion of the input array, orDouble.NaNif 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 doublepercentile(double[] values, double p)Returns an estimate of thepth percentile of the values in thevaluesarray.static doublepercentile(double[] values, int begin, int length, double p)Returns an estimate of thepth percentile of the values in thevaluesarray, starting with the element in (0-based) positionbeginin the array and includinglengthvalues.static doublepopulationVariance(double[] values)Returns the population variance of the entries in the input array, orDouble.NaNif the array is empty.static doublepopulationVariance(double[] values, double mean)Returns the population variance of the entries in the input array, using the precomputed mean value.static doublepopulationVariance(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 doublepopulationVariance(double[] values, int begin, int length)Returns the population variance of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doubleproduct(double[] values)Returns the product of the entries in the input array, orDouble.NaNif the array is empty.static doubleproduct(double[] values, int begin, int length)Returns the product of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublesum(double[] values)Returns the sum of the values in the input array, orDouble.NaNif the array is empty.static doublesum(double[] values, int begin, int length)Returns the sum of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublesumDifference(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 doublesumLog(double[] values)Returns the sum of the natural logs of the entries in the input array, orDouble.NaNif the array is empty.static doublesumLog(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.NaNif the designated subarray is empty.static doublesumSq(double[] values)Returns the sum of the squares of the entries in the input array, orDouble.NaNif the array is empty.static doublesumSq(double[] values, int begin, int length)Returns the sum of the squares of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublevariance(double[] values)Returns the variance of the entries in the input array, orDouble.NaNif the array is empty.static doublevariance(double[] values, double mean)Returns the variance of the entries in the input array, using the precomputed mean value.static doublevariance(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 doublevariance(double[] values, int begin, int length)Returns the variance of the entries in the specified portion of the input array, orDouble.NaNif the designated subarray is empty.static doublevarianceDifference(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 Detail
-
sum
public static double sum(double[] values) throws MathIllegalArgumentException
Returns the sum of the values in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif the input array is null.- Parameters:
values- array of values to sum- Returns:
- the sum of the values or
Double.NaNif 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif 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
public static double sumSq(double[] values) throws MathIllegalArgumentException
Returns the sum of the squares of the entries in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif the array is null.- Parameters:
values- input array- Returns:
- the sum of the squared values or
Double.NaNif 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif 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
public static double product(double[] values) throws MathIllegalArgumentException
Returns the product of the entries in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif 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
public static double sumLog(double[] values) throws MathIllegalArgumentException
Returns the sum of the natural logs of the entries in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif 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
public static double mean(double[] values) throws MathIllegalArgumentException
Returns the arithmetic mean of the entries in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif the array is null.See
Meanfor 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif the array is null.See
Meanfor 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
public static double geometricMean(double[] values) throws MathIllegalArgumentException
Returns the geometric mean of the entries in the input array, orDouble.NaNif the array is empty.Throws
IllegalArgumentExceptionif the array is null.See
GeometricMeanfor 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.NaNif the designated subarray is empty.Throws
IllegalArgumentExceptionif the array is null.See
GeometricMeanfor 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
public static double variance(double[] values) throws MathIllegalArgumentException
Returns the variance of the entries in the input array, orDouble.NaNif the array is empty.This method returns the bias-corrected sample variance (using
n - 1in the denominator). UsepopulationVariance(double[])for the non-bias-corrected population variance.See
Variancefor details on the computing algorithm.Returns 0 for a single-value (i.e. length = 1) sample.
Throws
MathIllegalArgumentExceptionif 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.NaNif the designated subarray is empty.This method returns the bias-corrected sample variance (using
n - 1in the denominator). UsepopulationVariance(double[], int, int)for the non-bias-corrected population variance.See
Variancefor details on the computing algorithm.Returns 0 for a single-value (i.e. length = 1) sample.
Throws
MathIllegalArgumentExceptionif 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.NaNif the designated subarray is empty.This method returns the bias-corrected sample variance (using
n - 1in the denominator). UsepopulationVariance(double[], double, int, int)for the non-bias-corrected population variance.See
Variancefor 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
MathIllegalArgumentExceptionif 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
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. ReturnsDouble.NaNif the array is empty.This method returns the bias-corrected sample variance (using
n - 1in the denominator). UsepopulationVariance(double[], double)for the non-bias-corrected population variance.See
Variancefor 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
MathIllegalArgumentExceptionif 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
public static double populationVariance(double[] values) throws MathIllegalArgumentException
Returns the population variance of the entries in the input array, orDouble.NaNif the array is empty.See
Variancefor details on the formula and computing algorithm.Returns 0 for a single-value (i.e. length = 1) sample.
Throws
MathIllegalArgumentExceptionif 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.NaNif the designated subarray is empty.See
Variancefor details on the computing algorithm.Returns 0 for a single-value (i.e. length = 1) sample.
Throws
MathIllegalArgumentExceptionif 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.NaNif the designated subarray is empty.See
Variancefor 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
MathIllegalArgumentExceptionif 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.NaNif the array is empty.See
Variancefor 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
MathIllegalArgumentExceptionif 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
public static double max(double[] values) throws MathIllegalArgumentException
Returns the maximum of the entries in the input array, orDouble.NaNif the array is empty.Throws
MathIllegalArgumentExceptionif the array is null.- The result is
NaNiff all values areNaN(i.e.NaNvalues 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.NaNif the designated subarray is empty.Throws
MathIllegalArgumentExceptionif the array is null or the array index parameters are not valid.- The result is
NaNiff all values areNaN(i.e.NaNvalues 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
public static double min(double[] values) throws MathIllegalArgumentException
Returns the minimum of the entries in the input array, orDouble.NaNif the array is empty.Throws
MathIllegalArgumentExceptionif the array is null.- The result is
NaNiff all values areNaN(i.e.NaNvalues 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.NaNif the designated subarray is empty.Throws
MathIllegalArgumentExceptionif the array is null or the array index parameters are not valid.- The result is
NaNiff all values areNaN(i.e.NaNvalues 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
public static double percentile(double[] values, double p) throws MathIllegalArgumentException
Returns an estimate of thepth percentile of the values in thevaluesarray.- Returns
Double.NaNifvalueshas length0 - Returns (for any value of
p)values[0]ifvalueshas length1 - Throws
IllegalArgumentExceptionifvaluesis null or p is not a valid quantile value (p must be greater than 0 and less than or equal to 100)
See
Percentilefor 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- ifvaluesis 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 thepth percentile of the values in thevaluesarray, starting with the element in (0-based) positionbeginin the array and includinglengthvalues.- Returns
Double.NaNiflength = 0 - Returns (for any value of
p)values[begin]iflength = 1 - Throws
MathIllegalArgumentExceptionifvaluesis null,beginorlengthis invalid, orpis not a valid quantile value (p must be greater than 0 and less than or equal to 100)
See
Percentilefor 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 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 arraysample2- 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 arraysample2- 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 arraysample2- the second arraymeanDifference- 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
-
mode
public static double[] mode(double[] sample) throws MathIllegalArgumentException
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
sampleis {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- Since:
- 3.3
-
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
sampleis {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- Since:
- 3.3
-
-