added intro to the policy model

docs/source/explainable_sir.ipynb

@@ -39,12 +39,12 @@
    "source": [
     "## Setup\n",
     "\n",
-    "We first install the required dependencies for this example: PyTorch, Pyro, Chirho and some auxiliary variables.\n"
+    "The main dependencies for this example are PyTorch, Pyro, and ChiRho.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 503,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -96,7 +96,18 @@
    "source": [
     "## Bayesian Epidemiological SIR model with Policies\n",
     "\n",
-    "Now, we build the epidemiological SIR model, one step at a time. We first encode deterministic SIR (Susceptible, Infected, Recovered) dynamics. Then we add uncertainty to the parameters that govern these dynamics, namely $\\beta$ and $\\gamma$. These parameters have been described in much detail in the [dynamical systems tutorial](https://basisresearch.github.io/chirho/dynamical_intro.html). We then integrate the resulting model into another model that describes the policy mechanisms such as imposing lockdown and masking restrictions."
+    "Now, we build the epidemiological SIR (Susceptible, Infected, Recovered/Removed) model, one step at a time. We first encode the deterministic SIR dynamics. Then we add uncertainty about the parameters that govern these dynamics - $\\beta$ and $\\gamma$. These parameters have been described in much detail in the [dynamical systems tutorial](https://basisresearch.github.io/chirho/dynamical_intro.html). We then incorporate the resulting model into a more complex causal model that describes the policy mechanisms such as imposing lockdown and masking restrictions.\n",
+    "\n",
+    "Our outcome of interest is overshoot, the proportion of the population that remains susceptible after the epidemic peak but eventually becomes infected as the epidemic continues. One way to compute it is to:\n",
+    "\n",
+    "1. Find the time at which the number of infected individuals is at its peak, `t_max`.\n",
+    "2. Determine the proportion of susceptibles at `t_max` in the whole population, `S_peak`.\n",
+    "3. Find the proportion of susceptibles (those not infected) at the end of the logging period, `S_final`.\n",
+    "4. Calculate the additional ratio of infected individuals since the peak as `S_peak - S_final`.\n",
+    "\n",
+    "This quantity is of interest because epidemic mitigation policies often have multiple goals that need to be balanced. One goal is to increase `S_final`, i.e., to limit the total number of infected individuals. Another goal is to limit the number of infected individuals at the peak of the epidemic to avoid overwhelming the healthcare system. A further goal is to minimize the proportion of the population that becomes infected after the peak, that is, the overshoot, to reduce healthcare and economic burdens. Balancing these objectives involves making trade-offs.\n",
+    "\n",
+    " Suppose we are working under constraint that the overshoot show be lower than 20% of the population, and we implement two policies, lockdown and masking, which together seem to lead to the overshoot being too high. In fact, only one of them is responsible, and we are interested in being able to identify which one. "
    ]
   },
   {
@@ -108,7 +119,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 504,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -131,9 +142,6 @@
     "        return dX\n",
     "\n",
     "\n",
-    "# TODO add running overshoot to states?\n",
-    "# beta = (1 - l) beta0\n",
-    "\n",
     "class SIRDynamicsLockdown(SIRDynamics):\n",
     "    def __init__(self, beta0, gamma):\n",
     "        super().__init__(beta0, gamma)\n",
@@ -148,7 +156,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 505,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {