Intervention Model Template

Important

To begin documenting an intervention for a Vivarium simulation, start by following these steps (after you have created a new git branch to work in):

1. Make a subdirectory intervention_name/ in the folder intervention_models , where intervention_name is replaced with the (potentially shortened) name of the intervention you are modeling. This subdirectory is where you will put all the files for your model documentation, including this document, image files, .csv files, etc.

2. Copy this template into your subdirectory and rename it index.rst.

3. Replace the internal hyperlink target .. _intervention_model_template: at the top of this file with a unique reference label for your cause. The reference label should have the form .. _intervention_{intervention_name}:, where {intervention_name} is replaced with a unique descriptive name or abbreviation for your cause, e.g. .. _intervention_bep:.

4. Delete this document’s title above:

   ----------------------------
   Intervention Model Template
   ----------------------------
   

   Once the above title is deleted, all the other section titles will be promoted up one level.

Full Name of Intervention

Todo

Add a brief introductory paragraph for this document.

Abbreviations

Abbreviation	Definition	Note

Todo

Fill out table with any abbreviations and their definitions used in this document.

Intervention Overview

Todo

Add a general narrative overview of the intervention, including what it is, what outcomes it affects, if/how/when/where it has been used, etc.

Todo

Fill out the following table with a list of known outcomes affected by the intervention, regardless of if they will be included in the simulation model or not, as it is important to recognize potential unmodeled effects of the intervention and note them as limitations as applicable.

The table below provides example entries for large scale food fortification with iron.

Affected Outcomes

Outcome	Effect	Modeled?	Note (ex: is this relationship direct or mediated?)
Hemoglobin concentration	Increases population mean	Yes
Malaria	Increases incidence rate	No

Baseline Coverage Data

Todo

Document known baseline coverage data, using the table below if appropriate

Baseline coverage data

Location	Subpopulation	Coverage parameter	Value	Note

Vivarium Modeling Strategy

Todo

Add an overview of the Vivarium modeling section.

Todo

Fill out the following table with all of the affected measures that have vivarium modeling strategies documented

Modeled Outcomes

Outcome	Outcome type	Outcome ID	Affected measure	Effect size measure	Effect size	Note
Lung cancer	GBD cause	c426	Preclinical incidence rate	Relative risk	0.8 (95% CI: 0.7, 1.01)

Affected Outcome #1

Important

Copy and paste this section for each affected outcome included in this document

Todo

Replace “Risk Outcome Pair #1” with the name of an affected entity for which a modeling strategy will be detailed. For additional risk outcome pairs, copy this section as many times as necessary and update the titles accordingly.

Todo

Link to existing document of the affected outcome (ex: cause or risk exposure model document)

Todo

Describe exactly what measure the intervention will affect

Todo

Fill out the tables below

Affected Outcome #1 Restrictions

Restriction	Value	Note
Male only
Female only
Age group start
Age group end
Other

Affected Outcome #1 Effect Size

Population	Effect size	Uncertainty	Note
Malnourished women	Mean difference: +50 g birthweight	No parameter uncertainty or individual-level stochastic uncertainty in effect
Total eligible population	Relative risk of outcome: 0.9, CI: 0.86 to 0.93	Use the specified RR estimate and confidence interval bounds to generate a lognormal distribution and randomly sample values to generate draw-level values to represent parameter uncertainty. No individual-level stochastic uncertainty in effect.

Note

The “Uncertainty” column in this table should provide instructions on how to represent parameter and/or individual-level stocastic uncertainty in the effect size.

When specifying a lognormal distribution of uncertainty, be aware that the code routinely used in vivarium simulations to implement such a distribution uses the specified RR value as the distribution median and uses the confidence interval bounds to calculate a standard deviation that is then applied about that median. Care should be taken to confirm that the mean and confidence intervals in your simulation results match your desired behavior. Otherwise, you may provide custom instructions for how to generate and sample from a distribution according to your desired specifications.

Todo

Describe exactly how to apply the effect sizes to the affected measures documented above

Todo

Note research considerations related to generalizability of the effect sizes listed above as well as the strength of the causal criteria, as discussed on the general research consideration document.

Assumptions and Limitations

Validation and Verification Criteria