AI-assisted refactor of opioid use disorder documentation into a cause model, take 2#1881
Open
aflaxman wants to merge 35 commits intoihmeuw:mainfrom
Open
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
- 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
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…w-opioid-documentation-019FaK4GYMbtsaogFUQrU8Nx
Co-authored-by: Zeb Burke-Conte <zmbc@users.noreply.github.com>
Co-authored-by: Zeb Burke-Conte <zmbc@users.noreply.github.com>
…U8Nx' of github.com:aflaxman/vivarium_research into aflaxman-claude/review-opioid-documentation-019FaK4GYMbtsaogFUQrU8Nx
…tation-019FaK4GYMbtsaogFUQrU8Nx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
For unknown reasons, these commits are not appearing in PR #1852, so I will try again.