Merge branch 'main' into anemia_vv_summary

Author: zmbc

docs/source/model_design/vivarium_overview/vivarium_versus_other_model_types/index.rst

@@ -168,6 +168,18 @@ regard to relationship type. Fortunately, this limitation has since been resolve
 individual-level data, but because this information is aggregated, the limitation won't be surfaced and improved upon. 
 Read more about this project `here <https://vivarium-research.readthedocs.io/en/latest/models/concept_models/vivarium_census_synthdata/concept_model.html>`__.
 
+A third example of this occurs with residual confounding. Unlike compartmental or multiplication models, which 
+typically assume a homogeneous population within a "state," 
+microsimulations explicitly model individual-level heterogeneity. This shift in granularity does not introduce 
+new confounding; rather, it surfaces existing data limitations that are often obscured by aggregation in other 
+model types. Whether a model is individual-level or population-level, the data required to fully eliminate residual 
+confounding remains the same: a complete map of the correlations between all risk exposures and outcomes. 
+
+While our team strives to account for the relationships between all risk exposures, no dataset can capture every 
+variable. Consequently, there will always be a degree of residual confounding in any model structure, and Vivarium
+is no exception to this. You can read more about how our team conceptualizes and accounts for limitations related to
+residual confounding :ref:`here <residual_confounding>`.
+
 
 Disadvantages of microsimulation
 ++++++++++++++++++++++++++++++++
@@ -194,14 +206,6 @@ records, medication histories, and other highly personal information.
 If we're not interested in the complexities described in the section above, then it is likely a less data- and resource-intensive alternative, such as a multiplication model, is a suitable modeling 
 strategy.
 
-Residual confounding
-~~~~~~~~~~~~~~~~~~~~
-
-Another limitation or disadvantage of microsimulations is that getting realistic, individual-level characteristics from population-level data is difficult, and 
-creates opportunity for residual confounding. 
-
-You can read more about residual confounding and how our team accounts for it `here <https://vivarium-research.readthedocs.io/en/latest/model_design/vivarium_model_components/risk_factors/residual_confounding/index.html>`__.
-
 .. todo::
 
   Cite [Allen-et-al-2019]_ and [Sorensen-et-al-2017]_ somewhere.

docs/source/models/concept_models/index.rst

@@ -13,6 +13,7 @@ Active concept model documents can be found here:
    vivarium_mncnh_portfolio/concept_model
    vivarium_moud/concept_model
    vivarium_alzheimers/concept_model
+   vivarium_mace_rct/concept_model
 
 A list of all (active and complete) concept model documents can be found here:
 

docs/source/models/concept_models/vivarium_mace_rct/concept_model.rst

@@ -0,0 +1,123 @@
+.. _2026_concept_model_vivarium_mace_rct:
+
+===================
+MACE RCT Simulation
+===================
+
+.. sectnum::
+  :depth: 3
+
+.. contents::
+   :local:
+
+.. list-table:: Definitions of terms and abbreviations
+  :widths: 15 15 15
+  :header-rows: 1
+
+  * - Term or Abbreviation
+    - Definition
+    - Note
+  * - IHD
+    - Ischemic Heart Disease
+    - Cause of cardiovascular mortality
+  * - LDL-C
+    - Low Density Lipoprotein Cholesterol
+    - Risk Factor
+  * - MACE
+    - Major Adverse Cardiovascular Events
+    - Composite outcome typically including cardiovascular death, myocardial infarction, and stroke
+  * - MASH
+    - Metabolic Dysfunction-Associated Steatohepatitis
+    - Updated nomenclature for NASH
+  * - MASLD
+    - Metabolic dysfunction–Associated Steatotic Liver Disease
+    - Spectrum of liver disease ranging from simple steatosis to MASH; a term gradually replacing NAFLD.
+  * - NAFLD
+    - Non-Alcoholic Fatty Liver Disease
+    - Spectrum of liver disease ranging from simple steatosis to NASH
+  * - NASH
+    - Non-Alcoholic Steatohepatitis
+    - Also referred to as MASH (metabolic dysfunction-associated steatohepatitis)
+  * - RCT
+    - Randomized Controlled Trial
+    - Study design
+
+Background
+++++++++++
+
+Elevated low-density lipoprotein cholesterol (LDL-C) is a well-established causal risk factor for
+atherosclerotic cardiovascular disease, including ischemic heart disease (IHD) and ischemic stroke.
+Despite the availability of statins and other
+lipid-lowering therapies, a substantial fraction of patients at elevated cardiovascular risk do not
+achieve guideline-recommended LDL-C targets, motivating the development of novel LDL-C-lowering
+agents.
+
+Non-alcoholic steatohepatitis (NASH), now more commonly referred to as metabolic dysfunction-associated
+steatohepatitis (MASH), is an increasingly prevalent condition characterized by hepatic inflammation
+and fibrosis in the setting of metabolic syndrome. Patients with NASH and significant liver fibrosis
+carry a metabolic risk profile that differs from the general population in important ways: they have
+higher rates of insulin resistance, dyslipidemia, obesity, and systemic inflammation. These
+comorbidities place NASH patients at substantially elevated risk of cardiovascular events. Indeed,
+cardiovascular disease is the leading cause of death in patients with non-alcoholic fatty liver
+disease (NAFLD), surpassing liver-related mortality in all but the most advanced stages of fibrosis.
+
+The randomized controlled trial (RCT) that this concept model simulates will enroll patients with a
+to-be-determined level of liver fibrosis (e.g., fibrosis stage F2--F3) and elevated LDL-C. Because
+this trial focuses on a population selected for hepatic fibrosis, the enrolled participants are
+expected to have a metabolic risk profile that is meaningfully different from the general population.
+In particular, they may have higher baseline rates of major adverse cardiovascular events (MACE)
+due to the clustering of cardiometabolic
+risk factors associated with NASH. Understanding these differences is critical for several reasons.
+
+First, it is useful to understand what fraction of the general population would meet the trial's
+inclusion criteria, as this determines the generalizability of the trial findings and the potential
+market size for the intervention. 
+
+Second, it is important to estimate how MACE rates in the trial population might differ from
+general population rates. If the trial population has meaningfully higher baseline MACE risk, the
+trial may be better powered to detect a treatment effect, but the absolute risk reduction observed
+may not translate directly to lower-risk populations. Conversely, if the trial population
+has lower baseline MACE risk, the trial may need to recruit an unexpectedly large sample
+of study participants to be likely to detect the treatment effect.
+
+This simulation will model the trial population, the randomization to treatment and control arms,
+LDL-C trajectories under the experimental agent, and the downstream incidence of MACE
+(cardiovascular death, myocardial infarction, and ischemic stroke) to inform trial design and
+expected outcomes.
+
+Modeling Aims and Objectives
+++++++++++++++++++++++++++++
+
+The aim of this simulation is to estimate the effect of the experimental
+LDL-C-lowering agent on MACE incidence under trial conditions.
+
+Concept Model Diagram
++++++++++++++++++++++
+
+The concept model diagram will represent the trial population, the randomization
+to treatment and control arms, LDL-C exposure, and downstream MACE outcomes.
+
+Vivarium Modeling Components
+++++++++++++++++++++++++++++
+
+The simulation will include cause models for cardiovascular outcomes, a
+risk exposure model for LDL-C, a risk effect linking LDL-C to MACE, and an
+intervention model representing the experimental agent.
+
+Back of the Envelope Calculations
++++++++++++++++++++++++++++++++++
+
+Back of the envelope calculations to estimate the expected effect size and
+required trial size will be added here.
+
+Limitations
++++++++++++
+
+Known limitations of the simulation, including assumptions about
+adherence, response heterogeneity, and trial design simplifications, will
+be documented here.
+
+References
+++++++++++
+
+References supporting the model design and parameters will be listed here.

docs/source/models/concept_models/vivarium_mncnh_portfolio/concept_model.rst

@@ -491,9 +491,23 @@ Postpartum component
     - * :ref:`Postpartum depression <2021_cause_postpartum_depression_mncnh>`
       * :ref:`Hemoglobin risk effects document <2023_hemoglobin_effects>`
 
-**Wave 1 Concept Model Map (has not been updated recently):**
+**Concept Model Map:**
+
+Please note that this is designed as a helpful visual aid, but is not
+designed to be fully inclusive of all work or modeled components. 
+
+**Pregnancy, influenced by ANC attendance**
+
+.. image:: pregnancy_figure_overview.png
+
+**Intrapartum, influenced by delivery facility**
+
+.. image:: intrapartum_figure_overview.png
+
+**Neonatal, influenced by neonatal care facility**
+
+.. image:: neonatal_figure_overview.png
 
-.. image:: wave_1_full.drawio.png
 
 .. _mncnh_portfolio_3.1:
 

docs/source/models/concept_models/vivarium_mncnh_portfolio/editable_concept_figures.pptx

@@ -1526,7 +1526,7 @@ Wave II
       * `MMS effect size update and implementation confirmed to be functioning in interactive sim <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/data_prep/verification_and_validation/child_model/model_12.1.1_interactive_MMS_effect.ipynb>`_
   * - 12.2
     - Check that results for this run approximate the mean of the results from run 12.1
-    - 
+    - [TODO: CONFIRM V&V CONCLUSIONS FROM THIS RUN]
 
 .. list-table:: Outstanding V&V issues
   :header-rows: 1
@@ -1625,6 +1625,19 @@ Wave III
     - All
     - National runs
     - Standard SQ-LNS effects only
+  * - ``vivarium_v4.0_vph_v5.0_update``
+    - Runs that integrate vivarium and vivarium_public_health framework updates to confirm we still meet V&V criteria following these updates
+    - Baseline, MMS (run using maternal simulation outputs from the ``vivarium_v4.0_vph_v5.0_update`` model version)
+    - Baseline, 8 (all)
+    - National runs (informed from subnational artifact). 10 draws (not the mean draw). Nigeria and Pakistan only. 
+    - Standard SQ-LNS effects only
+  * - 19.0
+    - Production runs for re-run of model 17 for Ethiopia to resolve subnational scrambling issue
+    - Same as model 17.0
+    - Same as model 17.0
+    - Same as model 17.0
+    - This run is to resolve an issue for Ethiopian results in model 17.0 in which data were scrambled across subnational locations (`see details here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/fea37d5913dca2a65c814decbe3a457d383913b6/emulator/sqlns_targeting/artifact_data_checks.ipynb>`__). New custom data was generated based on an updated Ethiopian artifact without this issue (`see PR here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/pull/207>`__ and `here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/pull/212>`__) and updated in the simulation repo (`see PR here <https://github.com/ihmeuw/vivarium_gates_nutrition_optimization_child/pull/197>`__ and `here <https://github.com/ihmeuw/vivarium_gates_nutrition_optimization_child/pull/198>`__). Notably, these runs will be performed in 2026 almost two years after model 17.0 and the exact environments used to run model 19.0 is not expected to exactly match that used to run model 17.0. This model will include Standard and modified SQ-LNS effects.
+
 
 
 .. list-table:: Output specifications
@@ -1723,13 +1736,21 @@ Wave III
       5. Stunting state person time stratified by SQ-LNS coverage
     - * Age group
       * Subnational location (need to determine how this will be "stratified")
-  * - 18.0
+  * - 18.0, ``vivarium_v4.0_vph_v5.0_update``
+    - 1. Deaths and YLLs 
+      2. YLDs 
+      3. Count of incident SAM cases stratified by SAM treatment coverage
+      4. Count of incident MAM cases stratified by MAM treatment coverage
+      5. Stunting state person time stratified by SQ-LNS coverage
+    - Age strata of 0-6 months, 6-18 months, 18-60 months
+  * - 19.0
     - 1. Deaths and YLLs (non-cause-specific)
       2. YLDs (all-cause observer only)
       3. Count of incident SAM cases stratified by SAM treatment coverage
       4. Count of incident MAM cases stratified by MAM treatment coverage
       5. Stunting state person time stratified by SQ-LNS coverage
-    - Age strata of 0-6 months, 6-18 months, 18-60 months
+    - * Age strata of 0-6 months, 6-18 months, 18-60 months
+      * Results specific to subnational location (in the same manner as model 17.0)
 
 
 .. list-table:: Verification and validation tracking
@@ -1798,7 +1819,18 @@ Wave III
   * - 17.0
     - * Confirm that results for production runs match expected outputs
     - * As in model 16, we checked the SQ-LNS effects to ensure these matched for both standard, and modifed effects. In general, all subnational locations were within the confidence intervals. The cases where this is untrue and the rationale for approval are noted in the Jupyter notebook here. `Model 17 SQLNS effects <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/0858f98bd9e19f2621873c83a20efef055a0a5d8/verification_and_validation/child_model/model_17.0_sqlns_effects.ipynb>`_. 
+      * An issue with artifact data used for subnational locations in Ethiopia was identified that necessitates a rerun (`see details here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/fea37d5913dca2a65c814decbe3a457d383913b6/emulator/sqlns_targeting/artifact_data_checks.ipynb>`__)
+      * An issue with the application of modified SQ-LNS effects was identified and `summarized in this PR <https://github.com/ihmeuw/vivarium_research/pull/1902>`__, but deemed an acceptable limitation.
   * - 18.0
     - * Confirm that results for production runs match expected outputs
+    - * An issue with artifact data used for subnational locations in Ethiopia was identified that necessitates a rerun (`see details here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/fea37d5913dca2a65c814decbe3a457d383913b6/emulator/sqlns_targeting/artifact_data_checks.ipynb>`__)
+      * Potential issue with mean draw systematically overestimating baseline parameters is expected (TODO: update with notebook demonstrating this issue)
+      * TODO: update with links to general V&V notebooks for this run
+  * - ``viv4.0_vph_v5.0_update``
+    - * Confirm baseline scenario cause burden and CGF risk exposures meets GBD expectation
+      * Compare total scenario-specifc (maternal MMS, child scenario 8) DALYs to results from model 18.0
+    - 
+  * - 19.0
+    - Re-run model 17.0 V&V for updated Ethiopian locations
     - 
 

docs/source/models/concept_models/vivarium_mncnh_portfolio/intrapartum_figure_overview.png

@@ -607,7 +607,13 @@ Specific outputs for specific models are specified in the following section.
     - Same as 9.2 but including count of live births and still births 
     - Same as 9.2
     - 
-
+  * - ``vivarium_v4.0_vph_v5.0_update``
+    - Runs that integrate vivarium and vivarium_public_health framework updates to confirm we still meet V&V criteria following these updates
+    - All
+    - 10 draws, 10 seeds with 20,000 population (200,000 pregnancies per draw). Nigeria and Pakistan only
+    - Default
+    - Default
+    - 
 
 .. note::
 
@@ -737,6 +743,13 @@ Specific outputs for specific models are specified in the following section.
     - `V&V notebooks for model 11.2 can be found here <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/pull/146>`_
       * Maternal disorders YLDs now look as expected -- ready to move on to production runs
       * Also confirmed that the birth outcome observer is capturing outcomes among all simulated individuals, including those who die during the simulation
+  * - ``vivarium_v4.0_vph_v5.0_update``
+    - All V&V checks
+    - All models are meeting V&V criteria. Notebooks linked below have been updated to support the results management system format as of March 2026, but currently only support a single location at once.
+
+      * `Intervention coverage notebook <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/data_prep/verification_and_validation/pregnancy_model/model_viv4.0_intervention_coverage.ipynb>`__
+      * `Maternal disorders and anemia burden notebook <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/data_prep/verification_and_validation/pregnancy_model/model_viv4.0_maternal_disorders_anemia.ipynb>`__
+      * `Pregnancy model notebook <https://github.com/ihmeuw/vivarium_research_nutrition_optimization/blob/data_prep/verification_and_validation/pregnancy_model/model_viv4.0_preg_states.ipynb>`__
 
 .. list-table:: Outstanding V&V issues
   :header-rows: 1