Address Ali's comments

Author: zmbc

docs/source/onboarding_resources/tutorial/index.ipynb

@@ -142,7 +142,7 @@
     "Often, this starts from a proposal on their side.\n",
     "The client may come to us with a question like this:\n",
     "\n",
-    "> How much impact could it have if we scaled up SQ-LNS in Ethiopia?\n",
+    "> What would the impact be of scaling up SQ-LNS in Ethiopia?\n",
     "\n",
     "However, this question is **not** precise enough to be our research question.\n",
     "We need to ask clarifying questions to understand what options decision-makers\n",
@@ -589,8 +589,14 @@
     "\n",
     "This is a complex topic, but for now what you need to know is:\n",
     "\n",
-    "* GBD causes and risks are both hierarchical; that is, there are higher-level causes and risks that are made up of lower-level causes and risks.\n",
-    "* We can't easily model higher-level entities, so we are usually only interested in the most-detailed entities in the cause and risk hierarchies.\n",
+    "* GBD causes and risks are both hierarchical.\n",
+    "  There are higher-level causes such as sexually transmitted infection that are made up of more detailed lower-level causes such as syphilis.\n",
+    "  Likewise, there are higher-level risks such as \"metabolic risks\" that are made up of more detailed risks such as high blood pressure.\n",
+    "* We typically only model most-detailed causes and risks.\n",
+    "  GBD doesn't estimate all the quantities we need for modeling about higher-level entities.\n",
+    "  With extra work, it may be possible for us to derive these quantities from GBD results, but that is not common practice on our team and is\n",
+    "  outside the scope of this tutorial. \n",
+    "  This is an area our team is interested in exploring more in the future.\n",
     "\n",
     "</div>"
    ]
@@ -619,7 +625,7 @@
     "* Internally to IHME, there is the [Shared Hierarchy Editor](https://she.ihme.washington.edu/explore/cause/version/655)\n",
     "  -- don't worry, you won't edit anything by accident.\n",
     "* Entities can be accessed programmatically with the `gbd_mapping` package, which is part of our Vivarium microsimulation suite.\n",
-    "  Internally to IHME, shared functions can also be used.\n",
+    "  Internally to IHME, [shared functions](https://hub.ihme.washington.edu/spaces/SF/pages/140542419/Shared+Functions+Home) can also be used.\n",
     "\n",
     "Here, we'll use `gbd_mapping`."
    ]
@@ -1493,7 +1499,7 @@
     "tags": []
    },
    "source": [
-    "Now seems like a good time to dissect what is happening with iron deficiency and anemia,\n",
+    "Now seems like a good time to dive a bit deeper into what is happening with iron deficiency and anemia,\n",
     "and in the process learn how to dig into the GBD methods.\n",
     "\n",
     "Remember, in our original causal diagram (from the FAQ) we had \"iron deficiency\" and \"anemia.\"\n",
@@ -1529,21 +1535,27 @@
     "> See the methodological description of “Anaemia (impairment)” for detailed description of\n",
     "> the analytic approach and inputs.\n",
     "\n",
-    "It sounds like the GBD \"iron deficiency\" risk factor is the same thing as anemia.\n",
-    "We can confirm this by some background research, which turns up (for example) [this page](https://www.hematology.org/education/patients/anemia)\n",
+    "It sounds like the GBD \"iron deficiency\" risk factor is closely related to the concept of anemia.\n",
+    "Its exposure is quantified in terms of hemoglobin.\n",
+    "Some background research turns up (for example) [this page](https://www.hematology.org/education/patients/anemia)\n",
     "from the American Society of Hematology which states that anemia is defined by hemoglobin:\n",
     "\n",
     "> [Anemia] is diagnosed when a blood test shows a hemoglobin value of less than 13.5 gm/dl\n",
     "> in a man or less than 12.0 gm/dl in a woman. Normal values for children vary with age.\n",
     "\n",
-    "In that case, what was meant by \"iron deficiency\" in the SQ-LNS FAQ, if that was distinct\n",
+    "However, there's additional complexity to the iron deficiency risk factor, which is explored in subsequent pages\n",
+    "of the risk factor methods appendix.\n",
+    "For the purposes of drawing this causal diagram, we can assume the iron deficiency risk factor is the same\n",
+    "as \"anemia\" from the SQ-LNS FAQ, but we'd need to understand some of these additional intricacies before actually modeling it.\n",
+    "\n",
+    "Given what we've learned so far, you might wonder: what was meant by \"iron deficiency\" in the SQ-LNS FAQ, if that was distinct\n",
     "from anemia?\n",
     "To find this out, we'll scan [the paper cited in the FAQ](https://pmc.ncbi.nlm.nih.gov/articles/PMC8560313/),\n",
     "which is available for free on PubMed Central.\n",
     "There, iron deficiency was defined using \"plasma ferritin,\" which we can confirm is _not_\n",
     "the same thing as hemoglobin and doesn't appear anywhere in the risk factors methods appendix.\n",
     "\n",
-    "So, to summarize: GBD \"iron deficiency\" risk = SQ-LNS FAQ \"anemia.\"\n",
+    "So, to summarize: GBD \"iron deficiency\" risk is approximately the same thing as SQ-LNS FAQ \"anemia.\"\n",
     "Good thing we checked!\n",
     "\n",
     "<!-- https://nbsphinx.readthedocs.io/en/latest/markdown-cells.html#Info/Warning-Boxes -->\n",
@@ -1695,8 +1707,8 @@
     "Don't be afraid of making a very complex diagram at this stage!\n",
     "This is the time to go maximalist before we start editing down to what we will actually model.\n",
     "\n",
-    "As an example, we think it is quite likely that SQ-LNS' effects are muted by unsafe sanitation,\n",
-    "which is a GBD risk:"
+    "As an example, based on having read studies like [Wessells et al. 2021](https://pubmed.ncbi.nlm.nih.gov/34590114/),\n",
+    "we think it is quite likely that SQ-LNS is less effective in areas with unsafe sanitation infrastructure (a risk factor available in GBD):"
    ]
   },
   {
@@ -2035,18 +2047,28 @@
     "For a cause, such as diarrheal diseases, the Vivarium suite can pull GBD results about:\n",
     "\n",
     "* Prevalence: proportion of people who have the disease\n",
-    "* Incidence rate: the rate at which people without the disease acquire it\n",
-    "* Excess mortality rate: the rate at which people who currently have the disease die of the disease\n",
+    "* Incidence rate: the rate at which people acquire the disease\n",
+    "* Mortality rate: the rate at which people die of the disease\n",
     "\n",
     "*Sometimes*, GBD will also save results about **remission**, which is the rate at which people with the disease get better and stop having the disease.\n",
     "However, this is not uniformly available for all most-detailed causes.\n",
     "Frequently, when this isn't saved, we can find information about duration of the condition in the nonfatal methods appendix.\n",
     "For diarrheal diseases, it *is* saved, so we don't have to look for this.\n",
     "\n",
-    "One thing to be careful of is COVID shocks. Since we want to simulate 2025-2030, we may be more\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "Note\n",
+    "\n",
+    "Sometimes, we *prefer* to use a duration from the methods appendix (or another source) over the GBD remission estimate,\n",
+    "so even if it exists, we don't *always* use it.\n",
+    "For the purposes of this tutorial, we will use the GBD remission estimate, since that makes our process a bit simpler.\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "One thing to be careful of is COVID effects. Since we want to simulate 2025-2030, we may be more\n",
     "comfortable assuming that infectious disease burden is like 2019 (pre-pandemic) than 2021 (during pandemic).\n",
     "Because diarrheal disease is mostly spread through contaminated water, and\n",
-    "[doesn't exhibit a strong COVID shock in GBD](http://ihmeuw.org/6syo), we will use 2021.\n",
+    "[doesn't exhibit a strong COVID \"shock\" (a sudden change coinciding with the pandemic) in GBD](http://ihmeuw.org/6syo), we will use 2021.\n",
     "\n",
     "For a risk factor, such as child wasting, our standard tools pull GBD results about **exposure**\n",
     "(what proportion of the population is exposed to what levels of the risk factor)\n",
@@ -2078,7 +2100,7 @@
     "\n",
     "We could do a whole literature review to inform the impact of the intervention on child wasting.\n",
     "But for simplicity here, we'll use the meta-analysis by Dewey et al. that was linked from the SQ-LNS FAQ.\n",
-    "Digging into that paper, Table 3 reports a 14% decrease in wasting with a CI of 7-20%.\n",
+    "Digging into that paper, Table 3 reports a 14% decrease in wasting with a confidence interval of 7-20%.\n",
     "Wasting was defined as a weight-for-length Z score (WLZ -- which is equivalent to WHZ) of less than -2.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
@@ -2146,6 +2168,8 @@
     "The simulants eligible to receive SQ-LNS in 2029 won't have even been *born*\n",
     "yet in 2025. For that reason, we'll start with a population of simulants ranging from 24 months old all the way down to newborns,\n",
     "and we'll need to model fertility to have new births during the simulation.\n",
+    "This is easier, with our current tools, than creating 6-month-old simulants out of thin air\n",
+    "during the simulation.\n",
     "\n",
     "There are several standard ways we model fertility. In this case, because we won't be\n",
     "simulating the adults who would be giving birth, using age-specific fertility rates doesn't\n",
@@ -2170,7 +2194,7 @@
     "#### Burden\n",
     "\n",
     "Burden is typically modeled the same in every simulation we make.\n",
-    "Death/mortality is modeled as a **state machines** where people move (\"transition\") dynamically\n",
+    "Death/mortality is modeled as a **state machine** where people move (\"transition\") dynamically\n",
     "between states depending on their current state.\n",
     "\n",
     "Here is a diagram of our standard mortality state machine, where a circle\n",
@@ -2220,10 +2244,13 @@
    "source": [
     "\n",
     "The transition in this diagram is informed by GBD mortality rates.\n",
-    "Our standard approach is to start from GBD's all-cause mortality and delete mortality due to any modeled causes to determine the \"background\" mortality rate (mortality rate due to everything we're not modeling explicitly).\n",
-    "We apply that background mortality rate to all simulants.\n",
-    "Then, for each modeled disease/cause, we additionally apply the GBD-derived *excess* mortality rate of that disease *only to simulants who currently have the disease*.\n",
-    "The excess mortality rate, as mentioned previously, is the term for the rate of death due to a disease among people who have that disease (which will of course be higher than the rate of death due to that disease among all people, since people without the disease cannot die of it).\n",
+    "Our standard approach is to start from GBD's all-cause mortality rate, which is the rate at which people in the population die (of any cause).\n",
+    "Then, we delete cause-specific mortality rates due to modeled causes to determine the \"background\" mortality rate (mortality rate due to everything we're not modeling explicitly),\n",
+    "which we apply to all simulants.\n",
+    "A \"cause-specific mortality rate\" is the rate at which people in the overall population die of a specific cause; it is directly comparable with the\n",
+    "all-cause mortality rate because both have the full population as the denominator.\n",
+    "On top of the background mortality, for each modeled disease/cause, we apply the GBD-derived *excess* mortality rate of that disease *only to simulants who currently have the disease*.\n",
+    "The excess mortality rate is the term for the rate of death due to a disease among people who have that disease (which will always be higher than the cause-specific mortality rate, since people without the disease cannot die of it).\n",
     "\n",
     "Nonfatal burden is estimated by applying GBD disability weights to those in\n",
     "infected states."
@@ -2266,8 +2293,10 @@
     "For our example, diarrheal diseases are typically of very short duration, so we definitely want to capture\n",
     "that people can have go in and out of episodes.\n",
     "However, unlike some infectious diseases,\n",
-    "having an episode of diarrheal disease does not make you immune from future episodes,\n",
-    "and there is no vaccinated or otherwise immune population, so everyone who doesn't have\n",
+    "having an episode of diarrheal disease does not generally make you immune from future episodes,\n",
+    "and while there are vaccines for some specific pathogens such as rotavirus,\n",
+    "there isn't a population totally immune to diarrhea.\n",
+    "Therefore we'll assume that everyone who doesn't have\n",
     "diarrheal diseases can be called \"susceptible\" to them.\n",
     "This makes diarrheal diseases best represented by this state machine:"
    ]
@@ -2488,7 +2517,7 @@
    },
    "source": [
     "These components all *do* things: create newborn simulants, make simulants get sick and recover, or make simulants die, for example.\n",
-    "We also typically need a type of component called an **observer**, which doesn't do anything but just records what happens.\n",
+    "We also typically need a type of component called an **observer**, which which does not act on the simulated population but just records what happens.\n",
     "This is how, for example, we can record the disease burden our simulants experience.\n",
     "There are standard observers in `vivarium_public_health` -- we'll use some that record the fatal and nonfatal burden."
    ]
@@ -2532,8 +2561,10 @@
     "tags": []
    },
    "source": [
-    "The last thing that is missing is our intervention. Unfortunately, we can't get this from `vivarium_public_health` -- we need to make this\n",
+    "The last thing that is missing is our intervention. Unfortunately, we can't currently get this from `vivarium_public_health` -- for now, we need to make this\n",
     "component from scratch.\n",
+    "There is work underway to add a cookie-cutter intervention component to `vivarium_public_health`,\n",
+    "which will make this easier!\n",
     "\n",
     "A component is a Python *class* with special methods and properties. We won't get into all the details here,\n",
     "but at a high level:\n",