octave_packages/statistics-1.1.3/random.m

   1 ## Copyright (C) 2007 Soren Hauberg <soren@hauberg.org>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} @var{r} = random(@var{name}, @var{arg1})
  18 ## @deftypefnx{Function File} @var{r} = random(@var{name}, @var{arg1}, @var{arg2})
  19 ## @deftypefnx{Function File} @var{r} = random(@var{name}, @var{arg1}, @var{arg2}, @var{arg3})
  20 ## @deftypefnx{Function File} @var{r} = random(@var{name}, ..., @var{s1}, ...)
  21 ## Generates pseudo-random numbers from a given one-, two-, or three-parameter
  22 ## distribution.
  23 ##
  24 ## The variable @var{name} must be a string that names the distribution from
  25 ## which to sample.  If this distribution is a one-parameter distribution @var{arg1}
  26 ## should be supplied, if it is a two-paramter distribution @var{arg2} must also
  27 ## be supplied, and if it is a three-parameter distribution @var{arg3} must also
  28 ## be present.  Any arguments following the distribution paramters will determine
  29 ## the size of the result.
  30 ##
  31 ## As an example, the following code generates a 10 by 20 matrix containing
  32 ## random numbers from a normal distribution with mean 5 and standard deviation
  33 ## 2.
  34 ## @example
  35 ## R = random("normal", 5, 2, [10, 20]);
  36 ## @end example
  37 ##
  38 ## The variable @var{name} can be one of the following strings
  39 ##
  40 ## @table @asis
  41 ## @item  "beta"
  42 ## @itemx "beta distribution"
  43 ## Samples are drawn from the Beta distribution.
  44 ## @item  "bino"
  45 ## @itemx "binomial"
  46 ## @itemx "binomial distribution"
  47 ## Samples are drawn from the Binomial distribution.
  48 ## @item  "chi2"
  49 ## @itemx "chi-square"
  50 ## @itemx "chi-square distribution"
  51 ## Samples are drawn from the Chi-Square distribution.
  52 ## @item  "exp"
  53 ## @itemx "exponential"
  54 ## @itemx "exponential distribution"
  55 ## Samples are drawn from the Exponential distribution.
  56 ## @item  "f"
  57 ## @itemx "f distribution"
  58 ## Samples are drawn from the F distribution.
  59 ## @item  "gam"
  60 ## @itemx "gamma"
  61 ## @itemx "gamma distribution"
  62 ## Samples are drawn from the Gamma distribution.
  63 ## @item  "geo"
  64 ## @itemx "geometric"
  65 ## @itemx "geometric distribution"
  66 ## Samples are drawn from the Geometric distribution.
  67 ## @item  "hyge"
  68 ## @itemx "hypergeometric"
  69 ## @itemx "hypergeometric distribution"
  70 ## Samples are drawn from the Hypergeometric distribution.
  71 ## @item  "logn"
  72 ## @itemx "lognormal"
  73 ## @itemx "lognormal distribution"
  74 ## Samples are drawn from the Log-Normal distribution.
  75 ## @item  "nbin"
  76 ## @itemx "negative binomial"
  77 ## @itemx "negative binomial distribution"
  78 ## Samples are drawn from the Negative Binomial distribution.
  79 ## @item  "norm"
  80 ## @itemx "normal"
  81 ## @itemx "normal distribution"
  82 ## Samples are drawn from the Normal distribution.
  83 ## @item  "poiss"
  84 ## @itemx "poisson"
  85 ## @itemx "poisson distribution"
  86 ## Samples are drawn from the Poisson distribution.
  87 ## @item  "rayl"
  88 ## @itemx "rayleigh"
  89 ## @itemx "rayleigh distribution"
  90 ## Samples are drawn from the Rayleigh distribution.
  91 ## @item  "t"
  92 ## @itemx "t distribution"
  93 ## Samples are drawn from the T distribution.
  94 ## @item  "unif"
  95 ## @itemx "uniform"
  96 ## @itemx "uniform distribution"
  97 ## Samples are drawn from the Uniform distribution.
  98 ## @item  "unid"
  99 ## @itemx "discrete uniform"
 100 ## @itemx "discrete uniform distribution"
 101 ## Samples are drawn from the Uniform Discrete distribution.
 102 ## @item  "wbl"
 103 ## @itemx "weibull"
 104 ## @itemx "weibull distribution"
 105 ## Samples are drawn from the Weibull distribution.
 106 ## @end table
 107 ## @seealso{rand, betarnd, binornd, chi2rnd, exprnd, frnd, gamrnd, geornd, hygernd,
 108 ## lognrnd, nbinrnd, normrnd, poissrnd, raylrnd, trnd, unifrnd, unidrnd, wblrnd}
 109 ## @end deftypefn
 110
 111 function retval = random(name, varargin)
 112   ## General input checking
 113   if (nargin < 2)
 114     print_usage();
 115   endif
 116   if (!ischar(name))
 117     error("random: first input argument must be a string");
 118   endif
 119
 120   ## Select distribution
 121   switch (lower(name))
 122     case {"beta", "beta distribution"}
 123       retval = betarnd(varargin{:});
 124     case {"bino", "binomial", "binomial distribution"}
 125       retval = binornd(varargin{:});
 126     case {"chi2", "chi-square", "chi-square distribution"}
 127       retval = chi2rnd(varargin{:});
 128     case {"exp", "exponential", "exponential distribution"}
 129       retval = exprnd(varargin{:});
 130     case {"ev", "extreme value", "extreme value distribution"}
 131       error("random: distribution type '%s' is not yet implemented", name);
 132     case {"f", "f distribution"}
 133       retval = frnd(varargin{:});
 134     case {"gam", "gamma", "gamma distribution"}
 135      retval = gamrnd(varargin{:});
 136     case {"gev", "generalized extreme value", "generalized extreme value distribution"}
 137       error("random: distribution type '%s' is not yet implemented", name);
 138     case {"gp", "generalized pareto", "generalized pareto distribution"}
 139       error("random: distribution type '%s' is not yet implemented", name);
 140     case {"geo", "geometric", "geometric distribution"}
 141       retval = geornd(varargin{:});
 142     case {"hyge", "hypergeometric", "hypergeometric distribution"}
 143       retval = hygernd(varargin{:});
 144     case {"logn", "lognormal", "lognormal distribution"}
 145       retval = lognrnd(varargin{:});
 146     case {"nbin", "negative binomial", "negative binomial distribution"}
 147       retval = nbinrnd(varargin{:});
 148     case {"ncf", "noncentral f", "noncentral f distribution"}
 149       error("random: distribution type '%s' is not yet implemented", name);
 150     case {"nct", "noncentral t", "noncentral t distribution"}
 151       error("random: distribution type '%s' is not yet implemented", name);
 152     case {"ncx2", "noncentral chi-square", "noncentral chi-square distribution"}
 153       error("random: distribution type '%s' is not yet implemented", name);
 154     case {"norm", "normal", "normal distribution"}
 155       retval = normrnd(varargin{:});
 156     case {"poiss", "poisson", "poisson distribution"}
 157       retval = poissrnd(varargin{:});
 158     case {"rayl", "rayleigh", "rayleigh distribution"}
 159       retval = raylrnd(varargin{:});
 160     case {"t", "t distribution"}
 161       retval = trnd(varargin{:});
 162     case {"unif", "uniform", "uniform distribution"}
 163       retval = unifrnd(varargin{:});
 164     case {"unid", "discrete uniform", "discrete uniform distribution"}
 165       retval = unidrnd(varargin{:});
 166     case {"wbl", "weibull", "weibull distribution"}
 167       retval = wblrnd(varargin{:});
 168     otherwise
 169       error("random: unsupported distribution type '%s'", name);
 170   endswitch
 171 endfunction