random

[Class]
  `random`

Generates data in random order (sampling with replacement). By default, each element in a random pattern has an equal probability of being selected and each element may be repeated in direct succession any number of times. This behavior can be modified for any element by specifying the element as a random node list:

> `(`element {keyword value}*`)`

where element is the item or sub-pattern to generate and the possible keyword value pairs are:

> `:weight` {number | pattern}
>   Sets the probability of the node relative to the probabilities of the other nodes in the pattern. The weight may also be specified as a pattern of numbers, in which case a new weight will be selected for each period in the random pattern. The default value is 1.
> `:min` number
>   Sets a floor on how many direct repetitions or element must be made before a new element might be selected.
> `:max` number
>   Sets a ceiling on how many direct repetitions of the element might be made before a new element must be selected.

`random` supports the following slot initializations:

`:state` random-state
  Sets the random state object of the pattern to random-state. Defaults to `*random-state*`.

See generic pattern initializations for documentation on additional keyword initializations to the pattern.

#### Examples:

Example 1. The random pattern.

    (define pat1 (new random :of '((a :max 1) b (c :weight 4) d)))

    (next pat1 12)
    ⇒ (a c c c a c c c d b c c)

Example 2. Changing random probability as a function of time.

    (define (black-to-white reps trope envl rate)
      ;; move from black keys to white keys in trope over rep iterations.
      (let* ((pn 0)
             (pw (pval pn)) ; white probability
             (pb (pval (- 1 pn))) ; black probability
             (rp (new random :of (loop for n in trope
                                       for w = (member (note-name n)
                                                       '(c d e f g a b))
                                       collect
                                       ;; node for white note uses pw
                                       (list n :weight (if w pw pb))))))
        (process for i below reps
                 set pn = (interpl (/ i reps) envl)
                 output (new midi :time (now) :keynum (next rp)
                             :duration (* rate 1.5))
                 wait rate)))

    (define mel (note '(c4 cs d ds e f fs g gs a as b c5)))

    (define env '(0 0 .2 0 .8 1 1 1))

    (events (black-to-white 180 mel env .1) "test.mid")
    ⇒ "test.mid"

#### See also:

- Pattern classes [Topic]