Skip to content

omop-graph

omop-graph is a lightweight Virtual Knowledge Graph (VKG) built on top of the OMOP CDM. It transforms the static OMOP vocabulary tables into a dynamic graph environment suitable for NLP grounding, clinical reasoning, and other tasks that benefit from a knowledge graph.

Why omop-graph?

Unlike generic graph libraries, omop-graph is built specifically for clinical data:

  • Semantic Awareness: Understands the difference between relationship kinds (hierarchy, identity, composition, association, attribute).
  • Efficient Grounding: Instead of traversing every possible path, the library uses a Standard Anchor approach — translating non-standard terms to standard concepts and leveraging the OMOP concept_ancestor table for high-speed hierarchy validation.
  • Transparent Scoring: Decisions aren't black boxes. Every candidate concept is scored based on textual similarity, graph distance (parsimony), and clinical generality (broadness).
  • Pre-classification: Relationships are pre-classified into semantic groups, enabling quicker traversal restrictions and more targeted reasoning.

Documentation Overview

Core Components

  • KnowledgeGraph: The VKG interface — connecting to OMOP and traversing the graph.
  • Relationships: Pre-classification of OMOP edges into semantic kinds.
  • Oaklib Interface: OAK-compliant adapter for cross-ontology tooling.

Reasoning

Explore the grounding pipeline used by clinical NLP tools.

Embedding Support

Powered by omop-emb

Embedding-based similarity (vector search, RAG retrieval, on-the-fly embedding computation) is provided by the companion omop-emb package. Install it with pip install "omop-graph[emb]" and see Knowledge Graph — Embedding Configuration for integration details.

Interactive Exploration

omop-graph includes built-in HTML and Mermaid renderers for Jupyter Notebooks, allowing you to visualise concepts, traversal traces, and relationship summaries directly in a notebook.

Testing

  • Testing: Test configuration, coverage, and how to set up environment variables for local runs.