---
title: "Micro-MoB (Microsimulation for mosquito-borne pathogens)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Micro-MoB (Microsimulation for mosquito-borne pathogens)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

**Micro-MoB** is a software package which implements a framework for building mathematical models of
mosquito-borne pathogen transmission (MBPT). The framework is flexible enough to incorporate vastly different
models while at the same time places constraints upon how parts of the framework interact so that the software does not become obfuscatingly complex each time a new feature must be added.

We define terms used to talk about **Micro-MoB** below:

  * **components**: these are the irreducible "parts" of MBPT models, and must be implemented in any model built
  in **Micro-MoB**, even if only as a trivial model (e.g. as a constant value or external forcing term). The components
  are adult mosquitoes, immature (aquatic) mosquitoes, resident (modeled) humans, non-resident visitors, and other blood hosts
  (e.g. livestock). Components can themselves have arbitrarily complex internal structure, but models in this framework insist
  each of these components be given a definition (even if it is trivial, for example the constant `0`).
  * **interface**: each component defines an interface, which other components and invariants (functions) can use to query
  information about it. The interface defines what a component is expected to compute and expose to the rest of the system.
  * **model**: a specific instantiation of a component, which necessarily fulfills that component's interface. The SIS (Susceptible-Infectious-Susceptible) model for human dynamics is a model for the human component, for example.
  * **composition pattern**: the specific set of components and how they interact in **Micro-MoB**.
  * **invariant component**: any computation which is generic across any specific set of models and which uses the generic interface
  to query state and compute values. The bloodmeal algorithm is an example, and the code
  is a contract with the modeller meaning any model fulfilling the component interface it fills will be able to interact
  with the rest of the framework, and the existing set of models. It is described in `vignette("bloodmeal")`.

### Software design

To accomplish this component-interface design in R, we use the [S3 object system](http://adv-r.had.co.nz/S3.html).
Each component is a named element in the model object (an environment). The interface
defines a set of generic functions which dispatch on the specific class of the object
taking the place of that component.

### Dynamics

A simplified schematic of the relationships between components (i.e. the model's _dynamics_) in
**Micro-MoB** is shown below.

```{r echo=FALSE, out.width='100%'}
knitr::include_graphics('./DynamicsOverview.png')
```

The aquatic (immature) mosquito component $L$ is in blue. Over a time step, it takes in eggs laid by
ovipositing adult mosquitoes $G$, and updates state, producing newly emerging adults $\Lambda$.
These emerging mosquitoes are added to the adult mosquito component (green). In the adult component,
$M$ represents the total mosquito density, $Y$ and $Z$ are infected and infectious mosquito
populations, respectively. Uninfected mosquitoes become infected by biting infectious hosts,
and during blood feeding are infected with probability $\kappa$, computed by the bloodmeal (red).
Infectious mosquitoes take bites on human hosts, resulting in a human per-capita rate of
infection $EIR$, computed by the bloodmeal, which changes prevalence of disease, $X$. The
overall human component (yellow) has dynamics acting on $H$.

## Components

For each component, the interface is defined in a file, for example, `R/humans_interface.R`
shows the user what methods must be defined for any human model.

A specific implementation of a component is a model, and files that replace _\_interface_ with the
model name implement that model (e.g. `R/humans_SIS.R` implements a SIS model). 

We list the components which require interfaces below and specific models
to implement them.

### Mosquitoes

The mosquito component is responsible for all dynamics which update adult mosquito
populations. The interface is defined in `R/mosquito_interface.R`, and the interface
methods which are required to be implemented can be found [here](https://dd-harp.github.io/MicroMoB/reference/index.html#adult-mosquito-component).

### Aquatic

The aquatic component is responsible for all dynamics which update immature (aquatic
stage) mosquito populations. The interface is defined in `R/aquatic_interface.R`,
and the interface methods with are required to be implemented can be found [here](https://dd-harp.github.io/MicroMoB/reference/index.html#aquatic-immature-mosquito-component).

### Humans

The human component updates human populations. The interface is defined in `R/humans_interface.R`,
and the interface methods with are required to be implemented can be found [here](https://dd-harp.github.io/MicroMoB/reference/index.html#human-component).

### Visitor

The human component updates human populations outside of the resident population of the geographic area being simulated. 
The interface is defined in `R/visitor_interface.R`, and the interface methods with are required to be implemented can be found [here](https://dd-harp.github.io/MicroMoB/reference/index.html#visitor-component).

### Other blood hosts

The other (alternative) blood host component is responsible for other blood hosts for 
mosquitoes (livestock, dogs, etc). The interface is defined in `R/other_interface.R`,
and the interface methods with are required to be implemented can be found [here](https://dd-harp.github.io/MicroMoB/reference/index.html#alternative-blood-hosts-component).

## Dynamics between components

Now that we've seen the components and know where to find the interfaces, we can present
the dynamics again, but annotated with more information telling us exactly what methods
are used to pass information between components. For example, we see a green arrow sending eggs, $G$, 
from the adult mosquitoes to the aquatic mosquitoes component. Within the aquatic component (blue oval)
we see a green method, `compute_oviposit`, meaning that the aquatic component's state update
method can use this interface method to get the number of eggs laid each time step.

Please note we do not include the visitor or other blood host components in this diagram,
as they are supplied as external forcing (or constants) to the bloodmeal and do not carry state.

```{r echo=FALSE, out.width='100%'}
knitr::include_graphics('./DynamicsDetailed.png')
```