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 mc2d::mcstoc() and mc2d::mcdata() to create nodes inline; nvariates is automatically inferred from the data unless sample_design is provided.

Usage

eval_module(
  exp,
  data = NULL,
  param_names = NULL,
  prev_mcmodule = NULL,
  summary = FALSE,
  mctable = set_mctable(),
  data_keys = set_data_keys(),
  match_keys = NULL,
  keys = NULL,
  overwrite_keys = NULL,
  sample_design = set_sample_design(),
  if_not_sampled = c("median", "mean", "max", "min"),
  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 mc2d::mcstoc()/mc2d::mcdata() in expressions when sample_design is not provided. With sample_design, inline nvariates is removed and defaults to

  1. Default: NULL (can only be NULL if sample_design with all inputs is provided).

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. If sample_design is provided, required inputs present in sample_design are created from it even when absent from mctable. Default set_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.

sample_design

(matrix, data frame, or list, optional). Sampling design used to create input nodes via matrix_to_mcnodes(). Accepts a matrix/data frame or a list with element X (typically output of sensitivity::sensitivity functions). Columns matching expression input nodes are created from this matrix. Defaults to set_sample_design().

if_not_sampled

(character). How to fill input nodes that are required by the expression but do not appear as columns in sample_design. A fixed value is computed from mctable$sample_space and replicated across all samples. Options are "median" (default), "mean", "max", and "min".

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

  • mc2d::mcstoc() and mc2d::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. If sample_design is provided, any inline nvariates argument is removed and the default nvariates = 1 is used for inline nodes. Other arguments are preserved, for example specify type = "0" when providing data without variability/uncertainty (see mc2d::mcdata() and mc2d::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. When sample_design is provided, required inputs that match sample_design column names are also created from sample_design even if they are not listed in mctable.

  • 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() unless
# sample_design is provided, in which case inline nvariates defaults to 1).
expr_example <- quote({
  # Within-herd prevalence (assigned from a pre-built mcnode w_prev)
  infected <- 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 <- infected * test_origin * (1 - test_sensi) * (1 - clinic_sensi)

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

  # no_detect: total probability an infected animal is not detected
  no_detect <- false_neg + no_test
})

# Evaluate
eval_module(
  exp = expr_example,
  data = imports_data,
  mctable = imports_mctable,
  data_keys = imports_data_keys
)
#> expr_example evaluated
#> mcmodule created (expressions: expr_example)
#> $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
#> $exp$expr_example
#> {
#>     infected <- w_prev
#>     clinic_sensi <- mcstoc(runif, min = 0.6, max = 0.8)
#>     false_neg <- infected * test_origin * (1 - test_sensi) * 
#>         (1 - clinic_sensi)
#>     no_test <- infected * (1 - test_origin) * (1 - clinic_sensi)
#>     no_detect <- false_neg + no_test
#> }
#> 
#> 
#> $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$infected
#> $node_list$infected$type
#> [1] "out_node"
#> 
#> $node_list$infected$node_exp
#> [1] "w_prev"
#> 
#> $node_list$infected$inputs
#> [1] "w_prev"
#> 
#> $node_list$infected$exp_name
#> [1] "expr_example"
#> 
#> $node_list$infected$mc_name
#> [1] "infected"
#> 
#> $node_list$infected$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$infected$exp_param
#> [1] "w_prev"
#> 
#> $node_list$infected$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$infected$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
#> $node_list$false_neg$function_call
#> [1] TRUE
#> 
#> $node_list$false_neg$type
#> [1] "out_node"
#> 
#> $node_list$false_neg$node_exp
#> [1] "infected * test_origin * (1 - test_sensi) * (1 - clinic_sensi)"
#> 
#> $node_list$false_neg$inputs
#> [1] "infected"     "test_origin"  "test_sensi"   "clinic_sensi"
#> 
#> $node_list$false_neg$exp_name
#> [1] "expr_example"
#> 
#> $node_list$false_neg$mc_name
#> [1] "false_neg"
#> 
#> $node_list$false_neg$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$false_neg$exp_param
#> [1] "infected"     "test_origin"  "test_sensi"   "clinic_sensi"
#> 
#> $node_list$false_neg$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$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$no_test
#> $node_list$no_test$function_call
#> [1] TRUE
#> 
#> $node_list$no_test$type
#> [1] "out_node"
#> 
#> $node_list$no_test$node_exp
#> [1] "infected * (1 - test_origin) * (1 - clinic_sensi)"
#> 
#> $node_list$no_test$inputs
#> [1] "infected"     "test_origin"  "clinic_sensi"
#> 
#> $node_list$no_test$exp_name
#> [1] "expr_example"
#> 
#> $node_list$no_test$mc_name
#> [1] "no_test"
#> 
#> $node_list$no_test$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$no_test$exp_param
#> [1] "infected"     "test_origin"  "clinic_sensi"
#> 
#> $node_list$no_test$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$data_name
#> [1] "imports_data"
#> 
#> 
#> $node_list$no_detect
#> $node_list$no_detect$function_call
#> [1] TRUE
#> 
#> $node_list$no_detect$type
#> [1] "out_node"
#> 
#> $node_list$no_detect$node_exp
#> [1] "false_neg + no_test"
#> 
#> $node_list$no_detect$inputs
#> [1] "false_neg" "no_test"  
#> 
#> $node_list$no_detect$exp_name
#> [1] "expr_example"
#> 
#> $node_list$no_detect$mc_name
#> [1] "no_detect"
#> 
#> $node_list$no_detect$keys
#> [1] "pathogen" "origin"  
#> 
#> $node_list$no_detect$exp_param
#> [1] "false_neg" "no_test"  
#> 
#> $node_list$no_detect$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$data_name
#> [1] "imports_data"
#> 
#> 
#> 
#> attr(,"class")
#> [1] "mcmodule"