ptolemy.math

Class DoubleArrayStat

java.lang.Object

ptolemy.math.DoubleArrayMath

ptolemy.math.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 and Description
protected	DoubleArrayStat()

Method Summary

Modifier and Type	Method and 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 ptolemy.math.DoubleArrayMath

_commonLength, add, add, allocCopy, append, append, applyBinaryOperation, applyBinaryOperation, applyBinaryOperation, applyUnaryOperation, divide, divideElements, dotProduct, l2norm, limit, modulo, multiply, multiply, negative, normalize, padMiddle, resize, resize, scale, subtract, sum, sumOfSquares, toComplexArray, toFloatArray, toIntegerArray, toLongArray, toString, toString, within, within

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] * log²(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] * log²(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.