Scoring
omop_graph.graph.scoring
Scoring algorithms for ranking resolved concepts.
This module implements the logic for scoring candidate OMOP concepts based on: 1. Relevance: How well the text matches the query (embeddings + string similarity). 2. Parsimony: Penalizing deep graph traversals (finding a concept far away). 3. Broadness: Rewarding concepts that are more general (higher ancestor count), often useful for finding category headers.
StandardConceptWithScore
dataclass
Bases: StandardConcept
A StandardConcept enriched with scoring metrics.
Attributes:
| Name | Type | Description |
|---|---|---|
total_score |
float
|
The final calculated score used for ranking.
Formula: |
embedding_score |
(float, optional)
|
The cosine similarity score from the embedding model. |
relevance |
float
|
The relevance score used for ranking: embedding similarity when available, textual similarity otherwise. |
parsimony_penalty |
float
|
Penalty based on graph distance (separation). |
broadness_bonus |
float
|
Bonus based on the concept's generality (ancestor count). |
from_standard_concept(standard_concept, embedding_score, relevance, parsimony_penalty, broadness_bonus, total_score)
classmethod
Factory method to promote a StandardConcept to a scored version.
score_standard_concepts(text, standard_concepts, kg, nearest_concept_matches=None)
Attach scoring metrics to each standard concept.
Notes
Scores are computed but the returned list preserves the input order. Callers are responsible for sorting if ranking is required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
The original query text. |
required |
standard_concepts
|
tuple[StandardConcept, ...]
|
The candidate concepts to score. |
required |
kg
|
KnowledgeGraph
|
The graph instance used for retrieving metadata (ancestor counts). |
required |
nearest_concept_matches
|
Tuple[Tuple[NearestConceptMatch, ...], ...]
|
Pre-computed nearest-concept matches from the embedding index. The outer tuple corresponds to query vectors in order; each inner tuple holds the nearest matches for that query vector. Currently only a single query vector is supported. |
None
|
Notes
Standard concept scoring is ONLY performed for concepts that were matched via the embedding resolver, and only if nearest_concept_matches are provided. Concepts matched via non-embedding resolvers will still receive parsimony and broadness scoring, but their relevance will be based solely on textual similarity.
Returns:
| Type | Description |
|---|---|
list[StandardConceptWithScore]
|
Scored concepts in the same order as |