Add clinical trials section

[caufieldjh]

The schema and UI should include a section for clinical trials.
The linkml-reference-validator can work with the Clinicaltrials.gov API (see https://linkml.io/linkml-reference-validator/how-to/validate-clinical-trials/) so sources for this section can be retrieved in a focused way.

[github-actions]

Issue Analysis: Adding Clinical Trials Section

Overview

This enhancement proposes adding a clinical trials section to both the LinkML schema and UI rendering. The integration would leverage the ClinicalTrials.gov API v2 through linkml-reference-validator, enabling structured validation and retrieval of clinical trial data.

Technical Foundation: linkml-reference-validator + ClinicalTrials.gov

Based on the linkml-reference-validator documentation, the tool provides:

Core Capabilities:

• Identifier Support: Accepts NCT identifiers (e.g., NCT00000001) with flexible formatting (bare codes, case-insensitive prefixes)
• Data Extraction: Retrieves official title, brief summary/detailed description, metadata (status, sponsor)
• Text Validation: Validates supporting text against actual trial records
• Caching: Pre-caches trials as markdown files with YAML frontmatter for offline validation
• Rate Management: Built-in rate limiting (0.5s default between requests)

This validation infrastructure is already used successfully in dismech for PubMed references via linkml-reference-validator, making clinical trials a natural extension.

Proposed Schema Design

Following existing patterns in the schema, a clinical trial section could be modeled as:

New Class: ClinicalTrial

ClinicalTrial:
  slots:
    - nct_id           # NCT identifier (e.g., NCT00000001)
    - title            # Official trial title
    - description      # Brief/detailed summary
    - phase            # Trial phase (Phase I/II/III/IV)
    - status           # Recruitment status (recruiting, completed, terminated, etc.)
    - intervention     # Intervention/treatment being studied
    - condition        # Condition/disease being studied
    - sponsor          # Primary sponsor organization
    - target_phenotypes # Link to phenotypes being addressed
    - evidence         # Supporting evidence/snippets
    - notes
    - review_notes

Integration with Disease Class

Add to the Disease class slots:

Disease:
  slots:
    # ... existing slots ...
    - clinical_trials   # multivalued: true, range: ClinicalTrial

Schema Pattern Consistency

The clinical trials section would follow established patterns:

1. Evidence-based validation: Like treatments and phenotypes, each trial entry would have evidence slots validated by linkml-reference-validator
2. Descriptor pattern: Could optionally use ClinicalTrialDescriptor for structured term references if linking to ontologies
3. Reference caching: Similar to PMID caching in references_cache/, NCT IDs would be cached locally

Implementation Considerations

Schema Changes (dismech.yaml)

1. Add ClinicalTrial class with appropriate slots
2. Add clinical_trials slot to Disease class
3. Configure prefix for NCT identifiers:

   prefixes:
     # ... existing prefixes ...
     clinicaltrials: https://clinicaltrials.gov/study/

UI Rendering (render.py)

1. Update Jinja2 templates to display clinical trials section
2. Link NCT identifiers to ClinicalTrials.gov study pages
3. Display trial status, phase, and key details

Validation Integration

1. Extend validation workflow to include NCT identifier validation
2. Configure linkml-reference-validator to cache trial data
3. Add to QC pipeline (just qc command)

Example Usage in Disorder File

name: Addison's Disease
# ... existing sections ...
clinical_trials:
  - nct_id: NCT00000001
    title: "Study of Hydrocortisone Replacement in Addison's Disease"
    phase: Phase III
    status: Completed
    intervention: Hydrocortisone replacement therapy
    evidence:
      - reference: clinicaltrials:NCT00000001
        supports: SUPPORT
        snippet: "This study evaluated modified-release hydrocortisone..."
        explanation: "Trial demonstrates efficacy of novel hydrocortisone formulation"

Benefits

1. Evidence-Based Treatment Info: Complements the existing treatments section with clinical trial evidence
2. Automatic Validation: Prevents incorrect or fabricated NCT IDs through API validation
3. Research Context: Provides current state of therapeutic research for each disorder
4. Consistency: Follows established validation patterns already used for PubMed references

Related Issues

This enhancement aligns with other schema improvements:

• Define pattern for using the therapeutic_agent slot on TreatmentDescriptor #146: Define pattern for therapeutic_agent slot (clinical trials could reference specific drugs)
• Make genetics section in schema more specific #126: Make genetics section more specific (trials often have genetic inclusion criteria)
• Define pattern for qualifiers #113: Define pattern for qualifiers (trials may target specific phenotype qualifiers)

Next Steps

1. Design decision: Should clinical trials be:

   • A separate top-level section (like treatments)?
   • Nested within treatments to show trial evidence for specific therapies?
   • Both (trials as evidence for treatments + standalone trials section)?

2. Scope: Should initial implementation include:

   • Active/recruiting trials only?
   • All completed/terminated trials?
   • User-configurable filters?

3. Curation workflow: How should curators identify relevant trials?

   • Manual NCT ID entry?
   • Automated search by disease MONDO ID?
   • Both approaches?

References

• linkml-reference-validator: Clinical Trials Validation
• ClinicalTrials.gov API v2 Documentation
• dismech schema: src/dismech/schema/dismech.yaml