Embeddings of clinical codes enable knowledge-grounded AI in medicine

Abstract

Standardization of electronic health records (EHRs) has enabled the use of clinical codes in AI. We introduce ClinVec, an embedding store that provides embeddings for 153,166 clinical codes and concepts across eight vocabularies. ClinVec embeds ClinGraph, a knowledge graph with over 2 million edges tailored to clinical vocabularies used in EHRs. We validate the embeddings using an inter-institutional clinician panel and N = 3767 clinical term pairs spanning 11 disease areas, and we find that embedding similarity reflects clinical relatedness. We use ClinVec for knowledge injection in large language model medical question answering and for unsupervised patient stratification and risk prediction. By providing a shared representation of clinical concepts, ClinVec supports knowledge-grounded AI systems for modeling patients and populations.

Introduction

Standardized clinical vocabularies underpin electronic health record (EHR) systems. These vocabularies enable interoperability across health systems, but each typically covers a narrow domain of patient records, such as diagnoses, laboratory tests, procedures, or administrative data^1,2. As a result, EHRs rely on multiple vocabularies, each tailored to a specific domain, which fragments the representation of clinical information^3,4. Several initiatives standardize clinical vocabularies and medical concepts. For example, OMOP⁵ and FHIR⁶ provide common data models that harmonize vocabularies into a unified system, while the UMLS Metathesaurus⁷ and Disease Ontology⁸ organize medical concepts and link clinical vocabularies through cross-references.

Widespread EHR adoption has accelerated the use of AI in medicine^9,10, with more than half of healthcare foundation AI models relying on structured clinical codes¹¹. Clinical codes are often represented as discrete inputs, for example, using one-hot encoding or tokenization¹². In transformer-based models, each EHR code is treated as a token, and its embedding is learned from patient-level data during training^13–15. However, these strategies overlook information encoded in clinical vocabularies. For example, ATC is a hierarchical taxonomy organized by therapeutic and pharmacological properties that groups drugs with shared indications, such as antineoplastic agents (L01) and antihypertensives (C02)¹⁶. SNOMED CT¹⁷ and LOINC¹⁸ similarly encode parent-child and attribute relations across disorders, procedures, and laboratory tests. Ignoring this structure can separate semantically related codes and miss clinically meaningful information essential for accurate patient representation^19,20.

Knowledge graphs (KGs) are a general data structure for organizing multimodal relational data^21–25 and can be used to capture structure among clinical codes together with their relationships, such as is-a and part-of type relationships, medical hierarchies, and cross-terminology mappings. Graph embedding techniques generate high-dimensional vector representations of the KG by encoding graph structure and typed relationships into a continuous space, so that clinically related concepts have similar representations. Integrating these embeddings into AI models can improve performance across clinical tasks, including disease prediction^26–29, drug interaction modeling^30,31, and clinical trial recommendations³².

Embedding stores offer readily available embeddings of concepts across a variety of domains³³, such as genes^34–36, proteins^37,38, and molecules³⁹. These embeddings provide compact representations of entities that reflect their properties and relationships. They are useful when labeled data are limited, because they let models start from these representations rather than learning them from scratch^40,41. When used as inputs to AI models, precomputed embeddings support transfer learning⁴², pre-training, and retrieval augmented systems⁴³, and can improve performance and generalization in clinical prediction and reasoning tasks^44–47. Embedding stores built from KGs can be integrated into foundation models to ground model outputs in factual and clinically vetted knowledge^48–51. Existing embeddings of clinical codes leverage information from either a single or limited number of clinical vocabularies at a time, limiting the breadth of clinical knowledge represented within an embedding store. For example, snomed2vec⁵² leverages only SNOMEDCT codes, cui2vec focuses only on the UMLS metathesaurus, and recent work by Finch et al. utilizes hierarchy information derived only from ICD10 codes⁵³. Because coding systems capture distinct facets of care, linking concepts across vocabularies is needed to fully capture the information contained in EHR data.

Here, we created a knowledge-graph-driven embedding store named ClinVec, which provides embeddings for 153,166 clinical codes and concepts across eight vocabularies. The underlying knowledge structure is provided by ClinGraph, a newly developed knowledge graph with more than two million edges that is tailored to clinical vocabularies used in EHRs and represents codes within their original namespaces. This preserves semantics unique to each vocabulary and avoids any mapping layer between EHR codes and ClinVec embeddings. Edges reflect equivalences and mappings across vocabularies, as well as clinical relationships between nodes. A panel of clinical experts validated a subset of relationships defined by the clinical knowledge embeddings across 3767 clinical term pairs spanning 11 disease areas. We show that integrating ClinVec into large language models improves medical question answering. Finally, we use ClinVec as a basis for phenotype risk score analyses for chronic kidney disease, chronic obstructive pulmonary disease, and heart failure, using EHR data from 4.57 million patients in Clalit Health Services.

Results

A comprehensive clinical knowledge graph for medical codes

We construct ClinGraph, a clinically broad, interoperable representation of clinical knowledge that can be leveraged by medical AI systems. ClinGraph is composed of 153,166 nodes and 2,873,025 edges and integrates eight commonly used vocabularies with EHRs and their secondary usage, ranging from diagnosis codes (ICD9CM, ICD10CM, phecodes⁵⁴), laboratory tests (LOINC), medications (RxNorm⁵⁵, ATC), procedures (CPT⁵⁶), and other controlled clinical vocabularies (SNOMED CT, UMLS) (Fig. 1a, b). Because each vocabulary was designed for a specific purpose and organizes concepts differently..., incorporating multiple vocabularies in ClinGraphis essential. In routine care, healthcare systems use terminologies to record diagnoses, laboratory tests, procedures, and medications, so multiple vocabularies are needed to describe patient care. We therefore build ClinGraph from vocabularies that are used directly in structured EHRs, which makes it compatible with most clinical datasets.

Fig. 1. Overview of approach.

a Meta-graph showing the structure of ClinGraph and the edge relationships between clinical vocabularies. b An example local neighborhood of ClinGraph. Each clinical code is represented as a node, and the color denotes the source clinical vocabulary. c ClinVec workflow for generating clinical knowledge embeddings. d Applications of ClinGraph and ClinVec. e A scatterplot showing a reduced dimension of the embedding space of diagnosis codes (phecodes), where each code is shaded by its corresponding organ system categorization. f Scatterplot of the latent space of ATC5 medication codes where each code is shaded according to the corresponding ATC-level 1 categorization.

Clinical codes are represented as nodes, and edges are drawn between codes according to EHR-vocabulary crosswalks (e.g., General Equivalence Mapping, GEM⁵⁷). By connecting related clinical concepts through edges, we avoid the need for collapsing all concepts into a single coding system, which can introduce errors or information loss when mapping across terminologies. This design allows ClinGraph to capture structure shared across vocabularies while preserving the differences in how each vocabulary defines and organizes clinical concepts. To link concepts in ClinGraph beyond equivalence mappings, we add cross-vocabulary edges derived from concept-level relations in UMLS and PheMap⁵⁸. PheMap knowledge base contains clinical relationships inferred through mining of biomedical literature, offering a complementary source of information to clinical ontologies. A list of sources and the distribution of nodes and edges in ClinGraph are provided in Supplementary Table S1 and Supplementary Table S2.

Although many KGs represent disease and drug entities, they generally do not represent nodes using standardized clinical vocabularies from EHRs^23,24,59,60. To compare the coverage of clinical vocabularies against six popular KGs, we map all disease and drug node identifiers of each KG to ICD10CM and ATC codes (Supplementary Table S3). ClinGraph has the highest coverage of ICD10CM and ATC codes across all KGs except GAT-ETM⁶¹, which includes all codes in both vocabularies. However, GAT-ETM mostly derives edges from the hierarchical relationships within each vocabulary and is limited solely to ICD10CM and ATC. Finally, most existing KGs do not represent procedures or lab tests, whereas ClinGraph adds both through CPT and LOINC.

Learning a unified representation of clinical knowledge

Using a heterogeneous graph transformer (HGT)⁶², ClinVec learns a function that maps each node in ClinGraph to an embedding vector (Fig. 1c). ClinVec determines how information is shared between nodes using a multi-head attention mechanism to up-weight and down-weight different parts of ClinGraph graph topology⁶³. We model four node types, administrative diagnosis codes, treatments, patient clinical state indicators (e.g., laboratory tests), and semantic clinical terminologies, to reflect how each vocabulary is utilized in clinical care. Modeling node types lets the embedding function learn edge type-specific patterns^64–66. The embedding function is trained through self-supervised learning via contrastive edge masking⁶⁷ (Methods). We note that the goal of this study is not to compare embedding techniques, as HGT is already a widely accepted approach in the field. Because the embeddings are generated without patient-level data, ClinVec embedding store can be shared without privacy risk (Fig. 1d). ClinVec embedding store comprises 153,166 clinical knowledge embeddings and is available to the research community (https://doi.org/10.7910/DVN/Z6H1A8)⁶⁸. We also provide an interactive visualization platform: https://huggingface.co/spaces/mims-harvard/ClinVec.

To gain insight into the robustness of ClinGraph and resulting ClinVec embeddings, we construct two alternative versions of ClinGraph to assess the impact of noise and knowledge base selection. We construct an alternative version of ClinGraph without the use of PheMap (ClinGraph-PheMap-ablation). To assess the impact of noise, such as small amounts of incorrect or incomplete information, we shuffled 1% of the edges of the original graph (ClinGraph-noise). The omission of PheMap leads to an 85.5% reduction in the number of edges, which also drastically impacts the connectivity of the graph. The resulting largest connected component of ClinGraph-PheMap-ablation shows a 34.4% reduction in the number of nodes. It is also much less compact, with the graph diameter increasing from 17 to 34, suggesting a much more fragmented graph structure. The number of nodes and graph connectivity of ClinGraph-noise were only minimally affected, with a 5.9% reduction in the number of nodes and a 2.6% in the number of edges, and the overall graph diameter was unchanged.

To assess how these changes in graph construction affect the resulting embedding space, we trained a separate HGT for ClinGraph-PheMap-ablation and ClinGraph-noise. ICD and ATC systems are organized by organ system and therapeutic purposes, making them a practical reference point for quantifying how well the resulting embedding spaces reflect relevant clinical patterns (Supplementary Fig. S1). Across silhouette score (SS) and adjusted mutual information (AMI), ClinGraph-PheMap-ablation performance is lower than ClinGraph for the majority of measurements (Supplementary Table S4). Specifically, we see a significant reduction in AMI in ClinGraph-PheMap-ablation (AMI-ICD = 0.30, AMI-ATC = 0.03) compared to ClinGraph (AMI-ICD = 0.37, AMI-ATC = 0.26) when clustering by ICD category and a significant drop when clustering ATC codes. In contrast, metrics from ClinGraph-noise show only slight deviations from ClinGraph in both scenarios. These results suggest that small perturbations in ClinGraph construction do not significantly change the ClinVec embedding space, whereas the removal of entire knowledge bases can drastically affect the resulting embedding space.

To compare the latent space defined by ClinVec to embedding spaces defined by other biomedical knowledge graphs, we perform a similar analysis with PrimeKG and SNOMED CT KG (Methods). Visualizing the latent space of diagnostic codes, the latent space described by ClinVec broadly clusters diseases by organ system, mirroring the organization of clinical care (Fig. 1E). This observation is supported with standard clustering metrics, where disease clusters from ClinGraph (silhouette: 0.54, AMI: 0.31) produce metrics at the same value or greater than clusters produced from other KGs (PrimeKG - silhouette: 0.54, AMI: 0.02; SNOMED-CT KG - silhouette: 0.15, AMI: -1e-4) (Supplementary Fig. S2). We repeat the analysis using ATC code embeddings and observed similar results, supporting the conclusion that ClinVec broadly captures drug-class and indication structure (Fig. 1f, Supplementary Fig. S2).

Evaluating ClinVec across clinical knowledge tasks

To evaluate the quality and alignment of ClinVec with existing clinical knowledge, we evaluate the embeddings across three tasks: hierarchical clinical term relationships, drug-pair similarity, and biomedical semantic similarity. For each benchmark, we compare our approach to embeddings generated from a set of biomedical LLMs, including BioBERT⁶⁹, UmlsBERT⁷⁰, MedCPT⁷¹, and BioLORD⁷². The full task definition and dataset descriptions are detailed in Methods, and we describe our key findings below.

The preservation of hierarchical relationships among clinical terms is essential to creating a semantically meaningful embedding space. Using cosine similarity between embeddings to evaluate the degree of similarity, we assess whether parent–child codes of diagnoses are located closer in the embedding space than sibling codes. Although these diagnoses are related and should lie in a similar region of the embedding space, broader and narrower codes for the same condition should be more similar to each other than to codes for distinct conditions, mirroring how disease hierarchies are used in clinical practice. We use the phecode disease hierarchy as ground truth, where for each phecode, we select one of its mapped ICD codes as the target, sample a “positive” ICD code from its parent or child phecode, and sample two “negative” ICD codes from sibling phecodes. We measure the “hit rate” or how many times the positive code embedding has the highest similarity to the target. Stratifying results by disease area, ClinVec attains the top hit rate in 8 out of 16 disease areas with ICD9 codes and 7 out of 16 with ICD10 codes. MedCPT and BioLORD have the next highest performance, achieving the top hit rates in 4 (ICD9) and 1 (ICD10) category, and 4 (ICD9) and 7 (ICD10) categories, respectively (Supplementary Table S5, Supplementary Table S6). Across instances where ClinVec is the highest performer, there’s an average 13.2% (range 4–42%) relative improvement for ICD9 codes and 18% (range 0.5–51%) for ICD10 codes compared to the second-best performing method.

We next formulate a drug-pair similarity task where we assess whether embeddings for generic drugs align with the corresponding brand-name drug embeddings. For each generic drug with a corresponding brand name present in ClinVec, we sample one “positive sample” as a brand linked to that generic and two “negative sample” brands under three settings: (1) random negatives drawn from any other brand drugs, (2) negatives restricted to drugs in the same ATC class, and (3) negatives whose names are lexically similar to the true brand. As shown in Supplementary Table S7, across all three negative‑sampling settings, ClinVec achieves the highest hit rate with an average of 11.8% relative improvement compared to the best-performing LLM baseline (MedCPT). In the more challenging negative sampling schemes, there’s a 14.4% relative improvement for lexically similar negatives, and even in the challenging ATC‑class negative setting with pharmacologically similar distractors, where all models have a reduction in hit rate, ClinVec has the highest hit rate with a 6.2% improvement over MedCPT. These results indicate that ClinVec encodes precise generic–brand relationships, even under hard, clinically realistic negatives.

Existing reference datasets for evaluating the semantic relatedness of clinical concepts are often limited in size and based on outdated coding systems that include obsolete codes^73,74. We construct a new validation dataset consisting of N = 3767 clinical term pairs graded on a 1–5 Likert scale by an inter-institutional panel of clinicians. We compute the cosine similarity between embeddings for every clinical term pair and measure its association with the corresponding clinician similarity scores using Kendall’s τ rank correlation coefficient (Fig. 2B). Grouping statistics by clinician rating reveals a positive correlation, with mean cosine similarity increasing across scores 1–5 (0.30, 0.53, 0.58, 0.63, 0.61). Across the 11 disease areas, ClinVec achieves the highest correlation in 6 specialities (circulatory, endocrine/metabolic, mental disorders, sense organs, digestive, and dermatologic), and remains competitive in the remaining 5 where MedCPT or BioLORD occasionally perform better (Table 1). We see significant gains in performance for mental disorders, where LLM-based methods struggled to capture clinically meaningful physiological manifestations, such as associating “chest tightness” with post-traumatic stress disorder or “brain tomography” with Alzheimer’s disease. We also find that ClinVec effectively captures cross–organ-system associations, such as links between ulcerative colitis and “excessive sweating” and between nonalcoholic fatty liver disease and “trouble sleeping”, both digestive diseases with well‑recognized extraintestinal manifestations. In contrast, the LLM‑based methods assigned these pairs low similarity.

Fig. 2. Concordance between ClinVec embedding similarity and clinical expert scores.

a Overview of clinical expert review process. b We report the mean cosine similarity across all disease-SNOMED CT pairs stratified by clinical expert scores 1–5. c We stratify cosine similarity scores across the four largest disease categories and show examples of SNOMED CT codes that were assigned a clinical expert score of 5.

Table 1.

Concordance between embedding similarity and clinical expert scores across ClinVec and biomedical LLMs

	BioBERT	UmlsBERT	MedCPT	BioLORD	ClinVec
Circulatory system	0.241 (0.039)	0.107 (0.039)	0.396 (0.039)	0.329 (0.036)	0.399 (0.037)
Neoplasms	0.234 (0.032)	0.173 (0.033)	0.468 (0.028)	0.379 (0.028)	0.240 (0.032)
Endocrine/metabolic	0.246 (0.039)	0.168 (0.040)	0.273 (0.039)	0.409 (0.036)	0.450 (0.038)
Genitourinary	0.366 (0.071)	0.353 (0.074)	0.573 (0.066)	0.524 (0.052)	0.232 (0.078)
Mental disorders	0.201 (0.075)	0.159 (0.069)	0.508 (0.051)	0.450 (0.057)	0.601 (0.040)
Sense organs	0.254 (0.085)	0.201 (0.084)	0.540 (0.090)	0.486 (0.093)	0.689 (0.062)
Neurological	−0.054 (0.113)	−0.013 (0.100)	0.130 (0.116)	0.239 (0.110)	0.172 (0.112)
Musculoskeletal	0.221 (0.116)	0.334 (0.092)	0.475 (0.100)	0.541 (0.086)	0.336 (0.108)
Digestive	0.232 (0.089)	0.173 (0.081)	0.427 (0.075)	0.396 (0.069)	0.441 (0.071)
Respiratory	0.441 (0.089)	0.084 (0.114)	0.618 (0.066)	0.495 (0.098)	0.515 (0.096)
Dermatologic	−0.238 (0.143)	−0.238 (0.130)	0.101 (0.137)	0.208 (0.120)	0.283 (0.122)

Kendall rank correlation coefficient measured between clinical expert scores 1-5 and cosine similarity of clinical term pairs using biomedical LLM-based methods and ClinVec. We perform 100 bootstrap samples and report the mean and standard deviation of the correlation coefficient across each model and disease category. The highest correlation statistic across models is bolded.

Embedding space reveals clinically grounded symptom patterns

We next demonstrate that ClinVec embeddings capture complex semantic properties, reflecting clinical knowledge that extends beyond anatomy groupings. Analogous to the geometric properties of word embeddings in natural language processing, clinical embeddings can be arithmetically combined to yield new representations that align with known disease patterns⁷⁵. As we sequentially sum the symptom embeddings associated with a given disease, the cosine similarity between the resulting aggregated symptom vector and the corresponding disease embedding increases with each added symptom (Fig. 3a–c).

Fig. 3. Embedding operations mirror symptomatic manifestations of clinical conditions.

a–c Line plot showing the cosine similarity across Multiple Sclerosis, Graves’ Disease, and Systemic lupus erythematosus with aggregated symptom embeddings. d, e Visualization of embedding space overlaid ICD10CM and UMLS codes shaded by cosine similarity with systematic lupus erythematosus and Marfan syndrome. The target disease embedding is denoted with a star, and the black diamonds indicate each disease’s symptom list. f We show the mean reciprocal rank and hits @ k across a set of nine chronic diseases. The value of k is computed as the per cent of the total number of possible diseases. Retrieval of chronic diseases was performed across all ICD10CM codes present in ClinVec (N = 34,842). g Retrieval of 14 rare genetic disorders across all UMLS concepts corresponding to an OMIM id, at least one HPO phenotype-association, and present in ClinVec (N = 900).

We repeat this analysis across nine chronic conditions and additionally compare the similarity of aggregated symptom embeddings to related diseases. For example, the symptoms of chronic obstructive pulmonary disease yield an aggregate embedding with high cosine similarity to the lung cancer embedding (Supplementary Fig. S3), and the symptom and disease embeddings for multiple sclerosis, Graves’ disease, and lupus cluster closely together (Supplementary Fig. S4). In contrast, these symptom sets show limited similarity to Crohn’s disease, despite its autoimmune etiology, likely due to digestive symptoms that are less relevant for the other conditions, highlighting how the precise choice of symptoms shapes semantic validity in the latent space. To assess robustness, we perform sensitivity analyses to mimic uncertainty in symptom selection, incorrect disease specification, and random noise in EHR data, and we find key results robust to these perturbations across all scenarios (Supplementary Fig. S5).

To assess this pattern more concretely, we use the prior nine common chronic diseases and an additional fourteen rare genetic disorders to construct a retrieval task. For each disease, we aggregate its associated symptom information by summing the ClinVec embeddings of all symptoms into a single “symptom vector,” and then perform zero-shot retrieval of the target disease by ranking all disease concepts according to cosine similarity with this symptom vector. Disease symptoms can span multiple organ systems and are not always localized within the embedding space, where symptom embeddings may appear unrelated because they do not have a high similarity with the target disease. For example, many symptoms for lupus are non-specific (e.g. fatigue, headache) and symptoms for Marfan syndrome span musculoskeletal, ocular, and cardiovascular systems (Fig. 3d, e).

As a comparison, we also perform this analysis with BioBERT, representing each disease’s symptoms by a single embedding derived from the concatenated symptom list and the disease itself with an embedding of its full name. Retrieval of chronic diseases was performed across all ICD10CM codes present in ClinVec (N = 34,842), and the retrieval of rare genetic disorders was performed across all OMIM diseases present in ClinVec (N = 900). We find that ClinVec embeddings achieve a higher mean reciprocal rank and hits@k compared to the other methods in both the chronic disease and rare disorder scenarios (Fig. 3f, g). We also find that ClinVec substantially outperforms BioBERT on the set of rare genetic disorders, for which BioBERT correctly retrieves only a single disease within the top 100 candidates, and ClinVec correctly retrieves 7 out of 14 diseases.

ClinVec enables knowledge-grounded LLMs

ClinVec embeddings can be incorporated into foundation models, such as LLMs, through knowledge injection^76–79 (Fig. 4a). Using MMed-Llama-8B⁷⁸ (MMed-Llama), we append ClinVec embeddings to the MMed-Llama’s original vocabulary and add a projector module that maps the dimension of ClinVec embeddings to the same dimension as MMed-Llama (Supplementary Fig. S6). We perform parameter-efficient fine-tuning to both MMed-Llama and the projector module. However, the ClinVec embeddings are frozen and are not updated during fine-tuning. We assess the impact of augmenting an LLM with ClinVec in medical question answering, where we evaluate the MedQA dataset⁸⁰, which contains questions from the US Medical Licensing Exams (USMLE). We apply the UMLS MetaMap API⁸¹ to map question text to UMLS concepts, retrieve the corresponding ClinVec embeddings, and append them to the tokenized prompt (Supplementary Fig. S7). This process allows the incorporation of clinically grounded knowledge at inference time to guide the response without extensive retraining.

Fig. 4. Integrating ClinVec with large language models improves medical question-answering.

a Overview diagram of question-answering with knowledge injection using ClinVec. b Accuracy of N = 1247 medical questions in the MedQA dataset. The red line denotes random performance with four answer options. c Accuracy of N = 3724 multiple-choice questions from AfriMed-QA dataset. The red line denotes baseline performance with five answer options. d Line plot showing the number of ClinVec embeddings included in MedQA questions by the absolute gain in accuracy. Standard errors are estimated from bootstrapped samples. e Stratified performance across questions of different clinical specialities. The right- and left-hand markers denote performance with and without the inclusion of ClinVec, and the connecting line denotes the difference in absolute performance.

Assessing performance with a held-out test set of MedQA questions (N = 1247), we find a 10.3% increase in question-answering accuracy when incorporating ClinVec (acc = 0.64) compared to question answering without it (acc = 0.58) (Fig. 4b). We observe the largest performance gains when questions are short, likely because shorter questions have limited contextual information for the language model to leverage. Adding one or two ClinVec embeddings leads to an average improvement of 11.7%, suggesting that the relationship information encoded in these embeddings helps compensate for missing context. Performance continues to improve as more tokens are added, reaching a peak at around 9 to 10 tokens (Fig. 4d).

To assess generalizability across different clinical scenarios, we also examined the recently released AfriMed-QA dataset⁸², which consists of 3724 multiple-choice questions collected from healthcare settings across 16 African countries. We observe a similar magnitude of performance improvement where we observe an accuracy of 0.64 with the addition of clinical knowledge embeddings compared to 0.59 without—a 8.5% increase (Fig. 4c). We identify the specialties with the greatest performance gains, including hematology ( + 37.0%) and ophthalmology ( + 20.3%) (Fig. 4e). Hematology shows the largest gains, likely due to the distinct disease presentations encountered in African healthcare settings that are underrepresented in the training data of most large language models, such as HIV and certain infectious diseases. These findings provide an example of how anchoring model responses in ClinVec can improve the performance of medical question-answering across geographic contexts and medical specialities.

ClinVec stratifies patients by disease risk and severity

We next investigate how ClinVec can be utilized in the context of patient outcome prediction, including disease progression and disease risk. Analogous to polygenic risk score frameworks⁸³, we compute a phenotype risk score⁸⁴ by scanning a patient’s EHR and aggregating the clinical codes as features. Each feature is weighted by the cosine similarity between the corresponding clinical code embedding and target disease embedding (Methods). We validated our approach using retrospective EHR data from 4.57 million individuals at Clalit Health Services (CHS)⁸⁵ and examined three clinical conditions with the largest sample sizes in the CHS chronic disease registry: chronic kidney disease (CKD), chronic obstructive pulmonary disease (COPD), and heart failure (Supplementary Fig. S8). For each disease, the codes with the highest similarity to the target disease align with established comorbidities, laboratory findings, and medication usage. For chronic kidney disease, diabetes mellitus ranks among the top features and is a recognized risk factor; proteinuria also appears and can signal early disease.

By ranking patients by their risk score percentiles, we observe the separation of patients according to disease status across all three conditions, particularly at the extreme end of the risk distribution (Fig. 5a–c). Within the group of individuals in the lower 10th percentile of the risk score distribution for CKD, there is a disease prevalence of 6.2%. For patients above the 99th percentile, the disease prevalence increases to 23.4%. We next evaluate how well the risk score percentiles capture disease severity and mortality risk. Since patients with higher risk scores reflect a greater number of EHR codes linked to the target disease, this may also indicate more severe disease presentations. To address confounding effects, we restrict the assessment to patients of the same age and sex for each disease (using the median age and the most common sex per disease). Re-calibrating score percentiles, we observe a stratification by 6-year survival rate (Fig. 5d–f). For CKD (age = 72 sex = Male), individuals within the top quintile of this score distribution for CKD had a relative 42.6% lower 6-year survival compared to those in the bottom quartile (top-quartile: 56.8% survival proportion, bottom-quartile: 76.5%).

Fig. 5. Clinical code embedding risk scores correlate with disease prevalence and severity.

a–c We provide scatter plots showing the risk score percentiles of each disease versus the disease prevalence within each bin. Dots are shaded according to disease prevalence. d–f We show the survival curve of cases that match the most common sex and age at diagnosis for each disease cohort. Lines are shaded by score percentiles, and standard error intervals are computed using 10,000 bootstrap samples. Columns are divided by diseases: COPD (Chronic Obstructive Pulmonary Disease), CKD (Chronic Kidney Disease), and Heart Failure.

Discussion

We introduce ClinGraph, a clinical knowledge graph, and ClinVec, a corresponding embedding store of 153,166 clinical vocabulary embeddings. These embeddings capture patterns among clinical codes that reflect human anatomy, disease presentation, and healthcare organization. Evaluations by inter-institutional panels of clinicians from the United States and Israel confirm that the embeddings align with clinical practice. ClinVec embeddings encode semantic relationships that support the combination and comparison of clinical concepts, creating a knowledge-grounded representation of clinical data that can be used in downstream machine learning applications. These representations are also well-suited to serve as inputs to foundation models, which can be adapted to specific tasks through fine-tuning with labeled datasets^86–88. Integrating ClinVec with LLMs through knowledge injection, we demonstrate how the representations in ClinVec can improve medical question-answering accuracy. We illustrate how ClinVec embeddings enable unsupervised patient prediction across diseases. ClinVec provides an embedding store for knowledge-grounded AI models that can be shared across healthcare systems without privacy risk.

While ClinGraph and ClinVec provide a structured representation of clinical knowledge, they have several limitations. ClinGraph inherits errors and gaps from the clinical knowledge bases and ontologies on which it is built. Clinical ontologies cover specific aspects of care, disease mechanisms, or healthcare organization, which limits their coverage of the full medical domain, and KGs constructed from these ontologies reflect these biases. Some information may be outdated or missing, particularly for conditions and populations that are underrepresented in biomedical research. These limitations propagate into the learned embeddings and can lead to representations that are dominated by well-studied diseases. In addition, ontological concepts follow a long tail distribution, where sparsely connected concepts are weakly represented. To address this issue, we upsample low-degree nodes when sampling negative edges during link prediction, which increases the representation of sparsely connected concepts during graph transformer training. This approach reduces dominance by highly connected nodes and improves representations for concepts with sparse knowledge graph neighborhoods.

Linking concepts across multiple vocabularies can introduce challenges in how relationships are encoded. To maintain relationship quality, ClinGraph includes edges from curated cross-mappings, including GEM, ATC PROD, UMLS, and PheMap. We use a single edge type in ClinGraph, because modeling distinct relationship types would require harmonizing definitions across sources, a process that demands additional clinical expertise and curation. As a result, we model distinct node types but do not encode edge-specific semantics. Extending ClinGraph to support typed edges is an important direction for future work. Another limitation of this study is the scope of applications we evaluate. Our goal is to show how ClinVec can incorporate structured clinical knowledge, not to provide a full benchmark of task-specific models. For knowledge injection, we use a controlled setup to measure the contribution of ClinVec. Future work will include comparison against retrieval augmented generation techniques such as GraphRAG⁸⁹ and larger language models^77,90,91. For disease prediction, additional comparisons with alternative models, including established clinical risk scores and disease-specific guidelines^92–94, would provide a more clinically grounded assessment of ClinVec-based representations. In the future, we want to expand the coverage of genetic and Mendelian diseases in ClinGraph and ClinVec. We plan to incorporate codes from phecodeX, an updated vocabulary that includes chromosomal anomalies, as well as resources focused on Mendelian diseases, such as the Online Mendelian Inheritance in Man (OMIM)⁹⁵ and Human Phenotype Ontology (HPO)⁹⁶. We also plan to integrate databases that capture biological mechanisms, including those involving genes and proteins, to improve the representation of diseases with complex or poorly defined clinical features.

Methods

Constructing ClinGraph

We use eight standardized clinical vocabularies to construct all clinical concepts in ClinGraph and ClinVec: Unified Medical Language System (UMLS)⁷, International Classification of Diseases (ICD)⁹⁷, Anatomical Therapeutic Chemical (ATC) Classification¹⁶, RxNorm⁵⁵, Systemized Nomenclature of Medicine—Clinical Terms (SNOMED CT)¹⁷, Current Procedural Terminology (CPT)⁵⁶, Logical Observation Identifiers Names and Codes (LOINC)¹⁸, and phecodes⁹⁸. We designate a node for each clinical concept. We define a clinical concept as an entry within a clinical vocabulary with a unique identifier.

We begin by integrating the clinical codes and relationships defined in the UMLS vocabulary. We incorporate all UMLS CUIs (concept unique identifier) with a source vocabulary in ICD10CM, SNOMED CT, LOINC, RxNorm, ATC, or CPT (N = 42,883 nodes). Next, we integrate all ICD10CM codes up to two decimal places (N = 34,842) and all ICD9CM codes. We add information from the phecode coding system, which represents clinical phenotypes as phecodes⁵⁴, formed by aggregating groups of diagnostic codes (i.e., ICD codes) into clinical sub-groupings (N = 1817). Next, we add nodes representing LOINC Part codes, which are standardized attribute values used to construct the LOINC codes that specify a given laboratory test. We restrict our inclusion to only LOINC Part component codes which refer to the substance being tested (N = 14,399). We also incorporate all CPT codes (N = 4377), ATC codes (levels 3–5: N = 5179), and RxNorm drug groups (N = 10,130).

Next, we integrate a subset of SNOMED CT codes as nodes, where we restrict the inclusion to the most clinically relevant codes. We select all SNOMED CT codes from the CORE (Clinical Observations Recording and Encoding) Subset, a set of the most frequently used codes designated to maximize data interoperability across institutions⁹⁹. We also include the Convergent Medical Terminology subset diagnosis list, a set of core SNOMED CT codes originally curated by Kaiser Permanente and is now used across numerous healthcare systems¹⁰⁰.

We formally organize the clinical codes and relationships into a heterogeneous knowledge graph²¹ called ClinGraph. We draw an undirected edge between two clinical codes if they have a parent–child relationship or cross-reference as defined in the source vocabularies. Edges between ICD9CM and ICD10CM codes are derived from the GEM⁵⁷, the official crosswalk mapping diagnoses codes to and from ICD9CM and ICD10CM. Edges between ICD10CM and SNOMED CT are derived from the official ICD10CM—SNOMED CT mapping¹⁰¹. To construct relationships between RxNorm and ATC codes, we use ATC PROD, a product-level mapping of RxNorm to ATC-4 classes¹⁰².

We designate edges between UMLS CUI nodes and RxNorm/ATC nodes based on the ‘may_treat’ and ‘may_prevent’ relationships defined in UMLS. This is repeated for linking UMLS CUI nodes and CPT nodes using the ‘associated_procedure_of’, ‘procedure_site_of’, and ‘pathology_of’ relationships defined in UMLS. SNOMED CT nodes are connected using the ‘cause_of’, ‘definitional_manifestation_of’, ‘associated_with’, ‘due_to’, ‘occurs_after’, and ‘occurs_before’ relationships with UMLS CUIs.

We incorporate relationships defined by the PheMap database, an existing knowledge base of biomedical knowledge derived from text mining and natural language processing of open-source biomedical literature⁵⁸. This database offers relationship pairs linking phecodes and clinical codes from other medical vocabularies, including RxNorm, CPT, LOINC, and SNOMED CT. These relationships can be interpreted as a phenotype being “associated with” a given clinical concept.

Multiple edges are drawn if two nodes have a relationship defined multiple times (e.g., a relationship between a phecode and ICD9CM code derived from the phecode hierarchy and the PheMap knowledge base). The final graph comprises 153,166 nodes across four node types and 2,873,025 edges, and the distribution of nodes and edges can be found in Supplementary Tables S1 and S2.

Heterogeneous graph transformer

A heterogeneous graph, $\mathcal{G}=\left(\mathcal{V},\mathcal{E}\right)$, is defined by a set of nodes $\mathcal{V}$ and edges $\mathcal{E}$. We define a mapping function $f_v\mathcal{:}\mathcal{V}\to {\mathcal{T}}^v$ where each node $v\in \mathcal{V}$ has an assigned node type $f_v\left(v\right)\in {\mathcal{T}}^v$. Here, the node types represent different clinical vocabularies. For a given graph, $\mathcal{G}$, we denote the GNN, ${\mathcal{H}}_{\mathcal{G}},$ as a function that maps a vector of features for a node $u$, written as ${\mathit{x}}_{\mathit{u}}\mathit{\in }{\mathbb{R}}^d$, to a vector of real numbers representing the latent space:

$${\mathcal{H}}_{\mathcal{G}}:{\mathit{x}}_{\mathit{u}}\to {\mathit{z}}_{\mathit{u}}.$$

Here, $d$ is the dimension of the input vector. This resulting mapped vector (also called an embedding) is denoted by $\mathit{z}\mathit{\in }{\mathbb{R}}^d$. For convenience of notation, we assume that the input and output dimensions are equal. We provide a table with relevant notation and indicate whether they are an inferred parameter within the model (Table 2).

Table 2.

Summary of notation

Variable	Description	Dimension	Trainable (Y/−)
$\mathbf{G}$	Graph	-	-
$\mathbf{V}$	Set of vertices or nodes	-	-
$\mathbf{E}$	Set of edges	-	-
${\mathbf{T}}^{\mathbf{v}}$	Space of node types	-	-
d	Input dimension	${\mathrm{R}}^1$	-
L	Number of layers	${\mathrm{R}}^1$	-
${\mathbf{H}}_{\mathbf{G}}$	Graph neural network function	${\mathrm{R}}^{\mathrm{d}}\to {\mathrm{R}}^{\mathrm{d}}$	Y
${\mathbf{x}}_{\mathbf{u}}$	Feature vector of node u	${\mathrm{R}}^{\mathrm{d}}$	-
${\mathbf{z}}_{\mathbf{u}}$	Embedding vector of node u	${\mathrm{R}}^{\mathrm{d}}$	Y
$\mathbf{N}\left(\mathbf{u}\right)$	Neighborhood of node u	-	-
${\mathbf{m}}_{\mathbf{u}}$	Message feature of node u	${\mathrm{R}}^{\mathrm{d}}$	Y
${\mathbf{h}}_{\mathbf{u}}^{\left(\mathbf{l}\right)}$	Embedding of node u at the lth layer	${\mathrm{R}}^{\mathrm{d}}$	Y
$\mathbf{ATT}\left(\mathbf{s},\mathbf{t}\right)$	Attention vector for node u	${\mathrm{R}}^{\mathrm{d}}$	Y
h	Number of heads	${\mathrm{R}}^1$	-
${\mathbf{W}}_{\mathbf{Q}}^{\mathbf{i}},{\mathbf{W}}_{\mathbf{K}}^{\mathbf{i}}$	Weight matrices	${\mathrm{R}}^{\mathrm{d}\times \frac{\mathrm{d}}{\mathrm{h}}}$	Y
$\mathbf{hea}{\mathbf{d}(\mathbf{s},\mathbf{t})}^{\mathbf{i}}$	Attention head vector for source node u and target node v	$\mathrm{d}/\mathrm{h}$	Y
${\mathbf{W}}_{\mathbf{Q}}^{\mathbf{i}},{\mathbf{W}}_{\mathbf{K}}^{\mathbf{i}}$	Weight matrices for attention computation	${\mathrm{R}}^{\mathrm{d}\times \frac{\mathrm{d}}{\mathrm{h}}}$	Y
${\mathbf{W}}_{\mathbf{V}}$	Weight matrix for attention computation	${\mathrm{R}}^{\frac{\mathrm{d}}{\mathrm{h}}\times \frac{\mathrm{d}}{\mathrm{h}}}$	Y
${\mathbf{K}}_{\mathbf{s}}^{\mathbf{i}},{\mathbf{Q}}_{\mathbf{t}}^{\mathbf{i}}$	Query and key vectors	${\mathrm{R}}^{\frac{\mathrm{d}}{\mathrm{h}}\times 1}$	Y
$\mathbf{A}\mathit{\odot }\mathbf{B}$	Hadamard product between A and B	-	-
$\mathbf{\oplus }$	Element-wise summation	-	-
${\mathbf{\parallel }}_{\mathbf{n}}({\mathbf{x}}^{\mathbf{i}}$)	Row-level concatenation of the set vectors $\{{\mathrm{x}}^1,...,{\mathrm{x}}^{\mathrm{n}}\}$	-	-
$\mathbf{f}\left(\mathbf{u},\mathbf{v}\right)$	Similarity scoring function	-	Y
$\parallel \cdot \parallel$	L2-norm	${\mathrm{R}}^1$	-
${\mathbf{v}}^{\mathbf{+}}$	Node forming a positive edge with $\mathrm{u}$	-	-
${\mathbf{v}}^{-}$	Node that does not form an edge with $\mathrm{u}$	-	-
${\mathbf{G}}^{\mathbf{\prime }}$	Graph with masked edges	-	-

We provide a summary of the variables used in deriving the graph transformer network model, the dimension of each variable, and whether it is a learned or fixed parameter. Rows are sorted according to the order in which each variable is introduced.

We model the architecture of our graph neural network (GNN) after the heterogeneous graph transformer (HGT)⁶². In this work, we briefly describe the key model steps. The complete derivation of HGT is detailed in previous work⁶².

Learning ${\mathcal{H}}_{\mathcal{G}}$ involves aggregating information across the graph structure defined by $\mathcal{G}$. For a target node $t$, we define its neighborhood, $\mathcal{N}\left(t\right)$, as the set of nodes with a direct connection or edge with t. Information is propagated through the graph by gathering information from the neighborhood of $t$, which is aggregated into a message feature ${\mathit{m}}_t$. The embedding of t can be updated with the resulting message feature, ${\mathit{h}}_t^{(l+1)}=\text{UPD}({\mathit{m}}_t^{\left(l\right)},{\mathit{h}}_{\mathit{t}}^{\left(\mathit{l}\right)})$ where ${\mathit{h}}_{\mathit{t}}^{\left(\mathit{l}\mathit{+}\mathit{1}\right)}$ is the embedding of node $t$ at the l + 1 layer and UPD(·) refers to an update function that integrates messages with the current node embedding. Note that the input of the l + 1 layer is the output of the previous layer, and by stacking L layers $[remove-equation]$, we represent the final HGT as a composition of these functions across all layers:

$${\mathcal{H}}_{\mathcal{G}}\left({\mathit{x}}_t\right)={(\mathit{h}}_t^{\left(L\right)}\circ {\mathit{h}}_t^{\left(L-1\right)}\circ \dots \circ {\mathit{h}}_t^{\left(1\right)}\left)\right({\mathit{x}}_t).$$

The input of the model is the set of node features, ${\mathit{x}}_t\in {\mathbb{R}}^d$ for all nodes in $\mathcal{G}$ which is then used to initialize the $0^{\mathit{th}}$ layer embedding of each node ${\mathit{h}}_t^{\left(0\right)}$. In practice, each of the node features is initialized using Xavier noise. The embedding represents the relational information learned from the knowledge graph without additional information from the node features.

The HGT uses multi-head attention, which is a key feature of the transformer architecture⁶³. Multi-head attention utilizes multiple attention mechanisms, or heads, in parallel to tend to different parts of the input, where each head has its own set of learnable weights. Updating a node’s embedding involves aggregating messages across all $h$ heads and weighting each message by its attention score. This mechanism essentially up- and down-weights messages based on their importance so that only necessary information is propagated to the target node.

For a target node $t$, a single attention head is a series of linear projections of the embedding from the previous layer, normalized by the embedding dimension. Here, a linear projection for an input $\mathit{x}\mathbf{\in }{\mathbb{R}}^d$, is defined as an affine linear transformation, $\mathit{y}={\mathit{W}}^{\mathit{T}}\mathit{x}+\mathit{b}$ where $\mathit{b}$ is a bias term, and $\mathit{W}$ is a learnable weight matrix. For convenience, we drop the bias term in the following derivations, but in practice, the parameter corresponding to the bias term is absorbed into the estimation of $\mathit{W}\mathit{.}$

The series of linear projections mirrors the standard query, key, and value vectors used in the standard transformer architecture. The attention score vector corresponding to the edge between source node s and target node t, represented as $\mathbf{ATT}\left(s,t\right)$, is computed as the concatenation of each head’s output:

$${\mathit{K}}_s^i={\left({\mathit{W}}_K^i\right)}^T{\mathit{h}}_s^{\left(l-1\right)},$$

$${\mathit{Q}}_t^i={\left({\mathit{W}}_Q^i\right)}^T{\mathit{h}}_t^{\left(l-1\right)},$$

$$\mathit{HEAD}{\left(s,t\right)}^i={\left({\mathit{W}}_V^i\right)}^T{\mathit{K}}_{\mathit{s}}^{\mathit{i}}\odot \left({\mathit{Q}}_{\mathit{t}}^i\right)\cdot \frac{1}{d},$$

$$\mathbf{ATT}\left(s,t\right)={\parallel }_{i\in \left[0,h\right]}\mathbf{HEAD}{(s,t)}^i\mathbf{.}$$

Here, the operator “$\mathit{A}\odot \mathit{B}$” represents the elementwise or Hadamard product between $\mathit{A}$ and $\mathit{B}$, and the operator “${\parallel }_n\left({\mathit{x}}^i\right)$” represents the row-level concatenation of the given set of vectors $\{{\mathit{x}}^1,\mathit{.}\mathit{.}\mathit{.},{\mathit{x}}^n\mathit{\}}$.

The input vector is ${\mathit{h}}_s^{(l-1)}\in {\mathbb{R}}^{d\times 1}$, and the learnable weight matrices are ${\mathit{W}}_Q^i,{\mathit{W}}_K^i\in {\mathbb{R}}^{d\times \frac{d}{h}}$, and ${\mathit{W}}_V\in {\mathbb{R}}^{\frac{d}{h}\times \frac{d}{h}}$ where $\frac{d}{h}$ is the input dimension divided by the number of heads. For these weight matrices, the subscripts refer to the query, key, and value elements in the transformer. The resulting query and key vectors follow as ${\mathit{K}}_s^i,{\mathit{Q}}_t^i\in {\mathbb{R}}^{\frac{d}{h}\times 1}$. The resulting attention vectors from each head and final multi-head attention vector are $\mathbf{HEAD}{(s,t)}^i\mathbf{\in }{\mathbb{R}}^{\frac{d}{h}\times 1}$ and $\mathbf{ATT}\left(s,t\right)\in {\mathbb{R}}^{d\times 1}$. And to ensure the attention scores for the target node t sum to 1, a $\mathit{Softmax}\left(\mathrm{·}\right)$ is applied across all neighbors of t.

For target node t, we first compute the message vectors across all heads for each neighbor of t. This message is calculated as a linear projection of the embedding for source node s from the prior layer multiplied by a weight matrix (${\mathit{W}}_{\mathit{T}}$). Each head maintains its own linear projection matrix, but ${\mathit{W}}_{\mathit{T}}$ is shared across all attention heads.

The final message passed from $s\to t$ is a concatenation of messages produced from each of the h heads. This resulting message vector is then multiplied by the multi-head attention vector. The final updated embedding (${\mathit{h}}_t^{\left(l\right)}$) is computed by aggregating across all neighbors of the node $t$ through an elementwise sum. This is followed by a linear projection (${\mathit{W}}_N$), which creates a separate projection for each node type. This is then followed by a residual connection and passed through an activation function:

$${\mathit{m}}_s^{\left(l\right)}={\parallel }_{i\in \left[1,h\right]}\left({\mathit{W}}_{\mathit{T}}{(\mathit{W}}_M^{i^T}{\mathit{h}}_s^{\left(l-1\right)})\right),$$

$${\tilde{\mathit{h}}}_t^{\left(l\right)}=\underset{\forall v\in N\left(u\right)}{⨁}\mathbf{ATT}\left(s,t\right)\odot {\mathit{m}}_s^{\left(l\right)},$$

$${\mathit{h}}_t^{\left(l\right)}=\mathrm{\sigma }\left({\mathit{W}}_N{\tilde{\mathit{h}}}_t^{\left(l\right)}+{\mathit{h}}_t^{\left(l-1\right)}\right).$$

The learnable weight matrices are ${\mathit{W}}_{\mathit{T}}\in {\mathbb{R}}^{\frac{d}{h}\times \frac{d}{h}}$, ${\mathit{W}}_M^i\in {\mathbb{R}}^{d\times \frac{d}{h}}$, and ${\mathit{W}}_N\in {\mathbb{R}}^{d\times d}$. The message vector is ${\mathit{m}}_t^{\left(l\right)}\in {\mathbb{R}}^{d\times 1}$. The operator $\oplus$ represents the elementwise summation. Training the final model involves optimizing the set of learnable weight matrices, $\{{\mathit{W}}_K^i,{\mathit{W}}_Q^i,{\mathit{W}}_V^i,{\mathit{W}}_M^i\}$ across h heads and finding $\{{\mathit{W}}_T,{\mathit{W}}_N\mathit{\}}$ that minimizes the loss function $\mathcal{L}$.

Self-supervised learning

For a given node $u$, our goal is to generate an embedding ${\mathit{z}}_u$ that quantifies the topological information of the graph w.r.t $u$. The learning objective can be framed as a link prediction problem, where given two nodes $u$ and $v$, we want to train a function to predict whether an edge exists between these two nodes. This function can be described by,

$$f\left(u,v\right)=\frac{{\left({\mathit{z}}_u\right)}^T{\mathit{z}}_v}{\parallel {\mathit{z}}_u\parallel \parallel {\mathit{z}}_v\parallel }=\cos \left({\mathit{z}}_u,{\mathit{z}}_v\right),$$

where ${\mathit{z}}_u=\mathcal{H}\left(u\right),$ and $\mathcal{H}\mathcal{(}·\mathcal{)}$ represents the trained GNN function that provides the node embeddings. Note that because edges are undirected and the scoring function is symmetric, $f\left(u,v\right)=f\left(v,u\right).$

Optimizing this above scoring functions means solving for the parameters of $\mathcal{H}\left(·\right)$. This can be performed using contrastive learning. We mask a random subset of edges to create a modified version of the graph, ${\mathcal{G}}^{\prime }$. Then, given a source node $u$, we define a node where $v^{+}\in \mathcal{N}\left(u\right)$ represents a target node that forms an edge with $u$ in the original graph $\mathcal{G}$. We denote $v^{-}\notin \mathcal{N}\left(u\right)$ as a node that does not form an edge with $u$ in $\mathcal{G}$ and denote the set of these negative examples as $\{v_1^{-},v_2^{-},\cdots ,v_n^{-}\}$.

The function $f\left(u,v\right)$ is trained on ${\mathcal{G}}^{\prime }$ to estimate whether a source node $u$ forms an edge with target node $v$ in the original graph $\mathcal{G}\mathcal{.}$ We can quantify the probability of an edge existing between $u$ and $v^{+}$ with negative edges $v_{\left\{1:n\right\}}^{-}$ as the probability,

$$p\left(u,v^{+},v_{\left\{1:n\right\}}^{-}\right)=\frac{\exp \left({\mathit{z}}_u^T{\mathit{z}}^{+}\right)}{\exp \left({\mathit{z}}_u^T{\mathit{z}}^{+}+{\mathit{z}}_u^T{\mathit{z}}_1^{-}+\dots +{\mathit{z}}_u^T{\mathit{z}}_n^{-}\right)}.$$

Given a dataset of N source nodes, each with a corresponding set of candidate nodes as described above, the negative log-likelihood over the dataset is equivalent to the cross-entropy loss where the true “class” always corresponds to the positive node $v^{+}$. This type of contrastive loss function is well established^67,103–105 and is formulated as follows:

$$\mathcal{L}=-\sum _u^N\log \left(p(u,v^{+},v_{\left\{1:n\right\}}^{-})\right),$$

where $v^{+}\mathcal{\in }\mathcal{N}\left(u\right)$ and $v_{\left\{1:n\right\}}^{-}\mathcal{\notin }\mathcal{N}\left(u\right)$.

Learning ClinVec embeddings from ClinGraph

Using the heterogeneous graph transformer framework, we model four distinct node types in ClinGraph to reflect how each vocabulary is utilized in clinical care: administrative diagnosis codes (ICD9CM, ICD10CM, phecodes), treatments (ATC, RxNorm), patient clinical state indicators (LNC, CPT), and semantic clinical terminologies (SNOMED CT, UMLS). Modeling distinct edge types would require harmonizing relationship definitions across databases, a process that would require additional resources and clinical expertise. For this reason, we only model distinct node types and leave the implementation of edge-type-specific embeddings as future work.

The contrastive learning requires specifying positive and negative edges during training, where a positive edge is defined as a pair of nodes with an existing edge in ClinGraph, and a negative edge is a pair of nodes that are not connected by an edge. To generate a training tuple comprised of a single positive edge and a set of corresponding negative edges, we randomly sample an existing edge within ClinGraph denoted as $\left(u,v\right)$ and ${\mathcal{T}}^V\left(v\right)$ is the node type of target node $v$. To create a negative sample, we select a node $r$ such that ${\mathcal{T}}^V\left(r\right)={\mathcal{T}}^V\left(v\right)$ and $r\notin \mathcal{N}\left(u\right).$

We use node neighbor sampling to select only a subset of nodes to include at each layer when computing a node’s message vector due to the large size of the KG. Specifically, we take a sample n of neighbors at each k-hop neighborhood at each gradient descent step when computing messages during optimization. Node types with a smaller set of nodes in ClinGraph are upweighted to ensure they are represented in the sampling. The number of samples at each layer is a hyperparameter selected through hyperparameter tuning. The final training was performed on an H100 GPU for ten epochs, during which we trained on all 2,873,025 edges of the KG.

We perform hyperparameter tuning in two steps: first for the model architecture and then for the parameters involved in the contrastive learning objective. We select a random subset of 500,000 edges for training and 100,000 for validation from ClinGraph. We perform hyperparameter tuning using Raytune where we fix the learning rate (1e-4), number of negative samples (10), batch size (100), and sampling neighborhood (10) and vary the following parameters: number of layers (2, 3, 4), input feature dimension (128, 256, 512), output embedding dimension (128, 256, 512), head dimension (128, 256, 512), number of heads (2, 3, 4), and dropout (0, 0.1, 0.2). The optimal set of GNN parameters is 4 layers, 128 input dimensions, 128 output embedding dimensions, 512-dimension head size, three heads, and a dropout of 0.0.

We repeat the hyperparameter selection process by fixing the parameters selected above and vary the following: learning rate (1e-3, 1e-4, 1e-5), neighborhood sampling (5, 10, 20), and number of negative samples (3, 5, 10). The final hyperparameter set selected is a learning rate of 1e-5, neighborhood sampling of 20 nodes, and three negative samples. All experiments were performed using the Ray Tune software (https://docs.ray.io/en/latest/tune/index.html).

After training a heterogeneous graph transformer on ClinGraph (“Methods: Stochastic mini-batch training with neighbor sampling”), we freeze all model parameters and compute a single embedding vector for every node via a full‑graph inference pass. Each node embedding is computed with a batch size of 1. The input node features are set using Xavier initialization and then are passed through the trained four-layer GNN. At inference time, we disable neighbor sampling and aggregate messages from all available neighbors. We take the final‑layer hidden state as that node’s ClinVec representation (dim = 128).

Analyzing the ClinVec embedding space

To visualize the entire ClinVec embedding space, we perform UMAP dimensionality reduction¹⁰⁶ (n_neighbors=35, min_dist=0.97, metric = ‘cosine’) directly on the embedding vectors and plot the first two dimensions. Phecode embeddings are shaded according to organ-level classification, and ATC5 embeddings are shaded according to ATC-level 1 categorizations.

We construct an alternative version of ClinGraph without the use of PheMap, an empirically constructed knowledge base derived from the biomedical literature. We refer to this specific graph construction as ‘ClinGraph-PheMap-ablation’. To assess the impact of noise, such as small amounts of incorrect or incomplete information, we shuffled 1% of edges such that the source node was connected to a randomly selected destination node (of the same node type) and refer to this as ‘ClinGraph-noise’.

We generate embeddings for PrimeKG and SNOMED-CT KG using the same HGT architecture and hyperparameters as ClinGraph. Because neither KG has ICD or ATC codes, we mapped the nodes as follows. For SNOMED-CT KG, we mapped each SNOMED CT code to its UMLS CUI and then to its corresponding ICD10CM code if present. If a UMLS CUI does not have a corresponding source ICD10CM code, we remove the node embedding from the cluster calculation. To map SNOMED CT to ATC, we first mapped SNOMED CT codes to their UMLS CUI. We then used UMLS to identify UMLS CUI codes with ‘ingredient-of’ relationships that describe the active ingredient (represented as ATC) present in each UMLS CUI drug. SNOMED CT codes that did not have a mapped ATC ingredient were removed from the clustering calculation. PrimeKG represents diseases and symptoms as MONDO and HPO codes. These were mapped to ICD10CM codes using mappings provided by MONDO¹⁰⁷ (https://github.com/monarch-initiative/mondo/tree/master/src/ontology/mappings). PrimeKG represents drugs as DrugBank IDs; we map each ID to ATC5 codes using the DrugBank database. For PrimeKG, we modeled 10 node types as defined by the KG. For SNOMED-CT KG, we only used a single node type (i.e., homogenous graph) since all nodes represent SNOMED CT codes. Clustering metrics, including silhouette score and adjusted mutual information, were computed according to ATC-level 1 and phecode organ category.

Measuring hierarchical consistency of disease diagnoses with phecodes

We evaluate whether ClinVec and baseline models preserve clinically meaningful hierarchical relationships by testing whether embeddings place parent–child codes closer together than sibling codes. Although all of these diagnoses are related and should lie in a similar region of the embedding space, broader or narrower representations of the same condition ought to be more similar to each other than to distinct conditions, mirroring how disease hierarchies are used in clinical practice. We use the phecode disease hierarchy as ground truth. While phecodes from version 1.2 were used to construct ClinGraph, we derive the ground truth hierarchy from the latest version, PhecodeX¹⁰⁸. For each phecode, we select one of its mapped ICD codes as the target, sample a “positive” ICD code from its parent or child phecode, and sample two “negative” ICD codes from sibling phecodes (sharing the same phecode parent but representing distinct diagnoses). In total, 3284 phecodes are evaluated, covering N = 11,422 ICD9 codes and N = 53,010 ICD10 codes.

We use the corresponding ICD9 and ICD10 embeddings from ClinVec, and for each LLM baseline, we embed the ICD9/10 code description. For each triplet (target, positive, two negatives), we compute the cosine similarities between the target and candidate ICD codes and record whether the positive code receives the highest similarity score. We refer to this metric as the “hit rate”. Model performance is summarized as the hit rate computed over all triplets for both ICD9 and ICD10. We repeat this process 100 times and report the mean and standard deviation of the hit rate stratified by disease category.

Generic-brand drug matching task

We assess whether embeddings for generic drugs align with the corresponding brand-name drug embeddings. Specifically, we connect the generic drug ingredient or clinical drug and its corresponding branded drug name; for example, the branded drug Tylenol has the generic form acetaminophen. In total, N = 440 (360 generic, 379 brand name) generic-brand pairs are present in ClinVec. The majority of drugs represented in ClinVec are on the ingredient level, but a subset of the most commonly used brand-name drugs is also included in ClinGraph (specifically through the PheMap database), leading to a reduced sample size for evaluation. Generic drugs are represented as RxNorm concepts, and ground‑truth brand names are identified via RxNorm using the “tradename of” relationship. This information was not used when constructing ClinGraph and ClinVec.

For each generic drug with a corresponding brand name present in ClinVec, we sample one “positive sample” as a brand linked to that generic and two “negative sample” brands under three settings: (1) random negatives drawn from any other brand drugs, (2) negatives restricted to drugs in the same ATC class, and (3) negatives whose names are lexically similar to the true brand (fuzzy matching ratio >60). The two negative samples will always be sampled from the same sampling scheme. For LLM baselines, we obtain an embedding by encoding the drug name, and ClinVec uses RxNorm code embeddings for generic drugs and UMLS concepts for brand-name drugs. For each triplet (generic, positive brand, two negatives), we compute cosine similarities between the generic drug embedding and each brand drug embedding and record how many times the true brand has the highest similarity. We refer to this metric as the “hit rate”. For every model and negative‑sampling setting, we perform 100 resampling iterations and report the mean and standard deviation of the hit rate.

Clinical evaluation study

We perform an evaluation with groups of clinical experts from Brigham and Women's Hospital (N = 1), Massachusetts General Hospital (N = 1), Boston Children’s Hospital (N = 1), and Clalit Health Services (N = 3). The panel was provided a scoring rubric where they were asked to evaluate each clinical concept according to how clinically relevant each code is to the given disease phenotype. We utilize a Likert scale¹⁰⁹ based on scores 1–5: ‘unrelated’ (1) and ‘ highly related’ (5). If a code is too broad or non-specific (e.g., ‘Clinical evaluation’), these are excluded from the performance metric calculations. ClinVec has embedding representations for SNOMED CT codes corresponding to the clinical terms. For LLM-based baselines, we obtain an embedding for each clinical term by encoding its human‑readable label (e.g., “cardiovascular disease”). In total, there are N = 3767 clinical term pairs spanning 11 disease areas.

For each model, we compute the cosine similarity between embeddings for every clinical term pair and measure its association with the corresponding clinician similarity scores using Kendall’s τ rank correlation coefficient, which we selected due to its handling of ties in ordinal ratings. We perform 100 bootstrap samples and report the mean and standard deviation of the correlation coefficient across each model and disease category.

Disease embedding arithmetic

We selected nine common chronic diseases, including common WHO-listed noncommunicable diseases and a set of chronic autoimmune conditions. We specifically included autoimmune conditions because their symptoms often span multiple organ systems, allowing us to assess the resulting aggregated embedding even when symptoms appear unrelated. We derived disease-symptom lists from Mayo Clinic clinical descriptions, which provide disease symptoms as an itemized list. To align symptoms with concepts in ClinVec, a clinician annotated each target disease and symptom set with the corresponding ICD10CM codes.

The target disease name, corresponding ICD10CM code, link to the Mayo Clinic description, and the number of symptoms per disease are in Supplementary Table S8. For each disease symptom, we provide the symptom name extracted from the Mayo Clinic clinical description and clinician-mapped ICD10CM in Supplementary Table S9.

We added a set of 14 diseases with disease-phenotype associations curated from OMIM. We selected the same set of rare genetic disorders as described in Morley et al¹¹⁰. and utilized HPO phenotype annotations as “gold standard” symptom sets. To align diseases and symptoms with concepts in ClinVec, we converted OMIM disease ids and HPO codes to UMLS concept ids. The target disease name, OMIM id, corresponding UMLS concept id, link to the HPO annotations, and the number of phenotype associations per disease are in Supplementary Table S10.

For each disease, we aggregate its associated symptom information by summing the ClinVec embeddings of all symptoms into a single “symptom vector” and then perform zero-shot retrieval of the target disease by ranking all disease concepts according to cosine similarity with this symptom vector. We apply this procedure to nine common chronic diseases and record the rank of the true disease for each case. As a comparison, we repeat the analysis with BioBERT, representing each disease’s symptoms by a single embedding derived from the concatenated symptom list and the disease itself with an embedding of its full name. Retrieval was performed across all ICD10CM codes present in ClinVec, excluding those in categories ‘S’, ‘T’, ‘U’, ‘V’, and ‘Z’ since these code external causes of injury and contact with health services (N = 42,883). For the rare disorders, retrieval was performed across all UMLS concepts corresponding to an OMIM ID, had at least one phenotype-association annotated in HPO, and present in ClinVec (N = 900).

We perform the same analysis above while perturbing different variables in the framework. To model real-world noise and uncertainty, we vary the ICD10CM code used to represent each symptom. We select a candidate set of ICD10CM codes for each symptom by taking the original ICD10CM from the clinician review and selecting all ICD10CM codes with the same parent code. For example, for code ‘786.2’ (Cough), the candidate set would include ‘786.1’ (Stridor), ‘786.0’ (Dyspnea and respiratory abnormalities), etc. Then, when selecting each symptom embedding for aggregation, a random code from the candidate set is selected. This process is repeated 10 times, yielding similarity curves constructed from 10 sets of disease symptoms.

To simulate when the disease of interest is mis-specified, we compare the aggregated symptoms to a set of diseases similar to the target disease. This was determined as the set of ICD10CM codes sharing the same parent code with the original disease. When computing the similarity between the aggregated symptoms and the target disease embedding, the embedding of each alternative embedding was instead used. To simulate situations where incorrect information is included in the symptom list, we randomly selected an ICD10CM from the symptom list and replaced it with a randomly chosen ICD10CM code. We place the random symptom at the beginning of the aggregation procedure and repeat the process 10 times for each set of symptoms.

Integrating ClinVec with LLMs

Fine-tuning was performed on the training English subset of multiple-choice questions from the MedQA dataset (https://huggingface.co/datasets/VodLM/medqa). We also perform a validation study on the AfriMed-QA⁸² dataset (https://huggingface.co/datasets/intronhealth/afrimedqa_v2). We restricted ourselves to only multiple-choice questions and removed questions that had more than one assigned correct answer. This dataset also provides clinical subspecialty information for each question.

We annotate each multiple-choice question using the MetaMap¹¹¹ tool, which annotates natural language text with UMLS CUI codes. For each question, we concatenated the text from the question with the answer options and submitted the text to the MetaMapLite REST API. We limit the choice of UMLS CUI codes to the following semantic types: “Sign or Symptom”, “Disease or Syndrome”, “Pharmacological Substance”, “Mental or Behavioral Dysfunction”, “Chemical”, “Anatomical Structure”. In the tokenization process, we append a token corresponding to the selected ClinVec embedding.

We base our analysis on a pre-trained biomedical LLM, specifically MMed-Llama-8B, an 8-billion-parameter open-source medical foundation model that already incorporates domain-specific knowledge through pre-training. We downloaded both the pre-trained model and tokenizer from Hugging Face: https://huggingface.co/Henrychur/MMed-Llama-3-8B. While our experiments focus on this specific model, the proposed knowledge-injection framework is, in principle, applicable to other LLM architectures.

We augment the base MMed-Llama model with 42,883 ClinVec embeddings corresponding to the UMLS concepts present in ClinGraph. We limit our analysis to this subset of concepts since the specific annotations produced by MetaMap only provide UMLS concepts. In principle, the entire set of ClinVec embeddings can be integrated into this knowledge-injection framework. We extend the tokenizer by adding a special token for each UMLS concept (e.g. ‘<C0001080 > ’) and maintain a separate embedding matrix for these ClinVec tokens. Specifically, the original embedding matrix in MMed-Llama remains unchanged, and the ClinVec embeddings are frozen at this stage. During preprocessing, we annotate each input question with UMLS concepts and append the corresponding ClinVec tokens to the original token sequence. An overview of our framework is in Supplementary Fig. S6.

To align the ClinVec embeddings with the MMed-Llama’s embedding space, we add a four-layer multilayer perceptron projector module with layers consisting of sizes 128 → 512 → 1024 → 4096. This projector module maps the 128-dimension ClinVec embedding to a 4096-dimension vector, which is consistent with the dimension of MMed-Llama’s embeddings. When a ClinVec token is encountered, its frozen embedding is retrieved from the ClinVec embedding matrix and passed through the projector; tokens from MMed-Llama’s original vocabulary bypass the projector because they are already 4096‑dimensional. The projected ClinVec embeddings and the original MMed-Llama token embeddings are then combined into a single sequence embedding matrix, which is fed into the MMed-Llama decoder for downstream processing.

We adapt the official MMed-Llama pipeline for medical question answering and use LoRA (Low-Rank Adaptation) for parameter‑efficient fine‑tuning: https://github.com/MAGIC-AI4Med/MMedLM/tree/main. Specifically, we apply LoRA (rank r = 16, as in the original MMed-Llama study) to the ClinVec projector and to the ‘q_proj’, ‘k_proj’, and ‘v_proj’ modules in the MMed-Llama decoder. All other parameters in the base model and all ClinVec embeddings remain frozen. Using the MedQA training data split and prompts provided in the MMed-Llama pipeline, training samples are constructed from a prompt, question and answer options, and ClinVec annotations. The resulting output is evaluated using standard next‑token cross‑entropy. We refer to the fine‑tuned model with the ClinVec projector as Baseline+ClinVec and to the otherwise identical model without this module as Baseline (Supplementary Fig. S6). The full training pipeline is publicly available at our repository: https://github.com/mims-harvard/ClinVec/tree/main/tutorials/060_medqa.

Phenotype risk scoring

We first selected all patients with at least one ICD9CM code from the list of case inclusion codes (CHS encodes their EHR using ICD9CM) and filtered to patients listed in the CHS chronic registry to confirm they have received a disease diagnosis. Because patients are not guaranteed to be added to the chronic registry when they are first diagnosed, we treat the first occurrence of the inclusion ICD9CM code as the date of diagnosis. For each patient, we set the index date as January 1 of the year of diagnosis, where only information occurring before the index date will be included in the risk score computation. For prediction, we select all EHRs recorded within the past 5 years of the index date.

To define controls, we begin with the phecode exclusion criteria provided by the phecode mapping v1.2. For each phecode, the mapping provides a list of exclusion phecodes that are typically similar conditions or overlap with the target disease. We begin by selecting all individuals who have never received any exclusion diagnoses at any point in their EHR. We also remove individuals from the chronic disease registry for the specified disease. We select a matched control from this set of candidate control patients for each case. Matching is based on the following criteria: 1) same sex, 2) year of birth ±2 years, and 3) number of recorded diagnoses in the EHR (with at least one diagnosis in the EHR). The complete case-control process is illustrated in Supplementary Fig. S5 and a summary of patient cohorts in Supplementary Table S11.

For each disease, we compute a risk score as a cosine-weighted sum over clinical codes, where each weight is the cosine similarity between the code embedding and the disease embedding. We restricted the set of potential features to laboratory tests, medications, and ICD9CM codes with at least a 0.1% prevalence within the CHS patient population. The CHS EHR did not have SNOMED CT or CPT codes for analysis. To determine the clinical codes related to each disease, we compute the cosine similarity between all clinical codes within the latent space and the target disease embedding, represented by a phecode. The final set of features is the top k codes, where k = 20, and the feature weights are the cosine similarity scores. In practice, the choice of k can be treated as a hyperparameter and optimized with a validation dataset. Patient risk scores are computed as a weighted sum where the associated weight is added to the sum if the patient has the given code in their EHR and given a 0 otherwise. Features are counted once in the score computation, even if a patient receives the codes multiple times.

For each disease, we computed the most common age at diagnosis and the sex with the highest disease prevalence. We restricted the survival analysis to patients meeting these age/sex criteria and those with a diagnosis date from 2016 or earlier. We re-computed risk score quantiles based only on this restricted set of patients. We looked at the 6 years of EHR after each patient’s index date and denoted a patient as deceased if they had a non-null death date. Patients were stratified into risk score quartiles based on the risk score computed at the index date. Confidence intervals for the survival curves were computed using 10,000 bootstrapped samples.

Ethics approval

Parts of this study that relate to the use of CHS data (for evaluating the predictive ability of the KG-derived concept embeddings) were approved by the Clalit Health Services Institutional Review Board (Helsinki) committee under approval number COM1-0161-19. This study was exempt from requiring written informed consent due to its retrospective nature of the study.

Author contributions

R.J. developed a unified knowledge graph representation of clinical concepts and designed, implemented, and benchmarked heterogeneous graph transformer models. U.G. implemented the approach and conducted detailed analyses using CHS individual-level data. X.S. assisted in writing code and planning the medical question answering analyses. L.H., J.W., S.D., C.R.G., P.H. and R.S. formed an inter-institutional panel of clinicians that evaluated the alignment of clinical concept representations with established clinical knowledge across 90 diseases and 3000 clinical codes. B.Y.R., R.B. and G.S. provided feedback on the methodology and evaluated the clinical concept embeddings through large-scale phenotype risk scoring and alignment with expert clinical knowledge. R.J., N.D. and M.Z. conceptualized and designed the study. All authors contributed to writing the manuscript.

Data availability

Data and clinical concept embeddings, as well as the ClinGraph knowledge graph, are available via Harvard Dataverse https://doi.org/10.7910/DVN/Z6H1A8. An interactive visualization platform is available at https://huggingface.co/spaces/mims-harvard/ClinVec. Due to national and organizational data privacy regulations, CHS individual-level data from this study cannot be shared publicly.

Code availability

The Python implementation of the heterogeneous graph transformer and the associated codebase for model training, (non-individual-level) analyses, and embedding evaluations are available at https://github.com/mims-harvard/ClinVec. The project website is at https://zitniklab.hms.harvard.edu/projects/ClinVec.

Competing interests

The authors declare no competing interests.

Supplementary information

The online version contains supplementary material available at https://doi.org/10.1038/s41746-026-02664-9.