Skip to contents

Evaluate Monte Carlo Model Expressions

Source: R/eval_module.R
eval_module.Rd

Evaluates a model expression or list of expressions to produce an mcmodule object containing simulation results and metadata. Expression may use mcstoc() and mcdata() to create nodes inline; nvariates is automatically inferred from the data.

Usage

eval_module(
  exp,
  data,
  param_names = NULL,
  prev_mcmodule = NULL,
  summary = FALSE,
  mctable = set_mctable(),
  data_keys = set_data_keys(),
  match_keys = NULL,
  keys = NULL,
  overwrite_keys = NULL,
  use_baseline = NULL,
  use_variation = NULL
)

Arguments

exp

(language or list). Model expression or list of expressions to evaluate.

data

(data frame). Input data; number of rows determines nvariates for mcstoc()/mcdata() in expressions. Default: required.

param_names

(named character vector, optional). Names to rename parameters. Default: NULL.

prev_mcmodule

(mcmodule or list, optional). Previous module(s) for dependent calculations. Default: NULL.

summary

(logical). If TRUE, calculate summary statistics for output nodes. Default: FALSE.

mctable

(data frame). Reference table for mcnodes with mcnode and mc_func columns. If NULL or not provided, nodes matching data column names are automatically created. Default: empty mctable().

data_keys

(list). Data structure and keys for input data. Default: set_data_keys().

match_keys

(character vector, optional). Keys to match prev_mcmodule mcnodes with current data. Default: NULL.

keys

(character vector, optional). Explicit keys for input data. Default: NULL.

overwrite_keys

(logical or NULL). If NULL (default), becomes TRUE when data_keys is NULL or empty; otherwise FALSE.

use_baseline

(character vector, optional). mcnode names to override with sensi_baseline values from mctable. Default: NULL.

use_variation

(character vector, optional). mcnode names to apply sensi_variation expression from mctable before node creation. Default: NULL.

Value

An mcmodule object (list) with elements:

  • data: List containing input data frames.

  • exp: List of evaluated expressions.

  • node_list: Named list of mcnode objects with metadata.

Details

  • mcstoc() and mcdata() may be used directly inside model expressions. When these are used you should NOT explicitly supply nvariates, nvariates will be inferred automatically as the number of rows in the input data. Other arguments are preserved, for example specify type = "0" when providing data without variability/uncertainty (see ?mcdata and ?mcstoc).

  • By design, mcmodule supports type = "V" (the default, with variability) and type = "0" (no variability) nodes. Expressions that specify other node types ("U" or "VU") are not fully supported and downstream compatibility is not guaranteed.

  • An explicit mctable is optional but highly recommended. If no mctable is provided, any model nodes that match column names in data will be built from the data. If a mctable is provided and a node is not found there but exists as a data column, a warning will be issued and the node will be created from the data column.

  • Within expressions reference input mcnodes by their bare names (e.g. column1). Do not use data$column1 or data["column1"].

Examples

# Basic usage with single expression
# Build a quoted expression using mcnodes defined in mctable or built with
# mcstoc()/mcdata within the expression (do NOT set nvariates, it is
# inferred from nrow(data) when evaluated by eval_module()).
expr_example <- quote({
  # Within-herd prevalence (assigned from a pre-built mcnode w_prev)
  inf_a <- w_prev

  # Estimate of clinic sensitivity
  clinic_sensi <- mcstoc(runif, min = 0.6, max = 0.8)

  # Probability an infected animal is tested in origin and not detected
  false_neg_a <- inf_a * test_origin * (1 - test_sensi) * (1 - clinic_sensi)

  # Probability an infected animal is not tested and not detected
  no_test_a <- inf_a * (1 - test_origin) * (1 - clinic_sensi)

  # no_detect_a: total probability an infected animal is not detected
  no_detect_a <- false_neg_a + no_test_a
})

# Evaluate
eval_module(
  exp = expr_example,
  data = imports_data,
  mctable = imports_mctable,
  data_keys = imports_data_keys
)
#> expr_example evaluated
#> mcmodule created (expressions: )
#> $data
#> $data$imports_data
#>   pathogen origin h_prev_min h_prev_max w_prev_min w_prev_max farms_n
#> 1        a   nord       0.08       0.10       0.15        0.2       5
#> 2        a  south       0.02       0.05       0.15        0.2      10
#> 3        a   east       0.10       0.15       0.15        0.2       7
#> 4        b   nord       0.50       0.70       0.45        0.6       5
#> 5        b  south       0.25       0.30       0.37        0.4      10
#> 6        b   east       0.30       0.50       0.45        0.6       7
#>   animals_n_mean animals_n_sd test_origin test_sensi_min test_sensi_mode
#> 1            100            6   sometimes           0.89            0.90
#> 2            130           10   sometimes           0.89            0.90
#> 3            140           12       never           0.89            0.90
#> 4            100            2      always           0.80            0.85
#> 5            130            4   sometimes           0.80            0.85
#> 6            140            3     unknown           0.80            0.85
#>   test_sensi_max
#> 1           0.91
#> 2           0.91
#> 3           0.91
#> 4           0.90
#> 5           0.90
#> 6           0.90
#> 
#> 
#> $exp
#> {
#>     inf_a <- w_prev
#>     clinic_sensi <- mcstoc(runif, min = 0.6, max = 0.8)
#>     false_neg_a <- inf_a * test_origin * (1 - test_sensi) * (1 - 
#>         clinic_sensi)
#>     no_test_a <- inf_a * (1 - test_origin) * (1 - clinic_sensi)
#>     no_detect_a <- false_neg_a + no_test_a
#> }
#> 
#> $node_list
#> $node_list$w_prev
#> $node_list$w_prev$type
#> [1] "in_node"
#> 
#> $node_list$w_prev$mc_func
#> [1] "runif"
#> 
#> $node_list$w_prev$description
#> [1] "Within herd prevalence"
#> 
#> $node_list$w_prev$inputs_col
#> [1] "w_prev_min" "w_prev_max"
#> 
#> $node_list$w_prev$input_dataset
#> [1] "prevalence_region"
#> 
#> $node_list$w_prev$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$w_prev$exp_name
#> [1] "expr_example"
#> 
#> $node_list$w_prev$mc_name
#> [1] "w_prev"
#> 
#> $node_list$w_prev$mcnode
#>   node    mode  nsv nsu nva variate  min  mean median max Nas type outm
#> 1    x numeric 1001   1   6       1 0.15 0.176  0.176 0.2   0    V each
#> 2    x numeric 1001   1   6       2 0.15 0.175  0.175 0.2   0    V each
#> 3    x numeric 1001   1   6       3 0.15 0.176  0.176 0.2   0    V each
#> 4    x numeric 1001   1   6       4 0.45 0.525  0.524 0.6   0    V each
#> 5    x numeric 1001   1   6       5 0.37 0.385  0.385 0.4   0    V each
#> 6    x numeric 1001   1   6       6 0.45 0.525  0.523 0.6   0    V each
#> 
#> $node_list$w_prev$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$inf_a
#> $node_list$inf_a$type
#> [1] "out_node"
#> 
#> $node_list$inf_a$node_exp
#> [1] "w_prev"
#> 
#> $node_list$inf_a$inputs
#> [1] "w_prev"
#> 
#> $node_list$inf_a$exp_name
#> [1] "expr_example"
#> 
#> $node_list$inf_a$mc_name
#> [1] "inf_a"
#> 
#> $node_list$inf_a$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$inf_a$exp_param
#> [1] "w_prev"
#> 
#> $node_list$inf_a$mcnode
#>   node    mode  nsv nsu nva variate  min  mean median max Nas type outm
#> 1    x numeric 1001   1   6       1 0.15 0.176  0.176 0.2   0    V each
#> 2    x numeric 1001   1   6       2 0.15 0.175  0.175 0.2   0    V each
#> 3    x numeric 1001   1   6       3 0.15 0.176  0.176 0.2   0    V each
#> 4    x numeric 1001   1   6       4 0.45 0.525  0.524 0.6   0    V each
#> 5    x numeric 1001   1   6       5 0.37 0.385  0.385 0.4   0    V each
#> 6    x numeric 1001   1   6       6 0.45 0.525  0.523 0.6   0    V each
#> 
#> $node_list$inf_a$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$clinic_sensi
#> $node_list$clinic_sensi$created_in_exp
#> [1] TRUE
#> 
#> $node_list$clinic_sensi$mc_func
#> [1] "runif"
#> 
#> $node_list$clinic_sensi$function_call
#> [1] TRUE
#> 
#> $node_list$clinic_sensi$type
#> [1] "out_node"
#> 
#> $node_list$clinic_sensi$node_exp
#> [1] "mcstoc(runif, min = 0.6, max = 0.8)"
#> 
#> $node_list$clinic_sensi$inputs
#> character(0)
#> 
#> $node_list$clinic_sensi$exp_name
#> [1] "expr_example"
#> 
#> $node_list$clinic_sensi$mc_name
#> [1] "clinic_sensi"
#> 
#> $node_list$clinic_sensi$exp_param
#> character(0)
#> 
#> $node_list$clinic_sensi$mcnode
#>   node    mode  nsv nsu nva variate min  mean median   max Nas type outm
#> 1    x numeric 1001   1   6       1 0.6 0.702  0.705 0.800   0    V each
#> 2    x numeric 1001   1   6       2 0.6 0.700  0.701 0.799   0    V each
#> 3    x numeric 1001   1   6       3 0.6 0.698  0.697 0.800   0    V each
#> 4    x numeric 1001   1   6       4 0.6 0.701  0.702 0.800   0    V each
#> 5    x numeric 1001   1   6       5 0.6 0.700  0.701 0.800   0    V each
#> 6    x numeric 1001   1   6       6 0.6 0.701  0.703 0.800   0    V each
#> 
#> $node_list$clinic_sensi$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$test_origin
#> $node_list$test_origin$type
#> [1] "in_node"
#> 
#> $node_list$test_origin$description
#> [1] "Probability of the animals being tested in origin"
#> 
#> $node_list$test_origin$inputs_col
#> [1] "test_origin"
#> 
#> $node_list$test_origin$input_dataset
#> [1] "prevalence_region"
#> 
#> $node_list$test_origin$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$test_origin$exp_name
#> [1] "expr_example"
#> 
#> $node_list$test_origin$mc_name
#> [1] "test_origin"
#> 
#> $node_list$test_origin$mcnode
#>   node    mode nsv nsu nva variate min mean median max Nas type outm
#> 1    x numeric   1   1   6       1 0.5  0.5    0.5 0.5   0    0 each
#> 2    x numeric   1   1   6       2 0.5  0.5    0.5 0.5   0    0 each
#> 3    x numeric   1   1   6       3 0.0  0.0    0.0 0.0   0    0 each
#> 4    x numeric   1   1   6       4 1.0  1.0    1.0 1.0   0    0 each
#> 5    x numeric   1   1   6       5 0.5  0.5    0.5 0.5   0    0 each
#> 6    x numeric   1   1   6       6 0.0  0.0    0.0 0.0   0    0 each
#> 
#> $node_list$test_origin$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$test_sensi
#> $node_list$test_sensi$type
#> [1] "in_node"
#> 
#> $node_list$test_sensi$mc_func
#> [1] "rpert"
#> 
#> $node_list$test_sensi$description
#> [1] "Test sensitivity"
#> 
#> $node_list$test_sensi$inputs_col
#> [1] "test_sensi_min"  "test_sensi_mode" "test_sensi_max" 
#> 
#> $node_list$test_sensi$input_dataset
#> [1] "test_sensitivity"
#> 
#> $node_list$test_sensi$keys
#> [1] "pathogen"
#> 
#> $node_list$test_sensi$exp_name
#> [1] "expr_example"
#> 
#> $node_list$test_sensi$mc_name
#> [1] "test_sensi"
#> 
#> $node_list$test_sensi$mcnode
#>   node    mode  nsv nsu nva variate   min  mean median   max Nas type outm
#> 1    x numeric 1001   1   6       1 0.890 0.900  0.900 0.908   0    V each
#> 2    x numeric 1001   1   6       2 0.891 0.900  0.900 0.909   0    V each
#> 3    x numeric 1001   1   6       3 0.891 0.900  0.900 0.910   0    V each
#> 4    x numeric 1001   1   6       4 0.805 0.850  0.850 0.897   0    V each
#> 5    x numeric 1001   1   6       5 0.801 0.850  0.850 0.893   0    V each
#> 6    x numeric 1001   1   6       6 0.802 0.851  0.851 0.896   0    V each
#> 
#> $node_list$test_sensi$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$false_neg_a
#> $node_list$false_neg_a$function_call
#> [1] TRUE
#> 
#> $node_list$false_neg_a$type
#> [1] "out_node"
#> 
#> $node_list$false_neg_a$node_exp
#> [1] "inf_a * test_origin * (1 - test_sensi) * (1 - clinic_sensi)"
#> 
#> $node_list$false_neg_a$inputs
#> [1] "inf_a"        "test_origin"  "test_sensi"   "clinic_sensi"
#> 
#> $node_list$false_neg_a$exp_name
#> [1] "expr_example"
#> 
#> $node_list$false_neg_a$mc_name
#> [1] "false_neg_a"
#> 
#> $node_list$false_neg_a$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$false_neg_a$exp_param
#> [1] "inf_a"        "test_origin"  "test_sensi"   "clinic_sensi"
#> 
#> $node_list$false_neg_a$mcnode
#>   node    mode  nsv nsu nva variate     min    mean  median     max Nas type
#> 1    x numeric 1001   1   6       1 0.00145 0.00262 0.00257 0.00425   0    V
#> 2    x numeric 1001   1   6       2 0.00151 0.00262 0.00259 0.00403   0    V
#> 3    x numeric 1001   1   6       3 0.00000 0.00000 0.00000 0.00000   0    V
#> 4    x numeric 1001   1   6       4 0.01105 0.02350 0.02296 0.04326   0    V
#> 5    x numeric 1001   1   6       5 0.00419 0.00864 0.00857 0.01494   0    V
#> 6    x numeric 1001   1   6       6 0.00000 0.00000 0.00000 0.00000   0    V
#>   outm
#> 1 each
#> 2 each
#> 3 each
#> 4 each
#> 5 each
#> 6 each
#> 
#> $node_list$false_neg_a$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$no_test_a
#> $node_list$no_test_a$function_call
#> [1] TRUE
#> 
#> $node_list$no_test_a$type
#> [1] "out_node"
#> 
#> $node_list$no_test_a$node_exp
#> [1] "inf_a * (1 - test_origin) * (1 - clinic_sensi)"
#> 
#> $node_list$no_test_a$inputs
#> [1] "inf_a"        "test_origin"  "clinic_sensi"
#> 
#> $node_list$no_test_a$exp_name
#> [1] "expr_example"
#> 
#> $node_list$no_test_a$mc_name
#> [1] "no_test_a"
#> 
#> $node_list$no_test_a$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$no_test_a$exp_param
#> [1] "inf_a"        "test_origin"  "clinic_sensi"
#> 
#> $node_list$no_test_a$mcnode
#>   node    mode  nsv nsu nva variate    min   mean median    max Nas type outm
#> 1    x numeric 1001   1   6       1 0.0152 0.0262 0.0255 0.0395   0    V each
#> 2    x numeric 1001   1   6       2 0.0155 0.0262 0.0259 0.0397   0    V each
#> 3    x numeric 1001   1   6       3 0.0303 0.0529 0.0530 0.0783   0    V each
#> 4    x numeric 1001   1   6       4 0.0000 0.0000 0.0000 0.0000   0    V each
#> 5    x numeric 1001   1   6       5 0.0374 0.0577 0.0575 0.0793   0    V each
#> 6    x numeric 1001   1   6       6 0.0910 0.1570 0.1560 0.2373   0    V each
#> 
#> $node_list$no_test_a$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$no_detect_a
#> $node_list$no_detect_a$function_call
#> [1] TRUE
#> 
#> $node_list$no_detect_a$type
#> [1] "out_node"
#> 
#> $node_list$no_detect_a$node_exp
#> [1] "false_neg_a + no_test_a"
#> 
#> $node_list$no_detect_a$inputs
#> [1] "false_neg_a" "no_test_a"  
#> 
#> $node_list$no_detect_a$exp_name
#> [1] "expr_example"
#> 
#> $node_list$no_detect_a$mc_name
#> [1] "no_detect_a"
#> 
#> $node_list$no_detect_a$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$no_detect_a$exp_param
#> [1] "false_neg_a" "no_test_a"  
#> 
#> $node_list$no_detect_a$mcnode
#>   node    mode  nsv nsu nva variate    min   mean median    max Nas type outm
#> 1    x numeric 1001   1   6       1 0.0167 0.0288 0.0281 0.0437   0    V each
#> 2    x numeric 1001   1   6       2 0.0170 0.0289 0.0286 0.0436   0    V each
#> 3    x numeric 1001   1   6       3 0.0303 0.0529 0.0530 0.0783   0    V each
#> 4    x numeric 1001   1   6       4 0.0111 0.0235 0.0230 0.0433   0    V each
#> 5    x numeric 1001   1   6       5 0.0423 0.0663 0.0662 0.0930   0    V each
#> 6    x numeric 1001   1   6       6 0.0910 0.1570 0.1560 0.2373   0    V each
#> 
#> $node_list$no_detect_a$data_name
#> [1] "imports_data"
#> 
#> 
#> 
#> attr(,"class")
#> [1] "mcmodule"