9.5 Function bodies
The body of a function is between an open curly brace ({) and
close curly brace (}). The body may contain local variable declarations at the
top of the function body’s block and these scope the same way as local
variables used in any other statement block.
The only restrictions on statements in function bodies are external, and determine whether the log probability accumulator or random number generators are available; see the rest of this section for details.
Random number generating functions
Functions that call random number generating functions in their bodies
must have a name that ends in _rng; attempts to use
random-number generators in other functions lead to a compile-time
error.
Like other random number generating functions, user-defined functions
with names that end in _rng may be used only in the generated
quantities block and transformed data block, or within the bodies of
user-defined functions ending in _rng. An attempt to use such
a function elsewhere results in a compile-time error.
Log probability access in functions
Functions that include sampling statements or log probability
increment statements must have a name that ends in _lp.
Attempts to use sampling statements or increment log probability
statements in other functions lead to a compile-time error.
Like the target log density increment statement and sampling
statements, user-defined functions with names that end in _lp
may only be used in blocks where the log probability accumulator is
accessible, namely the transformed parameters and model blocks. An
attempt to use such a function elsewhere results in a compile-time
error.
Defining probability functions for sampling statements
Functions whose names end in _lpdf and _lpmf (density
and mass functions) can be used as probability functions in sampling
statements. As with the built-in functions, the first argument will
appear on the left of the sampling statement operator (~) in
the sampling statement and the other arguments follow. For example,
suppose a function returning the log of the density of y given
parameter theta allows the use of the sampling statement is
defined as follows.
real foo_lpdf(real y, vector theta) { ... }Note that for function definitions, the comma is used rather than the vertical bar.
For every custom _lpdf and _lpmf defined there is a corresponding
_lupdf and _lupmf defined automatically. The _lupdf and _lupmf
versions of the functions cannot be defined directly (to do so will
produce an error). The difference in the
_lpdf and _lpmf and the corresponding _lupdf and _lupmf functions
is that if any other unnormalized density functions are used
inside the user-defined function, the _lpdf and _lpmf forms of the
user-defined function will change these densities to be normalized.
The _lupdf and _lupmf forms of the user-defined functions will
instead allow other unnormalized density functions to drop additive
constants.
The sampling shorthand
z ~ foo(phi);will have the same effect as incrementing the target with the log of the unnormalized density:
target += foo_lupdf(z | phi);Other _lupdf and _lupmf functions used in the definition of
foo_lpdf will drop additive constants when foo_lupdf is called and
will not drop additive constants when foo_lpdf is called.
If there are _lupdf and _lupmf functions used inside the following
call to foo_lpdf, they will be forced to normalize (return the equivalent
of their _lpdf and _lpmf forms):
target += foo_lpdf(z | phi);If there are no _lupdf or _lupmf functions used in the definition of
foo_lpdf, then there will be no difference between a foo_lpdf
or foo_lupdf call.
The unnormalized _lupdf and _lupmf functions can only be used in
the model block or in user-defined probability functions (those ending in
_lpdf or _lpmf).
The same syntax and shorthand that works for _lpdf also works for log
probability mass functions with suffixes _lpmf.
A function that is going to be accessed as distributions must return the log of the density or mass function it defines.