This is an old version, view current version.

22.2 Map Function

In order to generalize the form of functions and results that are possible and accomodate both parameters (which need derivatives) and data values (which don’t), Stan’s map function operates on more than just a sequence of inputs.

Map Function Signature

Stan’s map function has the following signature

vector map_rect((vector, vector, real[], int[]):vector f,
                vector phi, vector[] thetas,
                data real[ , ] x_rs, data int[ , ] x_is);

The arrays thetas of parametrs, x_rs of real data, and x_is of integer data have the suffix “s” to indicate they are arrays. These arrays must all be the same size, as they will be mapped in parallel by the function f. The value of phi is reused in each mapped operation.

The _rect suffix in the name arises because the data structures it takes as arguments are rectangular. In order to deal with ragged inputs, ragged inputs must be padded out to recangular form.

The last two arguments are two dimensional arrays of real and integer data values. These argument types are marked with the data qualifier to indicate that they must only contain variables originating in the data or transformed data blocks. This will allow such data to be pinned to a processor on which it is being processed to reduce communication overhead.

The notation (vector, vector, real[], int[]):vector indicates that the function argument f must have the following signature.

vector f(vector phi, vector theta,
         data real[] x_r, data int[] x_i);

Although f will often return a vector of size one, the built-in flexiblity allows general multivariate functions to be mapped, even raggedly.

Map Function Semantics

Stan’s map function applies the function f to the shared parameters along with one element each of the job parameters, real data, and integer data arrays. Each of the arguments theta, x_r, and x_i must be arrays of the same size. If the arrays are all size N, the result is defined as follows.

map_rect(f, phi, thetas, xs, ns)
= f(phi, thetas[1], xs[1], ns[1]) . f(phi, thetas[2], xs[2], ns[2])
  . ... . f(phi, thetas[N], xs[N], ns[N])

The dot operators in the notation above are meant to indicate concatenation (implemented as append_row in Stan). The output of each application of f is a vector, and the sequence of N vectors is concatenated together to return a single vector.