Define pattern for using the therapeutic_agent slot on TreatmentDescriptor

[caufieldjh]

need to extend the treatment data model so we can say pharmacotherapy + drug/drug class

Originally posted by @cmungall in #78 (comment)

[github-actions]

Summary: Treatment Data Model Enhancement for Pharmacotherapy

This issue proposes extending the treatment data model to allow specific drug or drug class annotations in addition to the generic MAXO "pharmacotherapy" term.

Current State

The schema (as of dismech.yaml line 1084-1103) already includes the TreatmentDescriptor class with a therapeutic_agent slot:

TreatmentDescriptor:
  is_a: Descriptor
  description: A descriptor for treatments/medical actions, bindable to Medical Action Ontology (MAXO)
  slots:
    - therapeutic_agent
  slot_usage:
    therapeutic_agent:
      description: >-
        The drug(s) or chemical agent(s) used in this treatment. Use when the MAXO term
        is generic (e.g., pharmacotherapy MAXO:0000058) but specific drugs are involved.
      comments:
        - Prefer CHEBI terms for specific drugs (e.g., CHEBI:15365 for aspirin)
        - Use NCIT for drug classes when specific CHEBI term unavailable

The therapeutic_agent slot is defined at line 337-346:

therapeutic_agent:
  description: >-
    The drug, chemical, or therapeutic agent used in a treatment. Use when the MAXO term
    is generic (e.g., pharmacotherapy) but specific drugs are involved.
  range: ChemicalEntityDescriptor
  inlined: true
  multivalued: true
  comments:
    - Bind to CHEBI for specific chemicals/drugs
    - Can also use NCIT for drug classes when CHEBI term unavailable

Current Problem

Looking at real disorder files (e.g., Fibromyalgia.yaml:314-349), all pharmacotherapy treatments use:

- name: Duloxetine
  description: SNRI, FDA-approved for fibromyalgia...
  treatment_term:
    preferred_term: pharmacotherapy
    term:
      id: MAXO:0000058
      label: pharmacotherapy

The therapeutic_agent slot is defined in the schema but not being used in practice. This means:

• We lose the ability to query/filter by specific drugs
• We can't link to CHEBI or other chemical entity ontologies
• Drug classes can't be formally represented
• No machine-readable connection between treatment names and standardized drug identifiers

Proposed Solution

The schema already supports the desired functionality. The issue is adoption. Here are two approaches:

Option 1: Document and Encourage Usage (Low-Effort)

Update documentation (CLAUDE.md) with examples:

- name: Duloxetine
  description: SNRI, FDA-approved for fibromyalgia...
  treatment_term:
    preferred_term: pharmacotherapy
    term:
      id: MAXO:0000058
      label: pharmacotherapy
    therapeutic_agent:
      - preferred_term: duloxetine
        term:
          id: CHEBI:36796
          label: duloxetine

Option 2: Make therapeutic_agent Recommended for Pharmacotherapy (Medium-Effort)

Add validation that warns when treatment_term has MAXO:0000058 (pharmacotherapy) but no therapeutic_agent is provided.

This could be implemented as:

1. A custom LinkML validation rule
2. A post-validation check in the pytest suite
3. A compliance metric in the dashboard

Implementation Considerations

Ontology sources for drugs:

• CHEBI (Chemical Entities of Biological Interest): 200,000+ terms, includes specific drugs
  • Example: CHEBI:36796 = duloxetine
  • Example: CHEBI:4469 = duloxetine hydrochloride
• NCIT (NCI Thesaurus): Good for drug classes
  • Example: NCIT:C26693 = Serotonin Norepinephrine Reuptake Inhibitor
• DrugBank: Not in current ontology config, would require adding

CHEBI is already configured in conf/oak_config.yaml and the schema (line 18), so it's ready to use.

Related Work

Common MAXO terms that would benefit from therapeutic_agent:

• MAXO:0000058 - pharmacotherapy (most common case)
• MAXO:0000647 - chemotherapy (could specify agents)
• MAXO:0000014 - radiation therapy (could specify isotopes with CHEBI)
• MAXO:0001017 - vaccination (could link to vaccine products)

Recommended Next Steps

1. Immediate: Add examples to CLAUDE.md showing proper use of therapeutic_agent
2. Short-term: Create a script (like scripts/add_maxo_terms.py) to batch-add CHEBI terms to existing pharmacotherapy treatments
3. Medium-term: Add compliance metrics tracking therapeutic_agent usage for pharmacotherapy
4. Optional: Make therapeutic_agent required (not just recommended) for MAXO:0000058 via schema constraint

Example Conversion

Current Fibromyalgia treatments could be enhanced:

- name: Duloxetine
  treatment_term:
    preferred_term: pharmacotherapy
    term:
      id: MAXO:0000058
      label: pharmacotherapy
    therapeutic_agent:
      - preferred_term: duloxetine
        term:
          id: CHEBI:36796
          label: duloxetine
  target_phenotypes:
    - Chronic Widespread Pain
    - Fatigue

- name: Pregabalin
  treatment_term:
    preferred_term: pharmacotherapy
    term:
      id: MAXO:0000058
      label: pharmacotherapy
    therapeutic_agent:
      - preferred_term: pregabalin
        term:
          id: CHEBI:64356
          label: pregabalin

This enables:

• Querying all disorders treated with duloxetine
• Linking to CHEBI chemical structure and properties
• Finding all SNRI-class drugs used across disorders
• Connecting treatments to drug-drug interaction databases

---

Label recommendation: schema, enhancement, data-model