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 user's workspace (`.GlobalEnv`) 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)

### 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.

### Details

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, a `seed` argument will be added to the `formals`. This `seed` argument defaults to `0L`, but any non-negative integer can be passed as the `seed` the first time any user-defined function ending in `_rng` is called. In other words, the Boost pseudo-random number generator is initialized with the given `seed` but is declared with the `static` C++ keyword, meaning that it will not be reinitialized by subsequent calls to user-defined functions ending in `_rng`.

#### 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 get_lp();` or can execute `print(lp__);` to verify that the calculation is correct.

### Value

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

### See Also

`sourceCpp`

### Examples

      # You could use a function like this to calculate the log-likelihood
      # for an observation over the posterior distribution to then use as
      # an ingredient to the calculation of the WAIC
      mc <-
      '
      functions {
        vector logLik(int y, real x, vector beta) {
          vector[rows(beta)] logLik;
          for (i in 1:rows(beta)) {
            logLik[i] <- poisson_log_log(y, x * beta[i]);
          }
          return logLik;
        }
      }
      model {}
      '
      cppcode <- stanc(model_code = mc, model_name = "Demonstration")
      ## Not run:
      expose_stan_functions(cppcode)

    ## End(Not run)

[Package rstan version 2.12.1 Index]