submit to NDEx

[cmungall]

submit causal graphs + genes to NDEx where they will be queryable using iQuery

context: https://docs.google.com/presentation/d/1lWUWOTAMJE11tgXvOAyZoCCrx2GaSzpQlS2sTuLcAgk/edit?slide=id.p#slide=id.p

[github-actions]

Analysis: Submit to NDEx

Overview

This issue proposes submitting dismech's causal graphs and gene data to NDEx (Network Data Exchange) where they can be queried using iQuery.

Current State of Causal Graphs in dismech

dismech already has infrastructure for building and visualizing causal graphs:

1. Graph Construction (src/dismech/graph.py)

The system currently:

• Extracts nodes from 6 entity types:

  • Pathophysiology mechanisms
  • Phenotypes
  • Environmental factors
  • Genetic factors
  • Treatments
  • Biochemical markers

• Extracts edges from two relationship types:

  • downstream relationships in pathophysiology (predicate: causes)
  • sequelae relationships in phenotypes (predicate: leads_to)

• Performs referential integrity checking (orphan target detection)

• Generates Mermaid diagrams for visualization

• Tracks graph complexity metrics (edge count, longest path length)

2. Current Export Capabilities (src/dismech/export/browser_export.py)

The system currently exports to:

• JSON format for faceted search browser
• JavaScript format for web rendering
• Includes graph metadata: causal_graph_edges and causal_graph_longest_path

3. Gene Data

Gene associations are captured in the genetic section of disorder YAML files and are already extracted during export.

What NDEx Submission Would Require

NDEx Overview

NDEx is a network data exchange platform that allows storage, sharing, and querying of biological networks. iQuery enables semantic querying across networks.

Implementation Requirements

To submit to NDEx, you would need to:

1. Format Conversion

   • Convert dismech causal graphs to NDEx-compatible formats (CX, CX2, or standard graph formats)
   • Map dismech node types to NDEx node attributes
   • Map dismech edge predicates to standardized relationships (e.g., RO terms)

2. NDEx API Integration

   • Authenticate with NDEx using their Python client (ndex2)
   • Create/update network entries programmatically
   • Handle network metadata (attribution, citations, evidence)

3. Annotation Enhancement

   • Ensure nodes have proper ontology term mappings (already largely done via HP, CL, GO, MONDO terms)
   • Add provenance metadata (PMID references already captured in evidence items)
   • Map gene names to standardized identifiers (HGNC, already in conf/oak_config.yaml)

4. Batch Processing

   • Process all 55+ disorder files in kb/disorders/
   • One network per disorder, or aggregate networks by category/pathway

Suggested Implementation Approach

# New module: src/dismech/export/ndex_export.py

import ndex2
from dismech.graph import build_causal_graph

def export_to_ndex(disorder_yaml, ndex_credentials):
    """Export a disorder's causal graph to NDEx."""
    
    # 1. Build causal graph
    graph = build_causal_graph(disorder_yaml)
    
    # 2. Convert to CX format
    cx_network = convert_to_cx(graph, disorder_yaml)
    
    # 3. Add metadata and annotations
    add_ndex_metadata(cx_network, disorder_yaml)
    
    # 4. Upload to NDEx
    ndex_client = ndex2.client.Ndex2(
        host='http://www.ndexbio.org',
        username=credentials['username'],
        password=credentials['password']
    )
    
    network_url = ndex_client.save_new_network(cx_network)
    return network_url

Benefits of NDEx Submission

1. Interoperability: Networks become queryable alongside other biological networks
2. iQuery Integration: Semantic search across disease mechanisms
3. Visualization: NDEx provides Cytoscape-based interactive visualization
4. Community Access: Makes dismech data more discoverable
5. Integration: Could integrate with GO-CAMs and other pathway databases (context from linked slides)

Related Context

The linked Google Slides presentation titled "GO-CAMs in NDEx - May 2025" suggests this is part of a broader effort to integrate Gene Ontology Causal Activity Models (GO-CAMs) with NDEx. dismech's pathophysiology graphs share structural similarities with GO-CAMs:

• Both model causal mechanisms
• Both link molecular activities to phenotypes
• Both support evidence-based curation

Next Steps

1. Research NDEx API: Review ndex2 Python client documentation
2. Define mapping strategy: How to map dismech graph elements to NDEx/CX format
3. Pilot with single disorder: Test export with one well-curated disorder (e.g., Asthma)
4. Handle evidence references: Map PMID evidence items to NDEx citations
5. Automate batch submission: Script to upload all disorders
6. Update documentation: Document NDEx URLs in disorder YAML metadata

Relevant dismech Commands

# Validate graph integrity for all disorders
uv run python -m dismech.graph --validate kb/disorders/

# Show Mermaid diagram for a single disorder
uv run python -m dismech.graph --show kb/disorders/Asthma.yaml

# Current export to browser format
uv run python -m dismech.export.browser_export --input-dir kb/disorders/ --output app/data.js

---

Ready for Implementation: This would be a valuable enhancement. If you'd like me to create a prototype NDEx exporter, I can start with a pilot implementation for a single disorder.