randist.texi

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY without ev

something like the Poisson Distribution, a modification would have to
be made, since it only takes a finite set of @math{K} outcomes.

@deftypefun {gsl_ran_discrete_t *} gsl_ran_discrete_preproc (size_t @var{K}, const double * @var{P})
@cindex Discrete random numbers
@cindex Discrete random numbers, preprocessing
This function returns a pointer to a structure that contains the lookup
table for the discrete random number generator.  The array @var{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 @code{gsl_ran_discrete} function below.
@end deftypefun

@deftypefun {size_t} gsl_ran_discrete (const gsl_rng * @var{r}, const gsl_ran_discrete_t * @var{g})
@cindex Discrete random numbers
After the preprocessor, above, has been called, you use this function to
get the discrete random numbers.
@end deftypefun

@deftypefun {double} gsl_ran_discrete_pdf (size_t @var{k}, const gsl_ran_discrete_t * @var{g})
@cindex Discrete random numbers
Returns the probability @math{P[k]} of observing the variable @var{k}.
Since @math{P[k]} is not stored as part of the lookup table, it must be
recomputed; this computation takes @math{O(K)}, so if @var{K} is large
and you care about the original array @math{P[k]} used to create the
lookup table, then you should just keep this original array @math{P[k]}
around.
@end deftypefun

@deftypefun {void} gsl_ran_discrete_free (gsl_ran_discrete_t * @var{g})
@cindex Discrete random numbers
De-allocates the lookup table pointed to by @var{g}.
@end deftypefun

@page
@node The Poisson Distribution
@section The Poisson Distribution
@deftypefun {unsigned int} gsl_ran_poisson (const gsl_rng * @var{r}, double @var{mu})
@cindex Poisson random numbers
This function returns a random integer from the Poisson distribution
with mean @var{mu}.  The probability distribution for Poisson variates is,
@tex
\beforedisplay
$$
p(k) = {\mu^k \over k!} \exp(-\mu)
$$
\afterdisplay
@end tex
@ifinfo

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

@end ifinfo
@noindent
for @c{$k \ge 0$}
@math{k >= 0}.
@end deftypefun

@deftypefun double gsl_ran_poisson_pdf (unsigned int @var{k}, double @var{mu})
This function computes the probability @math{p(k)} of obtaining  @var{k}
from a Poisson distribution with mean @var{mu}, using the formula
given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-poisson.tex}
@end tex

@deftypefun double gsl_cdf_poisson_P (unsigned int @var{k}, double @var{mu})
@deftypefunx double gsl_cdf_poisson_Q (unsigned int @var{k}, double @var{mu})
These functions compute the cumulative distribution functions
@math{P(k)}, @math{Q(k)} for the Poisson distribution with parameter
@var{mu}.
@end deftypefun


@page
@node The Bernoulli Distribution
@section The Bernoulli Distribution
@deftypefun {unsigned int} gsl_ran_bernoulli (const gsl_rng * @var{r}, double @var{p})
@cindex Bernoulli trial, random variates
This function returns either 0 or 1, the result of a Bernoulli trial
with probability @var{p}.  The probability distribution for a Bernoulli
trial is,
@tex
\beforedisplay
$$
\eqalign{
p(0) & = 1 - p \cr
p(1) & = p
}
$$
\afterdisplay
@end tex
@ifinfo

@example
p(0) = 1 - p
p(1) = p
@end example
@end ifinfo

@end deftypefun

@deftypefun double gsl_ran_bernoulli_pdf (unsigned int @var{k}, double @var{p})
This function computes the probability @math{p(k)} of obtaining
@var{k} from a Bernoulli distribution with probability parameter
@var{p}, using the formula given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-bernoulli.tex}
@end tex

@page
@node The Binomial Distribution
@section The Binomial Distribution
@deftypefun {unsigned int} gsl_ran_binomial (const gsl_rng * @var{r}, double @var{p}, unsigned int @var{n})
@cindex Binomial random variates
This function returns a random integer from the binomial distribution,
the number of successes in @var{n} independent trials with probability
@var{p}.  The probability distribution for binomial variates is,
@tex
\beforedisplay
$$
p(k) = {n! \over k! (n-k)!} p^k (1-p)^{n-k}
$$
\afterdisplay
@end tex
@ifinfo

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

@end ifinfo
@noindent
for @c{$0 \le k \le n$}
@math{0 <= k <= n}.
@end deftypefun

@deftypefun double gsl_ran_binomial_pdf (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
This function computes the probability @math{p(k)} of obtaining @var{k}
from a binomial distribution with parameters @var{p} and @var{n}, using
the formula given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-binomial.tex}
@end tex

@deftypefun double gsl_cdf_binomial_P (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
@deftypefunx double gsl_cdf_binomial_Q (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
These functions compute the cumulative distribution functions
@math{P(k)}, @math{Q(k)}  for the binomial
distribution with parameters @var{p} and @var{n}.
@end deftypefun


@page
@node The Multinomial Distribution
@section The Multinomial Distribution
@deftypefun void gsl_ran_multinomial (const gsl_rng * @var{r}, size_t @var{K}, unsigned int @var{N}, const double @var{p}[], unsigned int @var{n}[])
@cindex Multinomial distribution 

This function returns an array of @var{K} random variates from a 
multinomial distribution. The distribution function is,
@tex
\beforedisplay
$$
P(n_1, n_2,\cdots, n_K) = {{ N!}\over{n_1 ! n_2 ! \cdots n_K !}} \,
  p_1^{n_1} p_2^{n_2} \cdots p_K^{n_K}
$$
\afterdisplay
@end tex
@ifinfo

@example
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
@end example

@end ifinfo
@noindent
where @c{($n_1$, $n_2$, $\ldots$, $n_K$)}
@math{(n_1, n_2, ..., n_K)} 
are nonnegative integers with 
@c{$\sum_{k=1}^{K} n_k =N$} 
@math{sum_@{k=1@}^K n_k = N},
and
@c{$(p_1, p_2, \ldots, p_K)$} 
@math{(p_1, p_2, ..., p_K)}
is a probability distribution with @math{\sum p_i = 1}.  
If the array @var{p}[@var{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, @cite{The computer generation of multinomial random
variates}, Comp. Stat. Data Anal. 16 (1993) 205--217 for details).
@end deftypefun

@deftypefun double gsl_ran_multinomial_pdf (size_t @var{K}, const double @var{p}[], const unsigned int @var{n}[]) 
This function computes the probability 
@c{$P(n_1, n_2, \ldots, n_K)$}
@math{P(n_1, n_2, ..., n_K)}
of sampling @var{n}[@var{K}] from a multinomial distribution 
with parameters @var{p}[@var{K}], using the formula given above.
@end deftypefun

@deftypefun double gsl_ran_multinomial_lnpdf (size_t @var{K}, const double @var{p}[], const unsigned int @var{n}[]) 
This function returns the logarithm of the probability for the
multinomial distribution @c{$P(n_1, n_2, \ldots, n_K)$}
@math{P(n_1, n_2, ..., n_K)} with parameters @var{p}[@var{K}].
@end deftypefun


@page
@node The Negative Binomial Distribution
@section The Negative Binomial Distribution
@deftypefun {unsigned int} gsl_ran_negative_binomial (const gsl_rng * @var{r}, double @var{p}, double @var{n})
@cindex Negative Binomial distribution, random variates
This function returns a random integer from the negative binomial
distribution, the number of failures occurring before @var{n} successes
in independent trials with probability @var{p} of success.  The
probability distribution for negative binomial variates is,
@tex
\beforedisplay
$$
p(k) = {\Gamma(n + k) \over \Gamma(k+1) \Gamma(n) } p^n (1-p)^k
$$
\afterdisplay
@end tex
@ifinfo

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

@end ifinfo
@noindent
Note that @math{n} is not required to be an integer.
@end deftypefun

@deftypefun double gsl_ran_negative_binomial_pdf (unsigned int @var{k}, double @var{p}, double  @var{n})
This function computes the probability @math{p(k)} of obtaining @var{k}
from a negative binomial distribution with parameters @var{p} and
@var{n}, using the formula given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-nbinomial.tex}
@end tex

@deftypefun double gsl_cdf_negative_binomial_P (unsigned int @var{k}, double @var{p}, double @var{n})
@deftypefunx double gsl_cdf_negative_binomial_Q (unsigned int @var{k}, double @var{p}, double @var{n})
These functions compute the cumulative distribution functions
@math{P(k)}, @math{Q(k)} for the negative binomial distribution with
parameters @var{p} and @var{n}.
@end deftypefun

@page
@node The Pascal Distribution
@section The Pascal Distribution

@deftypefun {unsigned int} gsl_ran_pascal (const gsl_rng * @var{r}, double @var{p}, unsigned int @var{n})
This function returns a random integer from the Pascal distribution.  The
Pascal distribution is simply a negative binomial distribution with an
integer value of @math{n}.
@tex
\beforedisplay
$$
p(k) = {(n + k - 1)! \over k! (n - 1)! } p^n (1-p)^k
$$
\afterdisplay
@end tex
@ifinfo

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

@end ifinfo
@noindent
for @c{$k \ge 0$}
@math{k >= 0}
@end deftypefun

@deftypefun double gsl_ran_pascal_pdf (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
This function computes the probability @math{p(k)} of obtaining @var{k}
from a Pascal distribution with parameters @var{p} and
@var{n}, using the formula given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-pascal.tex}
@end tex

@deftypefun double gsl_cdf_pascal_P (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
@deftypefunx double gsl_cdf_pascal_Q (unsigned int @var{k}, double @var{p}, unsigned int @var{n})
These functions compute the cumulative distribution functions
@math{P(k)}, @math{Q(k)} for the Pascal distribution with
parameters @var{p} and @var{n}.
@end deftypefun

@page
@node The Geometric Distribution
@section The Geometric Distribution
@deftypefun {unsigned int} gsl_ran_geometric (const gsl_rng * @var{r}, double @var{p})
@cindex Geometric random variates
This function returns a random integer from the geometric distribution,
the number of independent trials with probability @var{p} until the
first success.  The probability distribution for geometric variates
is,
@tex
\beforedisplay
$$
p(k) =  p (1-p)^{k-1}
$$
\afterdisplay
@end tex
@ifinfo

@example
p(k) =  p (1-p)^(k-1)
@end example

@end ifinfo
@noindent
for @c{$k \ge 1$}
@math{k >= 1}.  Note that the distribution begins with @math{k=1} with this
definition.  There is another convention in which the exponent @math{k-1} 
is replaced by @math{k}.
@end deftypefun

@deftypefun double gsl_ran_geometric_pdf (unsigned int @var{k}, double @var{p})
This function computes the probability @math{p(k)} of obtaining @var{k}
from a geometric distribution with probability parameter @var{p}, using
the formula given above.
@end deftypefun

@sp 1
@tex
\centerline{\input rand-geometric.tex}
@end tex

@deftypefun double gsl_cdf_geometric_P (unsigned int @var{k}, double @var{p})
@deftypefunx double gsl_cdf_geometric_Q (unsigned int @var{k}, double @var{p})
These functions compute the cumulative distribution functions
@math{P(k)}, @math{Q(k)} for the geometric distribution with parameter
@var{p}.
@end deftypefun


@page
@node The Hypergeometric Distribution
@section The Hypergeometric Distribution
@cindex hypergeometric random variates
@deftypefun {unsigned int} gsl_ran_hypergeometric (const gsl_rng * @var{r}, unsigned int @var{n1}, unsigned int @var{n2}, unsigned int @var{t})
@cindex Geometric random variates
This function returns a random integer from the hypergeometric
distribution.  The probability distribution for hypergeometric
random variates is,
@tex
\beforedisplay
$$
p(k) =  C(n_1, k) C(n_2, t - k) / C(n_1 + n_2, t)
$$
\afterdisplay
@end tex
@ifinfo

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

@end ifinfo
@noindent
where @math{C(a,b) = a!/(b!(a-b)!)} and 
@c{$t \leq n_1 + n_2$}
@math{t <= n_1 + n_2}.  The domain of @math{k} is 
@c{$\hbox{max}(0,t-n_2), \ldots, \hbox{min}(t,n_1)$} 
@math{max(0,t-n_2), ..., min(t,n_1)}.

If a population contains @math{n_1} elements of ``type 1'' and
@math{n_2} elements of ``type 2'' then the hypergeometric
distribution gives the probability of obtaining @math{k} elements of
``type 1'' in @math{t} samples from the population without
replacement.
@end deftypefun

@deftypefun double gsl_ran_hypergeometric_pdf (unsigned int @var{k}, unsigned int @var{n1}, unsigned int @var{n2}, unsigned int @var{t})
This function computes the probability @math{p(k)} of obtaining @var{k}
from a hypergeometric distribution with paramet