R: Expose user-defined Stan functions to R for testing and...

expose_stan_functions {rstan} | R Documentation

## Expose user-defined Stan functions to R for testing and simulation

### Description

The Stan modeling language allows users to define their own functions in a `functions` block at the top of a Stan program. The `expose_stan_functions` utility function uses `sourceCpp` to export those user-defined functions to the specified environment for testing inside R or for doing posterior predictive simulations in R rather than in the `generated quantities` block of a Stan program.

### Usage

      expose_stan_functions(stanmodel, includes = NULL,
                            show_compiler_warnings = FALSE, ...)
      get_rng(seed = 0L)
      get_stream()

### Arguments

`stanmodel` | A `stanmodel` object, a `stanfit` object, a list produced by `stanc` or the path to a Stan program (`.stan` file). In any of these cases, the underlying Stan program should contain a non-empty `functions` block.
`includes` | If not `NULL` (the default), then a character vector of length one (possibly containing one or more `"\n"`) of the form `'#include "/full/path/to/my_header.hpp"'`, which will be inserted into the C++ code in the model's namespace and can be used to provide definitions of functions that are declared but not defined in `stanmodel`
`show_compiler_warnings` | Logical scalar defaulting to `FALSE` that controls whether compiler warnings, which can be numerous and have never been relevant, are shown
`seed` | An integer vector of length one indicating the state of Stan's pseudo-random number generator
`...` | Further arguments passed to `sourceCpp`.

### Details

The `expose_stan_functions` function requires as much compliance with the C++14 standard as is implemented in the RTools toolchain for Windows. On Windows, you will likely need to specify `CXX14 = g++ -std=c++1y` in the file whose path is `normalizePath("~/.R/Makevars")` in order for `expose_stan_functions` to work. Outside of Windows, the necessary compiler flags are set programatically, which is likely to suffice.

There are a few special types of user-defined Stan functions for which some additional details are relevant:

#### (P)RNG functions

If a user-defined Stan function ends in `_rng`, then it can use the Boost pseudo-random number generator used by Stan. When exposing such functions to R, `base_rng__` and `pstream__` arguments will be added to the `formals`. The `base_rng__` argument should be passed the result of a call to `get_rng` (perhaps specifying its `seed` argument for reproducibility) and the `pstream__` should be passed the result of a call to `get_stream`, which can be used to see the result of `print` and `reject` calls in the user-defined Stan functions. These arguments default to `get_stream()` and `get_rng()` respectively.

#### LP functions

If a user-defined Stan function ends in `_lp`, then it can modify the log-probability used by Stan to evaluate Metropolis proposals or as an objective function for optimization. When exposing such functions to R, a `lp__` argument will be added to the `formals`. This `lp__` argument defaults to zero, but a `double` precision scalar may be passed to this argument when the function is called from R. Such a user-defined Stan function can terminate with `return target();` or can execute `print(target());` to verify that the calculation is correct.

### Value

The names of the new functions in `env` are returned invisibly.

### See Also

`sourceCpp` and the section in the Stan User Manual on user-defined functions

### Examples

    ## Not run:
    model_code <-
      '
      functions {
        real standard_normal_rng() {
          return normal_rng(0,1);
       }
      }
    '
    expose_stan_functions(stanc(model_code = model_code))
    standard_normal_rng()
    PRNG <- get_rng(seed = 3)
    o <- get_stream()
    standard_normal_rng(PRNG, o)

    ## End(Not run)

[Package rstan version 2.21.2 Index]