@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2004, 2005, 2006,
@c               2007, 2008, 2009 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Statistics
@chapter Statistics

Octave has support for various statistical methods.  This includes
basic descriptive statistics, statistical tests, random number generation,
and much more.

The functions that analyze data all assume that multidimensional data
is arranged in a matrix where each row is an observation, and each
column is a variable.  So, the matrix defined by

@example
@group
a = [ 0.9, 0.7;
      0.1, 0.1;
      0.5, 0.4 ];
@end group
@end example

@noindent
contains three observations from a two-dimensional distribution.
While this is the default data arrangement, most functions support
different arrangements.

It should be noted that the statistics functions don't test for data
containing NaN, NA, or Inf.  Such values need to be handled explicitly.

@menu
* Descriptive Statistics::
* Basic Statistical Functions:: 
* Statistical Plots:: 
* Tests::                       
* Models::                      
* Distributions::     
* Random Number Generation::          
@end menu

@node Descriptive Statistics
@section Descriptive Statistics

Octave can compute various statistics such as the moments of a data set.

@c ./statistics/base/mean.m
@anchor{doc-mean}
@deftypefn {Function File} {} mean (@var{x}, @var{dim}, @var{opt})
If @var{x} is a vector, compute the mean of the elements of @var{x}
@tex
$$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$
@end tex
@ifnottex

@example
mean (x) = SUM_i x(i) / N
@end example
@end ifnottex
If @var{x} is a matrix, compute the mean for each column and return them
in a row vector.

With the optional argument @var{opt}, the kind of mean computed can be
selected.  The following options are recognized:

@table @code
@item "a"
Compute the (ordinary) arithmetic mean.  This is the default.

@item "g"
Compute the geometric mean.

@item "h"
Compute the harmonic mean.
@end table

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.

Both @var{dim} and @var{opt} are optional.  If both are supplied,
either may appear first.
@end deftypefn


@c ./statistics/base/median.m
@anchor{doc-median}
@deftypefn {Function File} {} median (@var{x}, @var{dim})
If @var{x} is a vector, compute the median value of the elements of
@var{x}.  If the elements of @var{x} are sorted, the median is defined
as
@tex
$$
{\rm median} (x) =
  \cases{x(\lceil N/2\rceil), & $N$ odd;\cr
          (x(N/2)+x(N/2+1))/2, & $N$ even.}
$$
@end tex
@ifnottex

@example
@group
            x(ceil(N/2)),             N odd
median(x) =
            (x(N/2) + x((N/2)+1))/2,  N even
@end group
@end example
@end ifnottex
If @var{x} is a matrix, compute the median value for each
column and return them in a row vector.  If the optional @var{dim}
argument is given, operate along this dimension.
@seealso{@ref{doc-std,,std}, @ref{doc-mean,,mean}}
@end deftypefn


@c ./statistics/base/quantile.m
@anchor{doc-quantile}
@deftypefn {Function File} {@var{q} =} quantile (@var{x}, @var{p})
@deftypefnx {Function File} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim})
@deftypefnx {Function File} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim}, @var{method})
For a sample, @var{x}, calculate the quantiles, @var{q}, corresponding to
the cumulative probability values in @var{p}.  All non-numeric values (NaNs) of
@var{x} are ignored.

If @var{x} is a matrix, compute the quantiles for each column and
return them in a matrix, such that the i-th row of @var{q} contains
the @var{p}(i)th quantiles of each column of @var{x}.

The optional argument @var{dim} determines the dimension along which 
the percentiles are calculated.  If @var{dim} is omitted, and @var{x} is
a vector or matrix, it defaults to 1 (column wise quantiles).  In the 
instance that @var{x} is a N-d array, @var{dim} defaults to the first 
dimension whose size greater than unity.

The methods available to calculate sample quantiles are the nine methods
used by R (http://www.r-project.org/).  The default value is METHOD = 5.

Discontinuous sample quantile methods 1, 2, and 3

@enumerate 1
@item Method 1: Inverse of empirical distribution function.
@item Method 2: Similar to method 1 but with averaging at discontinuities.
@item Method 3: SAS definition: nearest even order statistic.
@end enumerate

Continuous sample quantile methods 4 through 9, where p(k) is the linear
interpolation function respecting each methods' representative cdf.

@enumerate 4
@item Method 4: p(k) = k / n. That is, linear interpolation of the empirical cdf.
@item Method 5: p(k) = (k - 0.5) / n. That is a piecewise linear function where 
the knots are the values midway through the steps of the empirical cdf. 
@item Method 6: p(k) = k / (n + 1).
@item Method 7: p(k) = (k - 1) / (n - 1).
@item Method 8: p(k) = (k - 1/3) / (n + 1/3).  The resulting quantile estimates 
are approximately median-unbiased regardless of the distribution of @var{x}.
@item Method 9: p(k) = (k - 3/8) / (n + 1/4).  The resulting quantile estimates 
are approximately unbiased for the expected order statistics if @var{x} is 
normally distributed.
@end enumerate

Hyndman and Fan (1996) recommend method 8.  Maxima, S, and R
(versions prior to 2.0.0) use 7 as their default.  Minitab and SPSS
use method 6.  @sc{matlab} uses method 5.

References:

@itemize @bullet
@item Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New
S Language.  Wadsworth & Brooks/Cole.

@item Hyndman, R. J. and Fan, Y. (1996) Sample quantiles in
statistical packages, American Statistician, 50, 361--365.

@item R: A Language and Environment for Statistical Computing;
@url{http://cran.r-project.org/doc/manuals/fullrefman.pdf}.
@end itemize
@end deftypefn


@c ./statistics/base/prctile.m
@anchor{doc-prctile}
@deftypefn {Function File} {@var{y} =} prctile (@var{x}, @var{p})
@deftypefnx {Function File} {@var{q} =} prctile (@var{x}, @var{p}, @var{dim})
For a sample @var{x}, compute the quantiles, @var{y}, corresponding
to the cumulative probability values, P, in percent.  All non-numeric
values (NaNs) of X are ignored.

If @var{x} is a matrix, compute the percentiles for each column and
return them in a matrix, such that the i-th row of @var{y} contains the 
@var{p}(i)th percentiles of each column of @var{x}.

The optional argument @var{dim} determines the dimension along which
the percentiles are calculated.  If @var{dim} is omitted, and @var{x} is
a vector or matrix, it defaults to 1 (column wise quantiles).  In the 
instance that @var{x} is a N-d array, @var{dim} defaults to the first 
dimension whose size greater than unity.

@end deftypefn


@c ./statistics/base/meansq.m
@anchor{doc-meansq}
@deftypefn {Function File} {} meansq (@var{x})
@deftypefnx {Function File} {} meansq (@var{x}, @var{dim})
For vector arguments, return the mean square of the values.
For matrix arguments, return a row vector containing the mean square
of each column.  With the optional @var{dim} argument, returns the
mean squared of the values along this dimension.
@end deftypefn


@c ./statistics/base/std.m
@anchor{doc-std}
@deftypefn {Function File} {} std (@var{x})
@deftypefnx {Function File} {} std (@var{x}, @var{opt})
@deftypefnx {Function File} {} std (@var{x}, @var{opt}, @var{dim})
If @var{x} is a vector, compute the standard deviation of the elements
of @var{x}.
@tex
$$
{\rm std} (x) = \sigma (x) = \sqrt{{\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}}
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
@group
std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
@end group
@end example
@end ifnottex
If @var{x} is a matrix, compute the standard deviation for
each column and return them in a row vector.

The argument @var{opt} determines the type of normalization to use.  Valid values
are

@table @asis 
@item 0:
  normalizes with @math{N-1}, provides the square root of best unbiased estimator of 
  the variance [default]
@item 1:
  normalizes with @math{N}, this provides the square root of the second moment around 
  the mean
@end table

The third argument @var{dim} determines the dimension along which the standard
deviation is calculated.
@seealso{@ref{doc-mean,,mean}, @ref{doc-median,,median}}
@end deftypefn


@c ./statistics/base/var.m
@anchor{doc-var}
@deftypefn {Function File} {} var (@var{x})
For vector arguments, return the (real) variance of the values.
For matrix arguments, return a row vector containing the variance for
each column.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis 
@item 0:
Normalizes with @math{N-1}, provides the best unbiased estimator of the
variance [default].
@item 1:
Normalizes with @math{N}, this provides the second moment around the mean.
@end table

The third argument @var{dim} determines the dimension along which the 
variance is calculated.
@end deftypefn


@c ./statistics/base/mode.m
@anchor{doc-mode}
@deftypefn {Function File} {[@var{m}, @var{f}, @var{c}] =} mode (@var{x}, @var{dim})
Count the most frequently appearing value.  @code{mode} counts the 
frequency along the first non-singleton dimension and if two or more
values have the same frequency returns the smallest of the two in
@var{m}.  The dimension along which to count can be specified by the
@var{dim} parameter.

The variable @var{f} counts the frequency of each of the most frequently 
occurring elements.  The cell array @var{c} contains all of the elements
with the maximum frequency .
@end deftypefn


@c ./statistics/base/cov.m
@anchor{doc-cov}
@deftypefn {Function File} {} cov (@var{x}, @var{y})
Compute covariance.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, the (@var{i}, @var{j})-th entry of
@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th
variable in @var{x} and the @var{j}-th variable in @var{y}.
@tex
$$
\sigma_{ij} = {1 \over N-1} \sum_{i=1}^N (x_i - \bar{x})(y_i - \bar{y})
$$
where $\bar{x}$ and $\bar{y}$ are the mean values of $x$ and $y$.
@end tex
If called with one argument, compute @code{cov (@var{x}, @var{x})}.
@end deftypefn


@c ./statistics/base/cor.m
@anchor{doc-cor}
@deftypefn {Function File} {} cor (@var{x}, @var{y})
Compute correlation.

The (@var{i}, @var{j})-th entry of @code{cor (@var{x}, @var{y})} is
the correlation between the @var{i}-th variable in @var{x} and the
@var{j}-th variable in @var{y}.

@tex
$$
{\rm corrcoef}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@ifnottex
@example
corrcoef(x,y) = cov(x,y)/(std(x)*std(y))
@end example
@end ifnottex

For matrices, each row is an observation and each column a variable;
vectors are always observations and may be row or column vectors.

@code{cor (@var{x})} is equivalent to @code{cor (@var{x}, @var{x})}.

Note that the @code{corrcoef} function does the same as @code{cor}.
@end deftypefn


@c ./statistics/base/corrcoef.m
@anchor{doc-corrcoef}
@deftypefn {Function File} {} corrcoef (@var{x}, @var{y})
Compute correlation.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, the (@var{i}, @var{j})-th entry of
@code{corrcoef (@var{x}, @var{y})} is the correlation between the
@var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}.

@tex
$$
{\rm corrcoef}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@ifnottex
@example
corrcoef(x,y) = cov(x,y)/(std(x)*std(y))
@end example
@end ifnottex

If called with one argument, compute @code{corrcoef (@var{x}, @var{x})}.
@end deftypefn


@c ./statistics/base/kurtosis.m
@anchor{doc-kurtosis}
@deftypefn {Function File} {} kurtosis (@var{x}, @var{dim})
If @var{x} is a vector of length @math{N}, return the kurtosis
@tex
$$
 {\rm kurtosis} (x) = {1\over N \sigma(x)^4} \sum_{i=1}^N (x_i-\bar{x})^4 - 3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3
@end example
@end ifnottex

@noindent
of @var{x}.  If @var{x} is a matrix, return the kurtosis over the
first non-singleton dimension.  The optional argument @var{dim}
can be given to force the kurtosis to be given over that 
dimension.
@end deftypefn


@c ./statistics/base/skewness.m
@anchor{doc-skewness}
@deftypefn {Function File} {} skewness (@var{x}, @var{dim})
If @var{x} is a vector of length @math{n}, return the skewness
@tex
$$
{\rm skewness} (x) = {1\over N \sigma(x)^3} \sum_{i=1}^N (x_i-\bar{x})^3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)
@end example
@end ifnottex

@noindent
of @var{x}.  If @var{x} is a matrix, return the skewness along the
first non-singleton dimension of the matrix.  If the optional
@var{dim} argument is given, operate along this dimension.
@end deftypefn


@c ./statistics/base/statistics.m
@anchor{doc-statistics}
@deftypefn {Function File} {} statistics (@var{x})
If @var{x} is a matrix, return a matrix with the minimum, first
quartile, median, third quartile, maximum, mean, standard deviation,
skewness and kurtosis of the columns of @var{x} as its columns.

If @var{x} is a vector, calculate the statistics along the 
non-singleton dimension.
@end deftypefn


@c ./statistics/base/moment.m
@anchor{doc-moment}
@deftypefn {Function File} {} moment (@var{x}, @var{p}, @var{opt}, @var{dim})
If @var{x} is a vector, compute the @var{p}-th moment of @var{x}.

If @var{x} is a matrix, return the row vector containing the
@var{p}-th moment of each column.

With the optional string opt, the kind of moment to be computed can
be specified.  If opt contains @code{"c"} or @code{"a"}, central
and/or absolute moments are returned.  For example,

@example
moment (x, 3, "ac")
@end example

@noindent
computes the third central absolute moment of @var{x}.

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.
@end deftypefn


@node Basic Statistical Functions
@section Basic Statistical Functions

Octave also supports various helpful statistical functions.

@c ./statistics/base/mahalanobis.m
@anchor{doc-mahalanobis}
@deftypefn {Function File} {} mahalanobis (@var{x}, @var{y})
Return the Mahalanobis' D-square distance between the multivariate
samples @var{x} and @var{y}, which must have the same number of
components (columns), but may have a different number of observations
(rows).
@end deftypefn


@c ./statistics/base/center.m
@anchor{doc-center}
@deftypefn {Function File} {} center (@var{x})
@deftypefnx {Function File} {} center (@var{x}, @var{dim})
If @var{x} is a vector, subtract its mean.
If @var{x} is a matrix, do the above for each column.
If the optional argument @var{dim} is given, perform the above
operation along this dimension
@end deftypefn


@c ./statistics/base/studentize.m
@anchor{doc-studentize}
@deftypefn {Function File} {} studentize (@var{x}, @var{dim})
If @var{x} is a vector, subtract its mean and divide by its standard
deviation.

If @var{x} is a matrix, do the above along the first non-singleton
dimension.  If the optional argument @var{dim} is given then operate
along this dimension.
@end deftypefn


@c ./specfun/nchoosek.m
@anchor{doc-nchoosek}
@deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k})

Compute the binomial coefficient or all combinations of @var{n}.
If @var{n} is a scalar then, calculate the binomial coefficient
of @var{n} and @var{k}, defined as

@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
               = {n! \over k! (n-k)!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)       n!
 |   |  = ------------------------- =  ---------
 | k |               k!                k! (n-k)!
 \   /
@end group
@end example
@end ifnottex

If @var{n} is a vector generate all combinations of the elements
of @var{n}, taken @var{k} at a time, one row per combination.  The 
resulting @var{c} has size @code{[nchoosek (length (@var{n}), 
@var{k}), @var{k}]}.

@code{nchoosek} works only for non-negative integer arguments; use
@code{bincoeff} for non-integer scalar arguments and for using vector
arguments to compute many coefficients at once.

@seealso{@ref{doc-bincoeff,,bincoeff}}
@end deftypefn


@c ./statistics/base/histc.m
@anchor{doc-histc}
@deftypefn {Function File} {@var{n} =} histc (@var{y}, @var{edges})
@deftypefnx {Function File} {@var{n} =} histc (@var{y}, @var{edges}, @var{dim})
@deftypefnx {Function File} {[@var{n}, @var{idx}] =} histc (@dots{})
Produce histogram counts.

When @var{y} is a vector, the function counts the number of elements of
@var{y} that fall in the histogram bins defined by @var{edges}.  This must be
a vector of monotonically non-decreasing values that define the edges of the
histogram bins.  So, @code{@var{n} (k)} contains the number of elements in
@var{y} for which @code{@var{edges} (k) <= @var{y} < @var{edges} (k+1)}.
The final element of @var{n} contains the number of elements of @var{y}
that was equal to the last element of @var{edges}.

When @var{y} is a @math{N}-dimensional array, the same operation as above is
repeated along dimension @var{dim}.  If this argument is given, the operation
is performed along the first non-singleton dimension.

If a second output argument is requested an index matrix is also returned.
The @var{idx} matrix has same size as @var{y}.  Each element of @var{idx}
contains the index of the histogram bin in which the corresponding element
of @var{y} was counted.

@seealso{@ref{doc-hist,,hist}}
@end deftypefn


@c ./specfun/perms.m
@anchor{doc-perms}
@deftypefn {Function File} {} perms (@var{v})

Generate all permutations of @var{v}, one row per permutation.  The
result has size @code{factorial (@var{n}) * @var{n}}, where @var{n}
is the length of @var{v}.

As an example, @code{perms([1, 2, 3])} returns the matrix
@example
@group
  1   2   3
  2   1   3
  1   3   2
  2   3   1
  3   1   2
  3   2   1
@end group
@end example
@end deftypefn


@c ./statistics/base/values.m
@anchor{doc-values}
@deftypefn {Function File} {} values (@var{x})
Return the different values in a column vector, arranged in ascending
order.

As an example, @code{values([1, 2, 3, 1])} returns the vector
@code{[1, 2, 3]}.
@end deftypefn


@c ./statistics/base/table.m
@anchor{doc-table}
@deftypefn {Function File} {[@var{t}, @var{l_x}] =} table (@var{x})
@deftypefnx {Function File} {[@var{t}, @var{l_x}, @var{l_y}] =} table (@var{x}, @var{y})
Create a contingency table @var{t} from data vectors.  The @var{l}
vectors are the corresponding levels.

Currently, only 1- and 2-dimensional tables are supported.
@end deftypefn


@c ./statistics/base/spearman.m
@anchor{doc-spearman}
@deftypefn {Function File} {} spearman (@var{x}, @var{y})
Compute Spearman's rank correlation coefficient @var{rho} for each of
the variables specified by the input arguments.

For matrices, each row is an observation and each column a variable;
vectors are always observations and may be row or column vectors.

@code{spearman (@var{x})} is equivalent to @code{spearman (@var{x},
@var{x})}.

For two data vectors @var{x} and @var{y}, Spearman's @var{rho} is the
correlation of the ranks of @var{x} and @var{y}.

If @var{x} and @var{y} are drawn from independent distributions,
@var{rho} has zero mean and variance @code{1 / (n - 1)}, and is
asymptotically normally distributed.
@end deftypefn


@c ./statistics/base/run_count.m
@anchor{doc-run_count}
@deftypefn {Function File} {} run_count (@var{x}, @var{n})
Count the upward runs along the first non-singleton dimension of
@var{x} of length 1, 2, @dots{}, @var{n}-1 and greater than or equal 
to @var{n}.  If the optional argument @var{dim} is given operate
along this dimension
@end deftypefn


@c ./statistics/base/ranks.m
@anchor{doc-ranks}
@deftypefn {Function File} {} ranks (@var{x}, @var{dim})
Return the ranks of @var{x} along the first non-singleton dimension
adjust for ties.  If the optional argument @var{dim} is
given, operate along this dimension.
@end deftypefn


@c ./statistics/base/range.m
@anchor{doc-range}
@deftypefn {Function File} {} range (@var{x})
@deftypefnx {Function File} {} range (@var{x}, @var{dim})
If @var{x} is a vector, return the range, i.e., the difference
between the maximum and the minimum, of the input data.

If @var{x} is a matrix, do the above for each column of @var{x}.

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.
@end deftypefn


@c ./statistics/base/probit.m
@anchor{doc-probit}
@deftypefn {Function File} {} probit (@var{p})
For each component of @var{p}, return the probit (the quantile of the
standard normal distribution) of @var{p}.
@end deftypefn


@c ./statistics/base/logit.m
@anchor{doc-logit}
@deftypefn {Function File} {} logit (@var{p})
For each component of @var{p}, return the logit of @var{p} defined as
@tex
$$
{\rm logit}(p) = \log\Big({p \over 1-p}\Big)
$$
@end tex
@ifnottex
@example
logit(@var{p}) = log (@var{p} / (1-@var{p}))
@end example
@end ifnottex
@end deftypefn


@c ./statistics/base/cloglog.m
@anchor{doc-cloglog}
@deftypefn {Function File} {} cloglog (@var{x})
Return the complementary log-log function of @var{x}, defined as

@tex
$$
{\rm cloglog}(x) = - \log (- \log (x))
$$
@end tex
@ifnottex
@example
cloglog(x) = - log (- log (@var{x}))
@end example
@end ifnottex
@end deftypefn


@c ./statistics/base/kendall.m
@anchor{doc-kendall}
@deftypefn {Function File} {} kendall (@var{x}, @var{y})
Compute Kendall's @var{tau} for each of the variables specified by
the input arguments.

For matrices, each row is an observation and each column a variable;
vectors are always observations and may be row or column vectors.

@code{kendall (@var{x})} is equivalent to @code{kendall (@var{x},
@var{x})}.

For two data vectors @var{x}, @var{y} of common length @var{n},
Kendall's @var{tau} is the correlation of the signs of all rank
differences of @var{x} and @var{y};  i.e., if both @var{x} and
@var{y} have distinct entries, then

@tex
$$ \tau = {1 \over n(n-1)} \sum_{i,j} {\rm sign}(q_i-q_j) {\rm sign}(r_i-r_j) $$
@end tex
@ifnottex
@example
@group
         1    
tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
      n (n-1)   i,j
@end group
@end example
@end ifnottex

@noindent
in which the
@tex
$q_i$ and $r_i$
@end tex
@ifnottex
@var{q}(@var{i}) and @var{r}(@var{i})
@end ifnottex
 are the ranks of
@var{x} and @var{y}, respectively.

If @var{x} and @var{y} are drawn from independent distributions,
Kendall's @var{tau} is asymptotically normal with mean 0 and variance
@tex
${2 (2n+5) \over 9n(n-1)}$.
@end tex
@ifnottex
@code{(2 * (2@var{n}+5)) / (9 * @var{n} * (@var{n}-1))}.
@end ifnottex
@end deftypefn


@c ./statistics/base/iqr.m
@anchor{doc-iqr}
@deftypefn {Function File} {} iqr (@var{x}, @var{dim})
If @var{x} is a vector, return the interquartile range, i.e., the
difference between the upper and lower quartile, of the input data.

If @var{x} is a matrix, do the above for first non-singleton
dimension of @var{x}.  If the option @var{dim} argument is given,
then operate along this dimension.
@end deftypefn


@c ./statistics/base/cut.m
@anchor{doc-cut}
@deftypefn {Function File} {} cut (@var{x}, @var{breaks})
Create categorical data out of numerical or continuous data by
cutting into intervals.

If @var{breaks} is a scalar, the data is cut into that many
equal-width intervals.  If @var{breaks} is a vector of break points,
the category has @code{length (@var{breaks}) - 1} groups.

The returned value is a vector of the same size as @var{x} telling
which group each point in @var{x} belongs to.  Groups are labelled
from 1 to the number of groups; points outside the range of
@var{breaks} are labelled by @code{NaN}.
@end deftypefn


@node Statistical Plots
@section Statistical Plots

@c Should hist be moved to here, or perhaps the qqplot and ppplot
@c functions should be moved to the Plotting Chapter?

Octave can create Quantile Plots (QQ-Plots), and Probability Plots
(PP-Plots).  These are simple graphical tests for determining if a
data set comes from a certain distribution.

Note that Octave can also show histograms of data
using the @code{hist} function as described in
@ref{Two-Dimensional Plots}.

@c ./statistics/base/qqplot.m
@anchor{doc-qqplot}
@deftypefn {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist}, @var{params})
Perform a QQ-plot (quantile plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and G its inverse, and @var{x} a sample vector of length
@var{n}, the QQ-plot graphs ordinate @var{s}(@var{i}) = @var{i}-th
largest element of x versus abscissa @var{q}(@var{i}f) = G((@var{i} -
0.5)/@var{n}).

If the sample comes from F except for a transformation of location
and scale, the pairs will approximately follow a straight line.

The default for @var{dist} is the standard normal distribution.  The
optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, for a quantile plot of the uniform
distribution on [2,4] and @var{x}, use

@example
qqplot (x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_inv}
that calculates the inverse CDF of distribution @var{dist} exists.

If no output arguments are given, the data are plotted directly.
@end deftypefn


@c ./statistics/base/ppplot.m
@anchor{doc-ppplot}
@deftypefn {Function File} {[@var{p}, @var{y}] =} ppplot (@var{x}, @var{dist}, @var{params})
Perform a PP-plot (probability plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and @var{x} a sample vector of length @var{n}, the
PP-plot graphs ordinate @var{y}(@var{i}) = F (@var{i}-th largest
element of @var{x}) versus abscissa @var{p}(@var{i}) = (@var{i} -
0.5)/@var{n}.  If the sample comes from F, the pairs will
approximately follow a straight line.

The default for @var{dist} is the standard normal distribution.  The
optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, for a probability plot of the uniform
distribution on [2,4] and @var{x}, use

@example
ppplot (x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_cdf}
that calculates the CDF of distribution @var{dist} exists.

If no output arguments are given, the data are plotted directly.
@end deftypefn


@node Tests
@section Tests

Octave can perform several different statistical tests.  The following
table summarizes the available tests.

@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & # \vrule width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& @strong{Hypothesis} && {\bf Test Functions} &\cr
\noalign{\hrule}
& Equal mean values && anova, hotelling\_test2, t\_test\_2, &\cr
&                   && welch\_test, wilcoxon\_test, z\_test\_2 &\cr
& Equal medians && kruskal\_wallis\_test, sign\_test &\cr
& Equal variances && bartlett\_test, manova, var\_test &\cr
& Equal distributions && chisquare\_test\_homogeneity, &\cr
&                     && kolmogorov\_smirnov\_test\_2, u\_test &\cr
& Equal marginal frequencies && mcnemar\_test &\cr
& Equal success probabilities && prop\_test\_2 &\cr
& Independent observations && chisquare\_test\_independence, &\cr
&                          && run\_test &\cr
& Uncorrelated observations && cor\_test &\cr
& Given mean value && hotelling\_test, t\_test, z\_test &\cr
& Observations from distribution && kolmogorov\_smirnov\_test &\cr
& Regression && f\_test\_regression, t\_test\_regression &\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@ifnottex
@multitable @columnfractions .4 .5
@item @strong{Hypothesis}
  @tab @strong{Test Functions}
@item Equal mean values
  @tab @code{anova}, @code{hotelling_test2}, @code{t_test_2},
       @code{welch_test}, @code{wilcoxon_test}, @code{z_test_2}
@item Equal medians
  @tab @code{kruskal_wallis_test}, @code{sign_test}
@item Equal variances
  @tab @code{bartlett_test}, @code{manova}, @code{var_test}
@item Equal distributions
  @tab @code{chisquare_test_homogeneity}, @code{kolmogorov_smirnov_test_2},
       @code{u_test}
@item Equal marginal frequencies
  @tab @code{mcnemar_test}
@item Equal success probabilities
  @tab @code{prop_test_2}
@item Independent observations
  @tab @code{chisquare_test_independence}, @code{run_test}
@item Uncorrelated observations
  @tab @code{cor_test}
@item Given mean value
  @tab @code{hotelling_test}, @code{t_test}, @code{z_test}
@item Observations from given distribution
  @tab @code{kolmogorov_smirnov_test}
@item Regression
  @tab @code{f_test_regression}, @code{t_test_regression}
@end multitable
@end ifnottex

The tests return a p-value that describes the outcome of the test.
Assuming that the test hypothesis is true, the p-value is the probability
of obtaining a worse result than the observed one.  So large p-values
corresponds to a successful test.  Usually a test hypothesis is accepted
if the p-value exceeds @math{0.05}.

@c ./statistics/tests/anova.m
@anchor{doc-anova}
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_b}, @var{df_w}] =} anova (@var{y}, @var{g})
Perform a one-way analysis of variance (ANOVA).  The goal is to test
whether the population means of data taken from @var{k} different
groups are all equal.

Data may be given in a single vector @var{y} with groups specified by
a corresponding vector of group labels @var{g} (e.g., numbers from 1
to @var{k}).  This is the general form which does not impose any
restriction on the number of data in each group or the group labels.

If @var{y} is a matrix and @var{g} is omitted, each column of @var{y}
is treated as a group.  This form is only appropriate for balanced
ANOVA in which the numbers of samples from each group are all equal.

Under the null of constant means, the statistic @var{f} follows an F
distribution with @var{df_b} and @var{df_w} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is
returned in @var{pval}.

If no output argument is given, the standard one-way ANOVA table is
printed.
@end deftypefn


@c ./statistics/tests/bartlett_test.m
@anchor{doc-bartlett_test}
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} bartlett_test (@var{x1}, @dots{}) 
Perform a Bartlett test for the homogeneity of variances in the data
vectors @var{x1}, @var{x2}, @dots{}, @var{xk}, where @var{k} > 1.

Under the null of equal variances, the test statistic @var{chisq}
approximately follows a chi-square distribution with @var{df} degrees of
freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/chisquare_test_homogeneity.m
@anchor{doc-chisquare_test_homogeneity}
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_homogeneity (@var{x}, @var{y}, @var{c})
Given two samples @var{x} and @var{y}, perform a chisquare test for
homogeneity of the null hypothesis that @var{x} and @var{y} come from
the same distribution, based on the partition induced by the
(strictly increasing) entries of @var{c}.

For large samples, the test statistic @var{chisq} approximately follows a
chisquare distribution with @var{df} = @code{length (@var{c})}
degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/chisquare_test_independence.m
@anchor{doc-chisquare_test_independence}
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_independence (@var{x})
Perform a chi-square test for independence based on the contingency
table @var{x}.  Under the null hypothesis of independence,
@var{chisq} approximately has a chi-square distribution with
@var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at chisq) of the
test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/cor_test.m
@anchor{doc-cor_test}
@deftypefn {Function File} {} cor_test (@var{x}, @var{y}, @var{alt}, @var{method})
Test whether two samples @var{x} and @var{y} come from uncorrelated
populations.

The optional argument string @var{alt} describes the alternative
hypothesis, and can be @code{"!="} or @code{"<>"} (non-zero),
@code{">"} (greater than 0), or @code{"<"} (less than 0).  The
default is the two-sided case.

The optional argument string @var{method} specifies on which
correlation coefficient the test should be based.  If @var{method} is
@code{"pearson"} (default), the (usual) Pearson's product moment
correlation coefficient is used.  In this case, the data should come
from a bivariate normal distribution.  Otherwise, the other two
methods offer nonparametric alternatives.  If @var{method} is
@code{"kendall"}, then Kendall's rank correlation tau is used.  If
@var{method} is @code{"spearman"}, then Spearman's rank correlation
rho is used.  Only the first character is necessary.

The output is a structure with the following elements:

@table @var
@item pval
The p-value of the test.
@item stat
The value of the test statistic.
@item dist
The distribution of the test statistic.
@item params
The parameters of the null distribution of the test statistic.
@item alternative
The alternative hypothesis.
@item method
The method used for testing.
@end table

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/f_test_regression.m
@anchor{doc-f_test_regression}
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} f_test_regression (@var{y}, @var{x}, @var{rr}, @var{r})
Perform an F test for the null hypothesis rr * b = r in a classical
normal regression model y = X * b + e.

Under the null, the test statistic @var{f} follows an F distribution
with @var{df_num} and @var{df_den} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is
returned in @var{pval}.

If not given explicitly, @var{r} = 0.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/hotelling_test.m
@anchor{doc-hotelling_test}
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test (@var{x}, @var{m})
For a sample @var{x} from a multivariate normal distribution with unknown
mean and covariance matrix, test the null hypothesis that @code{mean
(@var{x}) == @var{m}}.

Hotelling's @math{T^2} is returned in @var{tsq}.  Under the null,
@math{(n-p) T^2 / (p(n-1))} has an F distribution with @math{p} and
@math{n-p} degrees of freedom, where @math{n} and @math{p} are the
numbers of samples and variables, respectively.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/hotelling_test_2.m
@anchor{doc-hotelling_test_2}
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test_2 (@var{x}, @var{y})
For two samples @var{x} from multivariate normal distributions with
the same number of variables (columns), unknown means and unknown
equal covariance matrices, test the null hypothesis @code{mean
(@var{x}) == mean (@var{y})}.

Hotelling's two-sample @math{T^2} is returned in @var{tsq}.  Under the null,

@tex
$$
{n_x+n_y-p-1) T^2 \over p(n_x+n_y-2)}
$$
@end tex
@ifnottex
@example
(n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))
@end example
@end ifnottex

@noindent
has an F distribution with @math{p} and @math{n_x+n_y-p-1} degrees of
freedom, where @math{n_x} and @math{n_y} are the sample sizes and
@math{p} is the number of variables.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/kolmogorov_smirnov_test.m
@anchor{doc-kolmogorov_smirnov_test}
@deftypefn {Function File} {[@var{pval}, @var{ks}] =} kolmogorov_smirnov_test (@var{x}, @var{dist}, @var{params}, @var{alt})
Perform a Kolmogorov-Smirnov test of the null hypothesis that the
sample @var{x} comes from the (continuous) distribution dist.  I.e.,
if F and G are the CDFs corresponding to the sample and dist,
respectively, then the null is that F == G.

The optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, to test whether a sample @var{x} comes from
a uniform distribution on [2,4], use

@example
kolmogorov_smirnov_test(x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_cdf}
that calculates the CDF of distribution @var{dist} exists.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative F
!= G.  In this case, the test statistic @var{ks} follows a two-sided
Kolmogorov-Smirnov distribution.  If @var{alt} is @code{">"}, the
one-sided alternative F > G is considered.  Similarly for @code{"<"},
the one-sided alternative F > G is considered.  In this case, the
test statistic @var{ks} has a one-sided Kolmogorov-Smirnov
distribution.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/kolmogorov_smirnov_test_2.m
@anchor{doc-kolmogorov_smirnov_test_2}
@deftypefn {Function File} {[@var{pval}, @var{ks}, @var{d}] =} kolmogorov_smirnov_test_2 (@var{x}, @var{y}, @var{alt})
Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis
that the samples @var{x} and @var{y} come from the same (continuous)
distribution.  I.e., if F and G are the CDFs corresponding to the
@var{x} and @var{y} samples, respectively, then the null is that F ==
G.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative F
!= G.  In this case, the test statistic @var{ks} follows a two-sided
Kolmogorov-Smirnov distribution.  If @var{alt} is @code{">"}, the
one-sided alternative F > G is considered.  Similarly for @code{"<"},
the one-sided alternative F < G is considered.  In this case, the
test statistic @var{ks} has a one-sided Kolmogorov-Smirnov
distribution.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

The third returned value, @var{d}, is the test statistic, the maximum
vertical distance between the two cumulative distribution functions.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/kruskal_wallis_test.m
@anchor{doc-kruskal_wallis_test}
@deftypefn {Function File} {[@var{pval}, @var{k}, @var{df}] =} kruskal_wallis_test (@var{x1}, @dots{})
Perform a Kruskal-Wallis one-factor "analysis of variance".

Suppose a variable is observed for @var{k} > 1 different groups, and
let @var{x1}, @dots{}, @var{xk} be the corresponding data vectors.

Under the null hypothesis that the ranks in the pooled sample are not
affected by the group memberships, the test statistic @var{k} is
approximately chi-square with @var{df} = @var{k} - 1 degrees of
freedom.

If the data contains ties (some value appears more than once)
@var{k} is divided by

1 - @var{sum_ties} / (@var{n}^3 - @var{n})

where @var{sum_ties} is the sum of @var{t}^2 - @var{t} over each group
of ties where @var{t} is the number of ties in the group and @var{n}
is the total number of values in the input data.  For more info on
this adjustment see "Use of Ranks in One-Criterion Variance Analysis"
in Journal of the American Statistical Association, Vol. 47,
No. 260 (Dec 1952) by William H. Kruskal and W. Allen Wallis.

The p-value (1 minus the CDF of this distribution at @var{k}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/manova.m
@anchor{doc-manova}
@deftypefn {Function File} {} manova (@var{y}, @var{g})
Perform a one-way multivariate analysis of variance (MANOVA).  The
goal is to test whether the p-dimensional population means of data
taken from @var{k} different groups are all equal.  All data are
assumed drawn independently from p-dimensional normal distributions
with the same covariance matrix.

The data matrix is given by @var{y}.  As usual, rows are observations
and columns are variables.  The vector @var{g} specifies the
corresponding group labels (e.g., numbers from 1 to @var{k}).

The LR test statistic (Wilks' Lambda) and approximate p-values are
computed and displayed.
@end deftypefn


@c ./statistics/tests/mcnemar_test.m
@anchor{doc-mcnemar_test}
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} mcnemar_test (@var{x})
For a square contingency table @var{x} of data cross-classified on
the row and column variables, McNemar's test can be used for testing
the null hypothesis of symmetry of the classification probabilities.

Under the null, @var{chisq} is approximately distributed as chisquare
with @var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/prop_test_2.m
@anchor{doc-prop_test_2}
@deftypefn {Function File} {[@var{pval}, @var{z}] =} prop_test_2 (@var{x1}, @var{n1}, @var{x2}, @var{n2}, @var{alt})
If @var{x1} and @var{n1} are the counts of successes and trials in
one sample, and @var{x2} and @var{n2} those in a second one, test the
null hypothesis that the success probabilities @var{p1} and @var{p2}
are the same.  Under the null, the test statistic @var{z}
approximately follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@var{p1} != @var{p2}.  If @var{alt} is @code{">"}, the one-sided
alternative @var{p1} > @var{p2} is used.  Similarly for @code{"<"},
the one-sided alternative @var{p1} < @var{p2} is used.
The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/run_test.m
@anchor{doc-run_test}
@deftypefn {Function File} {[@var{pval}, @var{chisq}] =} run_test (@var{x})
Perform a chi-square test with 6 degrees of freedom based on the
upward runs in the columns of @var{x}.  Can be used to test whether
@var{x} contains independent data.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn


@c ./statistics/tests/sign_test.m
@anchor{doc-sign_test}
@deftypefn {Function File} {[@var{pval}, @var{b}, @var{n}] =} sign_test (@var{x}, @var{y}, @var{alt})
For two matched-pair samples @var{x} and @var{y}, perform a sign test
of the null hypothesis PROB (@var{x} > @var{y}) == PROB (@var{x} <
@var{y}) == 1/2.  Under the null, the test statistic @var{b} roughly
follows a binomial distribution with parameters @code{@var{n} = sum
(@var{x} != @var{y})} and @var{p} = 1/2.

With the optional argument @code{alt}, the alternative of interest
can be selected.  If @var{alt} is @code{"!="} or @code{"<>"}, the
null hypothesis is tested against the two-sided alternative PROB
(@var{x} < @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 ("x is
stochastically greater than y") is considered.  Similarly for
@code{"<"}, the one-sided alternative PROB (@var{x} > @var{y}) < 1/2
("x is stochastically less than y") is considered.  The default is
the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/t_test.m
@anchor{doc-t_test}
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test (@var{x}, @var{m}, @var{alt})
For a sample @var{x} from a normal distribution with unknown mean and
variance, perform a t-test of the null hypothesis @code{mean
(@var{x}) == @var{m}}.  Under the null, the test statistic @var{t}
follows a Student distribution with @code{@var{df} = length (@var{x})
- 1} degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @var{"<"}, the one-sided alternative @code{mean
(@var{x}) < @var{m}} is considered.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/t_test_2.m
@anchor{doc-t_test_2}
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_2 (@var{x}, @var{y}, @var{alt})
For two samples x and y from normal distributions with unknown means
and unknown equal variances, perform a two-sample t-test of the null
hypothesis of equal means.  Under the null, the test statistic
@var{t} follows a Student distribution with @var{df} degrees of
freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If @var{alt} is @code{">"},
the one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is
used.  Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < mean (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/t_test_regression.m
@anchor{doc-t_test_regression}
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_regression (@var{y}, @var{x}, @var{rr}, @var{r}, @var{alt})
Perform an t test for the null hypothesis @code{@var{rr} * @var{b} =
@var{r}} in a classical normal regression model @code{@var{y} =
@var{x} * @var{b} + @var{e}}.  Under the null, the test statistic @var{t}
follows a @var{t} distribution with @var{df} degrees of freedom.

If @var{r} is omitted, a value of 0 is assumed.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{@var{rr} * @var{b} != @var{r}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{@var{rr} * @var{b} > @var{r}} is used.
Similarly for @var{"<"}, the one-sided alternative @code{@var{rr} *
@var{b} < @var{r}} is used.  The default is the two-sided case. 

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/u_test.m
@anchor{doc-u_test}
@deftypefn {Function File} {[@var{pval}, @var{z}] =} u_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y}, perform a Mann-Whitney U-test of
the null hypothesis PROB (@var{x} > @var{y}) == 1/2 == PROB (@var{x}
< @var{y}).  Under the null, the test statistic @var{z} approximately
follows a standard normal distribution.  Note that this test is
equivalent to the Wilcoxon rank-sum test.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 is considered.
Similarly for @code{"<"}, the one-sided alternative PROB (@var{x} >
@var{y}) < 1/2 is considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/var_test.m
@anchor{doc-var_test}
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} var_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and unknown variances, perform an F-test of the null
hypothesis of equal variances.  Under the null, the test statistic
@var{f} follows an F-distribution with @var{df_num} and @var{df_den}
degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{var (@var{x}) != var (@var{y})}.  If @var{alt} is @code{">"},
the one-sided alternative @code{var (@var{x}) > var (@var{y})} is
used.  Similarly for "<", the one-sided alternative @code{var
(@var{x}) > var (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/welch_test.m
@anchor{doc-welch_test}
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} welch_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and unknown and not necessarily equal variances,
perform a Welch test of the null hypothesis of equal means.
Under the null, the test statistic @var{t} approximately follows a
Student distribution with @var{df} degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative mean(x) > @var{m} is considered.  Similarly for
@code{"<"}, the one-sided alternative mean(x) < @var{m} is
considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/wilcoxon_test.m
@anchor{doc-wilcoxon_test}
@deftypefn {Function File} {[@var{pval}, @var{z}] =} wilcoxon_test (@var{x}, @var{y}, @var{alt})
For two matched-pair sample vectors @var{x} and @var{y}, perform a
Wilcoxon signed-rank test of the null hypothesis PROB (@var{x} >
@var{y}) == 1/2.  Under the null, the test statistic @var{z}
approximately follows a standard normal distribution when @var{n} > 25.

@strong{Warning}: This function assumes a normal distribution for @var{z}
and thus is invalid for @var{n} <= 25.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If alt is @code{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 is considered.  Similarly
for @code{"<"}, the one-sided alternative PROB (@var{x} > @var{y}) <
1/2 is considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn


@c ./statistics/tests/z_test.m
@anchor{doc-z_test}
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test (@var{x}, @var{m}, @var{v}, @var{alt})
Perform a Z-test of the null hypothesis @code{mean (@var{x}) ==
@var{m}} for a sample @var{x} from a normal distribution with unknown
mean and known variance @var{v}.  Under the null, the test statistic
@var{z} follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < @var{m}} is considered.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed
along with some information.
@end deftypefn


@c ./statistics/tests/z_test_2.m
@anchor{doc-z_test_2}
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test_2 (@var{x}, @var{y}, @var{v_x}, @var{v_y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and known variances @var{v_x} and @var{v_y}, perform a
Z-test of the hypothesis of equal means.  Under the null, the test
statistic @var{z} follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If alt is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is used.
Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < mean (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed
along with some information.
@end deftypefn


@node Models
@section Models

@c ./statistics/models/logistic_regression.m
@anchor{doc-logistic_regression}
@deftypefn {Function File} {[@var{theta}, @var{beta}, @var{dev}, @var{dl}, @var{d2l}, @var{p}] =} logistic_regression (@var{y}, @var{x}, @var{print}, @var{theta}, @var{beta})
Perform ordinal logistic regression.

Suppose @var{y} takes values in @var{k} ordered categories, and let
@code{gamma_i (@var{x})} be the cumulative probability that @var{y}
falls in one of the first @var{i} categories given the covariate
@var{x}.  Then

@example
[theta, beta] = logistic_regression (y, x)
@end example

@noindent
fits the model

@example
logit (gamma_i (x)) = theta_i - beta' * x,   i = 1 @dots{} k-1
@end example

The number of ordinal categories, @var{k}, is taken to be the number
of distinct values of @code{round (@var{y})}.  If @var{k} equals 2,
@var{y} is binary and the model is ordinary logistic regression.  The
matrix @var{x} is assumed to have full column rank.

Given @var{y} only, @code{theta = logistic_regression (y)}
fits the model with baseline logit odds only.

The full form is

@example
@group
[theta, beta, dev, dl, d2l, gamma]
   = logistic_regression (y, x, print, theta, beta)
@end group
@end example

@noindent
in which all output arguments and all input arguments except @var{y}
are optional.

Setting @var{print} to 1 requests summary information about the fitted
model to be displayed.  Setting @var{print} to 2 requests information
about convergence at each iteration.  Other values request no
information to be displayed.  The input arguments @var{theta} and
@var{beta} give initial estimates for @var{theta} and @var{beta}.

The returned value @var{dev} holds minus twice the log-likelihood.

The returned values @var{dl} and @var{d2l} are the vector of first
and the matrix of second derivatives of the log-likelihood with
respect to @var{theta} and @var{beta}.

@var{p} holds estimates for the conditional distribution of @var{y}
given @var{x}.
@end deftypefn


@node Distributions
@section Distributions

Octave has functions for computing the Probability Density Function
(PDF), the Cumulative Distribution function (CDF), and the quantile
(the inverse of the CDF) of a large number of distributions.

The following table summarizes the supported distributions (in 
alphabetical order).

@c Do the table explicitly in TeX if possible to get a better layout.
@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & \vrule # & # \hfil & \vrule # & # \hfil &
# \vrule width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& {\bf Distribution} && {\bf PDF}      && {\bf CDF}     && {\bf Quantile}&\cr
\noalign{\hrule}
&Beta         && betapdf        && betacdf       && betainv&\cr
&Binomial     && binopdf        && binocdf       && binoinv&\cr
&Cauchy       && cauchy\_pdf    && cauchy\_cdf   && cauchy\_inv&\cr
&Chi-Square   && chi2pdf        && chi2cdf       && chi2inv&\cr
&Univariate Discrete       && discrete\_pdf  && discrete\_cdf && discrete\_inv&\cr
&Empirical    && empirical\_pdf  && empirical\_cdf && empirical\_inv&\cr
&Exponential  && exppdf         && expcdf        && expinv&\cr
&F            && fpdf           && fcdf          && finv&\cr
&Gamma        && gampdf         && gamcdf        && gaminv&\cr
&Geometric    && geopdf         && geocdf        && geoinv&\cr
&Hypergeometric            && hygepdf      && hygecdf       && hygeinv&\cr
&Kolmogorov Smirnov && {\it Not Available} && kolmogorov\_&& {\it Not Available}&\cr
&             &&                && smirnov\_cdf &&&\cr
&Laplace      && laplace\_pdf    && laplace\_cdf   && laplace\_inv&\cr
&Logistic     && logistic\_pdf   && logistic\_cdf  && logistic\_inv&\cr
&Log-Normal   && lognpdf        && logncdf       && logninv&\cr
&Pascal       && nbinpdf        && nbincdf       && nbininv&\cr
&Univariate Normal && normpdf   && normcdf       && norminv&\cr
&Poisson      && poisspdf       && poisscdf      && poissinv&\cr
&t (Student)  && tpdf           && tcdf          && tinv&\cr
&Univariate Discrete && unidpdf && unidcdf       && unidinv&\cr
&Uniform      && unifpdf        && unifcdf       && unifinv&\cr
&Weibull      && wblpdf         && wblcdf        && wblinv&\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@ifnottex
@multitable @columnfractions .31 .23 .23 .23
@item @strong{Distribution}
  @tab @strong{PDF}
  @tab @strong{CDF}
  @tab @strong{Quantile}
@item Beta Distribution
  @tab @code{betapdf}
  @tab @code{betacdf}
  @tab @code{betainv}
@item Binomial Distribution
  @tab @code{binopdf}
  @tab @code{binocdf}
  @tab @code{binoinv}
@item Cauchy Distribution
  @tab @code{cauchy_pdf}
  @tab @code{cauchy_cdf}
  @tab @code{cauchy_inv}
@item Chi-Square Distribution
  @tab @code{chi2pdf}
  @tab @code{chi2cdf}
  @tab @code{chi2inv}
@item Univariate Discrete Distribution
  @tab @code{discrete_pdf}
  @tab @code{discrete_cdf}
  @tab @code{discrete_inv}
@item Empirical Distribution
  @tab @code{empirical_pdf}
  @tab @code{empirical_cdf}
  @tab @code{empirical_inv}
@item Exponential Distribution
  @tab @code{exppdf}
  @tab @code{expcdf}
  @tab @code{expinv}
@item F Distribution
  @tab @code{fpdf}
  @tab @code{fcdf}
  @tab @code{finv}
@item Gamma Distribution
  @tab @code{gampdf}
  @tab @code{gamcdf}
  @tab @code{gaminv}
@item Geometric Distribution
  @tab @code{geopdf}
  @tab @code{geocdf}
  @tab @code{geoinv}
@item Hypergeometric Distribution
  @tab @code{hygepdf}
  @tab @code{hygecdf}
  @tab @code{hygeinv}
@item Kolmogorov Smirnov Distribution
  @tab @emph{Not Available}
  @tab @code{kolmogorov_smirnov_cdf}
  @tab @emph{Not Available}
@item Laplace Distribution
  @tab @code{laplace_pdf}
  @tab @code{laplace_cdf}
  @tab @code{laplace_inv}
@item Logistic Distribution
  @tab @code{logistic_pdf}
  @tab @code{logistic_cdf}
  @tab @code{logistic_inv}
@item Log-Normal Distribution
  @tab @code{lognpdf}
  @tab @code{logncdf}
  @tab @code{logninv}
@item Pascal Distribution
  @tab @code{nbinpdf}
  @tab @code{nbincdf}
  @tab @code{nbininv}
@item Univariate Normal Distribution
  @tab @code{normpdf}
  @tab @code{normcdf}
  @tab @code{norminv}
@item Poisson Distribution
  @tab @code{poisspdf}
  @tab @code{poisscdf}
  @tab @code{poissinv}
@item t (Student) Distribution
  @tab @code{tpdf}
  @tab @code{tcdf}
  @tab @code{tinv}
@item Univariate Discrete Distribution
  @tab @code{unidpdf}
  @tab @code{unidcdf}
  @tab @code{unidinv}
@item Uniform Distribution
  @tab @code{unifpdf}
  @tab @code{unifcdf}
  @tab @code{unifinv}
@item Weibull Distribution
  @tab @code{wblpdf}
  @tab @code{wblcdf}
  @tab @code{wblinv}
@end multitable
@end ifnottex

@c ./statistics/distributions/betacdf.m
@anchor{doc-betacdf}
@deftypefn {Function File} {} betacdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the CDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}, i.e.,
PROB (beta (@var{a}, @var{b}) <= @var{x}).
@end deftypefn


@c ./statistics/distributions/betainv.m
@anchor{doc-betainv}
@deftypefn {Function File} {} betainv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Beta distribution with parameters @var{a}
and @var{b}.
@end deftypefn


@c ./statistics/distributions/betapdf.m
@anchor{doc-betapdf}
@deftypefn {Function File} {} betapdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the PDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}.
@end deftypefn


@c ./statistics/distributions/binocdf.m
@anchor{doc-binocdf}
@deftypefn {Function File} {} binocdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn


@c ./statistics/distributions/binoinv.m
@anchor{doc-binoinv}
@deftypefn {Function File} {} binoinv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn


@c ./statistics/distributions/binopdf.m
@anchor{doc-binopdf}
@deftypefn {Function File} {} binopdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the binomial distribution with parameters @var{n}
and @var{p}.
@end deftypefn


@c ./statistics/distributions/cauchy_cdf.m
@anchor{doc-cauchy_cdf}
@deftypefn {Function File} {} cauchy_cdf (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Cauchy distribution with location
parameter @var{lambda} and scale parameter @var{sigma}.  Default
values are @var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn


@c ./statistics/distributions/cauchy_inv.m
@anchor{doc-cauchy_inv}
@deftypefn {Function File} {} cauchy_inv (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the Cauchy distribution with location parameter
@var{lambda} and scale parameter @var{sigma}.  Default values are
@var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn


@c ./statistics/distributions/cauchy_pdf.m
@anchor{doc-cauchy_pdf}
@deftypefn {Function File} {} cauchy_pdf (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Cauchy distribution with location parameter
@var{lambda} and scale parameter @var{sigma} > 0.  Default values are
@var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn


@c ./statistics/distributions/chi2cdf.m
@anchor{doc-chi2cdf}
@deftypefn {Function File} {} chi2cdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the chisquare distribution with @var{n}
degrees of freedom.
@end deftypefn


@c ./statistics/distributions/chi2inv.m
@anchor{doc-chi2inv}
@deftypefn {Function File} {} chi2inv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the chisquare distribution with @var{n} degrees of
freedom.
@end deftypefn


@c ./statistics/distributions/chi2pdf.m
@anchor{doc-chi2pdf}
@deftypefn {Function File} {} chisquare_pdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the chisquare distribution with @var{n} degrees
of freedom.
@end deftypefn


@c ./statistics/distributions/discrete_cdf.m
@anchor{doc-discrete_cdf}
@deftypefn {Function File} {} discrete_cdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of a univariate discrete distribution which
assumes the values in @var{v} with probabilities @var{p}.
@end deftypefn


@c ./statistics/distributions/discrete_inv.m
@anchor{doc-discrete_inv}
@deftypefn {Function File} {} discrete_inv (@var{x}, @var{v}, @var{p})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the univariate distribution which assumes the
values in @var{v} with probabilities @var{p}.
@end deftypefn


@c ./statistics/distributions/discrete_pdf.m
@anchor{doc-discrete_pdf}
@deftypefn {Function File} {} discrete_pdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of a univariate discrete distribution which assumes
the values in @var{v} with probabilities @var{p}.
@end deftypefn


@c ./statistics/distributions/empirical_cdf.m
@anchor{doc-empirical_cdf}
@deftypefn {Function File} {} empirical_cdf (@var{x}, @var{data})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the empirical distribution obtained from
the univariate sample @var{data}.
@end deftypefn


@c ./statistics/distributions/empirical_inv.m
@anchor{doc-empirical_inv}
@deftypefn {Function File} {} empirical_inv (@var{x}, @var{data})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn


@c ./statistics/distributions/empirical_pdf.m
@anchor{doc-empirical_pdf}
@deftypefn {Function File} {} empirical_pdf (@var{x}, @var{data})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn


@c ./statistics/distributions/expcdf.m
@anchor{doc-expcdf}
@deftypefn {Function File} {} expcdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the exponential distribution with
mean @var{lambda}.

The arguments can be of common size or scalar.
@end deftypefn


@c ./statistics/distributions/expinv.m
@anchor{doc-expinv}
@deftypefn {Function File} {} expinv (@var{x}, @var{lambda})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the exponential distribution with mean
@var{lambda}.
@end deftypefn


@c ./statistics/distributions/exppdf.m
@anchor{doc-exppdf}
@deftypefn {Function File} {} exppdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) of the exponential distribution with mean @var{lambda}.
@end deftypefn


@c ./statistics/distributions/fcdf.m
@anchor{doc-fcdf}
@deftypefn {Function File} {} fcdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the CDF at @var{x} of the F
distribution with @var{m} and @var{n} degrees of freedom, i.e.,
PROB (F (@var{m}, @var{n}) <= @var{x}). 
@end deftypefn


@c ./statistics/distributions/finv.m
@anchor{doc-finv}
@deftypefn {Function File} {} finv (@var{x}, @var{m}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the F distribution with parameters @var{m} and
@var{n}.
@end deftypefn


@c ./statistics/distributions/fpdf.m
@anchor{doc-fpdf}
@deftypefn {Function File} {} fpdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the F distribution with @var{m} and @var{n}
degrees of freedom.
@end deftypefn


@c ./statistics/distributions/gamcdf.m
@anchor{doc-gamcdf}
@deftypefn {Function File} {} gamcdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Gamma distribution with parameters
@var{a} and @var{b}.
@seealso{@ref{doc-gamma,,gamma}, @ref{doc-gammaln,,gammaln}, @ref{doc-gammainc,,gammainc}, @ref{doc-gampdf,,gampdf}, @ref{doc-gaminv,,gaminv}, @ref{doc-gamrnd,,gamrnd}}
@end deftypefn


@c ./statistics/distributions/gaminv.m
@anchor{doc-gaminv}
@deftypefn {Function File} {} gaminv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@seealso{@ref{doc-gamma,,gamma}, @ref{doc-gammaln,,gammaln}, @ref{doc-gammainc,,gammainc}, @ref{doc-gampdf,,gampdf}, @ref{doc-gamcdf,,gamcdf}, @ref{doc-gamrnd,,gamrnd}}
@end deftypefn


@c ./statistics/distributions/gampdf.m
@anchor{doc-gampdf}
@deftypefn {Function File} {} gampdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, return the probability density function
(PDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@seealso{@ref{doc-gamma,,gamma}, @ref{doc-gammaln,,gammaln}, @ref{doc-gammainc,,gammainc}, @ref{doc-gamcdf,,gamcdf}, @ref{doc-gaminv,,gaminv}, @ref{doc-gamrnd,,gamrnd}}
@end deftypefn


@c ./statistics/distributions/geocdf.m
@anchor{doc-geocdf}
@deftypefn {Function File} {} geocdf (@var{x}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn


@c ./statistics/distributions/geoinv.m
@anchor{doc-geoinv}
@deftypefn {Function File} {} geoinv (@var{x}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn


@c ./statistics/distributions/geopdf.m
@anchor{doc-geopdf}
@deftypefn {Function File} {} geopdf (@var{x}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the geometric distribution with parameter @var{p}.
@end deftypefn


@c ./statistics/distributions/hygecdf.m
@anchor{doc-hygecdf}
@deftypefn {Function File} {} hygecdf (@var{x}, @var{t}, @var{m}, @var{n})
Compute the cumulative distribution function (CDF) at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and
@var{n}.  This is the probability of obtaining not more than @var{x}
marked items when randomly drawing a sample of size @var{n} without
replacement from a population of total size @var{t} containing
@var{m} marked items.

The parameters @var{t}, @var{m}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn


@c ./statistics/distributions/hygeinv.m
@anchor{doc-hygeinv}
@deftypefn {Function File} {} hygeinv (@var{x}, @var{t}, @var{m}, @var{n})
For each element of @var{x}, compute the quantile at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and
@var{n}.

The parameters @var{t}, @var{m}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn


@c ./statistics/distributions/hygepdf.m
@anchor{doc-hygepdf}
@deftypefn {Function File} {} hygepdf (@var{x}, @var{t}, @var{m}, @var{n})
Compute the probability density function (PDF) at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and
@var{n}.  This is the probability of obtaining @var{x} marked items
when randomly drawing a sample of size @var{n} without replacement
from a population of total size @var{t} containing @var{m} marked items.

The arguments must be of common size or scalar.
@end deftypefn


@c ./statistics/distributions/kolmogorov_smirnov_cdf.m
@anchor{doc-kolmogorov_smirnov_cdf}
@deftypefn {Function File} {} kolmogorov_smirnov_cdf (@var{x}, @var{tol})
Return the CDF at @var{x} of the Kolmogorov-Smirnov distribution,
@tex
$$ Q(x) = \sum_{k=-\infty}^\infty (-1)^k \exp(-2 k^2 x^2) $$
@end tex
@ifnottex
@example
@group
         Inf
Q(x) =   SUM    (-1)^k exp(-2 k^2 x^2)
       k = -Inf
@end group
@end example
@end ifnottex

@noindent
for @var{x} > 0.

The optional parameter @var{tol} specifies the precision up to which
the series should be evaluated;  the default is @var{tol} = @code{eps}.
@end deftypefn


@c ./statistics/distributions/laplace_cdf.m
@anchor{doc-laplace_cdf}
@deftypefn {Function File} {} laplace_cdf (@var{x})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Laplace distribution.
@end deftypefn


@c ./statistics/distributions/laplace_inv.m
@anchor{doc-laplace_inv}
@deftypefn {Function File} {} laplace_inv (@var{x})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the Laplace distribution.
@end deftypefn


@c ./statistics/distributions/laplace_pdf.m
@anchor{doc-laplace_pdf}
@deftypefn {Function File} {} laplace_pdf (@var{x})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Laplace distribution.
@end deftypefn


@c ./statistics/distributions/logistic_cdf.m
@anchor{doc-logistic_cdf}
@deftypefn {Function File} {} logistic_cdf (@var{x})
For each component of @var{x}, compute the CDF at @var{x} of the
logistic distribution.
@end deftypefn


@c ./statistics/distributions/logistic_inv.m
@anchor{doc-logistic_inv}
@deftypefn {Function File} {} logistic_inv (@var{x})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the logistic distribution.
@end deftypefn


@c ./statistics/distributions/logistic_pdf.m
@anchor{doc-logistic_pdf}
@deftypefn {Function File} {} logistic_pdf (@var{x})
For each component of @var{x}, compute the PDF at @var{x} of the
logistic distribution.
@end deftypefn


@c ./statistics/distributions/logncdf.m
@anchor{doc-logncdf}
@deftypefn {Function File} {} logncdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the lognormal distribution with
parameters @var{mu} and @var{sigma}.  If a random variable follows this
distribution, its logarithm is normally distributed with mean
@var{mu} and standard deviation @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn


@c ./statistics/distributions/logninv.m
@anchor{doc-logninv}
@deftypefn {Function File} {} logninv (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the lognormal distribution with parameters @var{mu}
and @var{sigma}.  If a random variable follows this distribution, its
logarithm is normally distributed with mean @code{log (@var{mu})} and
variance @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn


@c ./statistics/distributions/lognpdf.m
@anchor{doc-lognpdf}
@deftypefn {Function File} {} lognpdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the lognormal distribution with parameters
@var{mu} and @var{sigma}.  If a random variable follows this distribution,
its logarithm is normally distributed with mean @var{mu}
and standard deviation @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn


@c ./statistics/distributions/nbincdf.m
@anchor{doc-nbincdf}
@deftypefn {Function File} {} nbincdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at x of the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn


@c ./statistics/distributions/nbininv.m
@anchor{doc-nbininv}
@deftypefn {Function File} {} nbininv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
Pascal (negative binomial) distribution with parameters @var{n} and
@var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn


@c ./statistics/distributions/nbinpdf.m
@anchor{doc-nbinpdf}
@deftypefn {Function File} {} nbinpdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Pascal (negative binomial) distribution with
parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution. 
@end deftypefn


@c ./statistics/distributions/normcdf.m
@anchor{doc-normcdf}
@deftypefn {Function File} {} normcdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the normal distribution with mean
@var{m} and standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn


@c ./statistics/distributions/norminv.m
@anchor{doc-norminv}
@deftypefn {Function File} {} norminv (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn


@c ./statistics/distributions/normpdf.m
@anchor{doc-normpdf}
@deftypefn {Function File} {} normpdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn


@c ./statistics/distributions/poisscdf.m
@anchor{doc-poisscdf}
@deftypefn {Function File} {} poisscdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Poisson distribution with parameter
lambda.
@end deftypefn


@c ./statistics/distributions/poissinv.m
@anchor{doc-poissinv}
@deftypefn {Function File} {} poissinv (@var{x}, @var{lambda})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Poisson distribution with parameter
@var{lambda}.
@end deftypefn


@c ./statistics/distributions/poisspdf.m
@anchor{doc-poisspdf}
@deftypefn {Function File} {} poisspdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the poisson distribution with parameter @var{lambda}.
@end deftypefn


@c ./statistics/distributions/tcdf.m
@anchor{doc-tcdf}
@deftypefn {Function File} {} tcdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the t (Student) distribution with
@var{n} degrees of freedom, i.e., PROB (t(@var{n}) <= @var{x}).
@end deftypefn


@c ./statistics/distributions/tinv.m
@anchor{doc-tinv}
@deftypefn {Function File} {} tinv (@var{x}, @var{n})
For each probability value @var{x}, compute the inverse of the
cumulative distribution function (CDF) of the t (Student)
distribution with degrees of freedom @var{n}.  This function is
analogous to looking in a table for the t-value of a single-tailed
distribution.
@end deftypefn


@c ./statistics/distributions/tpdf.m
@anchor{doc-tpdf}
@deftypefn {Function File} {} tpdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the @var{t} (Student) distribution with @var{n}
degrees of freedom. 
@end deftypefn


@c ./statistics/distributions/unidcdf.m
@anchor{doc-unidcdf}
@deftypefn {Function File} {} unidcdf (@var{x}, @var{v})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of a univariate discrete distribution which
assumes the values in @var{v} with equal probability.
@end deftypefn


@c ./statistics/distributions/unidinv.m
@anchor{doc-unidinv}
@deftypefn {Function File} {} unidinv (@var{x}, @var{v})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the univariate discrete distribution which assumes the
values in @var{v} with equal probability
@end deftypefn


@c ./statistics/distributions/unidpdf.m
@anchor{doc-unidpdf}
@deftypefn {Function File} {} unidpdf (@var{x}, @var{v})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of a univariate discrete distribution which assumes
the values in @var{v} with equal probability.
@end deftypefn


@c ./statistics/distributions/unifcdf.m
@anchor{doc-unifcdf}
@deftypefn {Function File} {} unifcdf (@var{x}, @var{a}, @var{b})
Return the CDF at @var{x} of the uniform distribution on [@var{a},
@var{b}], i.e., PROB (uniform (@var{a}, @var{b}) <= x).

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn


@c ./statistics/distributions/unifinv.m
@anchor{doc-unifinv}
@deftypefn {Function File} {} unifinv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the uniform distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn


@c ./statistics/distributions/unifpdf.m
@anchor{doc-unifpdf}
@deftypefn {Function File} {} unifpdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the PDF at @var{x} of the uniform
distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn


@c ./statistics/distributions/wblcdf.m
@anchor{doc-wblcdf}
@deftypefn {Function File} {} wblcdf (@var{x}, @var{scale}, @var{shape})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}, which is

@tex
$$ 1 - \exp(-(x/shape)^{scale}) $$
for $x\geq 0$.
@end tex
@ifnottex
@example
1 - exp(-(x/shape)^scale)
@end example
for @var{x} >= 0.
@end ifnottex
@end deftypefn


@c ./statistics/distributions/wblinv.m
@anchor{doc-wblinv}
@deftypefn {Function File} {} wblinv (@var{x}, @var{scale}, @var{shape})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}.
@end deftypefn


@c ./statistics/distributions/wblpdf.m
@anchor{doc-wblpdf}
@deftypefn {Function File} {} wblpdf (@var{x}, @var{scale}, @var{shape})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape} which is given by

@tex
$$  scale \cdot shape^{-scale} x^{scale-1} \exp(-(x/shape)^{scale}) $$
@end tex
@ifnottex
@example
   scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)
@end example
@end ifnottex

@noindent
for @var{x} > 0.
@end deftypefn


@node Random Number Generation
@section Random Number Generation

Octave can generate random numbers from a large number of distributions.
The random number generators are based on the random number generators
described in @ref{Special Utility Matrices}.
@c Should rand, randn, rande, randp, and randg be moved to here?

The following table summarizes the available random number generators
(in alphabetical order).

@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & # \vrule width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& {\bf Distribution}                && {\bf Function} &\cr
\noalign{\hrule}
& Beta Distribution                 && betarnd &\cr
& Binomial Distribution             && binornd &\cr
& Cauchy Distribution               && cauchy\_rnd &\cr
& Chi-Square Distribution           && chi2rnd &\cr
& Univariate Discrete Distribution  && discrete\_rnd &\cr
& Empirical Distribution            && empirical\_rnd &\cr
& Exponential Distribution          && exprnd &\cr
& F Distribution                    && frnd &\cr
& Gamma Distribution                && gamrnd &\cr
& Geometric Distribution            && geornd &\cr
& Hypergeometric Distribution       && hygernd &\cr
& Laplace Distribution              && laplace\_rnd &\cr
& Logistic Distribution             && logistic\_rnd &\cr
& Log-Normal Distribution           && lognrnd &\cr
& Pascal Distribution               && nbinrnd &\cr
& Univariate Normal Distribution    && normrnd &\cr
& Poisson Distribution              && poissrnd &\cr
& t (Student) Distribution          && trnd &\cr
& Univariate Discrete Distribution  && unidrnd &\cr
& Uniform Distribution              && unifrnd &\cr
& Weibull Distribution              && wblrnd &\cr
& Wiener Process                    && wienrnd &\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@ifnottex
@multitable @columnfractions .4 .3
@item @strong{Distribution}             @tab @strong{Function}
@item Beta Distribution                 @tab @code{betarnd}
@item Binomial Distribution             @tab @code{binornd}
@item Cauchy Distribution               @tab @code{cauchy_rnd}
@item Chi-Square Distribution           @tab @code{chi2rnd}
@item Univariate Discrete Distribution  @tab @code{discrete_rnd}
@item Empirical Distribution            @tab @code{empirical_rnd}
@item Exponential Distribution          @tab @code{exprnd}
@item F Distribution                    @tab @code{frnd}
@item Gamma Distribution                @tab @code{gamrnd}
@item Geometric Distribution            @tab @code{geornd}
@item Hypergeometric Distribution       @tab @code{hygernd}
@item Laplace Distribution              @tab @code{laplace_rnd}
@item Logistic Distribution             @tab @code{logistic_rnd}
@item Log-Normal Distribution           @tab @code{lognrnd}
@item Pascal Distribution               @tab @code{nbinrnd}
@item Univariate Normal Distribution    @tab @code{normrnd}
@item Poisson Distribution              @tab @code{poissrnd}
@item t (Student) Distribution          @tab @code{trnd}
@item Univariate Discrete Distribution  @tab @code{unidrnd}
@item Uniform Distribution              @tab @code{unifrnd}
@item Weibull Distribution              @tab @code{wblrnd}
@item Wiener Process                    @tab @code{wienrnd}
@end multitable
@end ifnottex

@c ./statistics/distributions/betarnd.m
@anchor{doc-betarnd}
@deftypefn {Function File} {} betarnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of 
random samples from the Beta distribution with parameters @var{a} and
@var{b}.  Both @var{a} and @var{b} must be scalar or of size @var{r}
 by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn


@c ./statistics/distributions/binornd.m
@anchor{doc-binornd}
@deftypefn {Function File} {} binornd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the binomial distribution with parameters @var{n}
and @var{p}.  Both @var{n} and @var{p} must be scalar or of size
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}.
@end deftypefn


@c ./statistics/distributions/cauchy_rnd.m
@anchor{doc-cauchy_rnd}
@deftypefn {Function File} {} cauchy_rnd (@var{lambda}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} cauchy_rnd (@var{lambda}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the Cauchy distribution with parameters @var{lambda} 
and @var{sigma} which must both be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{lambda} and @var{sigma}.
@end deftypefn


@c ./statistics/distributions/chi2rnd.m
@anchor{doc-chi2rnd}
@deftypefn {Function File} {} chi2rnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} chi2rnd (@var{n}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the chisquare distribution with @var{n} degrees 
of freedom.  @var{n} must be a scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn


@c ./statistics/distributions/discrete_rnd.m
@anchor{doc-discrete_rnd}
@deftypefn {Function File} {} discrete_rnd (@var{n}, @var{v}, @var{p})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{sz})
Generate a row vector containing a random sample of size @var{n} from
the univariate distribution which assumes the values in @var{v} with
probabilities @var{p}.  @var{n} must be a scalar.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn


@c ./statistics/distributions/empirical_rnd.m
@anchor{doc-empirical_rnd}
@deftypefn {Function File} {} empirical_rnd (@var{n}, @var{data})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{r}, @var{c})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{sz})
Generate a bootstrap sample of size @var{n} from the empirical
distribution obtained from the univariate sample @var{data}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn


@c ./statistics/distributions/exprnd.m
@anchor{doc-exprnd}
@deftypefn {Function File} {} exprnd (@var{lambda}, @var{r}, @var{c})
@deftypefnx {Function File} {} exprnd (@var{lambda}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
exponential distribution with mean @var{lambda}, which must be a
scalar or of size @var{r} by @var{c}.  Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn


@c ./statistics/distributions/frnd.m
@anchor{doc-frnd}
@deftypefn {Function File} {} frnd (@var{m}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the F
distribution with @var{m} and @var{n} degrees of freedom.  Both
@var{m} and @var{n} must be scalar or of size @var{r} by @var{c}.
If @var{sz} is a vector the random samples are in a matrix of 
size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{n}.
@end deftypefn


@c ./statistics/distributions/gamrnd.m
@anchor{doc-gamrnd}
@deftypefn {Function File} {} gamrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the Gamma distribution with parameters @var{a}
and @var{b}.  Both @var{a} and @var{b} must be scalar or of size 
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@seealso{@ref{doc-gamma,,gamma}, @ref{doc-gammaln,,gammaln}, @ref{doc-gammainc,,gammainc}, @ref{doc-gampdf,,gampdf}, @ref{doc-gamcdf,,gamcdf}, @ref{doc-gaminv,,gaminv}}
@end deftypefn


@c ./statistics/distributions/geornd.m
@anchor{doc-geornd}
@deftypefn {Function File} {} geornd (@var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} geornd (@var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
geometric distribution with parameter @var{p}, which must be a scalar
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn


@c ./statistics/distributions/hygernd.m
@anchor{doc-hygernd}
@deftypefn {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{sz})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n})
Return an @var{r} by @var{c} matrix of random samples from the
hypergeometric distribution with parameters @var{t}, @var{m},
and @var{n}.

The parameters @var{t}, @var{m}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.

The parameter @var{sz} must be scalar or a vector of matrix
dimensions.  If @var{sz} is scalar, then a @var{sz} by @var{sz}
matrix of random samples is generated.
@end deftypefn


@c ./statistics/distributions/laplace_rnd.m
@anchor{doc-laplace_rnd}
@deftypefn {Function File} {} laplace_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} laplace_rnd (@var{sz});
Return an @var{r} by @var{c} matrix of random numbers from the
Laplace distribution.  Or if @var{sz} is a vector, create a matrix of
@var{sz}.
@end deftypefn


@c ./statistics/distributions/logistic_rnd.m
@anchor{doc-logistic_rnd}
@deftypefn {Function File} {} logistic_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} logistic_rnd (@var{sz})
Return an @var{r} by @var{c} matrix of random numbers from the
logistic distribution.  Or if @var{sz} is a vector, create a matrix of
@var{sz}.
@end deftypefn


@c ./statistics/distributions/lognrnd.m
@anchor{doc-lognrnd}
@deftypefn {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
lognormal distribution with parameters @var{mu} and @var{sigma}.  Both
@var{mu} and @var{sigma} must be scalar or of size @var{r} by @var{c}.
Or if @var{sz} is a vector, create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{mu} and @var{sigma}.
@end deftypefn


@c ./statistics/distributions/nbinrnd.m
@anchor{doc-nbinrnd}
@deftypefn {Function File} {} nbinrnd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.
Both @var{n} and @var{p} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}.  Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.
@end deftypefn


@c ./statistics/distributions/normrnd.m
@anchor{doc-normrnd}
@deftypefn {Function File} {} normrnd (@var{m}, @var{s}, @var{r}, @var{c})
@deftypefnx {Function File} {} normrnd (@var{m}, @var{s}, @var{sz})
Return an @var{r} by @var{c}  or @code{size (@var{sz})} matrix of
random samples from the normal distribution with parameters mean @var{m} 
and standard deviation @var{s}.  Both @var{m} and @var{s} must be scalar 
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{s}.
@end deftypefn


@c ./statistics/distributions/poissrnd.m
@anchor{doc-poissrnd}
@deftypefn {Function File} {} poissrnd (@var{lambda}, @var{r}, @var{c})
Return an @var{r} by @var{c} matrix of random samples from the
Poisson distribution with parameter @var{lambda}, which must be a 
scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn


@c ./statistics/distributions/trnd.m
@anchor{doc-trnd}
@deftypefn {Function File} {} trnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} trnd (@var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the t
(Student) distribution with @var{n} degrees of freedom.  @var{n} must
be a scalar or of size @var{r} by @var{c}.  Or if @var{sz} is a
vector create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn


@c ./statistics/distributions/unidrnd.m
@anchor{doc-unidrnd}
@deftypefn {Function File} {} unidrnd (@var{mx});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{v});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{m}, @var{n}, @dots{});
Return random values from discrete uniform distribution, with maximum
value(s) given by the integer @var{mx}, which may be a scalar or
multidimensional array.

If @var{mx} is a scalar, the size of the result is specified by
the vector @var{v}, or by the optional arguments @var{m}, @var{n},
@dots{}.  Otherwise, the size of the result is the same as the size
of @var{mx}.
@end deftypefn


@c ./statistics/distributions/unifrnd.m
@anchor{doc-unifrnd}
@deftypefn {Function File} {} unifrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the uniform distribution on [@var{a}, @var{b}]. 
Both @var{a} and @var{b} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn


@c ./statistics/distributions/wblrnd.m
@anchor{doc-wblrnd}
@deftypefn {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{r}, @var{c})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}.  Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@end deftypefn


@c ./statistics/distributions/wienrnd.m
@anchor{doc-wienrnd}
@deftypefn {Function File} {} wienrnd (@var{t}, @var{d}, @var{n})
Return a simulated realization of the @var{d}-dimensional Wiener Process
on the interval [0, @var{t}].  If @var{d} is omitted, @var{d} = 1 is
used.  The first column of the return matrix contains time, the
remaining columns contain the Wiener process.

The optional parameter @var{n} gives the number of summands used for
simulating the process over an interval of length 1.  If @var{n} is
omitted, @var{n} = 1000 is used.
@end deftypefn


