Default Routines

The routines which are exported by default are the only ones that the average Perl programmer is likely to need.

random_set_seed_from_phrase($phrase)

Sets the seed of the base generator to a value determined by $phrase. If the module is installed with the default option, the value depends on the machine collating sequence. It should, however, be the same for 7-bit ASCII character strings on all ASCII machines. In the original randlib, the value generated for a given $phrase was consistent from implementation to implementation (it did not rely on the machine collating sequence). Check with your Perl administrator to see if the module was installed with the original seed generator. Note: When the Perl processor loads package Math::Random the seed is set to a value based on the current time. The seed changes each time Math::Random generates something random.

The ability to set the seed is useful for debugging, or for those who like reproducible runs.

random_get_seed()

Returns an array of length two which contains the two integers constituting the seed (assuming a call in array context). An invocation in a scalar context returns the integer 2, which is probably not useful.

random_seed_from_phrase($phrase)

Returns an array of length two which contains the two integers constituting the seed (assuming a call in array context). An invocation in a scalar context returns the integer 2, which is probably not useful. The seed generated is the seed used to set the seed in a call to "random_set_seed_from_phrase".

Note: the following two calls (for the same $phrase) are equivalent:

 random_set_seed(random_seed_from_phrase($phrase));
    

and

 random_set_seed_from_phrase($phrase);
    

random_set_seed(@seed)

Sets the seed of the base generator to the value @seed[0,1]. Usually, the argument @seed should be the result of a call to "random_get_seed" or "random_seed_from_phrase". @seed[0,1] must be two integers in the range (1, 1) to (2147483562, 2147483398), inclusive.

"random_uniform($n, $low, $high)"

random_uniform($n)

random_uniform()

When called in an array context, returns an array of $n deviates generated from a uniform($low, $high) distribution. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $low must be less than or equal to $high.

Defaults are (1, 0, 1). Note: $high must be specified if $low is specified.

"random_uniform_integer($n, $low, $high)"

When called in an array context, returns an array of $n integer deviates generated from a uniform($low, $high) distribution on the integers. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $low and $high are first rounded using int(); the resulting $low must be less than or equal to $high, and the resulting range ($high - $low) must not be greater than 2147483561.

There are no defaults; all three arguments must be provided.

random_permutation(@array)

Returns @array, randomly permuted.

random_permuted_index($n)

Returns an array of array indices, randomly permuted. The indices used are (0, ... , $n-1). This produces the indices used by "random_permutation" for a given seed, without passing arrays.

Note: the following are equivalent:

 random_set_seed_from_phrase('jjv');
 random_permutation(@array);
    

and

 random_set_seed_from_phrase('jjv');
 @array[(random_permuted_index(scalar(@array)))];
    

"random_normal($n, $av, $sd)"

"random_normal($n, $av)"

random_normal($n)

random_normal()

When called in an array context, returns an array of $n deviates generated from a normal($av, $sd^2) distribution. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $sd must be non-negative.

Defaults are (1, 0, 1).

Extended Routines

These routines generate deviates from many other distributions.

Note: The parameterizations of these deviates are standard (insofar as there is a standard ... ) but particular attention should be paid to the distributions of the beta and gamma deviates (noted in "random_beta" and "random_gamma" below).

"random_beta($n, $aa, $bb)"

When called in an array context, returns an array of $n deviates generated from the beta distribution with parameters $aa and $bb. The density of the beta is:

X^($aa - 1) * (1 - X)^($bb - 1) / B($aa , $bb) for 0 < X < 1.

When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: Both $aa and $bb must not be less than 1.0E-37.

There are no defaults; all three arguments must be provided.

"random_binomial($n, $nt, $p)"

When called in an array context, returns an array of $n outcomes generated from the binomial distribution with number of trials $nt and probability of an event in each trial $p. When called in a scalar context, generates and returns only one such outcome as a scalar, regardless of the value of $n.

Argument restrictions: $nt is rounded using int(); the result must be non-negative. $p must be between 0 and 1 inclusive.

There are no defaults; both arguments must be provided.

"random_chi_square($n, $df)"

When called in an array context, returns an array of $n deviates generated from the chi-square distribution with $df degrees of freedom. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $df must be positive.

There are no defaults; both arguments must be provided.

"random_exponential($n, $av)"

random_exponential($n)

random_exponential()

When called in an array context, returns an array of $n deviates generated from the exponential distribution with mean $av. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $av must be non-negative.

Defaults are (1, 1).

"random_f($n, $dfn, $dfd)"

When called in an array context, returns an array of $n deviates generated from the F (variance ratio) distribution with degrees of freedom $dfn (numerator) and $dfd (denominator). When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: Both $dfn and $dfd must be positive.

There are no defaults; all three arguments must be provided.

"random_gamma($n, $a, $r)"

When called in an array context, returns an array of $n deviates generated from the gamma distribution with parameters $a and $r. The density of the gamma is:

($a**$r) / Gamma($r) * X**($r - 1) * Exp(-$a*X)

When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: Both $a and $r must be positive.

There are no defaults; all three arguments must be provided.

"random_multinomial($n, @p)"

When called in an array context, returns single observation from the multinomial distribution, with $n events classified into as many categories as the length of @p. The probability of an event being classified into category i is given by the ith element of @p. The observation is an array with length equal to @p, so when called in a scalar context it returns the length of @p. The sum of the elements of the observation is equal to $n.

Argument restrictions: $n is rounded with int() before it is used; the result must be non-negative. @p must have length at least 2. All elements of @p except the last must be between 0 and 1 inclusive, and sum to no more than 0.99999. Note: The last element of @p is a dummy to indicate the number of categories, and it is adjusted to bring the sum of the elements of @p to 1.

There are no defaults; both arguments must be provided.

"random_multivariate_normal($n, @mean, @covar)"

When called in an array context, returns an array of $n deviates (each deviate being an array reference) generated from the multivariate normal distribution with mean vector @mean and variance-covariance matrix @covar. When called in a scalar context, generates and returns only one such deviate as an array reference, regardless of the value of $n.

Argument restrictions: If the dimension of the deviate to be generated is p, @mean should be a length p array of real numbers. @covar should be a length p array of references to length p arrays of real numbers (i.e. a p by p matrix). Further, @covar should be a symmetric positive-definite matrix, although the Perl code does not check positive-definiteness, and the underlying C code assumes the matrix is symmetric. Given that the variance-covariance matrix is symmetric, it doesn't matter if the references refer to rows or columns. If a non-positive definite matrix is passed to the function, it will abort with the following message:

 COVM not positive definite in SETGMN
    

Also, a non-symmetric @covar may produce deviates without complaint, although they may not be from the expected distribution. For these reasons, you are encouraged to verify the arguments passed.

The Perl code does check the dimensionality of @mean and @covar for consistency. It does so by checking that the length of the argument vector passed is odd, that what should be the last element of @mean and the first element of @covar look like they are a number followed by an array reference respectively, and that the arrays referred to in @covar are as long as @mean.

There are no defaults; all three arguments must be provided.

"random_negative_binomial($n, $ne, $p)"

When called in an array context, returns an array of $n outcomes generated from the negative binomial distribution with number of events $ne and probability of an event in each trial $p. When called in a scalar context, generates and returns only one such outcome as a scalar, regardless of the value of $n.

Argument restrictions: $ne is rounded using int(), the result must be positive. $p must be between 0 and 1 exclusive.

There are no defaults; both arguments must be provided.

"random_noncentral_chi_square($n, $df, $nonc)"

When called in an array context, returns an array of $n deviates generated from the noncentral chi-square distribution with $df degrees of freedom and noncentrality parameter $nonc. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $df must be at least 1, $nonc must be non-negative.

There are no defaults; all three arguments must be provided.

"random_noncentral_f($n, $dfn, $dfd, $nonc)"

When called in an array context, returns an array of $n deviates generated from the noncentral F (variance ratio) distribution with degrees of freedom $dfn (numerator) and $dfd (denominator); and noncentrality parameter $nonc. When called in a scalar context, generates and returns only one such deviate as a scalar, regardless of the value of $n.

Argument restrictions: $dfn must be at least 1, $dfd must be positive, and $nonc must be non-negative.

There are no defaults; all four arguments must be provided.

"random_poisson($n, $mu)"

When called in an array context, returns an array of $n outcomes generated from the Poisson distribution with mean $mu. When called in a scalar context, generates and returns only one such outcome as a scalar, regardless of the value of $n.

Argument restrictions: $mu must be non-negative.

There are no defaults; both arguments must be provided.