mcmodule (version 1.2.0)

eval_module: Evaluate Monte Carlo Model Expressions

Description

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
)

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.

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.

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
)