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

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)