Nodes

omop_graph.graph.nodes

Node definitions for the OMOP Knowledge Graph.

This module defines lightweight data structures (Views) representing entities in the OMOP graph, such as Concepts and search matches.

These classes are primarily used for: 1. Holding data returned by database queries. 2. Rendering rich representations in Jupyter notebooks via _repr_html_. 3. Ranking and sorting search results.

AncestorMatch dataclass

Represents a successful hierarchy check between two concepts.

Parameters:

Name	Type	Description	Default
ancestor_concept_id	int	The concept ID of the ancestor.	required
descendant_concept_id	int	The concept ID of the descendant.	required
min_levels_of_separation	int	The shortest path distance between them (0 = self).	required

ConceptView dataclass

A lightweight, immutable view of an OMOP Concept.

This class represents a row from the concept table, optimized for read-only access and visualization.

Parameters:

Name	Type	Description	Default
concept_id	int	The unique OMOP identifier.	required
concept_name	str	The human-readable name of the concept.	required
concept_code	str	The source code in the original vocabulary.	required
vocabulary_id	str	The vocabulary identifier (e.g., 'SNOMED', 'RxNorm').	required
domain_id	str	The domain identifier (e.g., 'Condition', 'Drug').	required
concept_class_id	str	The class of the concept (e.g., 'Clinical Finding').	required
standard_concept	bool	True if this is a Standard Concept ('S'), False otherwise.	required
valid_start_date	date	The start date of validity.	required
valid_end_date	date	The end date of validity.	required
invalid_reason	str	The reason for invalidation (e.g., 'D', 'U'), or None if valid.	required

from_row(row) classmethod

Create a ConceptView from a SQLAlchemy Row.

This method handles the conversion of the 'standard_concept' field from the DB string ("S") to a boolean.

Parameters:

Name	Type	Description	Default
row	Row	A row object returned by a SQLAlchemy query selecting from the Concept table.	required

Returns:

Type	Description
ConceptView	The instantiated view.

LabelMatch dataclass

A single result from a text search/grounding operation.

Parameters:

Name	Type	Description	Default
input_label	str	The original text that was searched.	required
matched_label	str	The text in the database that matched (concept name or synonym).	required
concept_id	int	The ID of the matched concept.	required
match_kind	LabelMatchKind	How the match was found (Exact, Synonym, etc.).	required
is_standard	bool	Whether the matched concept is Standard.	required
is_active	bool	Whether the matched concept is currently valid.	required

LabelMatchGroupView dataclass

A grouped collection of LabelMatch results.

Aggregates matches by Concept ID to present a unified view of why a specific concept was selected (e.g., matched via name AND synonym).

Parameters:

Name	Type	Description	Default
groups	dict[int, tuple[LabelMatch, ...]]	A dictionary mapping Concept ID to a tuple of sorted LabelMatches.	required

__iter__()

Iterate over all matches flattened.

from_matches(matches) classmethod

Construct a group view from a flat iterable of matches.

Matches are grouped by Concept ID.

Notes

This could also be performed in SQL during the query phase.

Parameters:

Name	Type	Description	Default
matches	Iterable[LabelMatch]	The raw search results.	required

Returns:

Type	Description
LabelMatchGroupView	The grouped view.

LabelMatchKind

Bases: Enum

Classification of how a label matched a concept. Value order defines priority (lower is better):

Notes

Supported match kinds include: - EXACT: Direct case-insensitive match on concept_name. - FTS: Full-text search match (fuzzy). - PARTIAL: Partial match (fuzzy) substrings with ILIKE. - EMBEDDING: Match based on vector similarity.

It currently does not distinguish between synonym vs. concept_name matches as they are recognised as identical. Could be extended in the future if needed.