Grounding
omop_graph.reasoning.grounding
Semantic Grounding Orchestration.
This module provides the high-level ground_term function, which orchestrates
the full grounding pipeline:
1. Candidate Resolution: Finding raw concepts that match the input text.
2. Hierarchy Validation: Ensuring candidates have a valid relationship path
to required parent concepts, when parent concepts are given. Grounding can
also run unconstrained (no parent concepts), trading disambiguation power
for coverage.
3. Standardization: Mapping non-standard candidates to standard OMOP concepts.
4. Semantic Ranking: Using embeddings and graph-based scoring to select the
best mapping.
GroundingConstraints
dataclass
Configuration for restricting the grounding search space.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_ids
|
tuple[int, ...]
|
OMOP Concept IDs that act as required ancestors for any valid result. When None, grounding is unconstrained: candidates are still resolved and standardized via identity hops, but without ancestor verification. This trades disambiguation power for coverage. Results are ranked by relevance and identity-hop distance only, not by proximity to a known hierarchy branch. |
required |
search_constraint
|
ConceptFilter
|
Domain and Vocabulary restrictions for the initial resolution phase. |
required |
max_depth
|
int
|
Maximum allowed distance in the hierarchy between a candidate and a parent.
Defaults to |
6
|
predicate_kinds
|
frozenset[PredicateKind]
|
Edge types allowed during BFS traversal. Defaults to IDENTITY only, which covers the OMOP "Maps to" and "Non-standard to Standard" relationships. Allowing HIERARCHY or ASSOCIATION edges would traverse parent-of and cross-domain links, expanding candidates to unrelated concepts and diluting grounding results. |
frozenset({IDENTITY})
|
find_standard_concepts(kg, candidate, parent_ids, max_depth, max_paths=3, predicate_kinds=frozenset({PredicateKind.IDENTITY}))
Identify standard concepts related to a candidate, optionally satisfying parent constraints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kg
|
KnowledgeGraph
|
The Knowledge Graph instance. |
required |
candidate
|
CandidateHit
|
The initial match found by a resolver. |
required |
parent_ids
|
tuple of int
|
Acceptable ancestor concept IDs. When None, no ancestor verification is performed. Instead, the candidate is standardized via identity hops only. |
required |
max_depth
|
int
|
Maximum min_levels_of_separation allowed in the ancestry check when parent_ids is given, or maximum identity-hop count allowed when parent_ids is None. |
required |
max_paths
|
int
|
Per-target cap on unique standard concepts collected (or an overall cap when parent_ids is None). |
3
|
predicate_kinds
|
frozenset of PredicateKind
|
Edge types to traverse. Defaults to IDENTITY only, which covers the OMOP "Maps to" relationships between non-standard and standard concepts. See GroundingConstraints.predicate_kinds for the rationale. |
frozenset({IDENTITY})
|
Returns:
| Type | Description |
|---|---|
list of StandardConcept
|
Standard concepts associated with the candidate that satisfy the ancestor constraint, or, when parent_ids is None, every standard concept reached. |
ground_term(resolver_pipeline, kg, query, query_embedding, constraints, max_candidates=None, context=None)
Ground a text string to a ranked list of standard OMOP concepts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
resolver_pipeline
|
ResolverPipeline
|
The pipeline of search strategies to find initial candidates. |
required |
kg
|
KnowledgeGraph
|
The OMOP Knowledge Graph instance. |
required |
query
|
str
|
The input query to ground. |
required |
query_embedding
|
ndarray
|
The embedding vector for the input query. When None and a writer interface is
available, the embedding is computed on demand from |
required |
constraints
|
GroundingConstraints
|
Contextual constraints (parents, domains, etc.) to apply. |
required |
max_candidates
|
int
|
Limit for the number of candidates returned. If None, returns all candidates. |
None
|
context
|
str
|
Additional free-form context folded into the on-demand query-embedding
text. Has no effect when |
None
|
Returns:
| Type | Description |
|---|---|
list[StandardConceptWithScore]
|
A list of standard concepts sorted by their total score (descending). |