ran

[Function]
  `(``ran` {keyword value}*`)`

Generates random numbers in a variety of distributions according to its keyword arguments.

`ran` supports the following keyword arguments:

`:below` number
  Sets the exclusive upper bounds for random number generation. Defaults to a value specific to the type of distribution specified, usually 1.0.
`:from` number
  Sets the inclusive upper bounds for random number generation. Defaults to a value specific to the type of distribution, usually 0.0.
`:type`
  Sets the distribution for random number generation to type specified as a symbol or keyword. Defaults to `:uniform`.

  `ran` supports the following distribution types:

  `:uniform`
    Equal probability distribution.
  `:low-pass`
    Likelihood of lower numbers is greater then higher numbers. Density is f(x)=2*(1-x) for {x 0<1} and mean is .2929.
  `:high-pass`
    Likelihood if higher numbers is greater than lower numbers. Density is f(x)=2*(1-x) for {x 0<1} and mean is .2929.
  `:mean`
    Likelihood of mid-range numbers is greater than lower or higher numbers. Mean is n/2.
  `:beta`
    The :a and :b parameters determine the shape of the distribution. When a=b=1 the distribution is uniform. When a=b, the distribution is symmetric around .5. When a<1 and b<1 then the density of larger and smaller numbers increases. When a>1 and b>1, density is similar to the gaussian distribution.
  `:exponential`
    Returns a floating point value greater than zero. The `:a` parameter is a stretching factor; increasing its value "prefers" smaller numbers. The distribution is unbounded but when a=1 then %99.9 of the time the value returned will be than 6.9077554, i.e. -log(.001). The distribution density is f(x)=(exp -x) with a mean of 1.0.
  `:gaussian`
    Gaussian (normal) distribution returns an unbounded value. The spread (standard deviation) is 1.0 centered at 0, so 68.26% of the results are between -1 and 1 inclusive and 99.74% of the results are between -3 and 3 inclusive.
  `:cauchy`
    Returns an unbounded value. The density function is a bell shaped curve centered at 0 similar to a normal distribution but with more values at the extremes. The mean and standard deviation of the Cauchy distribution are undefined. If parameter :a is true then only positive values are returned. Density is f(x)=1/(pi(1 + x^2)).
  `:poisson`
    A discrete distribution: returns positive integer values, theoretically unbounded but practically limited by the shape parameter. Parameter `:a` controls the distribution's shape and must be positive: the mean is a and the standard deviation is sqrt(a).
  `:gamma`
    Returns a floating point value greater than 0. Parameter `:a` controls the distribution's shape and should be a positive integer (if a non-integer is provided, the value is rounded.) When a=1, the distribution is the same as exponential. As its value increases, the probability density function becomes a curve with mean=a and standard deviation = sqrt(a)
`:a` number
  A control parameter whose interpretation depends on the distribution type.
`:b` number
  A control parameter whose interpretation depends on the distribution type.
`:state` state
  The random state object. The value defaults to `*random-state*`.

#### Examples:

Example 1. The `ran` function.

    (define (play-ran type len rate key1 key2)
      (process repeat len
               for r = (ran :type type)
               for k = (rescale r 0.0 1.0 key1 key2)
               output (new midi :time (now)
                           :keynum k
                           :duration (* rate 1.5))
               wait rate))

    ;;; Playing uniform distribution.
    (events (play-ran ':uniform 100 .1 20 100)
            "test.mid" :channel-tuning 4)
    ⇒ "test.mid"
    ;;; Playing the low pass distribution.
    (events (play-ran ':low 50 .1 20 100)
            "test.mid" :channel-tuning 4)
    ⇒ "test.mid"
    ;;; Playing the high pass distribution.
    (events (play-ran :high 50 .1 20 100)
            "test.mid" :channel-tuning 4)
    ⇒ "test.mid"

Example 2. The beta distribution.

    (define (rain len rate env key1 key2 amp)
      (process for i below len
               for e = (interpl (/ i len) env)
               for v = (vary rate e :above)
               ;; rescale e to control shape of beta distribution
               ;; when e=0 z=.4, and when e=1 z=1.
               for z = (rescale e 0 1 1 .4)
               for b = (ran :type ':beta :a z :b z)
               output (new midi :time (+ (now) v)
                           :duration v
                           :keynum (between key1 key2)
                           :amplitude (rescale b 0 1 .1 amp))
               wait rate))

    (define rain-env '(0 1 .4 0 .6 0 1 1))

    (events (list (rain 80 .5 rain-env 70 90 .8)
                  (rain 40 1 rain-env 40 60 .8)
                  (rain 20 2 rain-env 20 40 .9))
            "test.mid")
    ⇒ "test.mid"

#### See also:

- `between` [Function]
- `drunk` [Function]
- `odds` [Function]
- `pick` [Function]
- `pickl` [Function]
- `ransegs` [Function]
- `shuffle` [Function]
- `vary` [Function]