Develop approach for aligning with other Monarch resources

[caufieldjh]

Discussed at Monarch Data Call on Feb 13 2026.

There is a need to develop a framework for coordinating with and integrating evidence and artifacts from other Monarch resources, including the Monarch KG and ontologies.

This may include cases in which a Dismech page identifies a disorder relationship in conflict with edges presented in the Monarch KG.

As an immediate goal, it may be useful to link to Monarch KG entries when specific phenotypes or genes are mentioned.

Graph edges could also inform the chain of pathophysiological events.

[github-actions]

Summary: Monarch Initiative Integration Strategy

This issue outlines an important strategic initiative to align dismech with the broader Monarch Initiative ecosystem, specifically the Monarch Knowledge Graph (KG) and related ontology resources.

Current State

Existing Monarch Integration:

• dismech is already part of the Monarch Initiative (hosted at dismech.monarchinitiative.org)
• The schema uses standard Monarch-aligned ontologies: HP (phenotypes), MONDO (diseases), HGNC (genes), GO (biological processes), CL (cell types), UBERON (anatomy), MAXO (treatments)
• HTML templates link ontology terms to external browsers (HPO JAX, OLS, etc.)
• The schema defines causal graphs representing pathophysiological processes (see src/dismech/graph.py)

What's Missing:

• No direct links to Monarch KG disease/phenotype/gene pages
• No mechanism to query or integrate Monarch KG edges
• No systematic approach for handling conflicts between dismech assertions and Monarch KG data

Monarch Initiative Ecosystem Context

The Monarch Knowledge Graph is described as "an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists" that contains "millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources."

Key Components:

• Monarch KG: Aggregates heterogeneous biomedical data from dozens of sources
• Monarch App: Vue.js frontend + FastAPI backend (monarch-py)
• Monarch API: RESTful API at api.monarchinitiative.org (v3)
• Ontologies: MONDO, HPO, and others maintained by Monarch

Proposed Integration Areas

1. Entity Linking

Add direct links from dismech pages to corresponding Monarch KG entries:

For phenotypes (HP terms):

• Link from HP:0001250 (Seizures) → https://monarchinitiative.org/phenotype/HP:0001250
• This provides access to Monarch's aggregated associations, frequency data, and cross-references

For genes (HGNC):

• Link from HGNC:5 (FGFR2) → https://monarchinitiative.org/gene/HGNC:5
• Access gene-disease associations, expression data, orthology

For diseases (MONDO):

• Already partially done via MONDO badges in disorder headers
• Could enhance with direct "View in Monarch KG" buttons

Implementation: Modify src/dismech/render.py to include Monarch KG URLs in the curie_to_url() function or template rendering.

2. Causal Graph Enrichment

dismech already generates causal graphs from pathophysiology → downstream relationships (see issue #164 about atomic aberrant processes). The Monarch KG could inform these graphs:

Use Monarch KG edges to:

• Suggest candidate pathophysiological connections based on gene-phenotype associations
• Validate that dismech's manually curated chains align with computational predictions
• Identify gaps where Monarch KG shows associations but dismech lacks mechanistic explanations

Example workflow:

1. dismech curator models: FGFR2 gain-of-function → Craniosynostosis
2. Query Monarch KG for all FGFR2-associated phenotypes
3. Identify phenotypes in KG but not in dismech's model (e.g., hearing loss)
4. Curator investigates whether to add missing connections

Implementation: Python script using monarch-py or Monarch API to fetch associations, compare with dismech YAML, generate curation suggestions.

3. Conflict Resolution Framework

When dismech and Monarch KG disagree:

Possible conflict scenarios:

• Monarch KG shows gene-phenotype association; dismech model shows no mechanistic link
• Monarch KG lacks association; dismech has detailed pathophysiology
• Frequency estimates differ
• Inheritance patterns conflict

Proposed handling:

• Documentation field: Add optional monarch_kg_notes to evidence items
• Reconciliation tags: Mark assertions as consistent_with_monarch_kg, conflicts_with_monarch_kg, or not_in_monarch_kg
• Evidence priority: dismech focuses on mechanism (HOW), Monarch KG on associations (WHAT). Both are valuable but complementary.

Example:

phenotypes:
  - name: Craniosynostosis
    phenotype_term:
      term:
        id: HP:0001363
        label: Craniosynostosis
    monarch_kg_notes: "Consistent with Monarch KG FGFR2-HP:0001363 association (score: 0.98)"

4. Bidirectional Data Flow

dismech → Monarch KG:

• dismech's curated pathophysiology narratives could be exposed as structured knowledge
• Export dismech causal graphs as Biolink edges for ingestion into Monarch KG
• Contribute evidence-backed mechanistic chains not present in other sources

Monarch KG → dismech:

• Import high-confidence gene-disease associations as curation candidates
• Use Monarch's aggregated frequency data to enrich phenotype descriptors
• Leverage Monarch's cross-references (ClinVar, OMIM, Orphanet) for broader context

Related Work

• Issue Make genetics section in schema more specific #126: "Make genetics section in schema more specific" - relevant for gene representation alignment
• Issue many pathophys entries need to be split/debundled #164: "Many pathophys entries need to be split/debundled" - atomic process modeling would make KG mapping easier

Technical Implementation Notes

Monarch API Integration:
The Monarch API (v3) provides endpoints for querying associations. Key endpoints likely include:

• /association - query gene-disease-phenotype associations
• /entity/{id} - get details for specific entities
• /search - search across entity types

Example integration code:

import requests

def get_monarch_associations(entity_id: str):
    """Fetch Monarch KG associations for an entity."""
    url = f"https://api.monarchinitiative.org/v3/entity/{entity_id}/associations"
    response = requests.get(url)
    return response.json()

Monarch-py library:
The monarch-py Python library provides a higher-level interface:

from monarch_py import monarch_api

# Query associations
results = monarch_api.get_associations(
    subject="MONDO:0007404",  # Crouzon syndrome
    predicate="biolink:has_phenotype"
)

Next Steps

1. Research phase: Explore Monarch API capabilities, identify most relevant endpoints
2. Schema enhancement: Add optional fields for Monarch KG cross-references and conflict notes
3. Template updates: Modify HTML templates to include Monarch KG links for genes/phenotypes/diseases
4. Validation tooling: Script to compare dismech assertions with Monarch KG associations
5. Documentation: Create guidelines for curators on when/how to reference Monarch KG

Questions for Discussion

1. Should Monarch KG links be purely informational, or should we programmatically validate dismech content against KG assertions?
2. How should we handle cases where dismech's detailed mechanism contradicts a Monarch KG aggregate association?
3. Should dismech export its causal graphs for potential Monarch KG ingestion?
4. What level of Monarch API integration is appropriate (display-only links vs. active querying)?

---

CC: @cmungall @caufieldjh for strategic input on Monarch alignment priorities