A collection of functions for randomly generating deviates from probability distributions with define_rng().

beta_rng(
  shape1 = 1,
  shape2 = 1,
  mean = NULL,
  sd = NULL,
  names = NULL,
  n = parent.frame()$n
)

dirichlet_rng(alpha, names = NULL, n = parent.frame()$n)

fixed(est, names = NULL, n = parent.frame()$n)

custom(x, names = NULL, n = parent.frame()$n)

gamma_rng(mean, sd, names = NULL, n = parent.frame()$n)

lognormal_rng(meanlog, sdlog, names = NULL, n = parent.frame()$n)

multi_normal_rng(mu, Sigma, names = NULL, n = parent.frame()$n, ...)

normal_rng(mean, sd, names = NULL, n = parent.frame()$n)

uniform_rng(min, max, names = NULL, n = parent.frame()$n)

Arguments

shape1, shape2

Non-negative parameters of the Beta distribution.

mean, sd

Mean and standard deviation of the random variable.

names

Names for columns if an object with multiple columns is returned by the function.

n

The number of random samples of the parameters to draw. Default is the value of n in the environment in which the function is called, which can be useful when used inside define_rng because it means that a value does not need to be explicitly passed to n.

alpha

A matrix where each row is a separate vector of shape parameters.

est

A vector of estimates of the variable of interest.

x

A numeric vector, matrix, data.frame, or data.table containing random samples of the variable of interest from a suitable probability distribution. This would typically be a posterior distribution from a Bayesian analysis.

meanlog, sdlog

Mean and standard deviation of the distribution on the log scale.

mu, Sigma

mu is a vector giving the means of the variables and Sigma is a positive-definite symmetric matrix specifying the covariance matrix of the variables.

...

Additional arguments to pass to underlying random number generation functions. See "details".

min, max

Lower and upper limits of the distribution. Must be finite.

Value

Functions either return a vector of length n or an n by k data.table. Multivariate distributions always return a data.table. If a univariate distribution is used, then a data.table is returned if each parameter is specified as a vector with length greater than 1; otherwise, if parameters are scalars, then a vector is returned. In the data.table case, k is equal to the length of the parameter vectors entered as arguments. For example, if the probability distribution contained mean as an argument and mean were of length 3, then an n by 3 matrix would be returned. The length of all parameter vectors must be the same. For instance, if the vector mean were of length 3 then all additional parameters (e.g., sd) must also be of length 3.

If a data.table is returned by a distribution, then its column names are set according to the following hierarchy:

  1. With the names argument if it is not NULL

  2. With the names of the parameter vectors if they are named vectors. If there are multiple parameter vector arguments, then the names of the first parameter vector with non NULL names is used. For instance, if mean and sd are both arguments to a random number generation function and mean is a named vector, then the names from the vector mean are used.

  3. As v1, ..., vk if the names argument is NULL and there are no named parameter vectors.

Details

These functions are not exported and are meant for use with define_rng(). They consequently assume that the number of samples to draw, n, is defined in the parent environment. Convenience random number generation functions include:

beta_rng()

If mean and sd are both not NULL, then parameters of the beta distribution are derived using the methods of moments with mom_beta(). Beta variates are generated with stats::rbeta().

custom()

Use previously sampled values from a custom probability distribution. There are three possibilities: (i) if n is equal to the number previously sampled values (say n_samples), then x is returned as is; (ii) if n < n_samples, then samples from x are sampled without replacement; and (iii) if n > n_samples, then samples from x are sampled with replacement and a warning is provided.

dirichlet_rng()

Dirichlet variates for each row in the matrix are generated with rdirichlet_mat(). The sampled values are stored in a data.table where there is a column for each element of alpha (with elements ordered rowwise).

fixed()

This function should be used when values of the variable of interest are fixed (i.e., they are known with certainty). If length(est) > 1, an n by length(est) data.table is returned meaning that each element of est is repeated n times; otherwise (if length(est) == 1), a vector is returned where est is repeated n times.

gamma_rng()

The parameters of the gamma distribution are derived using the methods of moments with mom_gamma() and gamma variates are generated with stats::rgamma().

lognormal_rng()

Lognormal variates are generated with stats::rlnorm().

multi_normal_rng()

Multivariate normal variates are generated with MASS::mvrnorm().

normal_rng()

Normal variates are generated with stats::rnorm().

uniform_rng()

Uniform variates are generated with stats::runif().

See also