## Lee A. Barford   18 December 1999

The RandomArray.py module distributed with the LLNL Distribution 11 contains an interface to portions of the widely used and well tested random number generation package ranlib. Ranlib is capable of generating floating point random variables with a wide variety of probability density functions and some kinds of discrete random variables as well. Random variables with these nonuniform distributions have uses in diverse areas like Monte Carlo simulation and the testing of signal processing algorithms. However, RandomArray.py did not provide interfaces to those ranlib routines. This document describes functions that have been added to module RandomArray to allow access to all of the kinds of random variables provided by ranlib.

### Floating point random arrays

standard_normal(shape=ReturnFloat)
The standard_normal() function returns an array of the specified shape that contains double precision floating point numbers normally (Gaussian) distributed with mean zero and variance and standard deviation one. If no shape is specified, a single number is returned.

normal(mean, variance, shape=ReturnFloat)
The normal() function returns an array of the specified shape that contains double precision floating point numbers normally distributed with the specified mean and variance. If no shape is specified, a single number is returned.

multivariate_normal(mean, covariance) or multivariate_normal(mean, covariance, leadingAxesShape)
The multivariate_normal() function takes a one dimensional array argument mean and a two dimensional array argument covariance. Suppose the shape of mean is (n,). Then the shape of covariance must be (n,n).   The multivariate_normal() function returns a double precision floating point array. The effect of the leadingAxesShape parameter is:

• If no leadingAxesShape is specified, then an array with shape (n,) is returned containing a vector of numbers with a multivariate normal distribution with the specified mean and covariance.
• If leadingAxesShape is specified, then an array of such vectors is returned. The shape of the output is leadingAxesShape.append((n,)). The leading indices into the output array select a multivariate normal from the array. The final index selects one number from within the multivariate normal.
In either case, the behavior of multivariate_normal() is undefined  if covariance is not symmetric and positive definite.

exponential(mean, shape=ReturnFloat)
The exponential() function returns an array of the specified shape that contains double precision floating point numbers exponentially distributed with the specified mean. If no shape is specified, a single number is returned.

beta(a, b, shape=ReturnFloat)
The beta() function returns an array of the specified shape that contains double precision floating point numbers beta distributed with alpha parameter a and beta parameter b. If no shape is specified, a single number is returned.

gamma(a, r, shape=ReturnFloat)
The gamma() function returns an array of the specified shape that contains double precision floating point numbers beta distributed with location parameter a and distribution shape parameter r. If no shape is specified, a single number is returned.

chi_square(df, shape=ReturnFloat)
The chi_square() function returns an array of the specified shape that contains double precision floating point numbers with the chi square distribution with df degrees of freedom. If no shape is specified, a single number is returned.

noncentral_chi_square(df, nonc, shape=ReturnFloat)
The noncentral_chi_square() function returns an array of the specified shape that contains double precision floating point numbers with the chi square distribution with df degrees of freedom and noncentrality parameter nconc. If no shape is specified, a single number is returned.

F(dfn, dfd, shape=ReturnFloat)
The F() function returns an array of the specified shape that contains double precision floating point numbers with the F distribution with dfn degrees of freedom in the numerator and dfd degrees of freedom in the denominator. If no shape is specified, a single number is returned.

noncentral_F(dfn, dfd, nconc, shape=ReturnFloat)
The noncentral_F() function returns an array of the specified shape that contains double precision floating point numbers with the F distribution with dfn degrees of freedom in the numerator, dfd degrees of freedom in the denominator, and noncentrality parameter nconc. If no shape is specified, a single number is returned.

### Integer random arrays

binomial(trials, prob, shape=ReturnInt)
The binomial() function returns an array with the specified shape that contains integer numbers with the binomial distribution with trials trials and event probability prob. In other words, each value in the returned array is the number of times an event with probability prob occurred within trials repeated trials. If no shape is specified, a single number is returned.

negative_binomial(trials, prob, shape=ReturnInt)
The negative_binomial() function returns an array with the specified shape that contains integer numbers with the negative binomial distribution with trials trials and event probability prob. If no shape is specified, a single number is returned.

poisson(mean, shape=ReturnInt)
The poisson() function returns an array with the specified shape that contains integer numbers with the Poisson distribution with the specified mean. If no shape is specified, a single number is returned.

multinomial(trials, probs) or multinomial(trials, probs, leadingAxesShape)
The multinomial() function returns an array with that contains integer numbers with the multinomial distribution with trials trials and event probabilities given in probs. probs must be a one dimensional array. There are len(probs)+1 events. probs[i] is the probability of the i-th event for 0<=i<len(probs). The probability of event len(probs) is 1.-Numeric.sum(prob).

The first form returns an integer array of shape (len(probs)+1,) containing one multinomially distributed vector. The second form returns an array of shape (m, n, ..., len(probs)+1) where (m, n, ...) is leadingAxesShape. In this case, each output[i,j,...,:] is an integer array of shape (len(prob)+1,) containing one multinomially distributed vector..

### Examples

Mostof the functions in this package take zero or more distribution specific parameters plus an optional shape parameter. The shape parameter gives the shape of the output array:
Python 1.5.1 (#1, Mar 21 1999, 22:49:36) [GCC egcs-2.91.66 19990314/Li on linux-i386
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> from RandomArray import *
>>> print standard_normal()
-0.435568600893
>>> print standard_normal(5)
[-1.36134553 0.78617644 -0.45038718 0.18508556 0.05941355]
>>> print standard_normal((5,2))
[[ 1.33448863 -0.10125473]
[ 0.66838062 0.24691346]
[-0.95092064 0.94168913]
[-0.23919107 1.89288616]
[ 0.87651485 0.96400219]]
>>> print normal(7., 4., (5,2)) % mean=7, std. dev.=4
[[ 2.66997623 11.65832615]
[ 6.73916003 6.58162862]
[ 8.47180378 4.30354905]
[ 1.35531998 -2.80886841]
[ 7.07408469 11.39024973]]
>>> print exponential(10., 5) % mean=10
[ 18.03347754 7.11702306 9.8587961 32.49231603 28.55408891]
>>> print beta(3.1, 9.1, 5) % alpha=3.1, beta=9.1
[ 0.1175056 0.17504358 0.3517828 0.06965593 0.43898219]
>>> print chi_square(7, 5) % 7 degrees of freedom (dfs)
[ 11.99046516 3.00741053 4.72235727 6.17056274 8.50756836]
>>> print noncentral_chi_square(7, 3, 5) % 7 dfs, noncentrality 3
[ 18.28332138 4.07550335 16.0425396 9.51192093 9.80156231]
>>> F(5, 7, 5) % 5 and 7 dfs
array([ 0.24693671, 3.76726145, 0.66883826, 0.59169068, 1.90763224])
>>> noncentral_F(5, 7, 3., 5) % 5 and 7 dfs, noncentrality 3
array([ 1.17992553, 0.7500126 , 0.77389943, 9.26798989, 1.35719634])
>>> binomial(32, .5, 5) % 32 trials, prob of an event = .5
array([12, 20, 21, 19, 17])
>>> negative_binomial(32, .5, 5) % 32 trials: prob of an event = .5
array([21, 38, 29, 32, 36])
Two functions that return generate multivariate random numbers (that is, random vectors with some known relationship between the elements of each vector, defined by the distribution).  They are multivariate_normal() and multinomial(). For these two functions, the lengths of the leading axes of the output may be specified. The length of the last axis is determined by the length of some other parameter.
>>> from Numeric import *
>>> multivariate_normal([1,2], [[1,2],[2,1]], [2,3])
array([[[ 0.14157988, 1.46232224],
[-1.11820295, -0.82796288],
[ 1.35251635, -0.2575901 ]],
[[-0.61142141, 1.0230465 ],
[-1.08280948, -0.55567217],
[ 2.49873002, 3.28136372]]])
>>> x = multivariate_normal([10,100], [[1,2],[2,1]], 10000)
>>> x_mean = sum(x)/10000
>>> print x_mean
[ 9.98599893 100.00032416]
>>> x_minus_mean = x - x_mean
>>> cov = matrixmultiply(transpose(x_minus_mean), x_minus_mean) / 9999.
>>> cov
array([[ 2.01737122, 1.00474408],
[ 1.00474408, 2.0009806 ]])
The a priori probabilities for a multinomial distribution must sum to one. The prior probability argument to multinomial() doesn't give the prior probability of the last event: it is computed to be one minus the sum of the others.
>>> multinomial(16, [.1, .4, .2]) % prior probabilities [.1, .4, .2, .3]
array([2, 7, 1, 6])
>>> multinomial(16, [.1, .4, .2], [2,3]) % output shape [2,3,4]
array([[[ 1, 9, 1, 5],
[ 0, 10, 3, 3],
[ 4, 9, 3, 0]],
[[ 1, 6, 1, 8],
[ 3, 4, 5, 4],
[ 1, 5, 2, 8]]])