Package org.apache.commons.math.stat

Class StatUtils

  • public final class StatUtils
extends java.lang.Object
    StatUtils provides static methods for computing statistics based on data stored in double[] arrays.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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 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 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

        equals, 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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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.

        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:
        java.lang.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.

        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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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.

        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:
        java.lang.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.

        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:
        java.lang.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.

        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:
        java.lang.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.

        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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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 pth 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:
        java.lang.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 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.

        • 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:
        java.lang.IllegalArgumentException - if the parameters are not valid or the input array is null

      • sumDifference

        public static double sumDifference​(double[] sample1,
                                   double[] sample2)
                            throws java.lang.IllegalArgumentException
        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:
        java.lang.IllegalArgumentException - if the arrays do not have the same (positive) length

      • meanDifference

        public static double meanDifference​(double[] sample1,
                                    double[] sample2)
                             throws java.lang.IllegalArgumentException
        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:
        java.lang.IllegalArgumentException - if the arrays do not have the same (positive) length

      • varianceDifference

        public static double varianceDifference​(double[] sample1,
                                        double[] sample2,
                                        double meanDifference)
                                 throws java.lang.IllegalArgumentException
        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:
        java.lang.IllegalArgumentException - if the arrays do not have the same length or their common length is less than 2.
        See Also:
        meanDifference(double[],double[])

      • normalize

        public 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.
        Parameters:
        sample - sample to normalize
        Returns:
        normalized (standardized) sample
        Since:
        2.2