rfun: Create functions of random variables

In posterior: Tools for Working with Posterior Distributions

Create functions of random variables

Description

Function that create functions that can accept and/or produce rvars.

Usage

rfun(.f, rvar_args = NULL, rvar_dots = TRUE, ndraws = NULL)

Arguments

.f	(multiple options) A function to turn into a function that accepts and/or produces random variables: A function A one-sided formula that can be parsed by rlang::as_function()
rvar_args	(character vector) The names of the arguments of .f that should be allowed to accept rvars as arguments. If NULL (the default), all arguments to .f are turned into arguments that accept rvars, including arguments passed via ... (if rvar_dots is TRUE).
rvar_dots	(logical) Should dots (...) arguments also be converted? Only applies if rvar_args is NULL (i.e., all arguments are allowed to be rvars).
ndraws	(positive integer). The number of draws used to construct new random variables if no rvars are supplied as arguments to the returned function. If NULL, getOption("posterior.rvar_ndraws") is used (default 4000). If any arguments to the returned function contain rvars, the number of draws in the provided rvars is used instead of the value of this argument.

Details

This function wraps an existing function (.f) such that it returns rvars containing whatever type of data .f would normally return.

The returned function, when called, executes .f possibly multiple times, once for each draw of the rvars passed to it, then returns a new rvar representing the output of those function evaluations. If the arguments contain no rvars, then .f will be executed ndraws times and an rvar with that many draws returned.

Functions created by rfun() are not necessarily fast (in fact in some cases they may be very slow), but they have the advantage of allowing a nearly arbitrary R functions to be executed against rvars simply by wrapping them with rfun(). This makes it especially useful as a prototyping tool. If you create code with rfun() and it is unacceptably slow for your application, consider rewriting it using math operations directly on rvars (which should be fast), using rvar_rng(), and/or using operations directly on the arrays that back the rvars (via draws_of()).

Value

A function with the same argument specification as .f, but which can accept and return rvars.

See Also

Other rfun: rdo(), rvar_rng()

Examples

rvar_norm <- rfun(rnorm)
rvar_gamma <- rfun(rgamma)

mu <- rvar_norm(10, mean = 1:10, sd = 1)
sigma <- rvar_gamma(1, shape = 1, rate = 1)
x <- rvar_norm(10, mu, sigma)
x

posterior documentation built on April 4, 2025, 4:44 a.m.