This is gsl-ref.info, produced by makeinfo version 4.2 from
gsl-ref.texi.

INFO-DIR-SECTION Scientific software
START-INFO-DIR-ENTRY
* gsl-ref: (gsl-ref).                   GNU Scientific Library - Reference
END-INFO-DIR-ENTRY


File: gsl-ref.info,  Node: The Bivariate Gaussian Distribution,  Next: The Exponential Distribution,  Prev: The Gaussian Tail Distribution,  Up: Random Number Distributions

The Bivariate Gaussian Distribution
===================================

 - Random: void gsl_ran_bivariate_gaussian (const gsl_rng * R, double
          SIGMA_X, double SIGMA_Y, double RHO, double * X, double * Y)
     This function generates a pair of correlated gaussian variates,
     with mean zero, correlation coefficient RHO and standard deviations
     SIGMA_X and SIGMA_Y in the x and y directions.  The probability
     distribution for bivariate gaussian random variates is,

          p(x,y) dx dy = {1 \over 2 \pi \sigma_x \sigma_y \sqrt{1-\rho^2}} \exp (-(x^2 + y^2 - 2 \rho x y)/2\sigma_x^2\sigma_y^2 (1-\rho^2)) dx dy

     for x,y in the range -\infty to +\infty.  The correlation
     coefficient RHO should lie between 1 and -1.

 - Function: double gsl_ran_bivariate_gaussian_pdf (double X, double Y,
          double SIGMA_X, double SIGMA_Y, double RHO)
     This function computes the probability density p(x,y) at (X,Y) for
     a bivariate gaussian distribution with standard deviations
     SIGMA_X, SIGMA_Y and correlation coefficient RHO, using the
     formula given above.



File: gsl-ref.info,  Node: The Exponential Distribution,  Next: The Laplace Distribution,  Prev: The Bivariate Gaussian Distribution,  Up: Random Number Distributions

The Exponential Distribution
============================

 - Random: double gsl_ran_exponential (const gsl_rng * R, double MU)
     This function returns a random variate from the exponential
     distribution with mean MU. The distribution is,

          p(x) dx = {1 \over \mu} \exp(-x/\mu) dx

     for x >= 0.

 - Function: double gsl_ran_exponential_pdf (double X, double MU)
     This function computes the probability density p(x) at X for an
     exponential distribution with mean MU, using the formula given
     above.



File: gsl-ref.info,  Node: The Laplace Distribution,  Next: The Exponential Power Distribution,  Prev: The Exponential Distribution,  Up: Random Number Distributions

The Laplace Distribution
========================

 - Random: double gsl_ran_laplace (const gsl_rng * R, double A)
     This function returns a random variate from the Laplace
     distribution with width A.  The distribution is,

          p(x) dx = {1 \over 2 a}  \exp(-|x/a|) dx

     for -\infty < x < \infty.

 - Function: double gsl_ran_laplace_pdf (double X, double A)
     This function computes the probability density p(x) at X for a
     Laplace distribution with mean A, using the formula given above.



File: gsl-ref.info,  Node: The Exponential Power Distribution,  Next: The Cauchy Distribution,  Prev: The Laplace Distribution,  Up: Random Number Distributions

The Exponential Power Distribution
==================================

 - Random: double gsl_ran_exppow (const gsl_rng * R, double A, double B)
     This function returns a random variate from the exponential power
     distribution with scale parameter A and exponent B.  The
     distribution is,

          p(x) dx = {1 \over 2 a \Gamma(1+1/b)} \exp(-|x/a|^b) dx

     for x >= 0.  For b = 1 this reduces to the Laplace distribution.
     For b = 2 it has the same form as a gaussian distribution, but
     with a = \sqrt{2} \sigma.

 - Function: double gsl_ran_exppow_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for an
     exponential power distribution with scale parameter A and exponent
     B, using the formula given above.



File: gsl-ref.info,  Node: The Cauchy Distribution,  Next: The Rayleigh Distribution,  Prev: The Exponential Power Distribution,  Up: Random Number Distributions

The Cauchy Distribution
=======================

 - Random: double gsl_ran_cauchy (const gsl_rng * R, double A)
     This function returns a random variate from the Cauchy
     distribution with scale parameter A.  The probability distribution
     for Cauchy random variates is,

          p(x) dx = {1 \over a\pi (1 + (x/a)^2) } dx

     for x in the range -\infty to +\infty.  The Cauchy distribution is
     also known as the Lorentz distribution.

 - Function: double gsl_ran_cauchy_pdf (double X, double A)
     This function computes the probability density p(x) at X for a
     Cauchy distribution with scale parameter A, using the formula
     given above.



File: gsl-ref.info,  Node: The Rayleigh Distribution,  Next: The Rayleigh Tail Distribution,  Prev: The Cauchy Distribution,  Up: Random Number Distributions

The Rayleigh Distribution
=========================

 - Random: double gsl_ran_rayleigh (const gsl_rng * R, double SIGMA)
     This function returns a random variate from the Rayleigh
     distribution with scale parameter SIGMA.  The distribution is,

          p(x) dx = {x \over \sigma^2} \exp(- x^2/(2 \sigma^2)) dx

     for x > 0.

 - Function: double gsl_ran_rayleigh_pdf (double X, double SIGMA)
     This function computes the probability density p(x) at X for a
     Rayleigh distribution with scale parameter SIGMA, using the
     formula given above.



File: gsl-ref.info,  Node: The Rayleigh Tail Distribution,  Next: The Landau Distribution,  Prev: The Rayleigh Distribution,  Up: Random Number Distributions

The Rayleigh Tail Distribution
==============================

 - Random: double gsl_ran_rayleigh_tail (const gsl_rng * R, double A
          double SIGMA)
     This function returns a random variate from the tail of the
     Rayleigh distribution with scale parameter SIGMA and a lower limit
     of A.  The distribution is,

          p(x) dx = {x \over \sigma^2} \exp ((a^2 - x^2) /(2 \sigma^2)) dx

     for x > a.

 - Function: double gsl_ran_rayleigh_tail_pdf (double X, double A,
          double SIGMA)
     This function computes the probability density p(x) at X for a
     Rayleigh tail distribution with scale parameter SIGMA and lower
     limit A, using the formula given above.



File: gsl-ref.info,  Node: The Landau Distribution,  Next: The Levy alpha-Stable Distributions,  Prev: The Rayleigh Tail Distribution,  Up: Random Number Distributions

The Landau Distribution
=======================

 - Random: double gsl_ran_landau (const gsl_rng * R)
     This function returns a random variate from the Landau
     distribution.  The probability distribution for Landau random
     variates is defined analytically by the complex integral,

          p(x) = (1/(2 \pi i)) \int_{c-i\infty}^{c+i\infty} ds exp(s log(s) + x s)
     For numerical purposes it is more convenient to use the following
     equivalent form of the integral,
          p(x) = (1/\pi) \int_0^\infty dt \exp(-t \log(t) - x t) \sin(\pi t).

 - Function: double gsl_ran_landau_pdf (double X)
     This function computes the probability density p(x) at X for the
     Landau distribution using an approximation to the formula given
     above.



File: gsl-ref.info,  Node: The Levy alpha-Stable Distributions,  Next: The Levy skew alpha-Stable Distribution,  Prev: The Landau Distribution,  Up: Random Number Distributions

The Levy alpha-Stable Distributions
===================================

 - Random: double gsl_ran_levy (const gsl_rng * R, double C, double
          ALPHA)
     This function returns a random variate from the Levy symmetric
     stable distribution with scale C and exponent ALPHA.  The symmetric
     stable probability distribution is defined by a fourier transform,

          p(x) = {1 \over 2 \pi} \int_{-\infty}^{+\infty} dt \exp(-it x - |c t|^alpha)

     There is no explicit solution for the form of p(x) and the library
     does not define a corresponding `pdf' function.  For \alpha = 1
     the distribution reduces to the Cauchy distribution.  For \alpha =
     2 it is a Gaussian distribution with \sigma = \sqrt{2} c.  For
     \alpha < 1 the tails of the distribution become extremely wide.

     The algorithm only works for 0 < alpha <= 2.



File: gsl-ref.info,  Node: The Levy skew alpha-Stable Distribution,  Next: The Gamma Distribution,  Prev: The Levy alpha-Stable Distributions,  Up: Random Number Distributions

The Levy skew alpha-Stable Distribution
=======================================

 - Random: double gsl_ran_levy_skew (const gsl_rng * R, double C,
          double ALPHA, double BETA)
     This function returns a random variate from the Levy skew stable
     distribution with scale C, exponent ALPHA and skewness parameter
     BETA.  The skewness parameter must lie in the range [-1,1].  The
     Levy skew stable probability distribution is defined by a fourier
     transform,

          p(x) = {1 \over 2 \pi} \int_{-\infty}^{+\infty} dt \exp(-it x - |c t|^alpha (1-i beta sign(t) tan(pi alpha/2)))

     When \alpha = 1 the term \tan(\pi \alpha/2) is replaced by
     -(2/\pi)\log|t|.  There is no explicit solution for the form of
     p(x) and the library does not define a corresponding `pdf'
     function.  For \alpha = 2 the distribution reduces to a Gaussian
     distribution with \sigma = \sqrt{2} c and the skewness parameter
     has no effect.  For \alpha < 1 the tails of the distribution
     become extremely wide.  The symmetric distribution corresponds to
     \beta = 0.

     The algorithm only works for 0 < alpha <= 2.

   The Levy alpha-stable distributions have the property that if N
alpha-stable variates are drawn from the distribution p(c, \alpha,
\beta) then the sum Y = X_1 + X_2 + \dots + X_N will also be
distributed as an alpha-stable variate, p(N^(1/\alpha) c, \alpha,
\beta).



File: gsl-ref.info,  Node: The Gamma Distribution,  Next: The Flat (Uniform) Distribution,  Prev: The Levy skew alpha-Stable Distribution,  Up: Random Number Distributions

The Gamma Distribution
======================

 - Random: double gsl_ran_gamma (const gsl_rng * R, double A, double B)
     This function returns a random variate from the gamma
     distribution.  The distribution function is,

          p(x) dx = {1 \over \Gamma(a) b^a} x^{a-1} e^{-x/b} dx

     for x > 0.

 - Function: double gsl_ran_gamma_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     gamma distribution with parameters A and B, using the formula
     given above.



File: gsl-ref.info,  Node: The Flat (Uniform) Distribution,  Next: The Lognormal Distribution,  Prev: The Gamma Distribution,  Up: Random Number Distributions

The Flat (Uniform) Distribution
===============================

 - Random: double gsl_ran_flat (const gsl_rng * R, double A, double B)
     This function returns a random variate from the flat (uniform)
     distribution from A to B. The distribution is,

          p(x) dx = {1 \over (b-a)} dx

     if a <= x < b and 0 otherwise.

 - Function: double gsl_ran_flat_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     uniform distribution from A to B, using the formula given above.



File: gsl-ref.info,  Node: The Lognormal Distribution,  Next: The Chi-squared Distribution,  Prev: The Flat (Uniform) Distribution,  Up: Random Number Distributions

The Lognormal Distribution
==========================

 - Random: double gsl_ran_lognormal (const gsl_rng * R, double ZETA,
          double SIGMA)
     This function returns a random variate from the lognormal
     distribution.  The distribution function is,

          p(x) dx = {1 \over x \sqrt{2 \pi \sigma^2} } \exp(-(\ln(x) - \zeta)^2/2 \sigma^2) dx

     for x > 0.

 - Function: double gsl_ran_lognormal_pdf (double X, double ZETA,
          double SIGMA)
     This function computes the probability density p(x) at X for a
     lognormal distribution with parameters ZETA and SIGMA, using the
     formula given above.



File: gsl-ref.info,  Node: The Chi-squared Distribution,  Next: The F-distribution,  Prev: The Lognormal Distribution,  Up: Random Number Distributions

The Chi-squared Distribution
============================

   The chi-squared distribution arises in statistics If Y_i are n
independent gaussian random variates with unit variance then the
sum-of-squares,

     X_i = \sum_i Y_i^2

has a chi-squared distribution with n degrees of freedom.

 - Random: double gsl_ran_chisq (const gsl_rng * R, double NU)
     This function returns a random variate from the chi-squared
     distribution with NU degrees of freedom. The distribution function
     is,

          p(x) dx = {1 \over \Gamma(\nu/2) } (x/2)^{\nu/2 - 1} \exp(-x/2) dx

     for x >= 0.

 - Function: double gsl_ran_chisq_pdf (double X, double NU)
     This function computes the probability density p(x) at X for a
     chi-squared distribution with NU degrees of freedom, using the
     formula given above.



File: gsl-ref.info,  Node: The F-distribution,  Next: The t-distribution,  Prev: The Chi-squared Distribution,  Up: Random Number Distributions

The F-distribution
==================

   The F-distribution arises in statistics.  If Y_1 and Y_2 are
chi-squared deviates with \nu_1 and \nu_2 degrees of freedom then the
ratio,

     X = { (Y_1 / \nu_1) \over (Y_2 / \nu_2) }

has an F-distribution F(x;\nu_1,\nu_2).

 - Random: double gsl_ran_fdist (const gsl_rng * R, double NU1, double
          NU2)
     This function returns a random variate from the F-distribution
     with degrees of freedom NU1 and NU2. The distribution function is,

          p(x) dx =
             { \Gamma((\nu_1 + \nu_2)/2)
                  \over \Gamma(\nu_1/2) \Gamma(\nu_2/2) }
             \nu_1^{\nu_1/2} \nu_2^{\nu_2/2}
             x^{\nu_1/2 - 1} (\nu_2 + \nu_1 x)^{-\nu_1/2 -\nu_2/2}

     for x >= 0.

 - Function: double gsl_ran_fdist_pdf (double X, double NU1, double NU2)
     This function computes the probability density p(x) at X for an
     F-distribution with NU1 and NU2 degrees of freedom, using the
     formula given above.



File: gsl-ref.info,  Node: The t-distribution,  Next: The Beta Distribution,  Prev: The F-distribution,  Up: Random Number Distributions

The t-distribution
==================

   The t-distribution arises in statistics.  If Y_1 has a normal
distribution and Y_2 has a chi-squared distribution with \nu degrees of
freedom then the ratio,

     X = { Y_1 \over \sqrt{Y_2 / \nu} }

has a t-distribution t(x;\nu) with \nu degrees of freedom.

 - Random: double gsl_ran_tdist (const gsl_rng * R, double NU)
     This function returns a random variate from the t-distribution.
     The distribution function is,

          p(x) dx = {\Gamma((\nu + 1)/2) \over \sqrt{\pi \nu} \Gamma(\nu/2)}
             (1 + x^2/\nu)^{-(\nu + 1)/2} dx

     for -\infty < x < +\infty.

 - Function: double gsl_ran_tdist_pdf (double X, double NU)
     This function computes the probability density p(x) at X for a
     t-distribution with NU degrees of freedom, using the formula given
     above.



File: gsl-ref.info,  Node: The Beta Distribution,  Next: The Logistic Distribution,  Prev: The t-distribution,  Up: Random Number Distributions

The Beta Distribution
=====================

 - Random: double gsl_ran_beta (const gsl_rng * R, double A, double B)
     This function returns a random variate from the beta distribution.
     The distribution function is,

          p(x) dx = {\Gamma(a+b) \over \Gamma(a) \Gamma(b)} x^{a-1} (1-x)^{b-1} dx

     for 0 <= x <= 1.

 - Function: double gsl_ran_beta_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     beta distribution with parameters A and B, using the formula given
     above.



File: gsl-ref.info,  Node: The Logistic Distribution,  Next: The Pareto Distribution,  Prev: The Beta Distribution,  Up: Random Number Distributions

The Logistic Distribution
=========================

 - Random: double gsl_ran_logistic (const gsl_rng * R, double A)
     This function returns a random variate from the logistic
     distribution.  The distribution function is,

          p(x) dx = { \exp(-x/a) \over a (1 + \exp(-x/a))^2 } dx

     for -\infty < x < +\infty.

 - Function: double gsl_ran_logistic_pdf (double X, double A)
     This function computes the probability density p(x) at X for a
     logistic distribution with scale parameter A, using the formula
     given above.



File: gsl-ref.info,  Node: The Pareto Distribution,  Next: The Spherical Distribution (2D & 3D),  Prev: The Logistic Distribution,  Up: Random Number Distributions

The Pareto Distribution
=======================

 - Random: double gsl_ran_pareto (const gsl_rng * R, double A, double B)
     This function returns a random variate from the Pareto
     distribution of order A.  The distribution function is,

          p(x) dx = (a/b) / (x/b)^{a+1} dx

     for x >= b.

 - Function: double gsl_ran_pareto_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     Pareto distribution with exponent A and scale B, using the formula
     given above.



File: gsl-ref.info,  Node: The Spherical Distribution (2D & 3D),  Next: The Weibull Distribution,  Prev: The Pareto Distribution,  Up: Random Number Distributions

The Spherical Distribution (2D & 3D)
====================================

   The spherical distributions generate random vectors, located on a
spherical surface.  They can be used as random directions, for example
in the steps of a random walk.

 - Random: void gsl_ran_dir_2d (const gsl_rng * R, double *X, double *Y)
 - Random: void gsl_ran_dir_2d_trig_method (const gsl_rng * R, double
          *X, double *Y)
     This function returns a random direction vector v = (X,Y) in two
     dimensions.  The vector is normalized such that |v|^2 = x^2 + y^2
     = 1.  The obvious way to do this is to take a uniform random
     number between 0 and 2\pi and let X and Y be the sine and cosine
     respectively.  Two trig functions would have been expensive in the
     old days, but with modern hardware implementations, this is
     sometimes the fastest way to go.  This is the case for my home
     Pentium (but not the case for my Sun Sparcstation 20 at work).
     Once can avoid the trig evaluations by choosing X and Y in the
     interior of a unit circle (choose them at random from the interior
     of the enclosing square, and then reject those that are outside
     the unit circle), and then dividing by \sqrt{x^2 + y^2}.  A much
     cleverer approach, attributed to von Neumann (See Knuth, v2, 3rd
     ed, p140, exercise 23), requires neither trig nor a square root.
     In this approach, U and V are chosen at random from the interior
     of a unit circle, and then x=(u^2-v^2)/(u^2+v^2) and
     y=uv/(u^2+v^2).

 - Random: void gsl_ran_dir_3d (const gsl_rng * R, double *X, double
          *Y, double * Z)
     This function returns a random direction vector v = (X,Y,Z) in
     three dimensions.  The vector is normalized such that |v|^2 = x^2
     + y^2 + z^2 = 1.  The method employed is due to Robert E. Knop
     (CACM 13, 326 (1970)), and explained in Knuth, v2, 3rd ed, p136.
     It uses the surprising fact that the distribution projected along
     any axis is actually uniform (this is only true for 3d).

 - Random: void gsl_ran_dir_nd (const gsl_rng * R, size_t N, double *X)
     This function returns a random direction vector v =
     (x_1,x_2,...,x_n) in N dimensions.  The vector is normalized such
     that |v|^2 = x_1^2 + x_2^2 + ... + x_n^2 = 1.  The method uses the
     fact that a multivariate gaussian distribution is spherically
     symmetric.  Each component is generated to have a gaussian
     distribution, and then the components are normalized.  The method
     is described by Knuth, v2, 3rd ed, p135-136, and attributed to G.
     W. Brown, Modern Mathematics for the Engineer (1956).


File: gsl-ref.info,  Node: The Weibull Distribution,  Next: The Type-1 Gumbel Distribution,  Prev: The Spherical Distribution (2D & 3D),  Up: Random Number Distributions

The Weibull Distribution
========================

 - Random: double gsl_ran_weibull (const gsl_rng * R, double A, double
          B)
     This function returns a random variate from the Weibull
     distribution.  The distribution function is,

          p(x) dx = {b \over a^b} x^{b-1}  \exp(-(x/a)^b) dx

     for x >= 0.

 - Function: double gsl_ran_weibull_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     Weibull distribution with scale A and exponent B, using the
     formula given above.



File: gsl-ref.info,  Node: The Type-1 Gumbel Distribution,  Next: The Type-2 Gumbel Distribution,  Prev: The Weibull Distribution,  Up: Random Number Distributions

The Type-1 Gumbel Distribution
==============================

 - Random: double gsl_ran_gumbel1 (const gsl_rng * R, double A, double
          B)
     This function returns  a random variate from the Type-1 Gumbel
     distribution.  The Type-1 Gumbel distribution function is,

          p(x) dx = a b \exp(-(b \exp(-ax) + ax)) dx

     for -\infty < x < \infty.

 - Function: double gsl_ran_gumbel1_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     Type-1 Gumbel distribution with parameters A and B, using the
     formula given above.



File: gsl-ref.info,  Node: The Type-2 Gumbel Distribution,  Next: The Dirichlet Distribution,  Prev: The Type-1 Gumbel Distribution,  Up: Random Number Distributions

The Type-2 Gumbel Distribution
==============================

 - Random: double gsl_ran_gumbel2 (const gsl_rng * R, double A, double
          B)
     This function returns a random variate from the Type-2 Gumbel
     distribution.  The Type-2 Gumbel distribution function is,

          p(x) dx = a b x^{-a-1} \exp(-b x^{-a}) dx

     for 0 < x < \infty.

 - Function: double gsl_ran_gumbel2_pdf (double X, double A, double B)
     This function computes the probability density p(x) at X for a
     Type-2 Gumbel distribution with parameters A and B, using the
     formula given above.



File: gsl-ref.info,  Node: The Dirichlet Distribution,  Next: General Discrete Distributions,  Prev: The Type-2 Gumbel Distribution,  Up: Random Number Distributions

The Dirichlet Distribution
==========================

 - Random: void gsl_ran_dirichlet (const gsl_rng * R, const size_t K,
          const double ALPHA[], double THETA[])
     This function returns an array of K random variates from a
     Dirichlet distribution of order K-1. The distribution function is

          p(\theta_1, ..., \theta_K) d\theta_1 ... d\theta_K =
            (1/Z) \prod_{i=1}^K \theta_i^{\alpha_i - 1} \delta(1 -\sum_{i=1}^K \theta_i) d\theta_1 ... d\theta_K

     for theta_i >= 0 and alpha_i >= 0.  The normalization factor Z is

          Z = {\prod_{i=1}^K \Gamma(\alpha_i)} / {\Gamma( \sum_{i=1}^K \alpha_i)}

     The random variates are generated by sampling K values from gamma
     distributions with parameters a=alpha_i, b=1, and renormalizing.
     See A.M. Law, W.D. Kelton, `Simulation Modeling and Analysis'
     (1991).

 - Function: double gsl_ran_dirichlet_pdf (const size_t K, const double
          ALPHA[], const double THETA[])
     This function computes the probability density p(\theta_1, ... ,
     \theta_K) at THETA[K] for a Dirichlet distribution with parameters
     ALPHA[K], using the formula given above.

 - Function: double gsl_ran_dirichlet_lnpdf (const size_t K, const
          double ALPHA[], const double THETA[])
     This function computes the logarithm of the probability density
     p(\theta_1, ... , \theta_K) for a Dirichlet distribution with
     parameters ALPHA[K].


File: gsl-ref.info,  Node: General Discrete Distributions,  Next: The Poisson Distribution,  Prev: The Dirichlet Distribution,  Up: Random Number Distributions

General Discrete Distributions
==============================

   Given K discrete events with different probabilities P[k], produce a
random value k consistent with its probability.

   The obvious way to do this is to preprocess the probability list by
generating a cumulative probability array with K+1 elements:

       C[0] = 0
     C[k+1] = C[k]+P[k].

Note that this construction produces C[K]=1.  Now choose a uniform
deviate u between 0 and 1, and find the value of k such that C[k] <= u
< C[k+1].  Although this in principle requires of order \log K steps per
random number generation, they are fast steps, and if you use something
like \lfloor uK \rfloor as a starting point, you can often do pretty
well.

   But faster methods have been devised.  Again, the idea is to
preprocess the probability list, and save the result in some form of
lookup table; then the individual calls for a random discrete event can
go rapidly.  An approach invented by G. Marsaglia (Generating discrete
random numbers in a computer, Comm ACM 6, 37-38 (1963)) is very clever,
and readers interested in examples of good algorithm design are
directed to this short and well-written paper.  Unfortunately, for
large K, Marsaglia's lookup table can be quite large.

   A much better approach is due to Alastair J. Walker (An efficient
method for generating discrete random variables with general
distributions, ACM Trans on Mathematical Software 3, 253-256 (1977);
see also Knuth, v2, 3rd ed, p120-121,139).  This requires two lookup
tables, one floating point and one integer, but both only of size K.
After preprocessing, the random numbers are generated in O(1) time,
even for large K.  The preprocessing suggested by Walker requires
O(K^2) effort, but that is not actually necessary, and the
implementation provided here only takes O(K) effort.  In general, more
preprocessing leads to faster generation of the individual random
numbers, but a diminishing return is reached pretty early.  Knuth points
out that the optimal preprocessing is combinatorially difficult for
large K.

   This method can be used to speed up some of the discrete random
number generators below, such as the binomial distribution.  To use if
for something like the Poisson Distribution, a modification would have
to be made, since it only takes a finite set of K outcomes.

 - Function: gsl_ran_discrete_t * gsl_ran_discrete_preproc (size_t K,
          const double * P)
     This function returns a pointer to a structure that contains the
     lookup table for the discrete random number generator.  The array
     P[] contains the probabilities of the discrete events; these array
     elements must all be positive, but they needn't add up to one (so
     you can think of them more generally as "weights") - the
     preprocessor will normalize appropriately.  This return value is
     used as an argument for the `gsl_ran_discrete' function below.

 - Random: size_t gsl_ran_discrete (const gsl_rng * R, const
          gsl_ran_discrete_t * G)
     After the preprocessor, above, has been called, you use this
     function to get the discrete random numbers.

 - Function: double gsl_ran_discrete_pdf (size_t K, const
          gsl_ran_discrete_t * G)
     Returns the probability P[k] of observing the variable K.  Since
     P[k] is not stored as part of the lookup table, it must be
     recomputed; this computation takes O(K), so if K is large and you
     care about the original array P[k] used to create the lookup
     table, then you should just keep this original array P[k] around.

 - Function: void gsl_ran_discrete_free (gsl_ran_discrete_t * G)
     De-allocates the lookup table pointed to by G.


File: gsl-ref.info,  Node: The Poisson Distribution,  Next: The Bernoulli Distribution,  Prev: General Discrete Distributions,  Up: Random Number Distributions

The Poisson Distribution
========================

 - Random: unsigned int gsl_ran_poisson (const gsl_rng * R, double MU)
     This function returns a random integer from the Poisson
     distribution with mean MU.  The probability distribution for
     Poisson variates is,

          p(k) = {\mu^k \over k!} \exp(-\mu)

     for k >= 0.

 - Function: double gsl_ran_poisson_pdf (unsigned int K, double MU)
     This function computes the probability p(k) of obtaining  K from a
     Poisson distribution with mean MU, using the formula given above.



File: gsl-ref.info,  Node: The Bernoulli Distribution,  Next: The Binomial Distribution,  Prev: The Poisson Distribution,  Up: Random Number Distributions

The Bernoulli Distribution
==========================

 - Random: unsigned int gsl_ran_bernoulli (const gsl_rng * R, double P)
     This function returns either 0 or 1, the result of a Bernoulli
     trial with probability P.  The probability distribution for a
     Bernoulli trial is,

          p(0) = 1 - p
          p(1) = p


 - Function: double gsl_ran_bernoulli_pdf (unsigned int K, double P)
     This function computes the probability p(k) of obtaining K from a
     Bernoulli distribution with probability parameter P, using the
     formula given above.



File: gsl-ref.info,  Node: The Binomial Distribution,  Next: The Multinomial Distribution,  Prev: The Bernoulli Distribution,  Up: Random Number Distributions

The Binomial Distribution
=========================

 - Random: unsigned int gsl_ran_binomial (const gsl_rng * R, double P,
          unsigned int N)
     This function returns a random integer from the binomial
     distribution, the number of successes in N independent trials with
     probability P.  The probability distribution for binomial variates
     is,

          p(k) = {n! \over k! (n-k)! } p^k (1-p)^{n-k}

     for 0 <= k <= n.

 - Function: double gsl_ran_binomial_pdf (unsigned int K, double P,
          unsigned int N)
     This function computes the probability p(k) of obtaining K from a
     binomial distribution with parameters P and N, using the formula
     given above.



File: gsl-ref.info,  Node: The Multinomial Distribution,  Next: The Negative Binomial Distribution,  Prev: The Binomial Distribution,  Up: Random Number Distributions

The Multinomial Distribution
============================

 - Random: void gsl_ran_multinomial (const gsl_rng * R, const size_t K,
          const unsigned int N, const double P[], unsigned int N[])
     This function returns an array of K random variates from a
     multinomial distribution. The distribution function is,

          P(n_1, n_2, ..., n_K) =
            (N!/(n_1! n_2! ... n_K!)) p_1^n_1 p_2^n_2 ... p_K^n_K

     where (n_1, n_2, ..., n_K) are nonnegative integers with
     sum_{k=1,K} n_k = N, and (p_1, p_2, ..., p_K) is a probability
     distribution with \sum p_i = 1.  If the array P[K] is not
     normalized then its entries will be treated as weights and
     normalized appropriately.

     Random variates are generated using the conditional binomial
     method (see C.S. David, `The computer generation of multinomial
     random variates', Comp. Stat. Data Anal. 16 (1993) 205-217 for
     details).

 - Function: double gsl_ran_multinomial_pdf (const size_t K, const
          double P[], const unsigned int N[])
     This function computes the probability P(n_1, n_2, ..., n_K) of
     sampling N[K] from a multinomial distribution with parameters
     P[K], using the formula given above.

 - Function: double gsl_ran_multinomial_lnpdf (const size_t K, const
          double P[], const unsigned int N[])
     This function returns the logarithm of the probability for the
     multinomial distribution P(n_1, n_2, ..., n_K) with parameters
     P[K].


File: gsl-ref.info,  Node: The Negative Binomial Distribution,  Next: The Pascal Distribution,  Prev: The Multinomial Distribution,  Up: Random Number Distributions

The Negative Binomial Distribution
==================================

 - Random: unsigned int gsl_ran_negative_binomial (const gsl_rng * R,
          double P, double N)
     This function returns a random integer from the negative binomial
     distribution, the number of failures occurring before N successes
     in independent trials with probability P of success.  The
     probability distribution for negative binomial variates is,

          p(k) = {\Gamma(n + k) \over \Gamma(k+1) \Gamma(n) } p^n (1-p)^k

     Note that n is not required to be an integer.

 - Function: double gsl_ran_negative_binomial_pdf (unsigned int K,
          double P, double N)
     This function computes the probability p(k) of obtaining K from a
     negative binomial distribution with parameters P and N, using the
     formula given above.



File: gsl-ref.info,  Node: The Pascal Distribution,  Next: The Geometric Distribution,  Prev: The Negative Binomial Distribution,  Up: Random Number Distributions

The Pascal Distribution
=======================

 - Random: unsigned int gsl_ran_pascal (const gsl_rng * R, double P,
          unsigned int K)
     This function returns a random integer from the Pascal
     distribution.  The Pascal distribution is simply a negative
     binomial distribution with an integer value of n.

          p(k) = {(n + k - 1)! \over k! (n - 1)! } p^n (1-p)^k

     for k >= 0

 - Function: double gsl_ran_pascal_pdf (unsigned int K, double P,
          unsigned int N)
     This function computes the probability p(k) of obtaining K from a
     Pascal distribution with parameters P and N, using the formula
     given above.



File: gsl-ref.info,  Node: The Geometric Distribution,  Next: The Hypergeometric Distribution,  Prev: The Pascal Distribution,  Up: Random Number Distributions

The Geometric Distribution
==========================

 - Random: unsigned int gsl_ran_geometric (const gsl_rng * R, double P)
     This function returns a random integer from the geometric
     distribution, the number of independent trials with probability P
     until the first success.  The probability distribution for
     geometric variates is,

          p(k) =  p (1-p)^(k-1)

     for k >= 1.

 - Function: double gsl_ran_geometric_pdf (unsigned int K, double P)
     This function computes the probability p(k) of obtaining K from a
     geometric distribution with probability parameter P, using the
     formula given above.



File: gsl-ref.info,  Node: The Hypergeometric Distribution,  Next: The Logarithmic Distribution,  Prev: The Geometric Distribution,  Up: Random Number Distributions

The Hypergeometric Distribution
===============================

 - Random: unsigned int gsl_ran_hypergeometric (const gsl_rng * R,
          unsigned int N1, unsigned int N2, unsigned int T)
     This function returns a random integer from the hypergeometric
     distribution.  The probability distribution for hypergeometric
     random variates is,

          p(k) =  C(n_1,k) C(n_2, t-k) / C(n_1 + n_2,k)

     where C(a,b) = a!/(b!(a-b)!).  The domain of k is max(0,t-n_2),
     ..., max(t,n_1).

 - Function: double gsl_ran_hypergeometric_pdf (unsigned int K,
          unsigned int N1, unsigned int N2, unsigned int T)
     This function computes the probability p(k) of obtaining K from a
     hypergeometric distribution with parameters N1, N2, N3, using the
     formula given above.



File: gsl-ref.info,  Node: The Logarithmic Distribution,  Next: Shuffling and Sampling,  Prev: The Hypergeometric Distribution,  Up: Random Number Distributions

The Logarithmic Distribution
============================

 - Random: unsigned int gsl_ran_logarithmic (const gsl_rng * R, double
          P)
     This function returns a random integer from the logarithmic
     distribution.  The probability distribution for logarithmic random
     variates is,

          p(k) = {-1 \over \log(1-p)} {(p^k \over k)}

     for k >= 1.

 - Function: double gsl_ran_logarithmic_pdf (unsigned int K, double P)
     This function computes the probability p(k) of obtaining K from a
     logarithmic distribution with probability parameter P, using the
     formula given above.



File: gsl-ref.info,  Node: Shuffling and Sampling,  Next: Random Number Distribution Examples,  Prev: The Logarithmic Distribution,  Up: Random Number Distributions

Shuffling and Sampling
======================

   The following functions allow the shuffling and sampling of a set of
objects.  The algorithms rely on a random number generator as source of
randomness and a poor quality generator can lead to correlations in the
output.  In particular it is important to avoid generators with a short
period.  For more information see Knuth, v2, 3rd ed, Section 3.4.2,
"Random Sampling and Shuffling".

 - Random: void gsl_ran_shuffle (const gsl_rng * R, void * BASE, size_t
          N, size_t SIZE)
     This function randomly shuffles the order of N objects, each of
     size SIZE, stored in the array BASE[0..N-1].  The output of the
     random number generator R is used to produce the permutation.  The
     algorithm generates all possible n!  permutations with equal
     probability, assuming a perfect source of random numbers.

     The following code shows how to shuffle the numbers from 0 to 51,

          int a[52];
          
          for (i = 0; i < 52; i++)
            {
              a[i] = i;
            }
          
          gsl_ran_shuffle (r, a, 52, sizeof (int));


 - Random: int gsl_ran_choose (const gsl_rng * R, void * DEST, size_t
          K, void * SRC, size_t N, size_t SIZE)
     This function fills the array DEST[k] with K objects taken
     randomly from the N elements of the array SRC[0..N-1].  The
     objects are each of size SIZE.  The output of the random number
     generator R is used to make the selection.  The algorithm ensures
     all possible samples are equally likely, assuming a perfect source
     of randomness.

     The objects are sampled _without_ replacement, thus each object can
     only appear once in DEST[k].  It is required that K be less than
     or equal to `n'.  The objects in DEST will be in the same relative
     order as those in SRC.  You will need to call `gsl_ran_shuffle(r,
     dest, n, size)' if you want to randomize the order.

     The following code shows how to select a random sample of three
     unique numbers from the set 0 to 99,

          double a[3], b[100];
          
          for (i = 0; i < 100; i++)
            {
              b[i] = (double) i;
            }
          
          gsl_ran_choose (r, a, 3, b, 100, sizeof (double));


 - Random: void gsl_ran_sample (const gsl_rng * R, void * DEST, size_t
          K, void * SRC, size_t N, size_t SIZE)
     This function is like `gsl_ran_choose' but samples K items from
     the original array of N items SRC with replacement, so the same
     object can appear more than once in the output sequence DEST.
     There is no requirement that K be less than N in this case.


File: gsl-ref.info,  Node: Random Number Distribution Examples,  Next: Random Number Distribution References and Further Reading,  Prev: Shuffling and Sampling,  Up: Random Number Distributions

Examples
========

   The following program demonstrates the use of a random number
generator to produce variates from a distribution.  It prints 10
samples from the Poisson distribution with a mean of 3.

     #include <stdio.h>
     #include <gsl/gsl_rng.h>
     #include <gsl/gsl_randist.h>
     
     int
     main (void)
     {
       const gsl_rng_type * T;
       gsl_rng * r;
     
       int i, n = 10;
       double mu = 3.0;
     
       /* create a generator chosen by the
          environment variable GSL_RNG_TYPE */
     
       gsl_rng_env_setup();
     
       T = gsl_rng_default;
       r = gsl_rng_alloc (T);
     
       /* print n random variates chosen from
          the poisson distribution with mean
          parameter mu */
     
       for (i = 0; i < n; i++)
         {
           unsigned int k = gsl_ran_poisson (r, mu);
           printf(" %u", k);
         }
     
       printf("\n");
       return 0;
     }

If the library and header files are installed under `/usr/local' (the
default location) then the program can be compiled with these options,

     gcc demo.c -lgsl -lgslcblas -lm

Here is the output of the program,

     $ ./a.out
      4 2 3 3 1 3 4 1 3 5

The variates depend on the seed used by the generator.  The seed for the
default generator type `gsl_rng_default' can be changed with the
`GSL_RNG_SEED' environment variable to produce a different stream of
variates,

     $ GSL_RNG_SEED=123 ./a.out
     GSL_RNG_SEED=123
      1 1 2 1 2 6 2 1 8 7

The following program generates a random walk in two dimensions.

     #include <stdio.h>
     #include <gsl/gsl_rng.h>
     #include <gsl/gsl_randist.h>
     
     int
     main (void)
     {
       int i;
       double x = 0, y = 0, dx, dy;
     
       const gsl_rng_type * T;
       gsl_rng * r;
     
       gsl_rng_env_setup();
       T = gsl_rng_default;
       r = gsl_rng_alloc (T);
     
       printf("%g %g\n", x, y);
     
       for (i = 0; i < 10; i++)
         {
           gsl_ran_dir_2d (r, &dx, &dy);
           x += dx; y += dy;
           printf("%g %g\n", x, y);
         }
       return 0;
     }

Example output from the program, three 10-step random walks from the
origin.



File: gsl-ref.info,  Node: Random Number Distribution References and Further Reading,  Prev: Random Number Distribution Examples,  Up: Random Number Distributions

References and Further Reading
==============================

For an encyclopaedic coverage of the subject readers are advised to
consult the book `Non-Uniform Random Variate Generation' by Luc
Devroye.  It covers every imaginable distribution and provides hundreds
of algorithms.

     Luc Devroye, `Non-Uniform Random Variate Generation',
     Springer-Verlag, ISBN 0-387-96305-7.

The subject of random variate generation is also reviewed by Knuth, who
describes algorithms for all the major distributions.

     Donald E. Knuth, `The Art of Computer Programming: Seminumerical
     Algorithms' (Vol 2, 3rd Ed, 1997), Addison-Wesley, ISBN 0201896842.

The Particle Data Group provides a short review of techniques for
generating distributions of random numbers in the "Monte Carlo" section
of its Annual Review of Particle Physics.

     `Review of Particle Properties' R.M. Barnett et al., Physical
     Review D54, 1 (1996) <http://pdg.lbl.gov/>.

The Review of Particle Physics is available online in postscript and pdf
format.


File: gsl-ref.info,  Node: Statistics,  Next: Histograms,  Prev: Random Number Distributions,  Up: Top

Statistics
**********

   This chapter describes the statistical functions in the library.  The
basic statistical functions include routines to compute the mean,
variance and standard deviation.  More advanced functions allow you to
calculate absolute deviations, skewness, and kurtosis as well as the
median and arbitrary percentiles.  The algorithms use recurrence
relations to compute average quantities in a stable way, without large
intermediate values that might overflow.

   The functions are available in versions for datasets in the standard
floating-point and integer types.  The versions for double precision
floating-point data have the prefix `gsl_stats' and are declared in the
header file `gsl_statistics_double.h'.  The versions for integer data
have the prefix `gsl_stats_int' and are declared in the header files
`gsl_statistics_int.h'.

* Menu:

* Mean and standard deviation and variance::
* Absolute deviation::
* Higher moments (skewness and kurtosis)::
* Autocorrelation::
* Covariance::
* Weighted Samples::
* Maximum and Minimum values::
* Median and Percentiles::
* Example statistical programs::
* Statistics References and Further Reading::


File: gsl-ref.info,  Node: Mean and standard deviation and variance,  Next: Absolute deviation,  Up: Statistics

Mean, Standard Deviation and Variance
=====================================

 - Statistics: double gsl_stats_mean (const double DATA[], size_t
          STRIDE, size_t N)
     This function returns the arithmetic mean of DATA, a dataset of
     length N with stride STRIDE.  The arithmetic mean, or "sample
     mean", is denoted by \Hat\mu and defined as,

          \Hat\mu = (1/N) \sum x_i

     where x_i are the elements of the dataset DATA.  For samples drawn
     from a gaussian distribution the variance of \Hat\mu is \sigma^2 /
     N.

 - Statistics: double gsl_stats_variance (const double DATA[], size_t
          STRIDE, size_t N)
     This function returns the estimated, or "sample", variance of
     DATA, a dataset of length N with stride STRIDE.  The estimated
     variance is denoted by \Hat\sigma^2 and is defined by,

          \Hat\sigma^2 = (1/(N-1)) \sum (x_i - \Hat\mu)^2

     where x_i are the elements of the dataset DATA.  Note that the
     normalization factor of 1/(N-1) results from the derivation of
     \Hat\sigma^2 as an unbiased estimator of the population variance
     \sigma^2.  For samples drawn from a gaussian distribution the
     variance of \Hat\sigma^2 itself is 2 \sigma^4 / N.

     This function computes the mean via a call to `gsl_stats_mean'.  If
     you have already computed the mean then you can pass it directly to
     `gsl_stats_variance_m'.

 - Statistics: double gsl_stats_variance_m (const double DATA[], size_t
          STRIDE, size_t N, double MEAN)
     This function returns the sample variance of DATA relative to the
     given value of MEAN.  The function is computed with \Hat\mu
     replaced by the value of MEAN that you supply,

          \Hat\sigma^2 = (1/(N-1)) \sum (x_i - mean)^2

 - Statistics: double gsl_stats_sd (const double DATA[], size_t STRIDE,
          size_t N)
 - Statistics: double gsl_stats_sd_m (const double DATA[], size_t
          STRIDE, size_t N, double MEAN)
     The standard deviation is defined as the square root of the
     variance.  These functions return the square root of the
     corresponding variance functions above.

 - Statistics: double gsl_stats_variance_with_fixed_mean (const double
          DATA[], size_t STRIDE, size_t N, double MEAN)
     This function computes an unbiased estimate of the variance of
     DATA when the population mean MEAN of the underlying distribution
     is known _a priori_.  In this case the estimator for the variance
     uses the factor 1/N and the sample mean \Hat\mu is replaced by the
     known population mean \mu,

          \Hat\sigma^2 = (1/N) \sum (x_i - \mu)^2


 - Statistics: double gsl_stats_sd_with_fixed_mean (const double
          DATA[], size_t STRIDE, size_t N, double MEAN)
     This function calculates the standard deviation of DATA for a
     fixed population mean MEAN.  The result is the square root of the
     corresponding variance function.


File: gsl-ref.info,  Node: Absolute deviation,  Next: Higher moments (skewness and kurtosis),  Prev: Mean and standard deviation and variance,  Up: Statistics

Absolute deviation
==================

 - Statistics: double gsl_stats_absdev (const double DATA[], size_t
          STRIDE, size_t N)
     This function computes the absolute deviation from the mean of
     DATA, a dataset of length N with stride STRIDE.  The absolute
     deviation from the mean is defined as,

          absdev  = (1/N) \sum |x_i - \Hat\mu|

     where x_i are the elements of the dataset DATA.  The absolute
     deviation from the mean provides a more robust measure of the
     width of a distribution than the variance.  This function computes
     the mean of DATA via a call to `gsl_stats_mean'.

 - Statistics: double gsl_stats_absdev_m (const double DATA[], size_t
          STRIDE, size_t N, double MEAN)
     This function computes the absolute deviation of the dataset DATA
     relative to the given value of MEAN,

          absdev  = (1/N) \sum |x_i - mean|

     This function is useful if you have already computed the mean of
     DATA (and want to avoid recomputing it), or wish to calculate the
     absolute deviation relative to another value (such as zero, or the
     median).

