| Title: | Meta-Population Compartmental Model for Respiratory Virus Diseases |
|---|---|
| Description: | Simulates respiratory virus epidemics using meta-population compartmental models following Fadikar et. al. (2025) <doi:10.1109/WSC68292.2025.11338996>. 'MetaRVM' implements a stochastic SEIRD (Susceptible-Exposed-Infected-Recovered-Dead) framework with demographic stratification by user provided attributes. It supports complex epidemiological scenarios including asymptomatic and presymptomatic transmission, hospitalization dynamics, vaccination schedules, and time-varying contact patterns via mixing matrices. |
| Authors: | Arindam Fadikar [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-7396-0350>), Charles Macal [ctb], Martinez Moyano Ignacio Javier [ctb], Ozik Jonathan [ctb] |
| Maintainer: | Arindam Fadikar <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.1.0 |
| Built: | 2026-05-26 10:33:56 UTC |
| Source: | https://github.com/resume-epi/metarvm |
This function formats raw MetaRVM simulation output by:
Converting time steps to calendar dates
Adding user-defined demographic attributes from the initialization-derived population metadata
Handling different disease states appropriately:
Regular states (S, E, I, etc.): Keep values at integer time points
New count states (n_ prefix): Sum pairs to get daily counts
format_metarvm_output(sim_output, config)format_metarvm_output(sim_output, config)
sim_output |
data.table containing raw simulation output from |
config |
MetaRVMConfig object or config list containing parameters |
data.table with formatted output including calendar dates and demographics
This function is used for formatting the meta_sim output when MetaRVM
function is called.
The core simulation engine that implements a stochastic compartmental SEIRD (Susceptible-Exposed-Infected-Recovered-Dead) model for respiratory virus epidemics across multiple demographic subpopulations. The function compiles and executes an ODIN-based differential equation model with time-varying contact patterns, vaccination dynamics, and complex disease progression pathways.
meta_sim( N_pop, ts, S0, I0, P0, R0, H0 = rep(0, N_pop), D0 = rep(0, N_pop), Ia0 = rep(0, N_pop), Ip0 = rep(0, N_pop), E0 = rep(0, N_pop), V0 = rep(0, N_pop), m_weekday_day, m_weekday_night, m_weekend_day, m_weekend_night, start_day = 0, delta_t, vac_mat, dv, de, pea, dp, da, ds, psr, dh, phr, dr, ve, nsteps, is.stoch = FALSE, seed = NULL, do_chk = FALSE, chk_time_steps = NULL, chk_file_names = NULL )meta_sim( N_pop, ts, S0, I0, P0, R0, H0 = rep(0, N_pop), D0 = rep(0, N_pop), Ia0 = rep(0, N_pop), Ip0 = rep(0, N_pop), E0 = rep(0, N_pop), V0 = rep(0, N_pop), m_weekday_day, m_weekday_night, m_weekend_day, m_weekend_night, start_day = 0, delta_t, vac_mat, dv, de, pea, dp, da, ds, psr, dh, phr, dr, ve, nsteps, is.stoch = FALSE, seed = NULL, do_chk = FALSE, chk_time_steps = NULL, chk_file_names = NULL )
N_pop |
Integer. Number of demographic subpopulations in the model |
ts |
Numeric vector or scalar. Transmission rate for symptomatic individuals in susceptible population. If scalar, applied to all subpopulations |
S0 |
Numeric vector of length N_pop. Initial number of susceptible individuals in each subpopulation |
I0 |
Numeric vector of length N_pop. Initial number of symptomatic infected individuals in each subpopulation |
P0 |
Numeric vector of length N_pop. Total population sizes for each subpopulation |
R0 |
Numeric vector of length N_pop. Initial number of recovered individuals in each subpopulation |
H0 |
Numeric vector of length N_pop. Initial number of hospitalized individuals in each subpopulation (default: rep(0, N_pop)) |
D0 |
Numeric vector of length N_pop. Initial number of deceased individuals in each subpopulation (default: rep(0, N_pop)) |
Ia0 |
Numeric vector of length N_pop. Initial number of asymptomatic infected individuals in each subpopulation (default: rep(0, N_pop)) |
Ip0 |
Numeric vector of length N_pop. Initial number of presymptomatic infected individuals in each subpopulation (default: rep(0, N_pop)) |
E0 |
Numeric vector of length N_pop. Initial number of exposed individuals in each subpopulation (default: rep(0, N_pop)) |
V0 |
Numeric vector of length N_pop. Initial number of vaccinated individuals in each subpopulation |
m_weekday_day |
Numeric matrix (N_pop × N_pop). Contact mixing matrix for weekday daytime (6 AM - 6 PM) interactions |
m_weekday_night |
Numeric matrix (N_pop × N_pop). Contact mixing matrix for weekday nighttime (6 PM - 6 AM) interactions |
m_weekend_day |
Numeric matrix (N_pop × N_pop). Contact mixing matrix for weekend daytime (6 AM - 6 PM) interactions |
m_weekend_night |
Numeric matrix (N_pop × N_pop). Contact mixing matrix for weekend nighttime (6 PM - 6 AM) interactions |
start_day |
Start day of the week expressed as an integer value between 0 and 6, 0 being Monday. Default simulation start day is Monday. |
delta_t |
Positive numeric. Discrete time increment in days (typically 0.5) |
vac_mat |
Numeric matrix. Vaccination schedule with dimensions (nsteps × (1 + N_pop)). First column contains time indices, remaining columns contain vaccination counts for each subpopulation at each time step |
dv |
Numeric vector or scalar. Mean duration (days) in vaccinated state before immunity waning. If scalar, applied to all subpopulations |
de |
Numeric vector or scalar. Mean duration (days) in exposed state. If scalar, applied to all subpopulations |
pea |
Numeric vector or scalar. Proportion of exposed individuals becoming asymptomatic infectious (vs. presymptomatic), values between 0 and 1. If scalar, applied to all subpopulations. If scalar, applied to all subpopulations |
dp |
Numeric vector or scalar. Mean duration (days) in presymptomatic infectious state. If scalar, applied to all subpopulations |
da |
Numeric vector or scalar. Mean duration (days) in asymptomatic infectious state. If scalar, applied to all subpopulations |
ds |
Numeric vector or scalar. Mean duration (days) in symptomatic infectious state. If scalar, applied to all subpopulations |
psr |
Numeric vector or scalar. Proportion of symptomatic individuals recovering directly (vs. hospitalization), values between 0 and 1. If scalar, applied to all subpopulations. If scalar, applied to all subpopulations |
dh |
Numeric vector or scalar. Mean duration (days) in hospitalized state. If scalar, applied to all subpopulations |
phr |
Numeric vector or scalar. Proportion of hospitalized individuals recovering (vs. death). , values between 0 and 1. If scalar, applied to all subpopulations. |
dr |
Numeric vector or scalar. Mean duration (days) of immunity in recovered state. If scalar, applied to all subpopulations |
ve |
Numeric vector or scalar. Vaccine effectiveness (proportion) , values between 0 and 1. If scalar, applied to all subpopulations |
nsteps |
Integer. Total number of discrete time evolution steps in simulation |
is.stoch |
Logical. Whether to run stochastic simulation (TRUE) or deterministic simulation (FALSE). Default: FALSE |
seed |
Integer or NULL. Random seed for reproducibility. Only used when is.stoch = TRUE. Default: NULL |
do_chk |
Logical. Whether to save model checkpoint at simulation end. Default: FALSE |
chk_time_steps |
Integer vector or NULL. Time steps at which to save checkpoints. |
chk_file_names |
List of character vectors or NULL. File names for checkpoints.
Each element of the list corresponds to a time step in |
The model implements a metapopulation epidemiological framework with the following features:
Compartmental Structure:
S: Susceptible individuals
E: Exposed (incubating) individuals
I_presymp: Presymptomatic infectious individuals
I_asymp: Asymptomatic infectious individuals
I_symp: Symptomatic infectious individuals
H: Hospitalized individuals
R: Recovered individuals
D: Deceased individuals
V: Vaccinated individuals
P: Total living population (excludes deaths)
Disease Progression Pathways:
S → E: Exposure through contact with infectious individuals
E → I_asymp/I_presymp: Progression to infectious states (proportion pea)
I_presymp → I_symp: Development of symptoms
I_asymp → R: Direct recovery from asymptomatic state
I_symp → R/H: Recovery or hospitalization (proportion psr)
H → R/D: Hospital discharge or death (proportion phr)
R → S: Loss of immunity
S → V: Vaccination
V → S/E: Vaccine waning or breakthrough infection
Mixing Patterns: Contact patterns vary by:
Day of week: Weekday vs. weekend patterns
Time of day: Day (6 AM - 6 PM) vs. night (6 PM - 6 AM) patterns
Each pattern specified by N_pop × N_pop contact matrix
Force of Infection: Transmission occurs through contact between susceptible/vaccinated individuals and all infectious compartments (I_presymp + I_asymp + I_symp), modified by:
Population-specific transmission rate, ts
Time-varying contact patterns
Vaccine effectiveness for breakthrough infections
Stochastic vs. Deterministic Mode:
Deterministic: Uses exact differential equations
Stochastic: Adds demographic stochasticity via binomial draws
Vaccination Implementation: Vaccination is implemented as time-varying input with:
Scheduled vaccination counts per time step and subpopulation
Vaccine effectiveness reducing infection probability
Waning immunity returning individuals to susceptible state
Returns a data.table with the following structure:
Integer time step index (0 to nsteps)
Continuous simulation time (step × delta_t)
Character vector of compartment names
Character vector of subpopulation identifiers
Numeric values representing population counts in each compartment
Available disease states in output:
Core compartments: S, E, I_presymp, I_asymp, I_symp, H, R, D, V, P
Derived outputs: I_all (total infectious), cum_V (cumulative vaccinations)
Transition flows: n_SE, n_EI, n_HR, n_HD, etc. (new infections, hospitalizations, deaths)
Debug outputs: p_SE, p_VE, I_eff (probabilities and effective populations)
All duration parameters are automatically converted to rates (1/duration). Scalar parameters are automatically expanded to vectors of length N_pop. This allows flexible specification of homogeneous or heterogeneous parameters.
When do_chk = TRUE, the function saves a checkpoint file containing:
Final compartment states for simulation continuation
All model parameters for reproducibility
Vaccination schedule data
Population structure information
Arindam Fadikar, Charles Macal, Ignacio Martinez-Moyano, Jonathan Ozik
ODIN package: https://mrc-ide.github.io/odin/
Fadikar, A., et al. "Developing and deploying a use-inspired metapopulation modeling framework for detailed tracking of stratified health outcomes"
metaRVM for high-level simulation interface with configuration files
parse_config for configuration file processing
format_metarvm_output for output formatting with demographics
options(odin.verbose = FALSE) # Basic deterministic simulation N_pop <- 2 nsteps <- 400 # Initialize populations S0 <- rep(1000, N_pop) I0 <- rep(10, N_pop) P0 <- S0 + I0 R0 <- rep(0, N_pop) # Contact matrices (simplified - identity matrices) contact_matrix <- diag(N_pop) # Basic vaccination schedule (10% vaccination) vac_mat <- matrix(0, nrow = nsteps + 1, ncol = N_pop + 1) vac_mat[, 1] <- 0:nsteps vac_mat[1, 1 + (1:N_pop)] <- P0 * 0.1 # Run simulation results <- meta_sim( N_pop = N_pop, ts = 0.5, S0 = S0, I0 = I0, P0 = P0, R0 = R0, m_weekday_day = contact_matrix, m_weekday_night = contact_matrix, m_weekend_day = contact_matrix, m_weekend_night = contact_matrix, delta_t = 0.5, vac_mat = vac_mat, dv = 365, de = 3, pea = 0.3, dp = 2, da = 7, ds = 7, psr = 0.95, dh = 10, phr = 0.9, dr = 180, ve = 0.8, nsteps = nsteps, is.stoch = FALSE )options(odin.verbose = FALSE) # Basic deterministic simulation N_pop <- 2 nsteps <- 400 # Initialize populations S0 <- rep(1000, N_pop) I0 <- rep(10, N_pop) P0 <- S0 + I0 R0 <- rep(0, N_pop) # Contact matrices (simplified - identity matrices) contact_matrix <- diag(N_pop) # Basic vaccination schedule (10% vaccination) vac_mat <- matrix(0, nrow = nsteps + 1, ncol = N_pop + 1) vac_mat[, 1] <- 0:nsteps vac_mat[1, 1 + (1:N_pop)] <- P0 * 0.1 # Run simulation results <- meta_sim( N_pop = N_pop, ts = 0.5, S0 = S0, I0 = I0, P0 = P0, R0 = R0, m_weekday_day = contact_matrix, m_weekday_night = contact_matrix, m_weekend_day = contact_matrix, m_weekend_night = contact_matrix, delta_t = 0.5, vac_mat = vac_mat, dv = 365, de = 3, pea = 0.3, dp = 2, da = 7, ds = 7, psr = 0.95, dh = 10, phr = 0.9, dr = 180, ve = 0.8, nsteps = nsteps, is.stoch = FALSE )
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.
metaRVM(config_input)metaRVM(config_input)
config_input |
Configuration specification in one of three forms:
|
The configuration input controls:
Population structure (user-defined categories and the initial compartment counts from the initialization file)
Disease parameters (ts, 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():
Parses the YAML configuration via parse_config().
Calls the ODIN-based simulation engine meta_sim() for each instance.
Uses format_metarvm_output() to convert time steps to dates and
attach demographic attributes.
Wraps the formatted output and metadata in a MetaRVMResults
object that supports method chaining for subsetting, summarizing,
and plotting.
A MetaRVMResults R6 object with three key components:
A tidy data.table with one row per
date–subpopulation–disease state–instance combination. Typical
columns include:
date: calendar date (Date)
user-defined demographic category columns (if present in the initialization file)
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, …)
The MetaRVMConfig object used for the run.
A list with metadata such as n_instances,
date_range, delta_t, and checkpoint information.
Arindam Fadikar, Charles Macal, Ignacio Martinez-Moyano, Jonathan Ozik
Fadikar, A., et al. "Developing and deploying a use-inspired metapopulation modeling framework for detailed tracking of stratified health outcomes"
parse_config() for reading YAML configurations,
MetaRVMConfig for configuration management,
MetaRVMResults for analysis and plotting,
meta_sim() for the low-level simulation engine.
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 user-defined categories results$summarize( group_by = c("age", "zone"), 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)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 user-defined categories results$summarize( group_by = c("age", "zone"), 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)
R6 class to handle MetaRVM checkpoint data. This class is a simplified version of MetaRVMConfig tailored for storing and accessing simulation checkpoints.
The MetaRVMCheck class is designed to hold the state of a simulation at a
specific time point, allowing for continuation or analysis. It stores all
necessary parameters and population states.
MetaRVM::MetaRVMConfig -> MetaRVMCheck
check_dataList containing all parsed checkpoint data
MetaRVM::MetaRVMConfig$get()MetaRVM::MetaRVMConfig$get_all()MetaRVM::MetaRVMConfig$get_all_categories()MetaRVM::MetaRVMConfig$get_category_names()MetaRVM::MetaRVMConfig$get_category_values()MetaRVM::MetaRVMConfig$get_pop_map()MetaRVM::MetaRVMConfig$list_parameters()MetaRVM::MetaRVMConfig$parameter_summary()MetaRVM::MetaRVMConfig$print()MetaRVM::MetaRVMConfig$set()new()
Initialize a new MetaRVMCheck object
MetaRVMCheck$new(input)
inputA list containing checkpoint data.
A new MetaRVMCheck object.
clone()
The objects of this class are cloneable with this method.
MetaRVMCheck$clone(deep = FALSE)
deepWhether to make a deep clone.
Arindam Fadikar
R6 class to handle MetaRVM configuration data with validation and methods. This class encapsulates all configuration parameters needed for MetaRVM simulations, providing methods for parameter access, validation, and introspection.
The MetaRVMConfig class stores parsed configuration data from YAML files and provides structured access to simulation parameters. It automatically validates configuration completeness and provides convenient methods for accessing demographic categories, initialization-derived population metadata, and other simulation settings.
config_filePath to the original YAML config file (if applicable)
config_dataList containing all parsed configuration parameters
new()
Initialize a new MetaRVMConfig object
MetaRVMConfig$new(input)
inputEither a file path (character) or parsed config list
New MetaRVMConfig object (invisible)
get()
Get a configuration parameter
MetaRVMConfig$get(param)
paramParameter name
The requested parameter value
get_all()
Get all configuration parameters as a list
MetaRVMConfig$get_all()
Named list of all configuration parameters
list_parameters()
List all available parameter names
MetaRVMConfig$list_parameters()
Character vector of parameter names
parameter_summary()
Show summary of parameter types and sizes
MetaRVMConfig$parameter_summary()
Data frame with parameter information
set()
Set a configuration parameter
MetaRVMConfig$set(param, value)
paramCharacter string. Parameter name to set
valueThe value to assign to the parameter
Self (invisible) for method chaining
print()
Print summary of configuration
MetaRVMConfig$print()
Self (invisible)
get_pop_map()
Get population mapping data
MetaRVMConfig$get_pop_map()
data.table containing population_id and user-defined demographic category columns
get_category_names()
Get names of all category columns
MetaRVMConfig$get_category_names()
Category columns are automatically detected from the initialization CSV file. Any column that is not a reserved column (population_id, N, S0, I0, R0, V0, etc.) is treated as a demographic category (e.g., age, zone, income_level, occupation).
Character vector of category column names, or empty vector if no categories
\dontrun{
config <- MetaRVMConfig$new("config.yaml")
category_names <- config$get_category_names() # e.g., c("age", "zone", "risk_group")
}
get_category_values()
Get unique values for a specific category
MetaRVMConfig$get_category_values(category_name)
category_nameCharacter string specifying the category name
Character/numeric vector of unique values for the specified category
\dontrun{
config <- MetaRVMConfig$new("config.yaml")
ages <- config$get_category_values("age") # if age is defined
income_levels <- config$get_category_values("income_level") # if defined
}
get_all_categories()
Get all categories as a named list
MetaRVMConfig$get_all_categories()
Named list where names are category column names and values are vectors of unique values for each category. Returns empty list if no categories.
\dontrun{
config <- MetaRVMConfig$new("config.yaml")
all_cats <- config$get_all_categories()
# Returns: list(age = c("0-17", "18-64", "65+"), risk_group = c("low", "high"), ...)
}
clone()
The objects of this class are cloneable with this method.
MetaRVMConfig$clone(deep = FALSE)
deepWhether to make a deep clone.
Arindam Fadikar
# Initialize from YAML file example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") config <- MetaRVMConfig$new(example_config) # Access parameters config$get("N_pop") config$get("start_date") # Get demographic category names (user-defined) category_names <- config$get_category_names() # e.g., c("age", "zone", "risk_group") # Get values for specific categories ages <- config$get_category_values("age") # Get all categories as a named list all_categories <- config$get_all_categories() ## ------------------------------------------------ ## Method `MetaRVMConfig$get_category_names` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") category_names <- config$get_category_names() # e.g., c("age", "zone", "risk_group") ## End(Not run) ## ------------------------------------------------ ## Method `MetaRVMConfig$get_category_values` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") ages <- config$get_category_values("age") # if age is defined income_levels <- config$get_category_values("income_level") # if defined ## End(Not run) ## ------------------------------------------------ ## Method `MetaRVMConfig$get_all_categories` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") all_cats <- config$get_all_categories() # Returns: list(age = c("0-17", "18-64", "65+"), risk_group = c("low", "high"), ...) ## End(Not run)# Initialize from YAML file example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") config <- MetaRVMConfig$new(example_config) # Access parameters config$get("N_pop") config$get("start_date") # Get demographic category names (user-defined) category_names <- config$get_category_names() # e.g., c("age", "zone", "risk_group") # Get values for specific categories ages <- config$get_category_values("age") # Get all categories as a named list all_categories <- config$get_all_categories() ## ------------------------------------------------ ## Method `MetaRVMConfig$get_category_names` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") category_names <- config$get_category_names() # e.g., c("age", "zone", "risk_group") ## End(Not run) ## ------------------------------------------------ ## Method `MetaRVMConfig$get_category_values` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") ages <- config$get_category_values("age") # if age is defined income_levels <- config$get_category_values("income_level") # if defined ## End(Not run) ## ------------------------------------------------ ## Method `MetaRVMConfig$get_all_categories` ## ------------------------------------------------ ## Not run: config <- MetaRVMConfig$new("config.yaml") all_cats <- config$get_all_categories() # Returns: list(age = c("0-17", "18-64", "65+"), risk_group = c("low", "high"), ...) ## End(Not run)
R6 class to handle MetaRVM simulation results with comprehensive analysis and visualization methods. This class stores formatted simulation results and provides methods for data summarization, subsetting, and visualization with flexible demographic groupings.
The MetaRVMResults class automatically formats raw simulation output upon initialization, converting time steps to calendar dates and adding demographic attributes. It provides methods for flexible data summarization across any user-defined demographic categories, plus method chaining for streamlined analysis workflows.
configMetaRVMConfig object used to generate these results
resultsdata.table containing formatted simulation results
run_infoList containing run metadata
new()
Initialize a new MetaRVMResults object
MetaRVMResults$new( raw_results, config, run_info = NULL, formatted_results = NULL )
raw_resultsRaw simulation results data.table
configMetaRVMConfig object used for the simulation
run_infoOptional metadata about the run
formatted_resultsformatted simulation results data.table
New MetaRVMResults object (invisible)
print()
Print summary of results
MetaRVMResults$print()
Self (invisible)
plot()
Plot simulation trajectories directly from results
MetaRVMResults$plot( group_by = character(0), disease_states = NULL, date_range = NULL, instances = NULL, stats = NULL, quantiles = c(0.25, 0.75), exclude_p_columns = TRUE, ci_level = 0.95, theme = theme_minimal(), title = NULL )
group_byVector of demographic category names to group/facet by
disease_statesOptional disease states to include
date_rangeOptional date range for filtering
instancesOptional instance IDs to include
statsStatistics for summary plotting. If NULL, plots raw trajectories.
quantilesQuantiles for uncertainty bands when summary plotting
exclude_p_columnsLogical, whether to exclude p_ columns (default: TRUE)
ci_levelConfidence level label used in summary plot title
themeggplot2 theme function (default: theme_minimal())
titleOptional custom title
ggplot object
subset_data()
Subset the data based on any combination of parameters
MetaRVMResults$subset_data( ..., disease_states = NULL, date_range = NULL, instances = NULL, exclude_p_columns = TRUE )
...Named arguments for category filters (e.g., age = c("0-17"), income = c("low", "high"))
disease_statesVector of disease states to include (default: all, excludes p_ columns)
date_rangeVector of two dates start_date, and end_date for filtering (default: all)
instancesVector of instance numbers to include (default: all)
exclude_p_columnsLogical, whether to exclude p_ columns (default: TRUE)
MetaRVMResults object with subset of results
summarize()
Summarize results across specified demographic characteristics
MetaRVMResults$summarize(
group_by,
disease_states = NULL,
date_range = NULL,
stats = c("mean", "median", "sd"),
quantiles = c(0.25, 0.75),
exclude_p_columns = TRUE
)group_byVector of demographic category names to group by. Must be valid category names from the configuration (e.g., c("age", "zone"), c("income_level", "occupation")). Use config$get_category_names() to see available categories.
disease_statesVector of disease states to include (default: all, excludes p_ columns)
date_rangeOptional date range for filtering
statsVector of statistics to calculate: c("mean", "median", "sd", "min", "max", "sum", "quantile"). If NULL, returns all instances
quantilesVector of quantiles to calculate if "quantile" is in stats (default: c(0.25, 0.75))
exclude_p_columnsLogical, whether to exclude p_ columns (default: TRUE)
data.table with summarized time series data or all instances if stats = NULL
clone()
The objects of this class are cloneable with this method.
MetaRVMResults$clone(deep = FALSE)
deepWhether to make a deep clone.
Arindam Fadikar
options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") # Run simulation results_obj <- metaRVM(example_config) # Access formatted results head(results_obj$results) # Subset data with multiple filters subset_data <- results_obj$subset_data( age = c("18-64", "65+"), disease_states = c("H", "D"), date_range = c(as.Date("2024-01-01"), as.Date("2024-02-01")) ) # Method chaining for analysis and visualization results_obj$subset_data(disease_states = "H")$summarize( group_by = c("age", "zone"), stats = c("median", "quantile"), quantiles = c(0.25, 0.75) )$plot()options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") # Run simulation results_obj <- metaRVM(example_config) # Access formatted results head(results_obj$results) # Subset data with multiple filters subset_data <- results_obj$subset_data( age = c("18-64", "65+"), disease_states = c("H", "D"), date_range = c(as.Date("2024-01-01"), as.Date("2024-02-01")) ) # Method chaining for analysis and visualization results_obj$subset_data(disease_states = "H")$summarize( group_by = c("age", "zone"), stats = c("median", "quantile"), quantiles = c(0.25, 0.75) )$plot()
R6 class for summarized MetaRVM results with plotting capabilities and method chaining support. This class stores summarized simulation data and provides visualization methods that automatically adapt based on the data structure and grouping variables.
The MetaRVMSummary class is designed to work seamlessly with method chaining from MetaRVMResults. It stores either summary statistics (mean, median, quantiles, etc.) or individual instance data, and provides intelligent plotting methods that automatically determine appropriate visualizations based on the data structure and demographic groupings.
The class supports two data types:
Summary data: Contains aggregated statistics across simulation instances
Instance data: Contains individual trajectory data for each simulation instance
Plotting behavior adapts automatically:
Single grouping variable: Facets by demographic category, colors by disease state
Two grouping variables: Grid layout with both demographics as facet dimensions
Three grouping variables: Grid layout with first two as facets, third as color
datadata.table containing summarized results
configMetaRVMConfig object from original simulation
typeCharacter string indicating data type ("summary" or "instances")
dataSummarized data
configOriginal MetaRVMConfig object
typeType of summary ("instances" or "summary")
new()
Initialize MetaRVMSummary object
MetaRVMSummary$new(data, config, type)
datadata.table containing summarized or instance data
configMetaRVMConfig object from original simulation
typeCharacter string indicating data type ("summary" or "instances")
New MetaRVMSummary object (invisible)
print()
Print summary of the data object
MetaRVMSummary$print()
Self (invisible)
plot()
Plot method that shows median with quantile bands
MetaRVMSummary$plot(ci_level = 0.95, theme = theme_minimal(), title = NULL)
ci_levelConfidence level for empirical quantiles (default: 0.95). Only used if quantile columns are not pre-specified
themeggplot2 theme function (default: theme_minimal())
titleOptional custom plot title
This method creates time series plots with automatic layout adaptation based on grouping variables:
For summary data: Shows median lines with quantile confidence bands
Automatically determines faceting strategy based on number of grouping variables
Uses disease states for color differentiation when appropriate
The method requires specific data structure:
Summary data must contain 'median_value' and quantile columns (e.g., 'q25', 'q75')
Instance data must contain 'instance' column for individual trajectory grouping
ggplot object
clone()
The objects of this class are cloneable with this method.
MetaRVMSummary$clone(deep = FALSE)
deepWhether to make a deep clone.
Arindam Fadikar
options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config_dist.yaml", package = "MetaRVM") # Run simulation results <- metaRVM(example_config) # Typically created through method chaining summary_obj <- results$subset_data(disease_states = "H")$summarize( group_by = c("age", "zone"), stats = c("median", "quantile"), quantiles = c(0.25, 0.75) ) # Direct plotting summary_obj$plot() # Plot with custom ggplot theme and confidence level summary_obj$plot(theme = ggplot2::theme_bw())options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config_dist.yaml", package = "MetaRVM") # Run simulation results <- metaRVM(example_config) # Typically created through method chaining summary_obj <- results$subset_data(disease_states = "H")$summarize( group_by = c("age", "zone"), stats = c("median", "quantile"), quantiles = c(0.25, 0.75) ) # Direct plotting summary_obj$plot() # Plot with custom ggplot theme and confidence level summary_obj$plot(theme = ggplot2::theme_bw())
Reads and parses a YAML configuration file for MetaRVM simulations, extracting all necessary parameters for epidemic modeling including population data, disease parameters, mixing matrices, vaccination schedules, and simulation settings.
parse_config(config_file, return_object = FALSE)parse_config(config_file, return_object = FALSE)
config_file |
Character string. Path to a YAML configuration file containing model parameters and settings. |
return_object |
Logical. If |
The function processes a YAML configuration file with the following main sections:
Simulation Configuration:
random_seed: Optional random seed for reproducibility in case of stochastic simulations or stochastic parameters
nsim: Number of simulation instances (default: 1)
nrep: Number of stochastic replicates per parameter set (default: 1)
simulation_mode: Optional simulation mode. Must be one of
"deterministic" or "stochastic" (default: "deterministic").
start_date: Simulation start date in MM/DD/YYYY format
length: Simulation length in days
checkpoint_dir: Optional checkpoint directory for saving intermediate results
checkpoint_dates: Optional list of dates to save checkpoints.
restore_from: Optional path to restore simulation from checkpoint
Population Data:
initialization: CSV file with initial population states and optional
user-defined category columns. The file must contain columns
population_id, N, S0, I0, V0, R0.
Any additional columns are treated as demographic categories.
vaccination: CSV file with vaccination schedule over time. The first column must be dates
in MM/DD/YYYY format. The rest of the columns must corresponds to respective
subpopulations in the numeric order of population_id.
Mixing Matrices: Contact matrices for different time periods. Each CSV file must have a matrix of order (N_pop x N_pop), where, N_pop is the number of subpopulations. It is assumed that the i-th row and j-th column correspond to i-th and j-th subpopulations.
weekday_day, weekday_night: Weekday contact patterns
weekend_day, weekend_night: Weekend contact patterns
Disease Parameters: Epidemiological parameters (can be scalars or distributions):
ts: Transmission rate for symptomatic individuals
ve: Vaccine effectiveness
de, dp, da, ds, dh, dr: Duration parameters for different disease states
pea, psr, phr: Probability parameters for disease transitions
Sub-population Parameters:
sub_disease_params allows specification of different parameter values
for specific demographic categories (e.g., age groups, races).
The function supports stochastic parameters through distribution specifications
with dist, mu, sd, shape, rate, etc.
If return_object = FALSE (default), returns a named list containing:
Number of population groups
Data.table with population_id and user-defined demographic categories
Initial compartment populations
Vaccination schedule data
Contact mixing matrices
Disease parameter matrices (nsim × N_pop)
Simulation start date as Date object
Simulation length in days
Number of simulation instances
Number of stochastic replicates per parameter set
Simulation mode: "deterministic" or "stochastic"
Random seed used (if any)
Time step size (fixed at 0.5)
Checkpointing configuration
If return_object = TRUE, returns a MetaRVMConfig object with
methods for parameter access and validation.
Disease parameters can be specified as distributions for stochastic modeling:
lognormal: dist: "lognormal", mu: value, sd: value
gamma: dist: "gamma", shape: value, rate: value
uniform: dist: "uniform", min: value, max: value
beta: dist: "beta", shape1: value, shape2: value
gaussian: dist: "gaussian", mean: value, sd: value
Population initialization file must contain columns:
population_id: Unique identifier for each population group, natural numbers
N: Total population size of the subpopulation
S0, I0, V0, R0: Initial compartment counts
Optional user-defined category columns (e.g., age, race,
zone, income_level, occupation)
Vaccination file must contain:
date (MM/DD/YYYY format) and vaccination counts for each population group
Arindam Fadikar
metaRVM for running simulations with parsed configuration
MetaRVMConfig for the configuration object class
process_vac_data for vaccination data processing
options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") # Parse configuration file and return list (backward compatible) config <- parse_config(example_config) # Parse and return MetaRVMConfig object for method chaining config_obj <- parse_config(example_config, return_object = TRUE) # Access parameters from config object config_obj$get("N_pop") config_obj$list_parameters() # Use with MetaRVM simulation results <- metaRVM(config_obj)options(odin.verbose = FALSE) example_config <- system.file("extdata", "example_config.yaml", package = "MetaRVM") # Parse configuration file and return list (backward compatible) config <- parse_config(example_config) # Parse and return MetaRVMConfig object for method chaining config_obj <- parse_config(example_config, return_object = TRUE) # Access parameters from config object config_obj$get("N_pop") config_obj$list_parameters() # Use with MetaRVM simulation results <- metaRVM(config_obj)