Package ptolemy.math

Class DoubleArrayStat


  • public class DoubleArrayStat
    extends DoubleArrayMath
    This class provides a library for statistical operations on arrays of doubles. Unless explicitly noted otherwise, all array arguments are assumed to be non-null. If a null array is passed to a method, a NullPointerException will be thrown in the method or called methods.
    Since:
    Ptolemy II 0.3
    Version:
    $Id$
    Author:
    Jeff Tsay
    Pt.AcceptedRating:
    Red (ctsay)
    Pt.ProposedRating:
    Yellow (ctsay)
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected DoubleArrayStat()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      protected static int _nonZeroLength​(double[] array, java.lang.String methodName)
      Throw an exception if the array is null or length 0.
      static double[] autoCorrelation​(double[] x, int N, int startLag, int endLag)
      Return a new array that is the auto-correlation of the argument array, starting and ending at user-specified lag values.
      static double autoCorrelationAt​(double[] x, int N, int lag)
      Return the auto-correlation of an array at a certain lag value, summing over a certain number of samples defined by : Rxx[d] = sum of i = 0 to N - 1 of x[i] * x[i + d] N must be non-negative, but large numbers are ok because this routine will not overrun reading of the arrays.
      static double[] crossCorrelation​(double[] x, double[] y, int N, int startLag, int endLag)
      Return a new array that is the cross-correlation of the two argument arrays, starting and ending at user-specified lag values.
      static double crossCorrelationAt​(double[] x, double[] y, int N, int lag)
      Return the cross-correlation of two arrays at a certain lag value.
      static double entropy​(double[] p)
      Given an array of probabilities, treated as a probability mass function (pmf), calculate the entropy (in bits).
      static double geometricMean​(double[] array)
      Return the geometric mean of the elements in the array.
      static double max​(double[] array)
      Return the maximum value in the array.
      static java.lang.Object[] maxAndIndex​(double[] array)
      Return the maximum value of the array and the index at which the maximum occurs in the array.
      static double mean​(double[] array)
      Return the arithmetic mean of the elements in the array.
      static double min​(double[] array)
      Return the minimum value in the array.
      static java.lang.Object[] minAndIndex​(double[] array)
      Return the minimum value of the array and the index at which the minimum occurs in the array.
      static double productOfElements​(double[] array)
      Return the product of all of the elements in the array.
      static double[] randomBernoulli​(double p, int N)
      Return a new array of Bernoulli random variables with a given probability of success p.
      static double[] randomExponential​(double lambda, int N)
      Return a new array of exponentially distributed doubles with parameter lambda.
      static double[] randomGaussian​(double mean, double standardDeviation, int N)
      Return a new array of Gaussian distributed doubles with a given mean and standard deviation.
      static double[] randomPoisson​(double mean, int N)
      Return a new array of Poisson random variables (as doubles) with a given mean.
      static double[] randomUniform​(double a, double b, int N)
      Return a new array of uniformly distributed doubles ranging from a to b.
      static double relativeEntropy​(double[] p, double[] q)
      Given two array's of probabilities, calculate the relative entropy aka Kullback Leibler distance, D(p || q), (in bits) between the two probability mass functions.
      static double standardDeviation​(double[] array)
      Return the standard deviation of the elements in the array.
      static double standardDeviation​(double[] array, boolean sample)
      Return the standard deviation of the elements in the array.
      static double sumOfElements​(double[] array)
      Return the sum of all of the elements in the array.
      static double variance​(double[] array)
      Return the variance of the elements in the array, assuming sufficient statistics.
      static double variance​(double[] array, boolean sample)
      Return the variance of the elements in the array, assuming sufficient statistics.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • DoubleArrayStat

        protected DoubleArrayStat()
    • Method Detail

      • autoCorrelation

        public static final double[] autoCorrelation​(double[] x,
                                                     int N,
                                                     int startLag,
                                                     int endLag)
        Return a new array that is the auto-correlation of the argument array, starting and ending at user-specified lag values. The output array will have length (endLag - startLag + 1). The first element of the output will have the auto-correlation at a lag of startLag. The last element of the output will have the auto-correlation at a lag of endLag.
        Parameters:
        x - An array of doubles.
        N - An integer indicating the number of samples to sum over.
        startLag - An int indicating at which lag to start (may be negative).
        endLag - An int indicating at which lag to end.
        Returns:
        A new array of doubles.
      • autoCorrelationAt

        public static double autoCorrelationAt​(double[] x,
                                               int N,
                                               int lag)
        Return the auto-correlation of an array at a certain lag value, summing over a certain number of samples defined by : Rxx[d] = sum of i = 0 to N - 1 of x[i] * x[i + d] N must be non-negative, but large numbers are ok because this routine will not overrun reading of the arrays.
        Parameters:
        x - An array of doubles.
        N - An integer indicating the number of samples to sum over.
        lag - An integer indicating the lag value (may be negative).
        Returns:
        A double, Rxx[lag].
      • crossCorrelation

        public static final double[] crossCorrelation​(double[] x,
                                                      double[] y,
                                                      int N,
                                                      int startLag,
                                                      int endLag)
        Return a new array that is the cross-correlation of the two argument arrays, starting and ending at user-specified lag values. The output array will have length (endLag - startLag + 1). The first element of the output will have the cross-correlation at a lag of startLag. The last element of the output will have the cross-correlation at a lag of endLag.
        Parameters:
        x - The first array of doubles.
        y - The second array of doubles.
        N - An integer indicating the number of samples to sum over.
        startLag - An int indicating at which lag to start (may be negative).
        endLag - An int indicating at which lag to end.
        Returns:
        A new array of doubles.
      • crossCorrelationAt

        public static double crossCorrelationAt​(double[] x,
                                                double[] y,
                                                int N,
                                                int lag)
        Return the cross-correlation of two arrays at a certain lag value. The cross-correlation is defined by : Rxy[d] = sum of i = 0 to N - 1 of x[i] * y[i + d]
        Parameters:
        x - The first array of doubles.
        y - The second array of doubles.
        N - An integer indicating the number of samples to sum over. This must be non-negative, but large numbers are ok because this routine will not overrun reading of the arrays.
        lag - An integer indicating the lag value (may be negative).
        Returns:
        A double, Rxy[lag].
      • entropy

        public static final double entropy​(double[] p)
        Given an array of probabilities, treated as a probability mass function (pmf), calculate the entropy (in bits). The pmf is a discrete function that gives the probability of each element. The sum of the elements in the pmf should be 1, and each element should be between 0 and 1. This method does not check to see if the pmf is valid, except for checking that each entry is non-negative. The function computed is :

        H(p) = - sum (p[x] * log2(p[x]))

        The entropy is always non-negative. Throw an IllegalArgumentException if the length of the array is 0, or a negative probability is encountered.
        Parameters:
        p - The array of probabilities.
        Returns:
        The entropy of the array of probabilities.
      • geometricMean

        public static final double geometricMean​(double[] array)
        Return the geometric mean of the elements in the array. This is defined to be the Nth root of the product of the elements in the array, where N is the length of the array. This method is only useful for arrays of non-negative numbers. If the product of the elements in the array is negative, throw an IllegalArgumentException. However, the individual elements of the array are not verified to be non-negative. Return 1.0 if the length of the array is 0.
        Parameters:
        array - An array of doubles.
        Returns:
        A double.
      • max

        public static final double max​(double[] array)
        Return the maximum value in the array. Throw an exception if the length of the array is 0.
        Parameters:
        array - The array of doubles.
        Returns:
        The maximum value in the array.
      • maxAndIndex

        public static final java.lang.Object[] maxAndIndex​(double[] array)
        Return the maximum value of the array and the index at which the maximum occurs in the array. The maximum value is wrapped with the Double class, the index is wrapped with the Integer class, and an Object array is returned containing these values. If the array is of length zero, throw an IllegalArgumentException.
        Parameters:
        array - An array of doubles.
        Returns:
        An array of two Objects, returnValue[0] is the Double representation of the maximum value, returnValue[1] is the Integer representation of the corresponding index.
      • mean

        public static final double mean​(double[] array)
        Return the arithmetic mean of the elements in the array. If the length of the array is 0, return a NaN.
        Parameters:
        array - The array of doubles.
        Returns:
        The mean value in the array.
      • min

        public static final double min​(double[] array)
        Return the minimum value in the array. Throw an exception if the length of the array is 0.
        Parameters:
        array - The array of doubles.
        Returns:
        The minimum value in the array.
      • minAndIndex

        public static final java.lang.Object[] minAndIndex​(double[] array)
        Return the minimum value of the array and the index at which the minimum occurs in the array. The minimum value is wrapped with the Double class, the index is wrapped with the Integer class, and an Object array is returned containing these values. If the array is of length zero, throw an IllegalArgumentException.
        Parameters:
        array - An array of doubles.
        Returns:
        An array of two Objects, returnValue[0] is the Double representation of the minimum value, returnValue[1] is the Integer representation of the corresponding index.
      • productOfElements

        public static final double productOfElements​(double[] array)
        Return the product of all of the elements in the array. Return 1.0 if the length of the array is 0.
        Parameters:
        array - The array of doubles.
        Returns:
        The product of the elements in the array.
      • randomBernoulli

        public static final double[] randomBernoulli​(double p,
                                                     int N)
        Return a new array of Bernoulli random variables with a given probability of success p. On success, the random variable has value 1.0; on failure the random variable has value 0.0.
        Parameters:
        p - The probability, which should be a double between 0.0 and 1.0. The probability is compared to the output of java.lang.Random.nextDouble(). If the output is less than p, then the array element will be 1.0. If the output is greater than or equal to p, then the array element will be 0.0.
        N - The number of elements to allocate.
        Returns:
        The array of Bernoulli random variables.
      • randomExponential

        public static final double[] randomExponential​(double lambda,
                                                       int N)
        Return a new array of exponentially distributed doubles with parameter lambda. The number of elements to allocate is given by N.
        Parameters:
        lambda - The lambda, which may not by 0.0.
        N - The number of elements to allocate.
        Returns:
        The array of exponential random variables.
      • randomGaussian

        public static final double[] randomGaussian​(double mean,
                                                    double standardDeviation,
                                                    int N)
        Return a new array of Gaussian distributed doubles with a given mean and standard deviation. The number of elements to allocate is given by N. This algorithm is from [1].
        Parameters:
        mean - The mean of the new array.
        standardDeviation - The standard deviation of the new array.
        N - The number of elements to allocate.
        Returns:
        The array of random Gaussian variables.
      • randomPoisson

        public static final double[] randomPoisson​(double mean,
                                                   int N)
        Return a new array of Poisson random variables (as doubles) with a given mean. The number of elements to allocate is given by N. This algorithm is from [1].
        Parameters:
        mean - The mean of the new array.
        N - The number of elements to allocate.
        Returns:
        The array of random Poisson variables.
      • randomUniform

        public static double[] randomUniform​(double a,
                                             double b,
                                             int N)
        Return a new array of uniformly distributed doubles ranging from a to b. The number of elements to allocate is given by N.
        Parameters:
        a - A double indicating the lower bound.
        b - A double indicating the upper bound.
        N - An int indicating how many elements to generate.
        Returns:
        A new array of doubles.
      • relativeEntropy

        public static final double relativeEntropy​(double[] p,
                                                   double[] q)
        Given two array's of probabilities, calculate the relative entropy aka Kullback Leibler distance, D(p || q), (in bits) between the two probability mass functions. The result will be POSITIVE_INFINITY if q has a zero probability for a symbol for which p has a non-zero probability. The function computed is :

        D(p||q) = - sum (p[x] * log2(p[x]/q[x]))

        Throw an IllegalArgumentException if either array has length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.
        Parameters:
        p - An array of doubles representing the first pmf, p.
        q - An array of doubles representing the second pmf, q.
        Returns:
        A double representing the relative entropy of the random variable.
      • standardDeviation

        public static double standardDeviation​(double[] array)
        Return the standard deviation of the elements in the array. Simply return standardDeviation(array, false).
        Parameters:
        array - The input array.
        Returns:
        The standard deviation.
      • standardDeviation

        public static double standardDeviation​(double[] array,
                                               boolean sample)
        Return the standard deviation of the elements in the array. The standard deviation is computed as follows :

          stdDev = sqrt(variance)
          

        The sample standard deviation is computed as follows

          stdDev = sqrt(variancesample)
          

        Throw an exception if the array is of length 0, or if the sample standard deviation is taken on an array of length less than 2.

        Parameters:
        array - An array of doubles.
        sample - True if the sample standard deviation is desired.
        Returns:
        A double.
      • sumOfElements

        public static final double sumOfElements​(double[] array)
        Return the sum of all of the elements in the array. Return 0.0 of the length of the array is 0.
        Parameters:
        array - An array of doubles.
        Returns:
        The sum of all of the elements in the array.
      • variance

        public static double variance​(double[] array)
        Return the variance of the elements in the array, assuming sufficient statistics. Simply return variance(array, false). Throw a runtime exception if the array is of length 0, or if the sample variance is taken on an array of length less than 2.
        Parameters:
        array - An array of doubles.
        Returns:
        The variance of the elements in the array.
      • variance

        public static double variance​(double[] array,
                                      boolean sample)
        Return the variance of the elements in the array, assuming sufficient statistics. The variance is computed as follows :

          variance = (sum(X2) - (sum(X) / N)2) / N
          

        The sample variance is computed as follows :

          variancesample =
               (sum(X2) - (sum(X) / N)2) / (N - 1)
          

        Throw a runtime exception if the array is of length 0, or if the sample variance is taken on an array of length less than 2.

        Parameters:
        array - An array of doubles.
        sample - True if the sample standard deviation is desired.
        Returns:
        The variance of the elements in the array.
      • _nonZeroLength

        protected static final int _nonZeroLength​(double[] array,
                                                  java.lang.String methodName)
        Throw an exception if the array is null or length 0. Otherwise return the length of the array.
        Parameters:
        array - An array of doubles.
        methodName - A String representing the method name of the caller, without parentheses.
        Returns:
        The length of the array.