Random number generation expressions are used to randomly sample model parameters from suitable distributions for probabilistic sensitivity analysis. These functions are typically used when evaluating an object of class model_def defined using define_model().

define_rng(expr, n = 1, ...)

eval_rng(x, params = NULL, check = FALSE)

## Arguments

expr An expression used to randomly draw variates for each parameter of interest in the model. Braces should be used so that the result of the last expression within the braces is evaluated. The expression must return a list where each element is either a vector or tabular object ( matrix, data.frame, or data.table). The length of the vector must either be or n and the number of rows in the tabular object must be n. Number of samples of the parameters to draw. Additional arguments to pass to the environment used to evaluate expr. An object of class rng_def created with define_rng(). A list containing the values of parameters for random number generation. Each element of the list should either be a vector, matrix, data.frame, or data.table Whether to check the returned output so that (i) it returns a list and (ii) each element has the correct length or number of rows. Default is FALSE, meaning that any output can be returned. This is always TRUE when used inside define_model().

## Value

define_rng() returns an object of class rng_def, which is a list containing the unevaluated random number generation expressions passed to expr, n, and any additional arguments passed to ... . eval_rng() evaluates the rng_def object and returns an eval_rng object containing the evaluated expression.

## Details

hesim contains a number of random number generation functions that return parameter samples in convenient formats and do not typically require the number of samples, n, as arguments (see rng_distributions). The random number generation expressions are evaluated using eval_rng() and used within expr in define_rng(). If a multivariate object is returned by eval_rng(), then the rows are random samples and columns are distinct parameters (e.g., costs for each health state, elements of a transition probability matrix).

Parameters can be conveniently sampled from probability distributions using a number of random number generation functions (see rng_distributions). An economic model can be created with create_CohortDtstm() by using define_rng() (or a previously evaluated eval_rng object) alongside define_tparams() to define a model with define_model(). It can be useful to summarize an evaluated expression with summary.eval_rng().

## Examples


params <- list(
alpha = matrix(c(75, 25, 33, 67), byrow = TRUE, ncol = 2),
inptcost_mean = c(A = 900, B = 1500, C = 2000),
outptcost_mean = matrix(c(300, 600, 800,
400, 700, 700),
ncol = 3, byrow = TRUE)
)
rng_def <- define_rng({
aecost_mean <- c(500, 800, 1000) # Local object not
# not returned by eval_rng()
list( # Sampled values of parameters returned by eval_rng()
p = dirichlet_rng(alpha), # Default column names
inptcost = gamma_rng(mean = inptcost_mean, # Column names based on
sd = inptcost_mean),  # named vector
outptcost = outptcost_mean, # No column names because
# outptcost_mean has none.
aecost = gamma_rng(mean = aecost_mean, # Explicit naming of columns
sd = aecost_mean,
names = aecost_colnames)
)
}, n = 2, aecost_colnames = c("A", "B", "C")) # Add aecost_colnames to environment
params_sample <- eval_rng(x = rng_def, params)
summary(params_sample)
#>            param         mean           sd         2.5%        97.5%
#>  1:      p_s1_s1    0.7702367 4.716169e-02    0.7385557    0.8019176
#>  2:      p_s1_s2    0.2297633 4.716169e-02    0.1980824    0.2614443
#>  3:      p_s2_s1    0.3644564 3.105112e-02    0.3435978    0.3853150
#>  4:      p_s2_s2    0.6355436 3.105112e-02    0.6146850    0.6564022
#>  5:   inptcost_A  445.3385839 2.029738e+02  308.9906423  581.6865255
#>  6:   inptcost_B 1204.8593951 1.521172e+03  183.0095902 2226.7092000
#>  7:   inptcost_C 3224.6960145 2.754789e+03 1374.1624755 5075.2295536
#>  8: outptcost_v1  350.0000000 7.071068e+01  302.5000000  397.5000000
#>  9: outptcost_v2  650.0000000 7.071068e+01  602.5000000  697.5000000
#> 10: outptcost_v3  750.0000000 7.071068e+01  702.5000000  797.5000000
#> 11:     aecost_A  582.9307337 1.060057e+02  511.7212755  654.1401919
#> 12:     aecost_B 1418.9059007 8.511182e+02  847.1659978 1990.6458036
#> 13:     aecost_C  245.4707724 8.486242e+01  188.4643193  302.4772255params_sample
#> A summary of the "eval_rng" object:
#>
#>            param         mean           sd         2.5%        97.5%
#>  1:      p_s1_s1    0.7702367 4.716169e-02    0.7385557    0.8019176
#>  2:      p_s1_s2    0.2297633 4.716169e-02    0.1980824    0.2614443
#>  3:      p_s2_s1    0.3644564 3.105112e-02    0.3435978    0.3853150
#>  4:      p_s2_s2    0.6355436 3.105112e-02    0.6146850    0.6564022
#>  5:   inptcost_A  445.3385839 2.029738e+02  308.9906423  581.6865255
#>  6:   inptcost_B 1204.8593951 1.521172e+03  183.0095902 2226.7092000
#>  7:   inptcost_C 3224.6960145 2.754789e+03 1374.1624755 5075.2295536
#>  8: outptcost_v1  350.0000000 7.071068e+01  302.5000000  397.5000000
#>  9: outptcost_v2  650.0000000 7.071068e+01  602.5000000  697.5000000
#> 10: outptcost_v3  750.0000000 7.071068e+01  702.5000000  797.5000000
#> 11:     aecost_A  582.9307337 1.060057e+02  511.7212755  654.1401919
#> 12:     aecost_B 1418.9059007 8.511182e+02  847.1659978 1990.6458036
#> 13:     aecost_C  245.4707724 8.486242e+01  188.4643193  302.4772255