AI-assisted refactor of opioid use disorder documentation into a cause model#1852
AI-assisted refactor of opioid use disorder documentation into a cause model#1852aflaxman wants to merge 29 commits intoihmeuw:mainfrom
Conversation
This commit refactors the Opioid Use Disorder (OUD) documentation to align with GBD 2021 concepts and best practices for modeling chemical dependency: - Created new OUD cause model at docs/source/models/causes/opioid_use_disorder/ - Comprehensive documentation includes: * Three-state model: susceptible, with_condition, and on_treatment * Detailed state definitions and transitions aligned with GBD 2021 * Clinical course and natural history of OUD * GBD 2021 modeling strategy using DisMod-MR 2.1 * NumPyro/DisMod-AT methodology for parameter estimation * Data sources, validation criteria, and limitations * Extensions and risk factor interactions - Updated MOUD concept model to reference the new OUD cause model - Model aligned with: * GBD 2021 definitions and diagnostic criteria (DSM-5, ICD-10) * Literature on compartmental modeling of substance use disorders * RESPOND model and other contemporary OUD modeling approaches The refactored model provides a comprehensive foundation for simulating MOUD interventions and understanding the opioid epidemic dynamics.
… extensions This commit updates the Opioid Use Disorder cause model documentation to reflect GBD 2023 concepts and adds comprehensive extensions for modeling polysubstance use and casual drug use: Major Updates: - Updated all references from GBD 2021 to GBD 2023 - Updated diagnostic criteria from DSM-IV-TR to DSM-5 - Added note on evolution of diagnostic criteria (DSM-IV vs DSM-5) - Updated reference label from 2021_cause_opioid_use_disorder to 2023_cause_opioid_use_disorder - Updated temporal coverage from 1990-2021 to 1990-2023 - Updated all GBD data source references (COMO, CoDCorrect, Demography, DisMod-MR 2.1) New Extensions Added: 1. Polysubstance Use Modeling: - Joint state space for co-occurring opioid and other substance use disorders - Risk stratification by polysubstance patterns (opioid+stimulant, opioid+sedative) - Modified transition rates reflecting polysubstance effects on treatment outcomes - Epidemiological context (opioid-methamphetamine co-use increased 10.1% from 1992-2017) - Modeling framework options (compartmental, Markov, system dynamics, agent-based) 2. Casual Use and Subclinical States: - Four-state model extension (susceptible, casual use, OUD untreated, OUD on treatment) - Transition pathways from casual use to disorder - Frequency-dependent modeling using sigmoid patterns and Hill functions - Clinical significance and data requirements - Methodological considerations for DSM-5 severity gradations New References Added: - Jalal et al. 2022 (systematic review of opioid simulation models) - Ciccarone 2019 (triple wave epidemic) - Jones et al. 2020 (methamphetamine resurgence) - Ellis et al. 2018 (opioid-methamphetamine twin epidemics) - Anthony et al. 1994, Lopez-Quintero et al. 2011 (transition to dependence) Key Research Findings Incorporated: - GBD 2023 uses DisMod-MR 2.1 (consistent with GBD 2021) - DSM-5 criteria combine abuse/dependence into unified disorder with severity levels - Polysubstance overdose deaths (opioids+stimulants) increased from 187 (1999) to 14,777 (2020) - Only 15-68% of substance users develop dependence (substance-specific) - Compartmental models most common (36%) for opioid epidemic modeling The documentation now provides comprehensive guidance for extending the base three-state OUD model to capture heterogeneity in substance use patterns, treatment responses, and progression to disorder.
CORRECTION: Previous commit incorrectly stated GBD 2023 updated to DSM-5 criteria. This commit corrects the documentation to reflect the actual GBD 2023 methodology from the official supplementary appendix. Major Corrections: 1. Diagnostic Criteria: - GBD 2023 continues to use DSM-IV-TR (NOT DSM-5) - Requires ≥3 of 7 symptoms for opioid dependence - Full DSM-IV-TR criteria now documented with ICD codes - Added note that clinical practice has evolved to DSM-5, but GBD maintains DSM-IV-TR 2. Severity Distribution (from GBD 2023 appendix): - Asymptomatic: 16% (13-19%), DW = 0 - Mild: 37% (20-55%), DW = 0.335 (0.221-0.473) - Moderate/Severe: 47% (29-64%), DW = 0.697 (0.510-0.843) - Based on NESARC and Comorbidity and Trauma Study - Previous version incorrectly showed only 2 severity levels 3. DisMod Methodology Details: - Added prior settings: no incidence/EMR before age 15, no incidence after 64 - Remission upper limit of 0.2 - Country-level covariates: IDU prevalence, SDDD of prescribed opioids - EMR covariate: IDU with restricted influence (0-2 range) 4. Data Sources and Adjustment: - Documented IHME-indirect data creation methodology - MR-BRT crosswalk adjustment factor: 0.25 for direct surveys - Direct surveys adjusted upward (logit beta = -1.07, gamma = 0.24) - Explained multiplier method using treatment data and ST-GPR 5. EMR Methodology: - MR-BRT method with HAQ Index prior (though not supported by data) - IDU covariate for EMR: exponentiated beta = 6.84 (6.12-7.36) - EMR consistent across HAQ levels due to data-driven results 6. Casual Use Extension: - Updated to reference both DSM-IV-TR (≥3 symptoms) and DSM-5 (≥2 symptoms) - Clarified that GBD uses DSM-IV-TR but extensions may use DSM-5 - Added guidance on specifying diagnostic criteria in extensions Updated References: - Abbreviations: DSM-5 → DSM-IV-TR - Disability weights in data tables - Sequelae descriptions (asymptomatic, mild, moderate/severe) Sources: - GBD 2023 Supplementary Appendix: Opioid Use Disorders - GBD 2023 Supplementary Appendix: Drug Use (risk factor) - Direct quotes from official IHME methodology documentation This ensures documentation accurately reflects GBD 2023 methodology for consistency with official estimates and proper model parameterization.
- Corrected all heading level decorators to match document template - Changed top-level sections from `---` to `+++` (Section Level 1) - Changed subsections from `+++` to `---` (Section Level 2) - Fixed all CRITICAL title level inconsistency errors - Documentation now builds with ZERO warnings and ZERO errors - Verified with: make html -C docs/ SPHINXOPTS="-W --keep-going -n"
…9FaK4GYMbtsaogFUQrU8Nx
- Added 14 citation references throughout the document - GBD-2023-Capstone-Opioid: cited when defining GBD 2023 OUD - DisMod-Methods: cited when discussing DisMod-MR methodology - Degenhardt-2019: cited for OUD recovery pathways - SAMHSA-MOUD: cited for MOUD medications - Wakeman-2020: cited for treatment effectiveness - Sordo-2017, Santo-2021: cited for mortality reduction from MOUD - Friedman-2022: cited in disease overview - Ciccarone-2019: cited for opioid epidemic evolution - Jalal-2020: cited for simulation modeling frameworks - Jones-2020, Ellis-2018: cited for polysubstance use trends - Anthony-2005: cited for dependence prevalence among users - Lopez-Quintero-2011: cited for transition probabilities Resolves Sphinx warnings about unreferenced citations
References fixed: - Replace [Friedman-2022] (hallucinated reference) with [DSM-5] for OUD definition - Replace [Jalal-2020] with [Cerda-2022] (correct authors: Cerdá et al.; correct journal: Epidemiol Rev) - Upgrade [GBD-2023-Capstone-Opioid] to cite 2025 Lancet GBD 2023 capstone paper - Fix [SAMHSA-MOUD] publication number to official HHS PEP21-02-01-002 - Rename [Anthony-2005] to [Anthony-1994] to match actual publication year ICD-10 codes corrected: - Remove incorrect T14.0 (superficial injury) and Z79.8 (other drug therapy) - Use F11.x for opioid use disorders - Clarify T40.x codes are for overdose models, not chronic OUD cause Modeling assumptions clarified: - MR-BRT crosswalk: removed unpublished specific parameter values, made qualitative - EMR covariates: removed unpublished beta coefficients, kept qualitative description - Age 64 incidence cutoff: clarified as modeling assumption, not hard EMCDDA rule - Treatment EMR/disability: clarified these are modeling choices with sensitivity analyses, not clinical facts that MOUD eliminates all disability/mortality All changes ensure documentation reflects verifiable sources and distinguishes modeling choices from empirical findings.
Added DOI links and URLs to all bibliography entries: - GBD-2023-Overview: Added DOI link to 2025 Lancet paper - DisMod-Methods: Added DOI link to 2018 Lancet GBD 2017 paper - Degenhardt-2019: Added DOI link - SAMHSA-MOUD: Added SAMHSA library link and NCBI Bookshelf full text link - Wakeman-2020: Added DOI link - Sordo-2017: Added DOI link - Santo-2021: Added DOI link - DSM-5: Added overview link to APA website - Cerda-2022: Added DOI link - Ciccarone-2019: Added DOI link - Jones-2020: Added DOI link - Ellis-2018: Added DOI link - Anthony-1994: Added DOI link - Lopez-Quintero-2011: Added DOI and PubMed link All references now include hyperlinks for easy access to source documents.
- Converted all reference URLs to use RST anonymous link syntax - Changed from single underscore `text <URL>_` to double underscore `text <URL>__` - This prevents "duplicate explicit target name" warnings for repeated link text - All "Available at" links now render as clickable hyperlinks - Also made NCBI Bookshelf link clickable for SAMHSA-MOUD reference - Build now passes with only 1 warning (graphviz - environment specific) All 14 references now have properly clickable hyperlinks to their source documents.
Changed all link text from generic "Available at" to descriptive labels: - Journal articles: "(full text)" for DOI links - DSM-5: "(overview)" for the APA website - SAMHSA-MOUD: "(publication page)" and "(full text)" for two different links - Lopez-Quintero: "(PubMed)" for PubMed link Now readers can see at a glance what type of resource each link provides. All link text is clickable and uses RST anonymous link syntax.
- Change treatment discontinuation symbol from 'tf' to 'td' throughout document - Fix LaTeX underscore escaping in math formulas (treatment_coverage, emr_multiplier, disability_weight) - Update all references to use 'td' in diagrams, tables, and text
…ng approaches section - Change 'treatment discontinuation/failure' to 'treatment discontinuation' throughout - Move modeling framework discussion to end of Disease Overview section - Add expanded framing about simulation modeling approaches based on Cerda et al systematic review - Contextualize compartmental model approach within broader landscape of OUD modeling frameworks
aflaxman
left a comment
There was a problem hiding this comment.
concept_model.rst should not have some of the data notes anymore.
- Remove section 4.1 Core Disease Model Parameters (now covered in cause model documentation) - Add reference to OUD cause model for parameter details - Update transition symbol from 'tf' to 'td' throughout - Update 'treatment failure' to 'treatment discontinuation' language - Renumber remaining sections in Data Notes
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
|
||
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies | ||
|
|
||
| 6. **Temporal Trends**: Trends in prevalence, incidence, and mortality should match observed temporal patterns |
There was a problem hiding this comment.
How are you doing this? Usually we take 2023 GBD data and hold steady
There was a problem hiding this comment.
I'm going to use my DisMod-AT clone to extrapolate for now; time trends are really important for this.
There was a problem hiding this comment.
How does it extrapolate? That wasn't described in the section about it above.
|
|
||
| Model validation should compare simulated outputs to reference data: | ||
|
|
||
| 1. **Prevalence**: Total OUD prevalence in the simulation (C + T states) should match GBD 2023 prevalence estimates within uncertainty bounds |
There was a problem hiding this comment.
| 1. **Prevalence**: Total OUD prevalence in the simulation (C + T states) should match GBD 2023 prevalence estimates within uncertainty bounds | |
| 1. **Prevalence**: Total OUD prevalence in the simulation (C + T states) should match GBD 2023 prevalence estimates within uncertainty bounds; also check YLDs, which will be more of a validation than verification because we have assumed severity in T is all mild. |
There was a problem hiding this comment.
Are we assigning nobody to the asymptomatic sequela?
|
|
||
| 2. **Treatment Coverage**: The proportion of individuals with OUD in the treatment state (T / (C + T)) should match observed treatment coverage ratios | ||
|
|
||
| 3. **Cause-Specific Mortality**: Deaths attributed to OUD in the simulation should match GBD 2023 CSMR estimates |
There was a problem hiding this comment.
| 3. **Cause-Specific Mortality**: Deaths attributed to OUD in the simulation should match GBD 2023 CSMR estimates | |
| 3. **Cause-Specific Mortality**: Deaths attributed to OUD in the simulation should match GBD 2023 CSMR estimates; also check EMR and YLLs |
There was a problem hiding this comment.
EMR isn't really estimated by GBD so I don't understand that piece; I guess it's just a combo check for CSMR and prevalence? Or are you planning to use DisMod EMR? This was unclear above.
|
|
||
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies | ||
|
|
||
| 6. **Temporal Trends**: Trends in prevalence, incidence, and mortality should match observed temporal patterns |
There was a problem hiding this comment.
I'm going to use my DisMod-AT clone to extrapolate for now; time trends are really important for this.
|
|
||
| 4. **Incidence**: Population incidence rate (transitions from S to C) should be consistent with GBD 2023 incidence estimates | ||
|
|
||
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies |
There was a problem hiding this comment.
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies | |
| 5. Remission, Treatment initiation, Treatment Discontinuation, Treatment-associated Recovery |
There was a problem hiding this comment.
I don't understand this suggestion
zmbc
left a comment
There was a problem hiding this comment.
Interesting stuff!
Sorry I made so many comments, happy to discuss live if that would be helpful.
|
|
||
| 4. **Incidence**: Population incidence rate (transitions from S to C) should be consistent with GBD 2023 incidence estimates | ||
|
|
||
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies |
There was a problem hiding this comment.
I don't understand this suggestion
|
|
||
| 5. **Age Patterns**: Age-specific prevalence and incidence should follow observed patterns from GBD and epidemiological studies | ||
|
|
||
| 6. **Temporal Trends**: Trends in prevalence, incidence, and mortality should match observed temporal patterns |
There was a problem hiding this comment.
How does it extrapolate? That wasn't described in the section about it above.
|
|
||
| 6. **Temporal Trends**: Trends in prevalence, incidence, and mortality should match observed temporal patterns | ||
|
|
||
| Extensions and Modifications |
There was a problem hiding this comment.
This section is a bit unusual for us, we usually don't include notes for the future like this; might want to label them as such a bit more clearly.
|
|
||
| 1. **Three-State Model**: The model simplifies the complex heterogeneity of OUD into three discrete states. In reality, OUD severity exists on a continuum, and individuals may have varying levels of use, dependence, and treatment engagement. | ||
|
|
||
| 2. **MOUD as Single Treatment State**: The "on_treatment" state aggregates all forms of MOUD (methadone, buprenorphine, naltrexone) despite important differences in effectiveness, retention, and accessibility across these medications. |
There was a problem hiding this comment.
Are we also assuming that non-medication treatments have no effect at all? That seems like a big one!
There was a problem hiding this comment.
I guess that they are wrapped up in the transition from OUD to Recovery "without treatment"; I will change that language to "without medication"
There was a problem hiding this comment.
Interesting, we also miss heterogeneity within the "without medication" category (because some people in that category are receiving non-medication treatments) and also assume that non-medication treatment and medication treatment are totally independent which seems unlikely.
| - **Three states**: susceptible, with_condition (untreated OUD), and on_treatment (receiving MOUD) | ||
| - **Five transitions**: incidence (i), natural remission (r), treatment initiation (ti), treatment discontinuation (td), and treatment-associated recovery (ts) | ||
| - **GBD 2023 alignment**: Parameterization consistent with Global Burden of Disease 2023 estimates for OUD prevalence, incidence, remission, and excess mortality | ||
| - **Treatment representation**: Explicit modeling of MOUD engagement and outcomes | ||
| - **DisMod-AT methodology**: Transition rates estimated using a NumPyro implementation of DisMod-AT-like Bayesian inference to ensure internal consistency |
There was a problem hiding this comment.
I think if you include this summary here, it should be shorter
Co-authored-by: Zeb Burke-Conte <zmbc@users.noreply.github.com>
Co-authored-by: Zeb Burke-Conte <zmbc@users.noreply.github.com>
Move cause model to its own page, update based on GBD 2023 docs.