Adds normalized source-concept context (parents, children, description, synonyms)
onto a candidate table, keyed by source vocabulary + concept code.
This is the source-side mirror of
:func:ariadne.llm_mapping.concept_context_retriever.add_concept_context.
Instead of querying the OMOP database, it reads context from a CSV (or an
already-loaded DataFrame) that carries the normalized schema, so the same
file can supply both source concepts and their context.
Source code in src/ariadne/llm_mapping/source_context_retriever.py
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108 | class SourceContextRetriever:
"""
Adds normalized source-concept context (parents, children, description, synonyms)
onto a candidate table, keyed by source vocabulary + concept code.
This is the source-side mirror of
:func:`ariadne.llm_mapping.concept_context_retriever.add_concept_context`.
Instead of querying the OMOP database, it reads context from a CSV (or an
already-loaded DataFrame) that carries the normalized schema, so the same
file can supply both source concepts and their context.
"""
def __init__(
self,
context_source: Union[str, Path, pd.DataFrame],
context_columns: List[str] = SOURCE_CONTEXT_COLUMNS,
) -> None:
"""
Args:
context_source: Path to a CSV, or a DataFrame, carrying the key columns
(source_vocabulary_id, source_concept_code) and any context columns.
context_columns: Normalized context columns to expose. Columns absent from
the source are treated as empty.
"""
self.context_columns = list(context_columns)
if isinstance(context_source, pd.DataFrame):
context_df = context_source.copy()
else:
context_df = pd.read_csv(context_source)
missing_keys = [c for c in KEY_COLUMNS if c not in context_df.columns]
if missing_keys:
raise ValueError(f"context_source is missing required key columns: {missing_keys}")
available_context = [c for c in self.context_columns if c in context_df.columns]
context_df = context_df[KEY_COLUMNS + available_context].copy()
for column in KEY_COLUMNS:
context_df[column] = context_df[column].astype(str)
# One context row per source concept.
self._context = context_df.drop_duplicates(subset=KEY_COLUMNS)
def add_source_context(
self,
candidate_table: pd.DataFrame,
vocabulary_id_column: str = "source_vocabulary_id",
code_column: str = "source_concept_code",
) -> pd.DataFrame:
"""
Merges the normalized source context onto *candidate_table* by
(vocabulary_id, concept_code).
Args:
candidate_table: DataFrame containing the source key columns.
vocabulary_id_column: Column in *candidate_table* holding the source vocabulary id.
code_column: Column in *candidate_table* holding the source concept code.
Returns:
*candidate_table* enriched with the normalized source_* context columns.
Unmatched rows and columns absent from the context source are filled with "".
"""
missing_keys = [c for c in (vocabulary_id_column, code_column) if c not in candidate_table.columns]
if missing_keys:
raise ValueError(f"candidate_table is missing required key columns: {missing_keys}")
context = self._context.rename(
columns={
"source_vocabulary_id": vocabulary_id_column,
"source_concept_code": code_column,
}
)
merge_keys = [vocabulary_id_column, code_column]
merged = candidate_table.copy()
merged[vocabulary_id_column] = merged[vocabulary_id_column].astype(str)
merged[code_column] = merged[code_column].astype(str)
# Drop any pre-existing context columns so retrieved context is authoritative and no _x/_y suffixes appear.
overlap = [c for c in self.context_columns if c in merged.columns]
if overlap:
merged = merged.drop(columns=overlap)
merged = merged.merge(context, on=merge_keys, how="left")
for column in self.context_columns:
if column not in merged.columns:
merged[column] = ""
else:
merged[column] = merged[column].fillna("")
return merged
|
__init__(context_source, context_columns=SOURCE_CONTEXT_COLUMNS)
Parameters:
| Name |
Type |
Description |
Default |
context_source
|
Union[str, Path, DataFrame]
|
Path to a CSV, or a DataFrame, carrying the key columns
(source_vocabulary_id, source_concept_code) and any context columns.
|
required
|
context_columns
|
List[str]
|
Normalized context columns to expose. Columns absent from
the source are treated as empty.
|
SOURCE_CONTEXT_COLUMNS
|
Source code in src/ariadne/llm_mapping/source_context_retriever.py
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60 | def __init__(
self,
context_source: Union[str, Path, pd.DataFrame],
context_columns: List[str] = SOURCE_CONTEXT_COLUMNS,
) -> None:
"""
Args:
context_source: Path to a CSV, or a DataFrame, carrying the key columns
(source_vocabulary_id, source_concept_code) and any context columns.
context_columns: Normalized context columns to expose. Columns absent from
the source are treated as empty.
"""
self.context_columns = list(context_columns)
if isinstance(context_source, pd.DataFrame):
context_df = context_source.copy()
else:
context_df = pd.read_csv(context_source)
missing_keys = [c for c in KEY_COLUMNS if c not in context_df.columns]
if missing_keys:
raise ValueError(f"context_source is missing required key columns: {missing_keys}")
available_context = [c for c in self.context_columns if c in context_df.columns]
context_df = context_df[KEY_COLUMNS + available_context].copy()
for column in KEY_COLUMNS:
context_df[column] = context_df[column].astype(str)
# One context row per source concept.
self._context = context_df.drop_duplicates(subset=KEY_COLUMNS)
|
add_source_context(candidate_table, vocabulary_id_column='source_vocabulary_id', code_column='source_concept_code')
Merges the normalized source context onto candidate_table by
(vocabulary_id, concept_code).
Parameters:
| Name |
Type |
Description |
Default |
candidate_table
|
DataFrame
|
DataFrame containing the source key columns.
|
required
|
vocabulary_id_column
|
str
|
Column in candidate_table holding the source vocabulary id.
|
'source_vocabulary_id'
|
code_column
|
str
|
Column in candidate_table holding the source concept code.
|
'source_concept_code'
|
Returns:
| Type |
Description |
DataFrame
|
candidate_table enriched with the normalized source_* context columns.
|
DataFrame
|
Unmatched rows and columns absent from the context source are filled with "".
|
Source code in src/ariadne/llm_mapping/source_context_retriever.py
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108 | def add_source_context(
self,
candidate_table: pd.DataFrame,
vocabulary_id_column: str = "source_vocabulary_id",
code_column: str = "source_concept_code",
) -> pd.DataFrame:
"""
Merges the normalized source context onto *candidate_table* by
(vocabulary_id, concept_code).
Args:
candidate_table: DataFrame containing the source key columns.
vocabulary_id_column: Column in *candidate_table* holding the source vocabulary id.
code_column: Column in *candidate_table* holding the source concept code.
Returns:
*candidate_table* enriched with the normalized source_* context columns.
Unmatched rows and columns absent from the context source are filled with "".
"""
missing_keys = [c for c in (vocabulary_id_column, code_column) if c not in candidate_table.columns]
if missing_keys:
raise ValueError(f"candidate_table is missing required key columns: {missing_keys}")
context = self._context.rename(
columns={
"source_vocabulary_id": vocabulary_id_column,
"source_concept_code": code_column,
}
)
merge_keys = [vocabulary_id_column, code_column]
merged = candidate_table.copy()
merged[vocabulary_id_column] = merged[vocabulary_id_column].astype(str)
merged[code_column] = merged[code_column].astype(str)
# Drop any pre-existing context columns so retrieved context is authoritative and no _x/_y suffixes appear.
overlap = [c for c in self.context_columns if c in merged.columns]
if overlap:
merged = merged.drop(columns=overlap)
merged = merged.merge(context, on=merge_keys, how="left")
for column in self.context_columns:
if column not in merged.columns:
merged[column] = ""
else:
merged[column] = merged[column].fillna("")
return merged
|