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: DoubleArrayStat.java 65768 2013-03-07 03:33:00Z cxh \$
Author:
Jeff Tsay
Accepted Rating:
 Red (ctsay)
Proposed Rating:
 Yellow (ctsay)
• ### Constructor Summary

Constructors
Modifier Constructor and Description
`protected ` `DoubleArrayStat()`
• ### Method Summary

All Methods
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] * 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 is the Double representation of the maximum value, returnValue 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 is the Double representation of the minimum value, returnValue 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 .
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 .
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.