MetaRVM

This is a compartmental model simulation code for generic respiratory virus diseases.

Model

MetaRVM is an open-source R package for modeling the spread of infectious diseases in subpopulations, which can be flexibly defined by geography, demographics, or other stratifications. It is designed to support real-time public health decision-making. MetaRVM is a metapopulation model, which extends the classic Susceptible-Infected-Recovered (SIR) framework by propagating infection across interacting subpopulations (e.g., age groups, neighborhoods), whose interactions are governed by realistic mixing patterns.

The MetaRVM model builds upon the SEIR framework by introducing additional compartments to capture more detailed dynamics of disease progression, while allowing for heterogeneous mixing among different demographic stratum. These generalizations allow the model to account for factors such as vaccinations, hospitalizations, and fatalities.

For more details, please refer to the paper: Developing and deploying a use-inspired metapopulation modeling framework for detailed tracking of stratified health outcomes

Documentation

Full documentation is available at: https://RESUME-Epi.github.io/MetaRVM/

Quickstart guide

Installation

install.packages("MetaRVM")

The development version of MetaRVM can be installed from GitHub with:

# install.packages("devtools")
devtools::install_github("RESUME-Epi/MetaRVM")

Running a simulation

library(MetaRVM)
options(odin.verbose = FALSE)

## prepare the configuration file
cfg <- system.file("extdata", "example_config.yaml", package = "MetaRVM")

The content of the yaml configuration file:

run_id: ExampleRun
population_data:
  mapping: demographic_mapping_n24.csv
  initialization: population_init_n24.csv
  vaccination: vaccination_n24.csv
mixing_matrix:
  weekday_day: m_weekday_day.csv
  weekday_night: m_weekday_night.csv
  weekend_day: m_weekend_day.csv
  weekend_night: m_weekend_night.csv
disease_params:
  ts: 0.5
  tv: 0.25
  ve: 0.4
  dv: 180
  dp: 1
  de: 3
  da: 5
  ds: 6
  dh: 8
  dr: 180
  pea: 0.3
  psr: 0.95
  phr: 0.97
simulation_config:
  start_date: 10/01/2023 # m/d/Y
  length: 150
  nsim: 1

# run simulation
sim_out <- metaRVM(cfg)
#> Loading required namespace: pkgbuild

# basic plot: daily hospitalizations by date
library(ggplot2)
hosp <- sim_out$results[disease_state == "H"]
hosp_sum <- hosp[disease_state == "H", .(total = sum(value)), by = "date"]
ggplot(hosp_sum, aes(date, total)) +
  geom_line(, color = "red") +
  labs(y = "Hospitalizations", x = "Date") + theme_bw()

Model structure

MetaRVM implements a stratified SEIR-type metapopulation model with vaccination, hospitalization, immunity waning, and reinfection. The core health states in each demographic stratum are:

• Susceptible S
• Vaccinated V
• Exposed E
• Asymptomatic infectious I_asymp
• Presymptomatic infectious I_presymp
• Symptomatic infectious I_symp
• Hospitalized H
• Recovered R
• Deceased D

At the start of a simulation, nearly all individuals are in S, with optional seeding of initial infections and/or vaccinated individuals in V. When susceptible or vaccinated individuals come into contact with infectious individuals, they become exposed (E) based on age/stratum-specific forces of infection and vaccine protection. Exposed individuals then progress through asymptomatic, presymptomatic, and symptomatic infectious states before either recovering, being hospitalized, or dying. Vaccinated and recovered immunity can wane over time, returning individuals to the susceptible pool, which allows MetaRVM to represent multiple respiratory pathogens with different natural histories.

Transmission is stratified by user-defined demographic groups (e.g., age, zone, race). Time-varying mixing matrices define how these strata interact (daytime vs. nighttime, weekday vs. weekend), and MetaRVM computes stratum-specific forces of infection for susceptible and vaccinated individuals. Hospitalized and deceased individuals are excluded from the “effective” mixing population. The same model can be run in deterministic or stochastic mode, and parameters are supplied through a YAML configuration.

Core disease progression parameters

Transmission and mixing parameters

These parameters drive the transitions from S and V to E, and determine how quickly individuals move through infectious, hospitalized, recovered, and deceased states.

Required input data and configuration

MetaRVM is configured through a YAML file and a small set of CSV inputs.

Model output structure

MetaRVM produces simulation results in a unified tidy long-format table that is easy to analyze with data.table, dplyr, or ggplot2. Every record corresponds to a single compartment count or flow quantity for a specific demographic stratum, simulation date, and scenario/instance.

The core output is available in:

• sim$results — compartment counts and flows for each day
  
• sim$config — the configuration object used to generate the run

Further examples and full documentation

MetaRVM includes several vignettes that demonstrate common workflows using real model configurations and data. These provide detailed, step-by-step examples of how to prepare inputs, configure the model, run simulations, and analyze outputs.

The vignettes can be accessed at:

https://resume-epi.github.io/MetaRVM/articles/

List of vignettes:

• Getting Started
  A gentle introduction showing how to load a configuration file, run a simulation, and inspect outputs.

• Model Configurations
  A detailed walkthrough of the YAML structure, required fields, parameter blocks, optional modules, and how to define population strata and mixing patterns.

• Running Simulation
  Full example using a complete set of input files, showing how MetaRVM reads population mappings, mixing matrices, and vaccination schedules.

• Checkpointing and Restoring
  Demonstrates how to run many scenarios at scale, resume long runs, and store intermediate model states.

For the complete function reference, visit:

https://resume-epi.github.io/MetaRVM/reference/

mirror server hosted at Truenetwork, Russian Federation.