MetaRVM (version 1.0.0)

metaRVM: Run a MetaRVM epidemic simulation

Description

metaRVM() is the high-level entry point for running a MetaRVM metapopulation respiratory virus simulation. It parses the configuration, runs one or more simulation instances (deterministic or stochastic), formats the ODIN/MetaRVM output into a tidy long table with calendar dates and demographic attributes, and returns a MetaRVMResults object for downstream analysis and plotting.

Usage

metaRVM(config_input)

Value

A MetaRVMResults R6 object with three key components:

$results

A tidy data.table with one row per date–subpopulation–disease state–instance combination. Typical columns include:

• date: calendar date (Date)

• age, race, zone: demographic categories (if present in the population mapping)

• disease_state: compartment or flow label (e.g., S, E, I_symp, H, R, D, n_SE, n_IsympH, etc.)

• value: population count or daily flow

• instance: simulation instance index (1, 2, …)

$config

The MetaRVMConfig object used for the run.

$run_info

A list with metadata such as n_instances, date_range, delta_t, and checkpoint information.

Arguments

config_input

Configuration specification in one of three forms:

• Character string: path to a YAML configuration file.

• MetaRVMConfig object: pre-initialized configuration.

• Named list: output from parse_config() with return_object = FALSE.

Author

Arindam Fadikar, Charles Macal, Ignacio Martinez-Moyano, Jonathan Ozik

Details

The configuration input controls:

• Population structure (e.g., age, race, zone)

• Disease parameters (ts, tv, ve, de, dp, da, ds, dh, dr, pea, psr, phr, dv, etc.)

• Mixing matrices (weekday/weekend, day/night contact patterns)

• Vaccination schedule and immunity waning

• Simulation settings (start date, length, number of instances, stochastic vs. deterministic mode, checkpointing)

Internally, metaRVM():

1. Parses the YAML configuration via parse_config().

2. Calls the ODIN-based simulation engine meta_sim() for each instance.

3. Uses format_metarvm_output() to convert time steps to dates and attach demographic attributes.

4. Wraps the formatted output and metadata in a MetaRVMResults object that supports method chaining for subsetting, summarizing, and plotting.

References

Fadikar, A., et al. "Developing and deploying a use-inspired metapopulation modeling framework for detailed tracking of stratified health outcomes"

See Also

parse_config() for reading YAML configurations, MetaRVMConfig for configuration management, MetaRVMResults for analysis and plotting, meta_sim() for the low-level simulation engine.

Examples

# \donttest{
options(odin.verbose = FALSE)
example_config <- system.file("extdata", "example_config.yaml",
                              package = "MetaRVM")

# Run a single-instance simulation from a YAML file
results <- metaRVM(example_config)

# Print a high-level summary
results

# Access the tidy results table
head(results$results)

# Summarize and plot hospitalizations and deaths by age and race
results$summarize(
  group_by       = c("age", "race"),
  disease_states = c("H", "D"),
  stats          = c("median", "quantile"),
  quantiles      = c(0.25, 0.75)
)$plot()

# Using a pre-parsed configuration object
cfg <- parse_config(example_config, return_object = TRUE)
results2 <- metaRVM(cfg)
# }