Title:	Modular Monte Carlo Risk Analysis
Version:	1.2.0
Description:	Framework for building modular Monte Carlo risk analysis models. It extends the capabilities of 'mc2d' to facilitate working with multiple risk pathways, variates and scenarios. It provides tools to organize risk analysis in independent flexible modules, perform multivariate Monte Carlo node operations, automate the creation of Monte Carlo nodes and visualise risk analysis models. For more details see Ciria (2025) https://nataliaciria.com/mcmodule/.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://nataliaciria.com/mcmodule/, https://github.com/NataliaCiria/mcmodule
BugReports:	https://github.com/NataliaCiria/mcmodule/issues
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), visNetwork, igraph, ggplot2
Config/testthat/edition:	3
Imports:	dplyr, stats, utils
Depends:	mc2d, R (≥ 3.5)
LazyData:	true
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-03-02 17:38:04 UTC; 1459229
Author:	Natalia Ciria [aut, cre, cph], Alberto Allepuz [ths], Giovanna Ciaravino [ths]
Maintainer:	Natalia Ciria <nataliaciria@hotmail.com>
Repository:	CRAN
Date/Publication:	2026-03-02 17:50:02 UTC

Add Group Identifiers to Data Frame

Description

Adds group IDs for matching and alignment between data frames.

Usage

add_group_id(x, y = NULL, by = NULL)

Arguments

Value

Data frame or list of data frames with added group identifiers (g_id, g_row).

Add Prefix to mcnode Names

Description

Adds a prefix to node names and their input references. Existing prefixes are preserved to avoid breaking references.

Usage

add_prefix(mcmodule, prefix = NULL, rewrite_module = NULL)

Arguments

Value

The mcmodule with prefixed node names.

Examples

print(names(imports_mcmodule$node_list))
imports_mcmodule_prefix<-purchase <- add_prefix(imports_mcmodule)
print(names(imports_mcmodule_prefix$node_list))

Aggregate mcnode Values Across Groups

Description

Aggregates node values across grouping variables using various methods (combined probability, sum, mean, or automatic selection). Returns an updated mcmodule with new aggregated node.

Usage

agg_totals(
  mcmodule,
  mc_name,
  agg_keys = NULL,
  agg_suffix = NULL,
  prefix = NULL,
  name = NULL,
  summary = TRUE,
  keep_variates = FALSE,
  agg_func = NULL
)

Arguments

Value

mcmodule with new aggregated node added

Examples

imports_mcmodule <- agg_totals(
  imports_mcmodule, "no_detect_a",
  agg_keys = c("scenario_id", "pathogen")
)
print(imports_mcmodule$node_list$no_detect_a_agg$summary)

Example Animal Import Data

Description

A dataset containing information about animal imports from three different regions.

Usage

animal_imports

Format

animal_imports

A data frame with 3 rows and 4 columns:

origin

Region of origin (nord, south, east)

farms_n

Number of farms exporting animals

animals_n_mean

Mean number of animals exported per farm

animals_n_sd

Standard deviation of animals exported per farm

Source

Simulated data for demonstration purposes

Combine Probabilities Assuming Independence

Description

Combines probabilities of multiple independent events using the formula: P(at least one) = 1 - (1-P(A)) * (1-P(B)) * ... Automatically matches dimensions and keys.

Usage

at_least_one(
  mcmodule,
  mc_names,
  name = NULL,
  all_suffix = NULL,
  prefix = NULL,
  summary = TRUE
)

Arguments

Value

Updated mcmodule with new combined probability node.

Examples

module <- list(
  node_list = list(
    p1 = list(
      mcnode = mcstoc(runif,
        min = mcdata(c(0.1, 0.2, 0.3), type = "0", nvariates = 3),
        max = mcdata(c(0.2, 0.3, 0.4), type = "0", nvariates = 3),
        nvariates = 3
      ),
      data_name = "data_x",
      keys = c("category")
    ),
    p2 = list(
      mcnode = mcstoc(runif,
        min = mcdata(c(0.5, 0.6, 0.7), type = "0", nvariates = 3),
        max = mcdata(c(0.6, 0.7, 0.8), type = "0", nvariates = 3),
        nvariates = 3
      ),
      data_name = "data_y",
      keys = c("category")
    )
  ),
  data = list(
    data_x = data.frame(
      category = c("A", "B", "C"),
      scenario_id = c("0", "0", "0")
    ),
    data_y = data.frame(
      category = c("B", "B", "B"),
      scenario_id = c("0", "1", "2")
    )
  )
)

module <- at_least_one(module, c("p1", "p2"), name = "p_combined")
print(module$node_list$p_combined$summary)

Validate and Prepare mctable Data Frame

Description

Validates that an mctable contains required columns (mcnode, mc_func), issues warnings for missing columns, and auto-fills missing optional columns with NA.

Usage

check_mctable(data)

Arguments

Details

If mc_func is missing, all nodes are treated as deterministic (no uncertainty). Optional columns are auto-filled with NA if absent.

Value

The validated data frame with all standard mctable columns present, with missing optional columns filled as NA.

Combine Two mcmodule Objects

Description

Combines two mcmodule objects into a single mcmodule by merging their data and node lists.

Usage

combine_modules(mcmodule_x, mcmodule_y)

Arguments

Value

An mcmodule object with combined data and node lists.

Examples

module_x <- list(
  data = list(data_x = data.frame(x = 1:3)),
  node_list = list(
    node1 = list(type = "in_node"),
    node2 = list(type = "out_node")
  ),
  modules = c("module_x"),
  exp = quote({node2 <- node1 * 2})
)

module_y <- list(
  data = list(data_y = data.frame(y = 4:6)),
  node_list = list(node3 = list(type = "out_node")),
  modules = c("module_y"),
  exp = quote({node3 <- node1 + node2})
)

module_xy <- combine_modules(module_x, module_y)

Create mcnodes from Data and Configuration Table

Description

Creates mcnodes based on mctable specifications and input data. Applies transformations and generates mcnodes in the calling environment.

Usage

create_mcnodes(data, mctable = set_mctable(), envir = parent.frame())

Arguments

Value

NULL (invisibly). mcnodes created in envir.

Examples

create_mcnodes(
  data = imports_data,
  mctable = imports_mctable
)

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
)

Arguments

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"].

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.

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
)

Generate Edge Table for Network Visualisation

Description

Creates a data frame containing edge relationships between nodes in a Monte Carlo module network. Each row represents a directed edge from one node to another.

Usage

get_edge_table(mcmodule, inputs = FALSE)

Arguments

Value

A data frame with columns node_from and node_to representing network edges.

Examples

edge_table <- get_edge_table(imports_mcmodule)

Get Nodes from Monte Carlo Module

Description

Retrieves nodes from a Monte Carlo module and assigns them to the parent environment

Usage

get_mcmodule_nodes(mcmodule, mc_names = NULL, envir = parent.frame())

Arguments

Value

A subset of the node list containing requested nodes

Create Node List from Model Expression

Description

Creates a list of nodes based on a given model expression, handling input, output, and previous nodes with their properties and relationships.

Usage

get_node_list(
  exp,
  param_names = NULL,
  mctable = set_mctable(),
  data_keys = set_data_keys(),
  keys = NULL
)

Arguments

Value

A list of class "mcnode_list" containing node information

Generate Node Table for Network Visualisation

Description

Creates a data frame containing node information from a Monte Carlo module network. Includes node attributes, values, and relationships.

Usage

get_node_table(mcmodule, variate = 1, inputs = FALSE)

Arguments

Value

A data frame containing node information and attributes.

Examples

node_table <- get_node_table(imports_mcmodule)

Merged Import Data for Risk Assessment

Description

A dataset combining information about animal imports, pathogen prevalence, and test sensitivity across regions.

Usage

imports_data

Format

imports_data

A data frame with 6 rows and 12 columns:

pathogen

Pathogen identifier (a or b)

origin

Region of origin (nord, south, east)

h_prev_min

Minimum herd prevalence value

h_prev_max

Maximum herd prevalence value

w_prev_min

Minimum within-herd prevalence value

w_prev_max

Maximum within-herd prevalence value

farms_n

Number of farms exporting animals

animals_n_mean

Mean number of animals exported per farm

animals_n_sd

Standard deviation of animals exported per farm

test_origin

Test used to detect infected animals at origin

test_sensi_min

Minimum test sensitivity value

test_sensi_mode

Most likely test sensitivity value

test_sensi_max

Maximum test sensitivity value

Source

Simulated data for demonstration purposes

Example Data Keys for Animal Imports Risk Assessment

Description

A hierarchical data structure containing test sensitivity, animal import, and regional prevalence information, each with defined columns and keys.

Usage

imports_data_keys

Format

A list with three components:

test_sensitivity

List containing column names for test sensitivity data and "pathogen" as key

animal_imports

List containing column names for animal import data and "origin" as key

prevalence_region

List containing column names for prevalence data with "pathogen" and "origin" as keys

Source

Simulated data for demonstration purposes

Expression for Calculating Import Infection Probability

Description

A quoted R expression that calculates the probability of importing an infected animal from an infected herd, taking into account testing procedures and accuracy.

Usage

imports_exp

Format

A quoted R expression containing the following variables:

w_prev

Within-herd prevalence

test_origin

Probability of testing at origin

test_sensi

Test sensitivity

inf_a

Probability of animal being infected

false_neg_a

Probability of false negative test result

no_test_a

Probability of no testing

no_detect_a

Overall probability of non-detection

Example Monte Carlo Module for Animal Imports Risk Assessment

Description

A list containing simulation results for pathogen testing of animal imports from different origins, including:

• Within-herd prevalence (w_prev)

• Test sensitivity (test_sensi)

• Test origin probability (test_origin)

• Infection probability (inf_a)

• False negative probability (false_neg_a)

• No test probability (no_test_a)

• Non-detection probability (no_detect_a)

Usage

imports_mcmodule

Format

An mcmodule object with the following components:

data

Input data frame with 6 rows and 13 variables

exp

Model expressions for calculating probabilities

node_list

List of Monte Carlo nodes with simulation results

modules

Character vector of module names

Source

Simulated data for demonstration purposes

Example Monte Carlo Input Table for Import Risk Assessment

Description

A configured table of Monte Carlo nodes used for modeling import risk scenarios, particularly focused on animal disease transmission pathways.

Usage

imports_mctable

Format

imports_mctable

A data frame with 7 rows and 7 columns:

mcnode

Node identifier used in Monte Carlo simulations

description

Human-readable description of what the node represents

mc_func

R function used for random number generation (e.g., runif, rnorm, rpert)

from_variable

Dependency reference to other variables if applicable

transformation

Mathematical transformations applied to the node values

sensi_baseline

Parameters for baseline mock distribution without uncertainty

sensi_variation

OAT variation expression using 'value' placeholder

Source

Simulated data for demonstration purposes

Match and Align Keys Between Datasets

Description

Matches and aligns keys between two datasets for downstream operations.

Usage

keys_match(x, y, keys_names = NULL)

Arguments

Value

A list containing:

Filter mcnode Variates by Condition

Description

Filters variates (data rows) from an mcnode based on logical conditions, similar to dplyr::filter(). Can return a new node in the mcmodule or return a filtered mcnode directly.

Usage

mc_filter(
  mcmodule = NULL,
  mc_name = NULL,
  ...,
  data = NULL,
  mcnode = NULL,
  name = NULL,
  prefix = NULL,
  filter_suffix = "filtered",
  summary = TRUE
)

Arguments

Details

Call signatures:

• To add filtered node to mcmodule: mc_filter(mcmodule, "node", conditions, name = "new_name")

• To return filtered mcnode only: mc_filter(conditions, data = data, mcnode = mcnode)

Filter conditions work on variates (data rows); only rows meeting all conditions are retained in the resulting mcnode.

Value

Either:

• Updated mcmodule with new filtered node (when mcmodule and name provided).

• Filtered mcnode object (when only data and mcnode provided).

Either:

• An updated mcmodule with a new filtered node (when mcmodule and name are provided)

• A raw filtered mcnode object (when only data and mcnode are provided)

Examples

# Filter within an mcmodule and create new node
imports_mcmodule <- mc_filter(
  imports_mcmodule,
  "w_prev",
  origin == "nord",
  name = "w_prev_countryA"
)

# Filter and return raw mcnode (note: conditions before named args)
w_prev <- imports_mcmodule$node_list$w_prev$mcnode
w_prev_filtered <- mc_filter(
  origin == "nord",
  data = imports_data,
  mcnode = w_prev
)

# Multiple filter conditions
imports_mcmodule <- mc_filter(
  imports_mcmodule,
  "w_prev",
  origin == "nord",
  pathogen == "virus",
  name = "w_prev_countryA_virus"
)

Extract Key Columns from Monte Carlo Nodes

Description

Extracts key columns from a mcnode's associated data.

Usage

mc_keys(mcmodule, mc_name, keys_names = NULL)

Arguments

Value

A data frame with scenario_id and requested key columns.

Examples

keys_df <- mc_keys(imports_mcmodule, "w_prev")

Match Two Monte Carlo Nodes

Description

Matches two mcnodes by aligning groups, scenarios, or adding missing groups across different scenarios.

Usage

mc_match(mcmodule, mc_name_x, mc_name_y, keys_names = NULL)

Arguments

Details

Matching proceeds in order:

1. Group matching — align nodes with same scenarios but different group order

2. Scenario matching — align nodes with same groups but different scenarios

3. Null matching — add missing groups across different scenarios

Value

A list containing matched nodes and combined keys (keys_xy).

Examples

test_module <- list(
  node_list = list(
    node_x = list(
      mcnode = mcstoc(runif,
        min = mcdata(c(1, 2, 3), type = "0", nvariates = 3),
        max = mcdata(c(2, 3, 4), type = "0", nvariates = 3),
        nvariates = 3
      ),
      data_name = "data_x",
      keys = c("category")
    ),
    node_y = list(
      mcnode = mcstoc(runif,
        min = mcdata(c(5, 6, 7), type = "0", nvariates = 3),
        max = mcdata(c(6, 7, 8), type = "0", nvariates = 3),
        nvariates = 3
      ),
      data_name = "data_y",
      keys = c("category")
    )
  ),
  data = list(
    data_x = data.frame(
      category = c("A", "B", "C"),
      scenario_id = c("0", "0", "0")
    ),
    data_y = data.frame(
      category = c("B", "B", "B"),
      scenario_id = c("0", "1", "2")
    )
  )
)

result <- mc_match(test_module, "node_x", "node_y")

Match Monte Carlo Node with Data Frame

Description

Matches an mcnode with a data frame by aligning groups, scenarios, or adding missing groups across different scenarios.

Usage

mc_match_data(mcmodule, mc_name, data, keys_names = NULL)

Arguments

Details

Matching proceeds in order:

1. Group matching — same scenarios but different group order

2. Scenario matching — same groups but different scenarios

3. Null matching — add missing groups across different scenarios

Value

A list containing matched mcnode, matched data, and combined keys (keys_xy).

Examples

test_data  <- data.frame(pathogen=c("a","b"),
                         inf_dc_min=c(0.05,0.3),
                         inf_dc_max=c(0.08,0.4))
result<-mc_match_data(imports_mcmodule,"no_detect_a", test_data)

Create Interactive Network Visualisation

Description

Generates an interactive network visualisation using visNetwork library. The visualisation includes interactive features for exploring model structure and relationships.

Usage

mc_network(
  mcmodule,
  variate = 1,
  color_pal = NULL,
  color_by = NULL,
  legend = FALSE,
  inputs = FALSE
)

Arguments

Value

An interactive visNetwork object with highlighting of connected nodes, node selection and filtering by module, directional arrows, hierarchical layout, and draggable nodes.

Examples

network <- mc_network(mcmodule=imports_mcmodule)

Plot Monte Carlo Node Distribution with Boxplot and Scatter Points

Description

Creates a ggplot2 visualisation of Monte Carlo node data showing distributions as semi-transparent boxplots overlaid with scatter points representing individual uncertainty iterations.

Usage

mc_plot(
  mcmodule = NULL,
  mc_name = NULL,
  mcnode = NULL,
  data = NULL,
  keys_names = NULL,
  color_by = NULL,
  order_by = NULL,
  group_by = NULL,
  filter = NULL,
  threshold = NULL,
  scale = NULL,
  max_dots = 300,
  point_alpha = 0.4,
  boxplot_alpha = 0.3,
  color_pal = NULL
)

Arguments

Details

When color_by is NULL, scenarios are coloured by default: — baseline scenario (scenario_id == "0"): blue (#6ABDEB); — alternative scenarios: green (#A4CF96). Boxplots show all uncertainty iterations for statistical accuracy; scatter points are sampled to improve readability with many variates.

Value

A ggplot2 object for further customisation and display.

Examples

# Basic plot using mcmodule and mc_name
mc_plot(imports_mcmodule, "w_prev")

# Plot with custom coloring and ordering
mc_plot(imports_mcmodule, "w_prev",
  color_by = "origin",
  order_by = "median"
)

# Plot with threshold and scale transformation
mc_plot(imports_mcmodule, "no_detect_a",
  threshold = 0.5,
  scale = "log10"
)

Summarise Monte Carlo Node Values

Description

Computes summary statistics for an mcnode object, including mean, standard deviation, and quantiles. Can be called with an mcmodule and node name, or directly with an mcnode and data frame.

Usage

mc_summary(
  mcmodule = NULL,
  mc_name = NULL,
  keys_names = NULL,
  data = NULL,
  mcnode = NULL,
  sep_keys = TRUE,
  digits = NULL
)

Arguments

Details

This function can be called in two ways:

1. By providing an mcmodule and mc_name

2. By providing data and mcnode directly

Value

A data frame with summary statistics for each mcnode variate. Columns include:

• mc_name: Node name.

• Key columns (if sep_keys = TRUE) or single keys column (if FALSE).

• mean: Average value.

• sd: Standard deviation.

• Quantile columns (2.5%, 25%, 50%, 75%, 97.5%).

Examples

# Use with mcmodule
summary_basic <- mc_summary(imports_mcmodule, "w_prev")

# Using custom keys and rounding
summary_custom <- mc_summary(imports_mcmodule, "w_prev",
  keys_names = c("origin"),
  digits = 3
)

# Use with data and mcnode
w_prev <- imports_mcmodule$node_list$w_prev$mcnode
summary_direct <- mc_summary(
  data = imports_data,
  mcnode = w_prev,
  sep_keys = FALSE
)

Analyse Monte Carlo Simulation Convergence

Description

Analyses convergence in Monte Carlo simulations by computing standardised and raw differences between consecutive iterations to evaluate stability and convergence of statistical measures.

Usage

mcmodule_converg(
  mcmodule,
  from_quantile = 0.95,
  to_quantile = 1,
  conv_threshold = NULL,
  print_summary = TRUE,
  progress = FALSE
)

Arguments

Details

The function performs the following:

• Calculates convergence statistics for specified quantile range

• Generates diagnostic plots for standardized and raw differences

• Provides detailed convergence summary including:

  • Total nodes analyzed

  • Number and percentage of nodes converged at different thresholds

  • Maximum/minimum deviations

  • List of non-converged nodes (if any)

Value

A data frame with convergence statistics. Each row represents one node. Key columns:

• expression: Expression identifier.

• variate: Variate (data row) identifier.

• node: Node name.

• max_dif_scaled: Maximum standardised difference.

• max_dif: Maximum raw difference.

• conv_threshold: Convergence at custom threshold, if provided.

• conv_01, conv_025, conv_05: Convergence at 1%, 2.5%, 5% thresholds.

Examples

## Not run: 
results <- mcmodule_converg(mc_results)
results <- mcmodule_converg(mc_results, from_quantile = 0.90, conv_threshold = 0.01)

## End(Not run)

Calculate Correlation Coefficients Between Inputs and Outputs

Description

Computes correlation coefficients between mcmodule inputs and outputs using tornado analysis (from the mc2d package). Supports multiple correlation methods and captures warnings generated during calculation.

Usage

mcmodule_corr(
  mcmodule,
  output = NULL,
  by_exp = FALSE,
  match_variates = TRUE,
  variates_as_nsv = FALSE,
  print_summary = TRUE,
  progress = FALSE,
  method = c("spearman", "kendall", "pearson"),
  use = "all.obs",
  lim = c(0.025, 0.975)
)

Arguments

Value

A data frame with correlation coefficients and metadata. Columns include:

• exp: Expression name

• exp_n: Expression number

• variate: Variate number

• output: Output node name

• input: Input node name

• value: Correlation coefficient value

• strength: Qualitative strength of association (Very strong, Strong, Moderate, Weak, None)

• method: Correlation method used (spearman, kendall, or pearson)

• use: Method for handling missing values (passed to the correlation function)

• warnings: Any warnings generated during correlation calculation (if present)

• Additional columns for global keys (e.g., pathogen, origin)

Examples

mcmodule <- agg_totals(
  mcmodule = imports_mcmodule,
  mc_name = "no_detect_a",
  agg_keys = "pathogen"
)
cor_results <- mcmodule_corr(mcmodule)

# Use single method
cor_results_spearman <- mcmodule_corr(mcmodule, method = "spearman")

Check Dimension Compatibility of Monte Carlo Nodes

Description

Validates that all mcnodes in a module have compatible dimensions for sensitivity analysis by checking uncertainty and variate dimensions.

Usage

mcmodule_dim_check(mcmodule, mc_names = NULL)

Arguments

Value

A list with: n_mcnodes (count), n_variate (variate count), n_uncertainty (uncertainty simulation count).

Get Comprehensive Monte Carlo Module Information

Description

Extracts comprehensive metadata about a Monte Carlo module, including:

• Module composition (raw vs combined modules)

• Input data per expression

• Keys for each variate (data row)

• Global data keys

Usage

mcmodule_info(mcmodule)

Arguments

Details

A raw module has a single expression in mcmodule$exp. A combined module has multiple expressions in mcmodule$exp, each representing a component module that was combined via combine_modules().

For combined modules, module names are recursively extracted up to one level deep. This allows identifying all base modules even in deeply nested combinations.

Value

A list with six elements:

Examples

# Get comprehensive module information
info <- mcmodule_info(imports_mcmodule)
str(info)

# Access composition information
info$is_combined
info$n_modules
info$module_names

# Access index information
head(info$module_exp_data)
head(info$data_keys)
info$global_keys

Convert Monte Carlo Module to Matrices

Description

Transforms an mcmodule into a list of matrices, with one matrix per variate. Each matrix has uncertainty simulations as rows and mcnodes as columns.

Usage

mcmodule_to_matrices(mcmodule, mc_names = NULL)

Arguments

Value

A list of matrices (one per variate). Each matrix has uncertainty simulations as rows and mcnodes as columns.

Convert Monte Carlo Module to mc2d Objects

Description

Converts an mcmodule into one or more mc objects (from the mc2d package). Returns either one mc object per variate or a single mc object with all variates combined into the variability dimension.

Usage

mcmodule_to_mc(
  mcmodule,
  mc_names = NULL,
  match = FALSE,
  variates_as_nsv = FALSE
)

Arguments

Value

If variates_as_nsv = FALSE, a list of mc objects (one per variate). If variates_as_nsv = TRUE, a single mc object with all variates combined into the variability dimension. Each mc object is compatible with mc2d package functions.

Replace NA and Infinite Values in mcnode Objects

Description

Replaces NA and infinite values in mcnode objects with a specified value.

Usage

mcnode_na_rm(mcnode, na_value = 0)

Arguments

Value

An mcnode object with NA and infinite values replaced by na_value

Examples

sample_mcnode <- mcstoc(runif,
               min = mcdata(c(NA, 0.2, -Inf), type = "0", nvariates = 3),
               max = mcdata(c(NA, 0.3, Inf), type = "0", nvariates = 3),
               nvariates = 3
)
# Replace NA and Inf with 0
clean_mcnode <- mcnode_na_rm(sample_mcnode)

Regional Pathogen Prevalence Data

Description

A dataset containing prevalence information for two pathogens across three regions.

Usage

prevalence_region

Format

prevalence_region

A data frame with 6 rows and 4 columns:

pathogen

Pathogen identifier (a or b)

origin

Region of origin (nord, south, east)

h_prev_min

Minimum herd prevalence value

h_prev_max

Maximum herd prevalence value

w_prev_min

Minimum within-herd prevalence value

w_prev_max

Maximum within-herd prevalence value

test_origin

Test used to detect infected animals at origin

Source

Simulated data for demonstration purposes

Reset Data Keys

Description

Reset Global Data Keys

Clears and resets the global data keys to an empty state.

Usage

reset_data_keys()

Value

NULL (invisibly). Clears global data_keys.

Examples

reset_data_keys()

Reset Monte Carlo Inputs Table

Description

Clears and resets the global mctable to an empty state with standard columns.

Usage

reset_mctable()

Value

Empty data frame with standard mctable columns.

Set or Get Global Data Keys

Description

Manages a global data model by setting or retrieving data keys. The data model defines column names and their associated grouping keys for each data frame.

Usage

set_data_keys(data_keys = NULL)

Arguments

Value

Current or newly set global data model (invisibly).

Examples

print(imports_data_keys)
set_data_keys(imports_data_keys)

Set or Get Monte Carlo Inputs Table

Description

Manages the global mctable (Monte Carlo nodes reference table) by setting or retrieving its value. The table stores metadata about mcnodes including descriptions, functions, and sensitivity analysis parameters.

Usage

set_mctable(data = NULL)

Arguments

Value

Current or newly set mctable. Columns include: mcnode (required), description, mc_func, from_variable, transformation, sensi_baseline, sensi_variation.

Examples

# Get current MC table
current_table <- set_mctable()

# Set new MC table
mct <- data.frame(
  mcnode = c("h_prev", "w_prev"),
  description = c("Herd prevalence", "Within herd prevalence"),
  mc_func = c("runif", "runif")
)
set_mctable(mct)

Test Sensitivity Data for Pathogens

Description

A dataset containing test sensitivity values for two pathogens.

Usage

test_sensitivity

Format

test_sensitivity

A data frame with 2 rows and 4 columns:

pathogen

Pathogen identifier (a or b)

test_sensi_min

Minimum test sensitivity value

test_sensi_mode

Most likely test sensitivity value

test_sensi_max

Maximum test sensitivity value

Convert mcnode to Long Format for Plotting

Description

Converts an mcnode to long format suitable for ggplot2 and tidyverse analysis. Each row represents one uncertainty iteration for one variate.

Usage

tidy_mcnode(
  mcmodule = NULL,
  mc_name = NULL,
  mcnode = NULL,
  data = NULL,
  keys_names = NULL,
  filter = NULL
)

Arguments

Details

Call signatures:

• ⁠tidy_mcnode(mcmodule, \"node_name\")⁠

• tidy_mcnode(mcnode = mcnode, data = data)

• tidy_mcnode(mcmodule, mcnode = mcnode)

Value

A long data frame with columns:

• All key columns from keys_names.

• variate: Variate index (data row number).

• simulation: Uncertainty iteration index.

• value: mcnode value for that combination.

Examples

# Using mcmodule and node name
long_data <- tidy_mcnode(imports_mcmodule, "w_prev")

# Using with specific keys
long_data <- tidy_mcnode(imports_mcmodule, "w_prev",
  keys_names = "origin"
)

# Using mcnode and data directly
w_prev <- imports_mcmodule$node_list$w_prev$mcnode
long_data <- tidy_mcnode(mcnode = w_prev, data = imports_data)

# Filter variates
long_data <- tidy_mcnode(imports_mcmodule, "w_prev",
  filter = pathogen == "a"
)

Trial Probability and Expected Counts

Description

Calculates probabilities and expected counts across hierarchical levels (trial, subset, set) in a structured population. Uses trial probabilities and handles nested sampling with conditional probabilities.

Usage

trial_totals(
  mcmodule,
  mc_names,
  trials_n,
  subsets_n = NULL,
  subsets_p = NULL,
  name = NULL,
  prefix = NULL,
  combine_prob = TRUE,
  all_suffix = NULL,
  level_suffix = c(trial = "trial", subset = "subset", set = "set"),
  mctable = set_mctable(),
  agg_keys = NULL,
  agg_suffix = NULL,
  keep_variates = FALSE,
  summary = TRUE,
  data_name = NULL
)

Arguments

Value

Updated mcmodule object containing combined node probabilities and probabilities/counts at trial, subset, and set levels.

Examples

imports_mcmodule <- trial_totals(
  mcmodule = imports_mcmodule,
  mc_names = "no_detect_a",
  trials_n = "animals_n",
  subsets_n = "farms_n",
  subsets_p = "h_prev",
  mctable = imports_mctable
)
print(imports_mcmodule$node_list$no_detect_a_set$summary)

Generate Formatted visNetwork Edge Table

Description

Creates a formatted edge table suitable for visualisation with visNetwork.

Usage

visNetwork_edges(mcmodule, inputs = FALSE)

Arguments

Value

A data frame containing edge information for visNetwork with columns: from, to, and id.

Generate Formatted Network Node Table for Visualisation

Description

Creates a formatted node table for visualisation with visNetwork. Includes styling and formatting for interactive network display.

Usage

visNetwork_nodes(
  mcmodule,
  variate = 1,
  color_pal = NULL,
  color_by = NULL,
  inputs = FALSE
)

Arguments

Value

A data frame formatted for visNetwork with columns: id, label, color, grouping, expression, and title (hover text).

Find mcnodes Matching a Condition

Description

Applies a test function to each mcnode in an mcmodule and returns the names of nodes where the test returns TRUE. Useful for identifying nodes with specific properties (e.g., NA values, negative values).

Usage

which_mcnode(mcmodule, test_func)

Arguments

Value

Character vector of mcnode names where test_func returns TRUE. Empty vector if no nodes meet the condition.

See Also

which_mcnode_na(), which_mcnode_inf()

Examples

# Find nodes with negative values
which_mcnode(imports_mcmodule, function(x) any(x < 0, na.rm = TRUE))

# Find nodes with values greater than 1
which_mcnode(imports_mcmodule, function(x) any(x > 1, na.rm = TRUE))

Find mcnodes with Infinite Values

Description

Identifies which mcnodes within an mcmodule contain infinite values (Inf or -Inf). Useful for troubleshooting and debugging Monte Carlo models.

Usage

which_mcnode_inf(mcmodule)

Arguments

Value

Character vector of mcnode names containing infinite values. Returns empty vector if no infinite values found.

See Also

which_mcnode(), which_mcnode_na(), mcnode_na_rm()

Examples

# Find nodes with infinite values in the imports_mcmodule
which_mcnode_inf(imports_mcmodule)

# Create a test mcmodule with Inf values
test_mcnode_inf <- mcdata(c(0.1, Inf, 0.3), type = "0", nvariates = 3)
test_mcnode_clean <- mcdata(c(0.1, 0.2, 0.3), type = "0", nvariates = 3)
test_mcmodule <- list(
  node_list = list(
    node_a = list(mcnode = test_mcnode_inf),
    node_b = list(mcnode = test_mcnode_clean)
  )
)
which_mcnode_inf(test_mcmodule)

Find mcnodes with Missing Values

Description

Find mcnodes with Missing Values

Usage

which_mcnode_na(mcmodule)

Arguments

Details

Identifies which mcnodes within an mcmodule contain NA values. Useful for troubleshooting and debugging Monte Carlo models.

Value

Character vector of mcnode names containing NA values. Returns empty vector if no NAs found.

See Also

which_mcnode(), which_mcnode_inf(), mcnode_na_rm()

Examples

# Find nodes with NAs in the imports_mcmodule
which_mcnode_na(imports_mcmodule)

# Create a test mcmodule with NAs
test_mcnode_na <- mcdata(c(0.1, NA, 0.3), type = "0", nvariates = 3)
test_mcnode_clean <- mcdata(c(0.1, 0.2, 0.3), type = "0", nvariates = 3)
test_mcmodule <- list(
  node_list = list(
    node_a = list(mcnode = test_mcnode_na),
    node_b = list(mcnode = test_mcnode_clean)
  )
)
which_mcnode_na(test_mcmodule)

Match Datasets with Differing Scenarios

Description

Matches datasets by group and preserves baseline scenarios (scenario_id = 0) when scenarios differ between them.

Usage

wif_match(x, y, by = NULL)

Arguments

Value

A list containing matched datasets with aligned scenario IDs. Element 1: matched version of x. Element 2: matched version of y.

Examples

x <- data.frame(
  category = c("a", "b", "a", "b"),
  scenario_id = c(0, 0, 1, 1),
  value = 1:4
)

y <- data.frame(
  category = c("a", "b", "a", "b"),
  scenario_id = c(0, 0, 2, 2),
  value = 5:8
)

# Automatic matching
result <- wif_match(x, y)