R: Random number generation distributions

rng_distributions {hesim}

R Documentation

Random number generation distributions

Description

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

Usage

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.

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().

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: