Transmission Readme (#7)

* readme

* review clarifications

* add description of recovered compartment

.gitignore

@@ -254,7 +254,7 @@ vignettes/*.pdf
 .Renviron
 
 # pkgdown site
-docs/
+!docs/
 
 # translation temp files
 po/*~

docs/transmission.md

@@ -0,0 +1,77 @@
+# Transmission model
+
+## Overview
+
+The transmission model controls person-to-person transmission between an
+infectious agent and other susceptible agents. Agents become infectious immediately
+upon successful infection attempt, though they may have a transmission probability of
+0 for some time (mimicking an exposed compartment). Once infectious, agents have a pre-assigned
+number of infection attempts. Infection attempt times are drawn from the generation interval.
+Once there are no more infection attempts remaining for the agent, the agent moves to the
+recovered compartment (for now), which triggers the immunity manager to set the agent's immunity
+levels.
+
+## Workflow
+
+The transmission model is centered around a key workflow:
+1. Watch for an agent becoming infectious (S --> I transition).
+2. For the infectious agent, draw a number of infection attempts. This could be from an $R_i$ distribution
+or the distribution of the number of contacts an individual has based on their network connectivity.
+There is also an option for each infection attempt to have a probability of transmission. This serves to
+scale the contact distribution to a potential $R_i$ distribution.
+3. Draw an infection time for the agent. This consists of taking an ordered draw from the generation
+interval. The math for this is abstracted away under a generic `get_next_infection_time` method.
+4. Draw a susceptible contact from the agent's contact group. Contacts could be drawn uniformly
+from the contact group or with weight based on person characteristics. The actual
+drawing of a contact can be abstracted into a `get_contact` method. Evaluate whether
+the infection attempt is successful. Success is based on:
+    - a potential probability of transmission in the case where we are drawing the
+    number of contacts from a contact distribution,
+    - whether any interventions are present that may reduce transmission,
+    - the contact's immunity level which is updated when the contact is drawn.
+
+    If the infection attempt is successful, the susceptible contact is labeled as infectious.
+5. Repeat steps #3 and #4, decreasing the number of infection attempts left by one each time
+regardless of whether the attempt is successful and ending when the agent has no zero
+infection attempts remaining.
+6. Label the agent as recovered. Doing so will trigger the immunity manager to set the
+agent's natural level of immunity.
+
+## Relationship to other managers/out of scope for the transmission manager
+
+- The transmission manager does not implement interventions. It does not keep track
+of interventions present or how they impact transmission.
+
+- The transmission manager does not track an individual's contacts. Instead, the transmission
+manager calls a generic method called `get_contact` which is in the `mod contact_manager` to obtain
+the individual's contacts.
+
+- The transmission manager does not track an individual's health status.
+
+- The transmission manager does not track an individual's waning immunity over time. It can
+interface with other methods that do calculate an individual's immunity -- for evaluating
+whether a susceptible agent with partial immunity gets infected -- and the agent's natural
+immunity level set at the end of their infectious period is done by that same immunity
+manager.
+
+## Diagram
+
+Diagram of workflow:
+
+```mermaid
+graph TB
+A[watch for becoming I]-->B[draw number of infection attempts]-->C[draw ordered transmission time from generation interval]-->D[Evaluate whether there are more infection attempts left]-->E[Repeat]-->C
+D-->F[agent's infectious period is over and gets relabeled as S]
+
+```
+
+Diagram of interactions:
+
+```mermaid
+graph TB
+
+A[transmission]-->B[contact manager]
+A[transmission]-->C[intervention plugin]
+A[transmission]-->D[immunity manager]
+
+```