Skip to content

AI-assisted refactor of opioid use disorder documentation into a cause model#1852

Closed
aflaxman wants to merge 29 commits intoihmeuw:mainfrom
aflaxman:claude/review-opioid-documentation-019FaK4GYMbtsaogFUQrU8Nx
Closed

AI-assisted refactor of opioid use disorder documentation into a cause model#1852
aflaxman wants to merge 29 commits intoihmeuw:mainfrom
aflaxman:claude/review-opioid-documentation-019FaK4GYMbtsaogFUQrU8Nx

Conversation

@aflaxman
Copy link
Member

Move cause model to its own page, update based on GBD 2023 docs.

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.

This comment was marked as outdated.

claude and others added 9 commits November 18, 2025 18:31
- 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"
- 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
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copy link
Member Author

@aflaxman aflaxman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How are you doing this? Usually we take 2023 GBD data and hold steady

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to use my DisMod-AT clone to extrapolate for now; time trends are really important for this.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this suggestion

Copy link
Collaborator

@zmbc zmbc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we also assuming that non-medication treatments have no effect at all? That seems like a big one!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess that they are wrapped up in the transition from OUD to Recovery "without treatment"; I will change that language to "without medication"

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +91 to +95
- **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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if you include this summary here, it should be shorter

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants