alterlab-primekg

PrimeKG 知识图谱技能

概述

PrimeKG（Chandak、Huang 和 Zitnik，Scientific Data 2023；mims-harvard/PrimeKG）是一个精准医疗知识图谱，整合了 20 个主要资源。它包含 129,375 个节点和 4,050,249 条边，涵盖 30 种边类型和 10 种节点类型，包括药物-靶点、疾病-基因和疾病-表型关联。已发布的 Dataverse 文件是固定的 2022 年快照。

已被上游取代。 PrimeKG 维护者现已说明，PrimeKG 已被 OptimusKG 取代（同一实验室；包含更多最新数据的超集——190,531 个节点、21.8M 条边、26 种关系类型），并建议几乎所有新工作都使用它。新分析请使用 OptimusKG（uv pip install optimuskg，Python ≥ 3.12；import optimuskg; nodes, edges = optimuskg.load_graph(lcc=True) 或 G = optimuskg.load_networkx(lcc=True)；数据：Harvard Dataverse doi:10.7910/DVN/IYNGEV，文档：https://optimuskg.ai）。如需复现或对比已发表的 PrimeKG 结果和基准测试，请继续使用此 PrimeKG 工作流。

主要功能：

• 搜索节点（基因、蛋白质、药物、疾病、表型）
• 获取直接邻居（相关实体和临床证据）
• 分析局部疾病背景（相关基因、药物、表型）
• 识别药物-疾病路径（潜在的药物再利用机会）

数据访问： 通过 scripts/query_primekg.py 进行程序化访问。通过 PRIMEKG_DATA_PATH 环境变量，将加载器指向 Harvard Dataverse 发布的 kg.csv（默认路径为相对于脚本的 ../data/kg.csv）。所有函数均对 kg.csv 中的 x_*/y_*/relation/display_relation 列进行操作。

何时使用此技能

在以下情况下应使用此技能：

• 基于知识的药物发现： 识别疾病的靶点和作用机制。
• 药物再利用： 查找可能有证据支持新适应症的现有药物。
• 表型分析： 了解症状/表型与疾病和基因的关联。
• 多尺度生物学： 连接分子靶点（基因）与临床结局（疾病）。
• 网络药理学： 研究药物-靶点相互作用产生的更广泛网络效应。

不适用场景

场景	改用
评分后的靶点-疾病证据、成药性和靶点已知药物	alterlab-opentargets
跨物种疾病-基因-表型关联（HPO、OMIM、Orphanet）	alterlab-monarch
药物的完整记录：药理学、相互作用、靶点、标签	alterlab-drugbank
训练用于链接预测的知识图谱嵌入模型（TransE/RotatE）	alterlab-torchdrug

核心工作流

在技能目录下通过 uv run python 运行（以便导入 scripts/）， 或将 scripts/ 目录添加到 sys.path。将 PRIMEKG_DATA_PATH 设为你的 kg.csv 路径。

1. 搜索实体

查找基因、药物或疾病的标识符。传入 node_type 时，请使用 PrimeKG 的精确类型字符串（参见下方的节点类型），例如 "gene/protein"，而不是 "gene"。

from scripts.query_primekg import search_nodes

# Search for Alzheimer's disease nodes
results = search_nodes("Alzheimer", node_type="disease")
# Returns: [{"id": <MONDO id>, "type": "disease", "name": "...",
#            "source": "MONDO" | "MONDO_grouped"}, ...]
# Disease ids are MONDO ids; PrimeKG groups diseases, so one name can map to
# several MONDO ids. Use the returned id with get_neighbors.

2. 获取邻居（直接关联）

检索所有相连的节点和关系类型。

from scripts.query_primekg import get_neighbors

# Get all neighbors of a specific disease ID (the MONDO id from search_nodes)
neighbors = get_neighbors(disease_id, relation_type="disease_protein")
# Returns: List of neighbors like
#   {"neighbor_name": "APOE", "neighbor_type": "gene/protein",
#    "relation": "disease_protein", "display_relation": "associated with", ...}

3. 分析疾病背景

用于汇总某种疾病关联信息的高级函数。

from scripts.query_primekg import get_disease_context

# Comprehensive summary for a disease
context = get_disease_context("Alzheimer")
# Access: context['associated_genes'], context['associated_drugs'],
#         context['phenotypes'], context['related_diseases']

4. 追踪药物-疾病路径（药物再利用）

查找深度为 2 的路径（药物 -> 共享基因/蛋白质靶点 -> 疾病），作为基于图的 药物再利用证据。

from scripts.query_primekg import find_paths

# drug_id and disease_id come from search_nodes
paths = find_paths(drug_id, disease_id, max_depth=2)
# Each path is a list of edge dicts; a drug -> gene/protein -> disease path is a
# candidate new-indication hypothesis. For deeper traversal, load kg.csv into networkx.

PrimeKG 中的节点和关系类型

以下是 kg.csv 中使用的确切字符串，筛选时请逐字匹配。

节点类型（x_type/y_type，共 10 种）：gene/protein、drug、disease、 effect/phenotype、biological_process、molecular_function、cellular_component、 pathway、anatomy、exposure。注意：基因使用 gene/protein（而非 gene），表型使用 effect/phenotype（而非 phenotype）。

关键关系（relation，共 30 种）。边是无向的；请检查两个端点。

• protein_protein：物理蛋白质-蛋白质相互作用（PPI）
• drug_protein：药物靶点／作用机制关联
• disease_protein：疾病-基因／蛋白质关联（不存在 disease_gene）
• indication、contraindication、off-label use：三种药物-疾病关系 （不存在统一的 drug_disease）
• disease_phenotype_positive / disease_phenotype_negative：表型存在／不存在
• bioprocess_protein、pathway_protein、molfunc_protein、cellcomp_protein：GO / 通路注释
• anatomy_protein_present / anatomy_protein_absent、exposure_*：解剖结构／暴露关联

最佳实践

1. 使用具体 ID： 使用 get_neighbors 时，请确保 ID 来自 search_nodes 且正确（疾病 ID 是 MONDO ID）。
2. 先了解背景： 深入查看特定基因或药物前，先使用 get_disease_context 获取整体概览。
3. 筛选关系： 使用 get_neighbors 中的 relation_type 筛选器，聚焦于特定证据（例如，仅查看 drug_protein，或使用 indication 查看治疗关联）。请使用上方列表中的确切关系字符串。
4. 注意疾病分组： PrimeKG 将约 2.2 万个 MONDO 概念合并为约 1.7 万个分组疾病节点，因此，一个疾病名称可能对应多个共享同一 node_index 的 MONDO ID。

资源

脚本

• scripts/query_primekg.py：核心函数 — search_nodes、get_neighbors、find_paths、get_disease_context。

数据路径

• 数据：kg.csv（设置 PRIMEKG_DATA_PATH；默认值为 ../data/kg.csv），来自 Harvard Dataverse（doi:10.7910/DVN/IXA7BM）。下载：wget -O kg.csv https://dataverse.harvard.edu/api/access/datafile/6180620。也可使用 PyTDC 自带的加载器（from tdc.resource import PrimeKG）。
• 129,375 个节点、4,050,249 条边；10 种节点类型、30 种边类型。
• 使用 pandas 加载（pd.read_csv，low_memory=True）。kg.csv 约为 0.98 GB（981,751,236 字节）——每个函数都会重新加载；对于重复查询，请缓存 DataFrame 或使用真正的图数据库。

属于 AlterLab Academic Skills 套件。