Fred Drake | 3a0351c | 1998-04-04 07:23:21 +0000 | [diff] [blame] | 1 | \section{Standard Module \module{random}} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame^] | 2 | \declaremodule{standard}{random} |
| 3 | |
| 4 | \modulesynopsis{Generate pseudo-random numbers with various common distributions.} |
| 5 | |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 6 | |
| 7 | This module implements pseudo-random number generators for various |
| 8 | distributions: on the real line, there are functions to compute normal |
| 9 | or Gaussian, lognormal, negative exponential, gamma, and beta |
| 10 | distributions. For generating distribution of angles, the circular |
| 11 | uniform and von Mises distributions are available. |
| 12 | |
| 13 | The module exports the following functions, which are exactly |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 14 | equivalent to those in the \module{whrandom} module: |
| 15 | \function{choice()}, \function{randint()}, \function{random()} and |
| 16 | \function{uniform()}. See the documentation for the \module{whrandom} |
| 17 | module for these functions. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 18 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 19 | The following functions specific to the \module{random} module are also |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 20 | defined, and all return real values. Function parameters are named |
| 21 | after the corresponding variables in the distribution's equation, as |
| 22 | used in common mathematical practice; most of these equations can be |
| 23 | found in any statistics text. |
| 24 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 25 | \begin{funcdesc}{betavariate}{alpha, beta} |
| 26 | Beta distribution. Conditions on the parameters are |
Fred Drake | 4e66887 | 1998-04-03 06:04:12 +0000 | [diff] [blame] | 27 | \code{\var{alpha} >- 1} and \code{\var{beta} > -1}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 28 | Returned values will range between 0 and 1. |
| 29 | \end{funcdesc} |
| 30 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 31 | \begin{funcdesc}{cunifvariate}{mean, arc} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 32 | Circular uniform distribution. \var{mean} is the mean angle, and |
| 33 | \var{arc} is the range of the distribution, centered around the mean |
| 34 | angle. Both values must be expressed in radians, and can range |
Guido van Rossum | a933f6a | 1998-04-20 14:43:44 +0000 | [diff] [blame] | 35 | between 0 and pi. Returned values will range between |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 36 | \code{\var{mean} - \var{arc}/2} and \code{\var{mean} + \var{arc}/2}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 37 | \end{funcdesc} |
| 38 | |
| 39 | \begin{funcdesc}{expovariate}{lambd} |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 40 | Exponential distribution. \var{lambd} is 1.0 divided by the desired |
| 41 | mean. (The parameter would be called ``lambda'', but that is a |
| 42 | reserved word in Python.) Returned values will range from 0 to |
| 43 | positive infinity. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 44 | \end{funcdesc} |
| 45 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 46 | \begin{funcdesc}{gamma}{alpha, beta} |
| 47 | Gamma distribution. (\emph{Not} the gamma function!) Conditions on |
Fred Drake | 4e66887 | 1998-04-03 06:04:12 +0000 | [diff] [blame] | 48 | the parameters are \code{\var{alpha} > -1} and \code{\var{beta} > 0}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 49 | \end{funcdesc} |
| 50 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{gauss}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 52 | Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the |
| 53 | standard deviation. This is slightly faster than the |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 54 | \function{normalvariate()} function defined below. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 55 | \end{funcdesc} |
| 56 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 57 | \begin{funcdesc}{lognormvariate}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 58 | Log normal distribution. If you take the natural logarithm of this |
| 59 | distribution, you'll get a normal distribution with mean \var{mu} and |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 60 | standard deviation \var{sigma}. \var{mu} can have any value, and \var{sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 61 | must be greater than zero. |
| 62 | \end{funcdesc} |
| 63 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 64 | \begin{funcdesc}{normalvariate}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 65 | Normal distribution. \var{mu} is the mean, and \var{sigma} is the |
| 66 | standard deviation. |
| 67 | \end{funcdesc} |
| 68 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 69 | \begin{funcdesc}{vonmisesvariate}{mu, kappa} |
Guido van Rossum | a933f6a | 1998-04-20 14:43:44 +0000 | [diff] [blame] | 70 | \var{mu} is the mean angle, expressed in radians between 0 and 2*pi, |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 71 | and \var{kappa} is the concentration parameter, which must be greater |
Guido van Rossum | a933f6a | 1998-04-20 14:43:44 +0000 | [diff] [blame] | 72 | than or equal to zero. If \var{kappa} is equal to zero, this |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 73 | distribution reduces to a uniform random angle over the range 0 to |
Guido van Rossum | a933f6a | 1998-04-20 14:43:44 +0000 | [diff] [blame] | 74 | 2*pi. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 75 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 76 | |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 77 | \begin{funcdesc}{paretovariate}{alpha} |
| 78 | Pareto distribution. \var{alpha} is the shape parameter. |
| 79 | \end{funcdesc} |
| 80 | |
| 81 | \begin{funcdesc}{weibullvariate}{alpha, beta} |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 82 | Weibull distribution. \var{alpha} is the scale parameter and |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 83 | \var{beta} is the shape parameter. |
| 84 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 85 | |
| 86 | \begin{seealso} |
| 87 | \seemodule{whrandom}{the standard Python random number generator} |
| 88 | \end{seealso} |