# Getting Started with MetaRVM

## Introduction

MetaRVM is a comprehensive R package for simulating respiratory virus epidemics using meta-population compartmental models. This vignette describes the basic usage of the package.

## Installation

The development version of MetaRVM can be installed from GitHub:

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

## Loading the Package

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

## Basic Example

This example shows how to run a basic meta-population simulation.

The `metaRVM` package includes a set of example files in its `extdata` directory. To run the example, these files must first be located. The `system.file()` function in R is the recommended way to do this, as it finds the files wherever the package is installed.

    # Locate the example YAML configuration file
    yaml_file <- system.file("extdata", "example_config.yaml", package = "MetaRVM")
    print(yaml_file)
    #> [1] "/tmp/RtmppE20dr/Rinst15c6d7215f780c/MetaRVM/extdata/example_config.yaml"

The `yaml_file` variable now holds the full path to the example configuration file. This file is set up to use the other example data files (also in the `extdata` directory) with relative paths. Below is the content of the yaml file.

    run_id: ExampleRun
    population_data:
      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
      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: 01/01/2023 # m/d/Y
      length: 150
      nsim: 1
      nrep: 1
      simulation_mode: deterministic
      random_seed: 42

For a detailed explanation of all the configuration options, please see the `yaml-configuration.html` vignette.

## Running the Simulation

Once the path to the configuration file is available, the simulation can be run using the `metaRVM()` function.

    # Load the metaRVM library
    library(MetaRVM)

    # Run the simulation
    sim_out <- metaRVM(yaml_file)
    #> Loading required namespace: pkgbuild
    #> Generating model in c
    #> ℹ Re-compiling odin0ddd3654 (debug build)
    #> ℹ Loading odin0ddd3654

    print(sim_out)
    #> MetaRVM Results Object
    #> =====================
    #> Instances: 1
    #> Populations:
    #> Date range: 2023-10-01 to 2024-02-27
    #> Parameter sets (nsim): 1
    #> Replicates per set (nrep): 1
    #> Simulation mode: deterministic
    #> Total observations: 388800
    #> Disease states: D, E, H, I_all, I_asymp, I_eff, I_presymp, I_symp, P, R, S, S_alloc, S_eff_prod, S_src_int, V, V_alloc, V_src_int, cum_V, mob_pop, n_EI, n_EIpresymp, n_HD, n_HR, n_HRD, n_IasympR, n_IsympH, n_IsympR, n_IsympRH, n_RS, n_SE, n_SE_eff, n_SV, n_VE, n_VS, n_preIsymp, p_HRD, p_RS, p_SE, p_VE
    head(sim_out$results)
    #>          date    age   race  zone disease_state        value instance
    #>        <Date> <char> <char> <int>        <char>        <num>    <int>
    #> 1: 2023-10-01   0-17      A    11             D 2.252583e-04        1
    #> 2: 2023-10-01   0-17      A    11             E 1.365434e+01        1
    #> 3: 2023-10-01   0-17      A    11             H 2.304447e-01        1
    #> 4: 2023-10-01   0-17      A    11         I_all 2.742619e+01        1
    #> 5: 2023-10-01   0-17      A    11       I_asymp 3.555784e-01        1
    #> 6: 2023-10-01   0-17      A    11         I_eff 2.483657e+01        1

For more details on running `metaRVM`, refer to the `running-a-simulation.html` vignette.