Tutorials/A-Practical-Guide |

# Pattern Guide 02: Basic Vocabulary

Common patterns to generate streams of single values

## Basic Vocabulary: Generating values

Before getting to the really cool things patterns can do, we need to build up a basic vocabulary. We'll start with some words, then move into phrases in the next tutorial.

Some of the patterns will be demonstrated with a Pbind construct. This is a taste of things to come -- sequencing sonic events using patterns. Don't worry about how Pbind works just yet... all in good time.

Let's start with a very quick reference of some basic patterns. More complete descriptions follow this list. The list might seem long at first, but concentrate your attention on the patterns called "primary patterns". They are the most basic, and commonly used.

Again, the purpose is to start learning the vocabulary of patterns -- like learning new words when studying a human language. You can always come back and look at the rest later.

For more information on any of these patterns, select the class name and use the help key for your editor to open its help file.

## Quick reference

### Primary Patterns

`Pseq(list, repeats, offset)`
Play through the entire list `repeats` times. Like `list.do`.
`Prand(list, repeats)`
Choose items from the list randomly (same as `list.choose`).
`Pxrand(list, repeats)`
Choose randomly, but never repeat the same item twice in immediate succession.
`Pshuf(list, repeats)`
Shuffle the list in random order, and use the same random order `repeats` times. Like `list.scramble`.
`Pwrand(list, weights, repeats)`
Choose randomly, according to weighted probabilities (same as `list.wchoose(weights)`).
`Pseries(start, step, length)`
`Pgeom(start, grow, length)`
Geometric series (multiplication).
`Pwhite(lo, hi, length)`
Random numbers, equal distribution ("white noise"). Like `rrand(lo, hi)` .
`Pexprand(lo, hi, length)`
Random numbers, exponential distribution. Like `exprand(lo, hi)` .
`Pbrown(lo, hi, step, length)`
`Pfunc(nextFunc, resetFunc)`
Get the stream values from a user-supplied function.
`Pfuncn(func, repeats)`
Get values from the function, but stop after `repeats` items.
`Prout(routineFunc)`
Use the function like a routine. The function should return values using `.yield` or `.embedInStream`.

`Pser(list, repeats, offset)`
Play through the list as many times as needed, but output only `repeats` items.
`Pslide(list, repeats, len, step, start, wrapAtEnd)`
Play overlapping segments from the list.
`Pwalk(list, stepPattern, directionPattern, startPos)`
Random walk over the list.
`Place(list, repeats, offset)`
Interlace any arrays found in the main list.
`Ppatlace(list, repeats, offset)`
Interlace any patterns found in the main list.
`Ptuple(list, repeats)`
Collect the list items into an array as the return value.

`Pgbrown(lo, hi, step, length)`
Brownian motion, geometric scale (multiplication).
`Pbeta(lo, hi, prob1, prob2, length)`
Beta distribution, where `prob1 = α` (alpha) and `prob2 = β` (beta).
`Pcauchy(mean, spread, length)`
Cauchy distribution.
`Pgauss(mean, dev, length)`
Guassian (normal) distribution.
`Phprand(lo, hi, length)`
Returns the greater of two equal-distribution random numbers.
`Plprand(lo, hi, length)`
Returns the lesser of two equal-distribution random numbers.
`Pmeanrand(lo, hi, length)`
Returns the average of two equal-distribution random numbers, i.e., `(x + y) / 2`.
`Ppoisson(mean, length)`
Poisson distribution.
`Pprob(distribution, lo, hi, length, tableSize)`
Arbitrary distribution, based on a probability table.

## Functional descriptions of patterns

### List Patterns

The most obvious thing one would want to do with a pattern is to give it a list of values and have it read them out in order. You have a couple of choices, which differ in their handling of the `repeats` parameter.

`Pseq(list, repeats, offset)`
Play through the entire list `repeats` times.
`Pser(list, repeats, offset)`
Play through the list as many times as needed, but output only `repeats` items.

Pseq is an obvious choice for streaming out known pitch and rhythm values.

Before playing a Pbind pattern such as this, make sure the server is booted.

To stop the examples in this file, use the "stop" keyboard shortcut (cmd-. on macOS, alt-. on Windows, check documentation for other editors). Or:

A variation, Pslide, plays overlapping segments of the input list.

`Pslide(list, repeats, len, step, start, wrapAtEnd)`
Play overlapping segments from the list.
`repeats`
number of segments
`len`
length of each segment
`step`
is how far to step the start of each segment from previous.
`start`
what index to start at.
`wrapAtEnd`
if true (default), indexing wraps around if goes past beginning or end. If false, the pattern stops if it hits a nil element or goes outside the list bounds.

If `step == 1`, then the first segment is at `start`, the second at `start + 1`, and so on.

### Random-order list patterns

`Prand(list, repeats)`
Choose items from the list randomly (same as `list.choose`).
`Pxrand(list, repeats)`
Choose randomly, but never repeat the same item twice in immediate succession.
`Pshuf(list, repeats)`
Shuffle the list in random order, and use the same random order `repeats` times. Like `list.scramble`.
`Pwrand(list, weights, repeats)`
Choose randomly, according to weighted probabilities (same as `list.wchoose(weights)`).
`Pwalk(list, stepPattern, directionPattern, startPos)`
Random walk over the list. This pattern is a bit more complicated; see its help file for details.

### Interlacing values and making arrays

These are opposing operations: interlacing means splitting arrays and merging them into a stream of single values, and arrays can be made out of single-value streams as well.

`Place(list, repeats, offset)`
Take one from each item in the main array item in succession. Hard to explain, easier to see:

If we turn this into a matrix and read vertically, the original arrays are clearly visible:

`Ppatlace(list, repeats, offset)`
Take one value from each sub-pattern in order.

That's also a taste of things to come: Patterns can be nested.

`Ptuple(list, repeats)`
Get one value from each item in the array, and return all of them as an array of values.

### Arithmetic and geometric series

Now, let's move to patterns that produce values mathematically, without using a predefined list.

`Pseries(start, step, length)`
Arithmetic series, successively adding `step` to the starting value, returning a total of `length` items.
`Pgeom(start, grow, length)`
Geometric series, successively multiplying the current value by `grow`.

Third-party extension alert : If you want an arithmetic or geometric series to start at one number and end at another specific number, the step size/multiplier must be calculated from the endpoints and the number of items desired. The ddwPatterns quark includes a convenience method, `fromEndpoints`, for both Pseries and Pgeom that performs this calculation. It's necessary to give an exact number of repeats, at least two and less than infinity.

Prints:

### Random numbers and probability distributions

`Pwhite(lo, hi, length)`
Produces `length` random numbers with equal distribution ('white' refers to white noise).
`Pexprand(lo, hi, length)`
Same, but the random numbers have an exponential distribution, favoring lower numbers. This is good for frequencies, and also durations (because you need more notes with a shorter duration to balance the weight of longer notes).
`Pbrown(lo, hi, step, length)`
Brownian motion. Each value adds a random `step` to the previous value, where the `step` has an equal distribution between `-step` and `+step`.
`Pgbrown(lo, hi, step, length)`
Brownian motion on a geometric scale. Each value multiplies a random `step` factor to the previous value.
`Pbeta(lo, hi, prob1, prob2, length)`
Beta distribution, where `prob1 = α` (alpha) and `prob2 = β` (beta).
`Pcauchy(mean, spread, length)`
Cauchy distribution.
`Pgauss(mean, dev, length)`
Gaussian (normal) distribution.
`Phprand(lo, hi, length)`
Returns the greater of two equal-distribution random numbers.
`Plprand(lo, hi, length)`
Returns the lesser of two equal-distribution random numbers.
`Pmeanrand(lo, hi, length)`
Returns the average of two equal-distribution random numbers, i.e., `(x + y) / 2`.
`Ppoisson(mean, length)`
Poisson distribution.
`Pprob(distribution, lo, hi, length, tableSize)`
Given an array of relative probabilities across the desired range (a histogram) representing an arbitrary distribution, generates random numbers corresponding to that distribution.

To see a distribution, make a histogram out of it.

### Catchall Patterns

Not everything is pre-written as a pattern class. These patterns let you embed custom logic.

`Pfunc(nextFunc, resetFunc)`
The next value is the return value from evaluating `nextFunc`. If `.reset` is called on a stream made from this pattern, `resetFunc` is evaluated. The stream will run indefinitely until `nextFunc` returns `nil`.
`Pfuncn(func, repeats)`
Like Pfunc, output values come from evaluating the function. Pfuncn, however, returns exactly `repeats` values and then stops. The default number of repeats is 1.
`Prout(routineFunc)`
Use the `routineFunc` in a routine. The stream's output values are whatever this function `.yield`s. Prout ends when it yields `nil`.

Next, we'll look at the central pattern for audio sequencing: Pbind.

Previous: Pattern Guide 01: Introduction