---
title: "Getting started with DAEDALUS"
output: rmarkdown::html_vignette
bibliography: resources/references.json
link-citations: true
vignette: >
  %\VignetteIndexEntry{Getting started with DAEDALUS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This vignette shows how to get started with the DAEDALUS model adapted from @haw2022 in R.

```{r libraries}
# load the package
library(daedalus)
library(ggplot2)
```

## Representing countries and territories

The model can be run for any country or territory included in package data simply by passing its name to `daedalus()`.
The `country_names` vector holds a list of country and territory names for which data is available.

Passing the country name directly leads to the model accessing country characteristics stored as package data.
To modify country characteristics, for example to examine assumptions around changed contact patterns, users should instead create an object of the class `<daedalus_country>`, which allows setting certain country characteristics to custom values.

The class also allows users to collect country data in one place more easily.

```{r make_country}
# get default values for Canada (chosen for its short name)
daedalus_country("Canada")

# make a <daedalus_country> representing Canada
# and modify contact patterns
country_canada <- daedalus_country(
  "Canada",
  parameters = list(
    contact_matrix = matrix(5, 4, 4) # uniform contacts across age groups
  )
)

# print to examine; only some essential information is shown
country_canada
```

The package provides data from @walker2020 on country demography, country workforce per economic sector, and social contacts between age groups in `country_data`.
The package also provides data from @jarvis2024 on workplace contacts in economic sectors.
Both datasets are accessed by internal functions to reduce the need for user input.

## Representing infection parameters

_daedalus_ allows users to quickly model one of seven historical epidemics by accessing infection parameters associated with those epidemics, which are stored as package data.
Epidemics with associated infection parameters are given in the package as `daedalus::epidemic_names`.

```{r epidemic_names}
daedalus::epidemic_names
```

Users can pass the epidemic names directly to `daedalus()` to use the default infection parameters.

```r
# not run
output <- daedalus("Canada", "influenza_1918")
```

To modify infection parameters associated with an epidemic, users should create a `<daedalus_infection>` class

Users can also override epidemic-specific infection parameter values when creating the `<infection>` class object. The `infection()` class helper function has more details on which parameters are included.

```{r example_infection_class}
# SARS-1 (2004) but with an R0 of 2.3
daedalus_infection("sars_cov_1", r0 = 2.3)

# Influenza 1918 but with mortality rising with age
daedalus_infection("influenza_1918", omega = c(0.01, 0.02, 0.03, 0.1))
```

## Representing vaccine investment for pandemic preparedness

_daedalus_ includes a vaccination response in the model. The default response assumes no advance, pre-pandemic investment in a vaccine specific to the pandemic-causing pathogen.

This scenario (`vaccine_investment = "none"`) is intended to represent the Covid-19 pandemic, and assumes that a vaccine only becomes available 1 year after the pandemic begins, that it is slow to roll out, and that uptake is low.

These parameters are contained in the package data `daedalus::vaccine_scenario_data`, for a total of four scenarios of advance vaccine investment ("none", "low", "medium", and "high").

Vaccine investment scenarios can be passed a string to `daedalus()` to use the default parameters for each scenario, or as a `<daedalus_vaccination>` object using `daedalus_vaccination(name, <PARAMETERS>)` to modify vaccination parameters.

```{r}
# the default vaccine investment scenario
daedalus_vaccination("none")
```

## Running the model

Run the model by passing the `country` and `infection` arguments to `daedalus()`.
The vaccine investment scenarios is automatically assumed to be "none".

```{r run_model}
# simulate a Covid-19 wild type outbreak in Canada; using default parameters
data <- daedalus("Canada", "sars_cov_2_pre_alpha")
```

The model runs for 300 timesteps by default; timesteps should be interpreted as days since model parameters are in terms of days.

Plot the data to view the epidemic curve.

```{r plot_epidemic}
data <- get_data(data)
ggplot(
  data[data$compartment == "infect_symp" & data$age_group == "20-65", ]
) +
  geom_line(
    aes(time, value, colour = econ_sector),
    show.legend = FALSE
  ) +
  facet_wrap(
    facets = vars(age_group)
  )
```

## References