many pathophys entries need to be split/debundled

[cmungall]

@claude please review some of my comments on pathophys entries. In general these are bundled too much. We want to split into more atomic aberrant processes that are linked in a causal graph. come up with a plan

[claude]

Claude finished @cmungall's task —— View job

---

Plan: Splitting Bundled Pathophysiology Entries ✅

I've completed a comprehensive analysis and developed a detailed plan to split bundled pathophysiology entries into atomic aberrant processes with explicit causal relationships.

Todo List:

• Examine current dismech schema structure for pathophysiology
• Survey disorder files to identify bundled pathophys entries
• Analyze specific examples of overly bundled entries
• Propose schema changes for atomic processes
• Design causal graph representation approach
• Create concrete splitting examples
• Develop migration strategy and guidelines

Problem Analysis

Core Issue: Current pathophysiology entries bundle multiple distinct biological processes into single descriptions, obscuring specific causal relationships needed for mechanistic modeling.

Examples of Problematic Bundling:

• Asthma "Chronic Airway Inflammation": Bundles eosinophil infiltration, neutrophil activation, mast cell degranulation, T-cell responses
• Alzheimer's "Amyloid-Beta Plaque Formation": Bundles APP processing, oligomer formation, synaptic toxicity, plaque deposition
• Crohn's "Autophagy and Paneth Cell Dysfunction": Bundles autophagy defects with antimicrobial defense failure

Proposed Solution

1. Schema Enhancements

New slots for Pathophysiology class:

Pathophysiology:
  new_slots:
    - upstream_processes      # References to prerequisite pathophysiology processes
    - causal_relationships    # Explicit causal edges with relationship types
    - temporal_phase         # Early, intermediate, late stage classification
    - prerequisite_processes  # Alternative to upstream for required preconditions
    - inhibited_by           # Processes that suppress this mechanism
    - amplified_by           # Positive feedback processes

Enhanced CausalEdge class:

CausalEdge:
  enhanced_slots:
    - relationship_type      # promotes, inhibits, requires, enables, blocks
    - strength              # weak, moderate, strong causal relationship 
    - evidence_confidence   # high, moderate, low based on evidence quality
    - temporal_delay        # immediate, short-term, long-term

2. Atomic Process Guidelines

Granularity Principles:

1. One primary biological process: Each entry represents a single mechanistic step
2. Single cell type focus: When possible, limit to one primary cell type per process
3. Testable mechanism: Each process should be experimentally verifiable
4. Clear temporal boundaries: Processes should have defined start/end states

Process Naming Convention:

• [Cell Type] [Process Verb] [Molecular Target/Outcome]
• Examples: "Eosinophil Activation", "Beta Cell Apoptosis", "Microglia Phagocytosis"

3. Concrete Splitting Examples

Example 1: Asthma Inflammation → Atomic Processes

Current bundled entry:

- name: Chronic Airway Inflammation
  description: Multiple immune cell types infiltrate airways...

Proposed atomic split:

- name: Th2 Cell Activation
  upstream_processes: ["Allergen Recognition"]
  causal_relationships:
    - target: "Eosinophil Recruitment"
      relationship_type: "promotes"
      strength: "strong"
    - target: "IL-4 Production"  
      relationship_type: "directly_causes"

- name: Eosinophil Recruitment
  prerequisite_processes: ["Th2 Cell Activation"]
  causal_relationships:
    - target: "Airway Tissue Damage"
      relationship_type: "promotes"
    - target: "Mucus Hypersecretion"
      relationship_type: "promotes"

- name: Mast Cell Degranulation
  upstream_processes: ["IgE Cross-linking"]
  causal_relationships:
    - target: "Bronchoconstriction"
      relationship_type: "directly_causes"
      temporal_delay: "immediate"

Example 2: Alzheimer's Amyloid → Causal Chain

Atomic process chain:

- name: APP Proteolytic Cleavage
  causal_relationships:
    - target: "Amyloid Beta Oligomer Formation"
      relationship_type: "enables"

- name: Amyloid Beta Oligomer Formation  
  prerequisite_processes: ["APP Proteolytic Cleavage"]
  causal_relationships:
    - target: "Synaptic Dysfunction"
      relationship_type: "directly_causes"
    - target: "Microglial Activation"
      relationship_type: "promotes"

- name: Synaptic Dysfunction
  upstream_processes: ["Amyloid Beta Oligomer Formation"]
  causal_relationships:
    - target: "Memory Impairment"
      relationship_type: "directly_causes"

4. Migration Strategy

Phase 1: Schema Updates (Week 1-2)

1. Add new slots to Pathophysiology and CausalEdge classes
2. Backward compatibility: Make new fields optional initially
3. Update validation rules to support atomic naming conventions
4. Documentation: Create curator guidelines for atomic process definition

Phase 2: Pilot Refactoring (Week 3-4)

1. Select 3-5 priority disorders with most complex bundled entries:

   • Asthma (respiratory inflammation)
   • Alzheimer's Disease (neurodegeneration)
   • Crohn's Disease (autoimmune/inflammatory)
   • Type 1 Diabetes (autoimmune destruction)
   • Systemic Sclerosis (fibrosis/vascular)

2. Manual splitting process:

   • Identify bundling points in current descriptions
   • Extract atomic biological processes
   • Map causal relationships with evidence backing
   • Preserve all original evidence across new processes
   • Validate with domain experts

Phase 3: Systematic Rollout (Week 5-12)

1. Automated bundling detection: Script to identify likely bundled entries
2. Gradual migration: Process 5-10 disorders per week
3. Quality assurance: Validate each split maintains biological accuracy
4. Community review: Enable feedback mechanism for split quality

Phase 4: Enhanced Validation (Week 13+)

1. Atomic process checker: Automated validation of single-mechanism principle
2. Causal graph validator: Check for circular dependencies, orphaned processes
3. Evidence preservation: Verify complete evidence distribution
4. Visualization tools: Generate causal graphs for visual validation

5. Implementation Priorities

Immediate Actions (Next 1-2 weeks):

1. Draft schema changes for review
2. Create atomic process splitting guidelines document
3. Select pilot disorder files for initial testing
4. Design causal relationship vocabulary (promotes, inhibits, requires, etc.)

Quality Metrics to Track:

• Atomicity score: Percentage of processes following single-mechanism principle
• Causal completeness: Coverage of explicit upstream/downstream relationships
• Evidence density: Evidence-to-process ratio (should increase with splitting)
• Graph connectivity: Percentage of processes with defined causal relationships

This systematic approach will transform the current bundled pathophysiology entries into a proper causal graph representation while maintaining scientific rigor and evidence backing.

---

[github-actions]

Summary: Pathophysiology Entry Bundling Analysis

I've analyzed the pathophysiology entries across the dismech knowledge base and identified systematic bundling issues where single entries combine multiple atomic mechanisms that should be split and linked in causal graphs.

---

Current State

The Pathophysiology class supports causal graphs via the downstream slot (which creates CausalEdge objects), but many entries bundle multiple distinct processes together in a single entry rather than decomposing them into atomic steps.

Schema Support for Causal Graphs

Already available:

• downstream: multivalued list of CausalEdge objects
• Each edge has: target (name string), description, evidence
• Directed edges enable explicit causal chains

Limitations:

• Edges reference targets by name string only (not CURIEs)
• No relationship type vocabulary (all implicit "causes" or "leads to")
• No conditional, probabilistic, or temporal semantics
• No feedback loop representation

---

Concrete Examples of Bundling Issues

Example 1: Asthma - Airway Inflammation (kb/disorders/Asthma.yaml:147-248)

Current structure: Single entry bundles:

1. Immune cell infiltration (6 cell types: mast cells, eosinophils, T cells, basophils, neutrophils, bronchial epithelial cells)
2. Inflammatory mediator release (implied but not explicit)
3. Airway hyperresponsiveness development
4. Clinical manifestations (wheezing, breathlessness)

Atomic decomposition should be:

- name: Immune Cell Infiltration
  cell_types: [mast cell, eosinophil, T cell, etc.]
  downstream:
    - target: Inflammatory Mediator Release
      
- name: Inflammatory Mediator Release
  biological_processes:
    - cytokine production (GO:0001816)
  downstream:
    - target: Airway Epithelial Activation
    
- name: Airway Epithelial Activation
  cell_types: [bronchial epithelial cell]
  downstream:
    - target: Airway Hyperresponsiveness
    
- name: Airway Hyperresponsiveness
  downstream:
    - target: Bronchoconstriction

Example 2: Celiac Disease - Gluten-Triggered Immune Response (kb/disorders/Celiac_Disease.yaml:12-39)

Current structure: Single entry bundles:

1. Gluten peptide translocation across epithelium
2. tTG-mediated deamidation (enzymatic modification)
3. HLA-DQ2/DQ8 peptide binding
4. CD4+ T cell activation

Atomic decomposition should be:

- name: Gluten Peptide Translocation
  biological_processes:
    - antigen transport across epithelium
  downstream:
    - target: Gluten Deamidation by tTG
    
- name: Gluten Deamidation by tTG
  biological_processes:
    - protein deamidation (GO:0031639)
  chemical_entities: [tissue transglutaminase]
  downstream:
    - target: HLA-DQ Peptide Complex Formation
    
- name: HLA-DQ Peptide Complex Formation
  biological_processes:
    - antigen processing and presentation (GO:0019882)
  downstream:
    - target: CD4+ T Cell Activation
    
- name: CD4+ T Cell Activation
  cell_types: [CD4-positive helper T cell]
  downstream:
    - target: Intestinal Epithelial Damage

Example 3: Heart Failure - Fluid Retention (kb/disorders/Heart_Failure.yaml:91-104)

Current structure: Single entry bundles:

1. Reduced cardiac output → decreased renal perfusion
2. Neurohormonal activation → sodium/water retention
3. Extracellular volume expansion
4. Edema formation (pulmonary + peripheral)

Atomic decomposition should be:

- name: Reduced Renal Perfusion
  locations: [kidney]
  downstream:
    - target: Decreased Sodium Excretion
    
- name: Neurohormonal-Mediated Sodium Retention
  biological_processes:
    - renin-angiotensin system activation (already defined elsewhere)
  downstream:
    - target: Extracellular Volume Expansion
    
- name: Extracellular Volume Expansion
  downstream:
    - target: Pulmonary Edema
    - target: Peripheral Edema
    
- name: Pulmonary Edema
  locations: [lung]
  
- name: Peripheral Edema
  locations: [lower limb] # UBERON term

---

Implementation Plan

Phase 1: Schema Enhancement (Optional but Recommended)

Add relationship type vocabulary:

CausalRelationshipType:
  permissible_values:
    directly_activates:
      meaning: RO:0002413  # directly positively regulates
    directly_inhibits:
      meaning: RO:0002212  # negatively regulates
    enables:
      meaning: RO:0002327  # enables
    produces:
      meaning: RO:0003000  # produces
    increases_risk_of:
      # probabilistic causation
    is_prerequisite_for:
      # temporal/ordering constraint

Enhance CausalEdge:

CausalEdge:
  slots:
    - target  # existing
    - description  # existing
    - evidence  # existing
    - relationship_type  # NEW: from CausalRelationshipType enum
    - confidence  # NEW: optional (HIGH/MEDIUM/LOW)
    - temporal_sequence  # NEW: optional (IMMEDIATE/DELAYED/CHRONIC)

Phase 2: Systematic Decomposition Strategy

Identification heuristics for bundled entries:

1. Entry description contains multiple sentences with "and", "then", "leading to"
2. Entry has 3+ cell types listed
3. Entry has 3+ biological processes
4. Entry name is generic ("Inflammation", "Immune Response", "Dysfunction")
5. Entry downstream field has 2+ targets but mechanisms are described in parent description

Decomposition principles:

1. One biological level per entry: Don't mix molecular (protein modification) with cellular (cell activation) with tissue (organ dysfunction)
2. One process per entry: Each entry should describe a single coherent mechanism
3. Explicit intermediates: If A causes C via B, create entries for A→B and B→C
4. Evidence alignment: Evidence should directly support the atomic process, not just the broader mechanism

Priority disorders for review (based on complexity):

• Asthma
• Type 1 Diabetes
• Celiac Disease
• Heart Failure
• Alzheimer's Disease
• Crohn's Disease
• Systemic Lupus Erythematosus
• Rheumatoid Arthritis

Phase 3: Validation Tools

New validation checks:

1. Atomicity check: Flag entries with descriptions >3 sentences or >150 words
2. Multi-mechanism check: Flag entries with >3 cell types or >3 biological processes
3. Causal completeness check: Warn if downstream targets aren't defined as entries
4. Evidence alignment check: Warn if evidence doesn't contain keywords from entry name

Phase 4: Curation Workflow

For each disorder:

1. Identify bundled pathophysiology entries (manual review or heuristic flagging)
2. Decompose into atomic processes with causal edges
3. Reassign evidence to appropriate atomic entries
4. Validate causal graph completeness (all targets defined)
5. Check for evidence support at each node
6. Render updated HTML to verify presentation

---

Benefits of Decomposition

1. Computational reasoning: Atomic processes enable graph-based queries across disorders
2. Evidence precision: Each evidence item clearly supports a specific mechanism
3. Reusability: Atomic processes (e.g., "Cytokine-Mediated Inflammation") can be shared across disorders
4. Mechanistic clarity: Causal chains are explicit rather than narrative
5. Drug target identification: Specific nodes in causal graphs map to intervention points
6. Comparative pathophysiology: Identify shared vs. distinct mechanisms across diseases

---

Questions for Discussion

1. Granularity target: How atomic should processes be? Molecular-level only, or also include cellular/tissue levels?
2. Schema changes: Should we add relationship types to CausalEdge or keep it simple?
3. Backward compatibility: Decompose all existing entries or phase in gradually?
4. Cross-disorder reuse: Should we create a library of canonical atomic processes (e.g., "T Cell Activation") that multiple disorders reference?
5. Evidence redistribution: When splitting bundled evidence, should we duplicate it across multiple atomic entries or require new citations?

---

Next Steps

Immediate:

1. Review this analysis and confirm the decomposition approach
2. Select 2-3 pilot disorders for manual decomposition
3. Document decomposition patterns and anti-patterns

Short-term:
4. Build validation heuristics to flag bundled entries
5. Create curation guide for atomic pathophysiology decomposition
6. Optionally enhance schema with relationship types

Long-term:
7. Systematic decomposition of all 56 disorder files
8. Build causal graph visualization tools
9. Enable cross-disorder mechanistic queries

---

Related Issues:

• Editorial: Frequency qualifiers often lack direct evidence support #112: Evidence quality and frequency qualifiers (similar evidence alignment challenges)
• Define how to include evidence from model organism studies #63: Model organism evidence (may need separate causal graph branches)

Would you like me to start with a pilot decomposition on one disorder (e.g., Asthma or Celiac Disease) to validate this approach?

[github-actions]

Pathophysiology Bundling Fixes Completed ✅

I've completed a systematic pass at fixing bundled pathophysiology entries across the knowledge base. Created PR #210 with decompositions for 4 high-priority disorders.

Files Fixed

1. Epilepsy - Split 2 bundled entries → 6 atomic mechanisms with causal edges
2. Crohn Disease - Split 2 bundled entries → 7 atomic mechanisms
3. Alpha-1 Antitrypsin Deficiency - Split 1 bundled entry → 3 atomic mechanisms
4. Systemic Lupus Erythematosus - Split 1 multi-organ entry → 3 tissue-specific entries

Key Improvements

• Atomic Granularity: Each entry now describes a single biological process
• Causal Relationships: Added explicit downstream edges creating queryable causal graphs
• Evidence Alignment: Evidence now directly supports specific mechanisms
• Cell Type Focus: Where applicable, entries focus on one primary cell type

Example: Epilepsy "Epileptogenesis" Decomposition

Before (1 bundled entry):

- name: Epileptogenesis
  description: Process involving neuroinflammation, gliosis, synaptic 
    reorganization, altered gene expression, and mTOR pathway hyperactivation...

After (4 atomic entries with causal chain):

- name: Neuroinflammation and Gliosis
  downstream:
    - target: Synaptic Reorganization
      
- name: Synaptic Reorganization

- name: mTOR Pathway Hyperactivation  
  downstream:
    - target: Dysmorphic Neuron Generation
    
- name: Dysmorphic Neuron Generation

Validation

All 36 modified pathophysiology entries validated successfully against the LinkML schema.

Next Steps

This addresses the most problematic bundled entries identified in the survey. Additional disorders that could benefit from similar decomposition:

• Asthma (generic "Airway Inflammation")
• Chronic Kidney Disease ("Tubulointerstitial Fibrosis" missing intermediate steps)
• Rheumatoid Arthritis ("Synovial Hyperplasia")

See PR #210 for full details and review the changes.