23.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);
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
is reused in each mapped operation.
_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
The last two arguments are two dimensional arrays of real and integer
data values. These argument types are marked with the
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.
(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);
f will often return a vector of size one, the built-in
flexiblity allows general multivariate functions to be mapped, even
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
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, xs, ns) . f(phi, thetas, xs, ns) . ... . 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.