distribution with mean vector I<@mean> and
variance-covariance matrix I<@covar>. When called in a scalar
context, generates and returns only one such deviate as an array
reference, regardless of the value of I<$n>.
Argument restrictions: If the dimension of the deviate to be generated
is I, I<@mean> should be a length I

array of real numbers.
I<@covar> should be a length I

array of references to length I

arrays of real numbers (i.e. a I

by I

matrix). Further,
I<@covar> should be a symmetric positive-definite matrix, although the
B code does not check positive-definiteness, and the underlying
B 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 I<@covar> may produce deviates without
complaint, although they may not be from the expected distribution.
For these reasons, you are encouraged to I.
The B code I check the dimensionality of I<@mean> and
I<@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 I<@mean> and the first element of I<@covar> look like they
are a number followed by an array reference respectively, and that the
arrays referred to in I<@covar> are as long as I<@mean>.
There are no defaults; all three arguments must be provided.
=item C
When called in an array context, returns an array of I<$n> outcomes
generated from the I distribution with number of
events I<$ne> and probability of an event in each trial I<$p>. When
called in a scalar context, generates and returns only one such
outcome as a scalar, regardless of the value of I<$n>.
Argument restrictions: I<$ne> is rounded using C, the result
must be positive. I<$p> must be between 0 and 1 exclusive.
There are no defaults; both arguments must be provided.
=item C
When called in an array context, returns an array of I<$n> deviates
generated from the I distribution with I<$df>
degrees of freedom and noncentrality parameter I<$nonc>. When called
in a scalar context, generates and returns only one such deviate as a
scalar, regardless of the value of I<$n>.
Argument restrictions: I<$df> must be at least 1, I<$nonc> must be
non-negative.
There are no defaults; all three arguments must be provided.
=item C
When called in an array context, returns an array of I<$n> deviates
generated from the I (variance ratio) distribution with
degrees of freedom I<$dfn> (numerator) and I<$dfd> (denominator); and
noncentrality parameter I<$nonc>. When called in a scalar context,
generates and returns only one such deviate as a scalar, regardless of
the value of I<$n>.
Argument restrictions: I<$dfn> must be at least 1, I<$dfd> must be
positive, and I<$nonc> must be non-negative.
There are no defaults; all four arguments must be provided.
=item C
When called in an array context, returns an array of I<$n> outcomes
generated from the I distribution with mean I<$mu>. When
called in a scalar context, generates and returns only one such
outcome as a scalar, regardless of the value of I<$n>.
Argument restrictions: I<$mu> must be non-negative.
There are no defaults; both arguments must be provided.
=back
=head1 ERROR HANDLING
The B code should C if bad arguments are passed or if the
underlying B code cannot allocate the necessary memory. The only
error which should kill the job without Cing is a non-positive
definite variance-covariance matrix passed to
C (see L<"Extended Routines">).
=head1 RANDLIB
B is available in B and B source form, and will
soon be available in B source as well. B can be
obtained from B. Send mail whose message is I<'send
randlib.c.shar from general'> to:
statlib@lib.stat.cmu.edu
B can also be obtained by anonymous B to:
odin.mdacc.tmc.edu (143.111.62.32)
where it is available as
/pub/source/randlib.c-1.3.tar.gz
For obvious reasons, the original B (in B) has been
renamed to
/pub/source/randlib.f-1.3.tar.gz
on the same machine.
Our FTP index is on file C<./pub/index>.
If you have Internet access and a browser you might note the following
web site addresses:
University of Texas M. D. Anderson Cancer Center Home Page:
http://www.mdanderson.org/
Department of Biomathematics Home Page:
http://odin.mdacc.tmc.edu/
Available software:
http://biostatistics.mdanderson.org/SoftwareDownload/
=head1 SUPPORT
This work was supported in part by grant CA-16672 from the National
Cancer Institute. We are grateful to Larry and Pat McNeil of Corpus
Cristi for their generous support. Some equipment used in this effort
was provided by IBM as part of a cooperative study agreement; we thank
them.
=head1 CODE MANIPULATION
The B version of B was obtained by translating the
original B B using B, and
performing some hand crafting of the result.
Information on B can be obtained from:
PROMULA Development Corporation
3620 N. High Street, Suite 301
Columbus, Ohio 43214
(614) 263-5454
F (now obsolete) was created by using B, and
performing some modification of the result. B also produced the
skeleton of F.
Information on B can be obtained from:
http://www.swig.org
=head1 SOURCES
The following routines, which were written by others and lightly
modified for consistency in packaging, are included in B.
=over 4
=item Bottom Level Routines
These routines are a transliteration of the B in the reference
to B, and thence to B.
L'Ecuyer, P., and Cote, S. "Implementing a Random Number Package with
Splitting Facilities." ACM Transactions on Mathematical Software,
17:98-111 (1991).
=item Exponential
This code was obtained from Netlib.
Ahrens, J. H., and Dieter, U. "Computer Methods for Sampling from the
Exponential and Normal Distributions." Comm. ACM, 15,10 (Oct. 1972),
873-882.
=item Gamma
(Case R >= 1.0)
Ahrens, J. H., and Dieter, U. "Generating Gamma Variates by a Modified
Rejection Technique." Comm. ACM, 25,1 (Jan. 1982), 47-54.
Algorithm GD
(Case 0.0 <= R <= 1.0)
Ahrens, J. H., and Dieter, U. "Computer Methods for Sampling from
Gamma, Beta, Poisson and Binomial Distributions." Computing, 12 (1974),
223-246. Adaptation of algorithm GS.
=item Normal
This code was obtained from netlib.
Ahrens, J. H., and Dieter, U. "Extensions of Forsythe's Method for
Random Sampling from the Normal Distribution." Math. Comput., 27,124
(Oct. 1973), 927-937.
=item Binomial
This code was kindly sent to Dr. Brown by Dr. Kachitvichyanukul.
Kachitvichyanukul, V., and Schmeiser, B. W. "Binomial Random Variate
Generation." Comm. ACM, 31, 2 (Feb. 1988), 216.
=item Poisson
This code was obtained from netlib.
Ahrens, J. H., and Dieter, U. "Computer Generation of Poisson Deviates
from Modified Normal Distributions." ACM Trans. Math. Software, 8, 2
(June 1982), 163-179.
=item Beta
This code was written by us following the recipe in the following.
Cheng, R. C. H. "Generating Beta Variables with Nonintegral Shape
Parameters." Comm. ACM, 21:317-322 (1978). (Algorithms BB and BC)
=item Linpack
Routines C and C are used to perform the Cholesky
decomposition of the covariance matrix in C (used for the
generation of multivariate normal deviates).
Dongarra, J. J., Moler, C. B., Bunch, J. R., and Stewart, G. W.
Linpack User's Guide. SIAM Press, Philadelphia. (1979)
=item Multinomial
The algorithm is from page 559 of Devroye, Luc Non-Uniform Random
Variate Generation. New York: Springer-Verlag, 1986.
=item Negative Binomial
The algorithm is from page 480 of Devroye, Luc Non-Uniform Random
Variate Generation. New York: Springer-Verlag, 1986.
=back
=head1 VERSION
This POD documents B version 0.71.
=head1 AUTHORS
=over 4
=item *
B (the B port of B) was put together by
John Venier and Barry W. Brown with help from B. For version
0.61, Geoffrey Rommel made various cosmetic changes. Version 0.64 uses
plain vanilla XS rather than SWIG.
=item *
B was compiled and written by Barry W. Brown, James Lovato,
Kathy Russell, and John Venier.
=item *
Correspondence regarding B or B should be
addressed to John Venier by email to
jvenier@mdanderson.org
=item *
Our address is:
Department of Biomathematics, Box 237
The University of Texas, M.D. Anderson Cancer Center
1515 Holcombe Boulevard
Houston, TX 77030
=item *
Geoffrey Rommel may be reached at grommel [at] cpan [dot] org.
=back
=head1 LEGALITIES
=over 4
=item *
The programs in the B code distributed with B and
in the B code F, as well as the documentation, are
copyright by John Venier and Barry W. Brown for the University of
Texas M. D. Anderson Cancer Center in 1997. They may be distributed
and used under the same conditions as B.
=item *
F, F, and F are from B (See
L<"RANDLIB">) and are distributed with the following legalities.
Code that appeared in an ACM publication is subject to their
algorithms policy:
Submittal of an algorithm for publication in one of the ACM
Transactions implies that unrestricted use of the algorithm within a
computer is permissible. General permission to copy and distribute
the algorithm without fee is granted provided that the copies are not
made or distributed for direct commercial advantage. The ACM
copyright notice and the title of the publication and its date appear,
and notice is given that copying is by permission of the Association
for Computing Machinery. To copy otherwise, or to republish, requires
a fee and/or specific permission.
Krogh, F. "Algorithms Policy." ACM Tran. Math. Softw. 13 (1987),
183-186.
Note, however, that only the particular expression of an algorithm can
be copyrighted, not the algorithm per se; see 17 USC 102E<40>bE<41>.
We place the Randlib code that we have written in the public domain.
=item *
B and B are distributed with B.
See L<"NO WARRANTY">.
=back
=head1 NO WARRANTY
WE PROVIDE ABSOLUTELY NO WARRANTY OF ANY KIND EITHER EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK
AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
THIS PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.
IN NO EVENT SHALL THE UNIVERSITY OF TEXAS OR ANY OF ITS COMPONENT
INSTITUTIONS INCLUDING M. D. ANDERSON HOSPITAL BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA OR
ITS ANALYSIS BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD
PARTIES FROM) THE PROGRAM.
(Above NO WARRANTY modified from the GNU NO WARRANTY statement.)
=cut