简介面向生物信息学中KEGG通路可视化与交互分析需求该资源提供了一套完整的KEGG Network Viewer项目源码采用HTML、JavaScript与PHP构建可直接部署为在线代谢途径查看器。工具实现了基于AP检测算法的蛋白质分类展示能够直观标记通路中的关键节点并通过动态HTML页面模拟节点去除、边添加等操作便于研究者分析网络结构变化。压缩包共956个文件体积约62.01MB主要文件类型包括js脚本、html页面、php服务端文件、css样式以及png/gif图像、Markdown说明文档、SQL数据库备份涵盖前端交互、后端接口、数据模型与样式主题等多个模块。该资源已有1086人学习与下载适合生物信息学入门学者、代谢通路分析开发者以及从事可视化成套项目设计的网页工程师参考。借助完整源码与配套数据库读者可掌握从KEGG数据解析到网络渲染的完整流程并利用内置编辑器、bootstrap响应式布局与数据库脚本快速搭建个性化应用。1. 给 KEGG 通路画一张能交互的网络图kegg-network-viewer 到底解决什么问题做富集分析的时候拿到几十条 KEGG 通路列表的那一刻才是真正头疼的开始。某课题组 A 同学以前的做法是一层层点开官方通路图截图最后汇报 PPT 里全是密密麻麻的箭头既看不清差异基因落在哪些环节也没法把上调和下调的基因颜色对齐到同一张图上。kegg-network-viewer 这类可视化 KEGG 网络的工具要解决的就是这个把 KEGG 通路的 KGML 文件解析成节点和边用交互式网络图把基因、化合物、反应关系画出来再叠加转录组或代谢组的差异结果一条通路一张图能缩放、能悬浮看基因名和表达量。适合每天跟富集结果打交道的生信从业者也适合想摆脱截图、把通路视图批量落进项目报告的人。2. 先拆开 KGMLKEGG 网络里的节点、边与三种数据形态很多人在可视化 KEGG 网络上栽跟头不是画图代码写错而是没搞清楚 KGML 里存的数据到底是什么。KGML 是 KEGG 通路的官方交换格式一个通路一个 XML 文件里面把基因、化合物、反应、调控关系全揉在一起。直接拿来画图第一版往往长成一张「意大利面」——所有节点挤在一团边互相缠绕根本没法读。这不是工具的问题是你没把 KGML 的语义拆出来。2.1 entry、relation、reaction 三段式KGML 里到底存了什么KGML 文件的根元素是 pathway下面主要挂三类子节点entry、relation、reaction。entry 是图的节点relation 是节点之间的逻辑关系reaction 是酶促反应本身。一个典型的 gene 类型 entry 长这样entry id42 typegene namehsa:2597 hsa:2599 reactionrn:R02865 graphics nameGAPDH x520 y340 width46 height17/ /entryname 字段里存的是 KEGG 的基因编号K 号多个编号用空格分隔reaction 字段指向该基因参与的反应graphics 里是官方通路图上的坐标。compound 类型的 entry 结构类似不过 name 里是 C 号比如 C00103葡萄糖。relation 描述的是调控关系比如 activation、inhibition、phosphorylation它的 entry1 和 entry2 指向两个 entry 的 id。reaction 节点则有自己的 id下面挂 substrate 和 product 列表指向参与反应的化合物 entry。所以一个 KEGG 网络图里其实有三种语义完全不同的节点基因、化合物、反应。基因通过「催化」连接到反应反应连接底物和产物基因和基因之间还有调控边。这三种边不能混为一谈画图时如果不区分看到的就只是一团无序的连线。2.2 节点全连在一起就是网络语义不同画法完全不同我见过最典型的错误做法把 entry 全部变成点把 relation 和 reaction 全部变成边丢给力导向布局就跑。结果图里化合物节点因为度很高被甩到外围基因节点全挤在中心调控边的方向乱成一团。原因在于没有区分边的语义。KGML 里的边至少有三类第一类是 relation 表达的调控边方向表示调控方向激活还是抑制由 subtype 决定第二类是 reaction 内部的底物-反应-产物边方向表示代谢流向不是调控关系第三类是 gene 到 reaction 的催化边表示「这个基因编码的酶催化这个反应」。三类边在生物学含义上完全不同在图上应该用不同颜色、不同线型区分。有一个常见误解很多人把 KEGG 官方通路图里的箭头当成调控方向。实际上官方图里的箭头大多是代谢流向或邻接关系真正的调控信息激活、抑制、磷酸化在 KGML 的 relation 里。所以可视化时如果想保留「调控」语义要优先渲染 relation 边如果想看代谢流优先渲染 reaction 边。一个 viewer 如果只给一张全混的图等于没做语义分层。2.3 三种常见的可视化形态官方坐标直出、逻辑重布局、组学叠加同样一份 KGML根据用途不同有三种画法。第一种是官方坐标直出直接用 graphics 里的 x、y 把节点摆在官方通路图的位置上这种最适合还原 KEGG 原图别人看起来亲切但节点一多就重叠第二种是逻辑重布局完全忽略官方坐标把节点和边交给力导向或层次布局算法这种适合看网络拓扑和调控模块第三种是组学叠加在布局之上把差异基因、表达量、p 值映射到节点的颜色、大小和悬浮信息上这就是做富集分析时最需要的视图。三种形态不是互斥的。一个完整的 kegg-network-viewer 管线通常是解析 KGML 得到图结构先把官方坐标存下来作为默认视图再提供重布局的开关最后把实验数据映射上去。第 3 章我直接给出一个最小可运行的方案你可以照着把这三层都落地。3. 本地跑通最小方案Python 解析 KGML 并渲染成交互网络讲完数据形态这一章直接上手。我推荐的技术栈是 Python networkx plotly理由很直接networkx 负责图结构和布局计算plotly 负责交互式渲染两者都是成熟库不用额外搭前端。整套代码跑完你会得到一个本地 HTML 文件浏览器打开就能缩放和悬停。3.1 拉取 KGML 并解析成 networkx 图最小代码与逐行说明第一步是从 KEGG API 拉 KGML 并解析成有向图。下面的代码把 KGML 的 entry 变成节点把 relation 和 reaction 拆成边并保留官方坐标import requests import networkx as nx import xml.etree.ElementTree as ET KEGG_URL https://rest.kegg.jp/get/{pathway}/kgml def load_kgml(pathway_id: str, local_path: str ) - nx.DiGraph: 拉取或读取 KGML解析成 networkx 有向图 if local_path: with open(local_path, r, encodingutf-8) as f: xml_text f.read() else: xml_text requests.get(KEGG_URL.format(pathwaypathway_id), timeout30).text # 缓存到本地避免重复请求触发限流 with open(f{pathway_id}.kgml, w, encodingutf-8) as f: f.write(xml_text) root ET.fromstring(xml_text) G nx.DiGraph() # entry 是节点gene 的 name 是 K 号列表compound 的 name 是 C 号 for entry in root.findall(entry): eid entry.get(id) G.add_node(eid, typeentry.get(type, ), namesentry.get(name, ).split( )) for g in entry.findall(graphics): # 官方坐标后续做布局用y 轴方向后面要处理 G.nodes[eid][x] int(g.get(x, 0)) G.nodes[eid][y] int(g.get(y, 0)) # relation 是调控边如 activation / inhibition for rel in root.findall(relation): src, dst rel.get(entry1), rel.get(entry2) rel_type rel.get(type) subtypes [s.get(name) for s in rel.findall(subtype)] G.add_edge(src, dst, kindfrelation:{rel_type}, subtypessubtypes) # reaction 是反应节点连接底物和产物 for react in root.findall(reaction): rid react.get(id) for s in react.findall(substrate): G.add_edge(s.get(id), rid, kindsubstrate) for p in react.findall(product): G.add_edge(rid, p.get(id), kindproduct) return G这个函数返回的 DiGraph 里节点属性有 type、names、x、y边属性有 kind 和 subtypes。逻辑说明我把 relation 和 reaction 分开建边而不是混在一起这样后续可以按 kind 过滤——只想看调控网络时只保留 relation 开头的边想看代谢流时只看 substrate/product 边。参数说明pathway_id 传类似hsa00010的通路号local_path 填本地 KGML 文件路径时走离线分支适合批量跑的时候用图是有向图方向保留语义。注意 relation 边的方向是「调控者 → 被调控者」如果你习惯反着画后面渲染时自行翻转。3.2 布局不是玄学官方坐标、力导向、层次布局怎么选拿到图结构后下一步是决定节点摆在哪。三种布局各有适用场景选择标准是节点数量和语义需求。官方坐标直出是最简单的直接用 KGML 里存好的坐标。但这里有一个坑KGML 的坐标是图像坐标系y 轴向下直接画出来图是上下颠倒的。渲染前把 y 取反即可# 官方坐标直出注意 y 轴翻转 pos {n: (G.nodes[n][x], -G.nodes[n][y]) for n in G.nodes if x in G.nodes[n]}力导向布局适合 100 到 2000 个节点的中等网络它能自然地把高度连接的节点聚在一起# 力导向布局k 控制节点间距seed 保证每次结果一致 pos nx.spring_layout(G, k0.8, seed42, iterations300)层次布局适合代谢通路这种方向性明显的网络按节点离起点的拓扑距离分层# 层次布局先算节点所在层再按层排布 layer {} for n in G.nodes: try: layer[n] nx.shortest_path_length(G, source33) # 选一个入口节点 except nx.NetworkXNoPath: layer[n] 0 pos nx.multipartite_layout(G, subsetlayer)我的经验阈值是节点少于 100 用官方坐标直出100 到 2000 用力导向超过 2000 先做子图提取再布局直接布局必然成一团黑。力导向的参数里 seed 一定要固定不然每次跑出来的图都不一样项目汇报时同一个通路长两个样会非常尴尬。3.3 用 plotly 把图变成可交互 HTML节点信息、缩放与悬停布局算完最后一步是渲染。plotly 的做法很直接把边拆成一段段线段把节点拆成散点然后用 Scatter 轨迹画出来。下面这个函数接收图和布局输出交互式 Figureimport plotly.graph_objects as go def draw_kegg_graph(G, pos, node_size18, node_color#4C78A8): # 边拆线段每条边画一条从 src 到 dst 的线 edge_x, edge_y [], [] for u, v, d in G.edges(dataTrue): x0, y0 pos[u] x1, y1 pos[v] edge_x [x0, x1, None] edge_y [y0, y1, None] # 节点散点text 里放节点 id 和类型悬浮可看 node_x [pos[n][0] for n in G.nodes] node_y [pos[n][1] for n in G.nodes] node_text [f{n}br{G.nodes[n].get(type, )} for n in G.nodes] fig go.Figure() fig.add_trace(go.Scatter(xedge_x, yedge_y, modelines, linedict(width1, color#A0A0A0), hoverinfonone)) fig.add_trace(go.Scatter(xnode_x, ynode_y, modemarkerstext, textnode_text, textpositionbottom center, markerdict(sizenode_size, colornode_color))) fig.update_layout(titleKEGG Pathway Network, height800, showlegendFalse, templateplotly_white) return fig渲染函数的逻辑说明第一条轨迹画边None用来断开不同线段第二条轨迹画节点节点 id 和类型作为悬浮文本。参数说明node_size可以传标量也可以传列表后面叠加表达量时传列表实现差异化大小node_color同理传颜色列表就能实现上调红色、下调蓝色。plotly 渲染出的 HTML 自带缩放、平移和悬浮查看不需要额外写前端代码。把这个函数和前面的 load_kgml 串起来输入一个通路号输出一个可交互 HTML最小方案就跑通了。4. 把差异基因和富集结果叠到 KEGG 网络上上色、定大小、加信息最小方案跑通后大多数人的下一步需求是把差异表达基因叠到通路上。这一步做得好不好直接决定这张图能不能放进论文或汇报。核心思路是三个映射——颜色映射表达变化方向大小映射显著性悬浮信息映射基因身份和数值。但映射之前数据对齐是绕不过去的一道坎。4.1 数据对齐是第一步K 号转基因符号的正确姿势KGML 里基因节点存的是 K 号如hsa:2597而你的差异表达表里通常是基因符号如GAPDH或 Entrez ID。不对齐就映射图上会出现一大片「找不到」的灰点。我一般会准备一个 K 号到基因符号的映射表来源可以是 KEGG 的 gene 数据库也可以自己用biopython批量查def build_symbol_map(pathway_id: str) - dict: 从 KEGG gene API 构建 K号 - 基因符号 映射 import requests symbol_map {} gene_list requests.get( fhttps://rest.kegg.jp/link/{pathway_id.split(hsa)[0]}/pathway:{pathway_id}, timeout30 ).text.strip().splitlines() # 返回格式pathway:hsa00010\thsa:2597 for line in gene_list: _, kegg_id line.split(\t) gene_detail requests.get( fhttps://rest.kegg.jp/get/{kegg_id}, timeout30 ).text for para in gene_detail.splitlines(): if para.startswith(NAME): # NAME 行格式NAME GAPDH (phosphoglyceraldehyde dehydrogenase) symbol para.split()[1].split(()[0] symbol_map[kegg_id] symbol break return symbol_map这段代码的逻辑说明link接口返回通路下所有基因的 K 号列表然后逐个查 gene 详情从 NAME 字段里取第一个符号。参数说明pathway_id.split(hsa)[0]提取物种前缀因为 link 接口的物种参数只接受hsa、mmu这类简称requests.get要加超时避免某个基因查询挂起拖垮整个脚本。注意这里逐基因查询比较慢几十个基因没问题几百个基因建议保存成文件缓存后面避坑章会细说。4.2 让节点“说话”颜色映射 FC大小映射 p 值形状映射类型对齐之后映射规则就很直接了。我给出一套经过多次项目验证的默认规则上调基因log2FC 1标红色下调基因log2FC -1标蓝色不显著标灰色显著性用-log10(padj)映射到节点大小越显著越大节点形状区分类型基因用圆点化合物用方块反应节点用三角。代码如下def map_expr_to_nodes(G, exp_df, symbol_map): exp_df 必须包含三列gene_symbol, log2FC, padj 返回值是三个列表colors, sizes, labels直接传给 draw_kegg_graph exp_dict exp_df.set_index(gene_symbol)[[log2FC, padj]].T.to_dict() colors, sizes, labels [], [], [] for n, data in G.nodes(dataTrue): if data.get(type) ! gene: # 化合物和反应节点用固定样式不参与表达映射 colors.append(#CCCCCC) sizes.append(10) labels.append(f{n}br{data.get(type)}) continue kegg_id data[names][0] symbol symbol_map.get(kegg_id, kegg_id) rec exp_dict.get(symbol) if rec is None or pd.isna(rec[padj]) or rec[padj] 0.05: colors.append(#999999) sizes.append(12) else: fc rec[log2FC] colors.append(#D62728 if fc 1 else #1F77B4 if fc -1 else #999999) sizes.append(14 26 * min(1.0, -np.log10(rec[padj]) / 10)) labels.append(f{symbol}br{kegg_id}brFC{rec.get(log2FC, NA)}brpadj{rec.get(padj, NA)}) return colors, sizes, labels这段映射的逻辑说明基因节点取names列表的第一个 K 号去查符号找到后再从差异表里取数值化合物和反应节点跳过映射用灰色固定大小避免它们过度抢眼。参数说明padj 0.05是显著性阈值按你的实验标准可改14 26 * min(1.0, -log10(padj)/10)把显著性线性映射到 14 到 40 像素/10是缩放因子如果你们的 p 值普遍极小可以把 10 调大到 20避免所有点都变成最大号。4.3 多通路批量出图一个循环输出整份通路视图单条通路做好后批量就是水到渠成的事。富集分析通常会给你 20 到 50 条显著通路一条条手动跑显然不现实。把前面所有函数串进一个循环import os def batch_build(pathway_list, exp_df, symbol_map, out_dirkegg_html): os.makedirs(out_dir, exist_okTrue) index_links [] for pid in pathway_list: # 缓存已存在的 KGML 文件避免重复请求 kgml_file fcache/{pid}.kgml if os.path.exists(fcache/{pid}.kgml) else G load_kgml(pid, kgml_file) # 布局按节点数选择少于100用官方坐标 if G.number_of_nodes() 100: pos {n: (G.nodes[n][x], -G.nodes[n][y]) for n in G.nodes if x in G.nodes[n]} else: pos nx.spring_layout(G, k0.8, seed42, iterations200) colors, sizes, labels map_expr_to_nodes(G, exp_df, symbol_map) fig draw_kegg_graph(G, pos, node_sizesizes, node_colorcolors) # 把 labels 写回 fig 的第二个 trace fig.data[1].text labels out_file os.path.join(out_dir, f{pid}.html) fig.write_html(out_file) index_links.append(fa href{pid}.html{pid}/a) with open(os.path.join(out_dir, index.html), w, encodingutf-8) as f: f.write(br.join(index_links))批量脚本的逻辑说明每个通路独立成 HTML最后生成一个 index.html 做汇总入口汇报时打开 index 就能逐条点进所有通路。参数说明cache/目录用来存 KGML脚本第二次跑时不再请求 API布局的节点数阈值、力导向的 seed 都在这里集中控制。到这里你已经拥有一个能直接用于项目交付的 KEGG 网络可视化管线了。5. KEGG 网络可视化避坑指南五个高频翻车现场与解决方案这条管线看着简单实际跑起来我几乎每次都要排掉一两个坑。下面五个问题是我在多个项目里反复遇到的按「现象 → 原因 → 解决」写清楚希望你不用再走一遍。5.1 拿到的通路号是 map 开头解析后网络形态完全不对现象富集结果表里通路 ID 是map00010、map04110这种传入代码后解析出的网络只有二三十个节点而且全是化合物没有基因。原因KEGG 里map开头的是 reference pathway只包含通用代谢物和反应骨架不含具体物种的基因而富集分析真正应该用的是hsa00010、mmu04110这类物种特异通路。很多富集工具默认输出 map 号直接拿来用必然出错。解决写代码时强制校验通路前缀遇到 map 开头就按物种前缀替换或者在富集分析的工具里设置organismhsa让它直接输出物种特异 ID。这个坑最隐蔽因为程序不报错图也能画出来但你拿到的是没有基因信息的空壳网络。5.2 K 号转基因名后节点变少或一个点代表多个基因现象映射完表达量后图上基因节点少了三分之一或者悬浮信息里好几个基因名挤在同一个点上。原因一是 K 号与基因符号之间存在多对一和一对多的关系多个 K 号映射到同一个 symbol导致按 symbol 查表达量时重复二是 KGML 的names字段里本身就有多个 K 号比如hsa:2597 hsa:2599对应同一个酶的多个亚基如果只取第一个另一个基因的信息就丢了。解决解析时把names字段按空格全部分割所有 K 号都保留映射表达量时按 symbol 去重同一个 symbol 的多条记录取平均或取最显著的那条并在悬浮信息里标注「该节点代表 N 个基因」。不要只取第一个 K 号也不要拿到重复记录后整行丢弃。5.3 基因和化合物混图统一配色后整张图失去可读性现象节点全部按表达量上色后化合物节点也变成红色蓝色看起来像化合物也在差异表达外行 reviewer 会直接误读。原因映射逻辑没按节点类型分流把所有节点一视同仁地套用 FC 配色。解决严格按节点类型分流——基因节点参与表达映射化合物节点固定灰色或浅黄色反应节点用三角形状单独标识。如果一定要给化合物上色那就单独映射代谢组数据不要和转录组数据混用同一套色标。这个问题的本质是视觉变量和语义没对齐改起来很简单但影响很大。5.4 网络一大浏览器就白屏十万级节点图的性能陷阱现象跑某个大通路或物种间整合网络时生成的 HTML 有几十 MB浏览器打开后缩放拖动都卡死最后直接白屏。原因plotly 的 HTML 把每个点的坐标和样式都内联进页面几千节点没感觉几万以上节点就成了灾难更糟的是如果每条边都拆成三段线边的数量直接翻三倍。解决先做子图再渲染不要一上来就画全图。常见策略有两种——只保留差异基因的 2 跳邻域用nx.ego_graph(G, seed_node, radius2)或者按连通分量拆成多个子图每个子图单独渲染成一张 HTML。节点超过 2000、边超过 5000 时我一般不做全网渲染。这不是 plotly 的问题是网络规模本身不适合单图展示。5.5 并发请求 KEGG API 被限流脚本跑到一半集体失败现象批量跑 30 条通路前面 5 条正常第 6 条开始requests连续报超时或 403。原因KEGG API 对短时间请求次数有限制批量脚本里每拉一个 KGML、每查一个基因都算一次请求几十个请求并发打过去必然被限。解决三个手段组合——一是所有请求加time.sleep(0.3)或更大间隔二是 KGML 和基因详情都缓存到本地二次运行不再请求网络三是失败重试机制捕获requests.exceptions.RequestException后等 5 秒重试最多重试三次。我现在的习惯是任何 KEGG 相关脚本永远留一个cache/目录跑完第一次后后续所有重跑都走离线模式既快又稳。6. 进阶把布局选型、子图提取和批量报告固化成本地管线做到这一步你已经不是「能画图」而是「有一套自己的出图流程」。最后一章分享我现在固定下来的三个习惯它们帮我省掉了大量重复劳动。第一个习惯是布局优先级写死进代码。我现在跑任何通路都先看节点数和连通分量数少于 100 个节点直接官方坐标直出100 到 2000 个节点用力导向布局超过 2000 个节点先按连通分量拆开只渲染包含差异基因的那个分量。这条规则我放在一个choose_layout函数里每次跑新数据都不用重新想。第二个习惯是邻域优先差异基因只有十几个的时候我几乎永远只用nx.ego_graph(G, gene_node, radius2)提取局部子图再渲染这样图面干净、信息聚焦也避开了大网络卡顿。第三个习惯是自动化报告批量脚本跑完所有通路后除了 index.html我还会生成一个summary.tsv里面记录每条通路的节点数、边数、差异基因命中数这样组会汇报时先看表格再点进感兴趣的图。这些习惯的核心只有一句话KEGG 网络可视化不是一次性脚本而是反复跑、反复改的项目资产。把缓存、异常处理、布局逻辑固化下来你每次拿到新数据只需替换差异表剩下的全是流水线。我以前也吃过不设 seed 导致布局每次不一样的亏后来所有随机性参数一律固定也吃过不缓存 KGML 导致限流中断的亏现在每个项目都有一个 cache 目录。希望这些经验能帮你在 KEGG 网络可视化上少走一段路希望帮到你。本文还有配套的精品资源点击获取
简介面向生物信息学中KEGG通路可视化与交互分析需求该资源提供了一套完整的KEGG Network Viewer项目源码采用HTML、JavaScript与PHP构建可直接部署为在线代谢途径查看器。工具实现了基于AP检测算法的蛋白质分类展示能够直观标记通路中的关键节点并通过动态HTML页面模拟节点去除、边添加等操作便于研究者分析网络结构变化。压缩包共956个文件体积约62.01MB主要文件类型包括js脚本、html页面、php服务端文件、css样式以及png/gif图像、Markdown说明文档、SQL数据库备份涵盖前端交互、后端接口、数据模型与样式主题等多个模块。该资源已有1086人学习与下载适合生物信息学入门学者、代谢通路分析开发者以及从事可视化成套项目设计的网页工程师参考。借助完整源码与配套数据库读者可掌握从KEGG数据解析到网络渲染的完整流程并利用内置编辑器、bootstrap响应式布局与数据库脚本快速搭建个性化应用。1. 给 KEGG 通路画一张能交互的网络图kegg-network-viewer 到底解决什么问题做富集分析的时候拿到几十条 KEGG 通路列表的那一刻才是真正头疼的开始。某课题组 A 同学以前的做法是一层层点开官方通路图截图最后汇报 PPT 里全是密密麻麻的箭头既看不清差异基因落在哪些环节也没法把上调和下调的基因颜色对齐到同一张图上。kegg-network-viewer 这类可视化 KEGG 网络的工具要解决的就是这个把 KEGG 通路的 KGML 文件解析成节点和边用交互式网络图把基因、化合物、反应关系画出来再叠加转录组或代谢组的差异结果一条通路一张图能缩放、能悬浮看基因名和表达量。适合每天跟富集结果打交道的生信从业者也适合想摆脱截图、把通路视图批量落进项目报告的人。2. 先拆开 KGMLKEGG 网络里的节点、边与三种数据形态很多人在可视化 KEGG 网络上栽跟头不是画图代码写错而是没搞清楚 KGML 里存的数据到底是什么。KGML 是 KEGG 通路的官方交换格式一个通路一个 XML 文件里面把基因、化合物、反应、调控关系全揉在一起。直接拿来画图第一版往往长成一张「意大利面」——所有节点挤在一团边互相缠绕根本没法读。这不是工具的问题是你没把 KGML 的语义拆出来。2.1 entry、relation、reaction 三段式KGML 里到底存了什么KGML 文件的根元素是 pathway下面主要挂三类子节点entry、relation、reaction。entry 是图的节点relation 是节点之间的逻辑关系reaction 是酶促反应本身。一个典型的 gene 类型 entry 长这样entry id42 typegene namehsa:2597 hsa:2599 reactionrn:R02865 graphics nameGAPDH x520 y340 width46 height17/ /entryname 字段里存的是 KEGG 的基因编号K 号多个编号用空格分隔reaction 字段指向该基因参与的反应graphics 里是官方通路图上的坐标。compound 类型的 entry 结构类似不过 name 里是 C 号比如 C00103葡萄糖。relation 描述的是调控关系比如 activation、inhibition、phosphorylation它的 entry1 和 entry2 指向两个 entry 的 id。reaction 节点则有自己的 id下面挂 substrate 和 product 列表指向参与反应的化合物 entry。所以一个 KEGG 网络图里其实有三种语义完全不同的节点基因、化合物、反应。基因通过「催化」连接到反应反应连接底物和产物基因和基因之间还有调控边。这三种边不能混为一谈画图时如果不区分看到的就只是一团无序的连线。2.2 节点全连在一起就是网络语义不同画法完全不同我见过最典型的错误做法把 entry 全部变成点把 relation 和 reaction 全部变成边丢给力导向布局就跑。结果图里化合物节点因为度很高被甩到外围基因节点全挤在中心调控边的方向乱成一团。原因在于没有区分边的语义。KGML 里的边至少有三类第一类是 relation 表达的调控边方向表示调控方向激活还是抑制由 subtype 决定第二类是 reaction 内部的底物-反应-产物边方向表示代谢流向不是调控关系第三类是 gene 到 reaction 的催化边表示「这个基因编码的酶催化这个反应」。三类边在生物学含义上完全不同在图上应该用不同颜色、不同线型区分。有一个常见误解很多人把 KEGG 官方通路图里的箭头当成调控方向。实际上官方图里的箭头大多是代谢流向或邻接关系真正的调控信息激活、抑制、磷酸化在 KGML 的 relation 里。所以可视化时如果想保留「调控」语义要优先渲染 relation 边如果想看代谢流优先渲染 reaction 边。一个 viewer 如果只给一张全混的图等于没做语义分层。2.3 三种常见的可视化形态官方坐标直出、逻辑重布局、组学叠加同样一份 KGML根据用途不同有三种画法。第一种是官方坐标直出直接用 graphics 里的 x、y 把节点摆在官方通路图的位置上这种最适合还原 KEGG 原图别人看起来亲切但节点一多就重叠第二种是逻辑重布局完全忽略官方坐标把节点和边交给力导向或层次布局算法这种适合看网络拓扑和调控模块第三种是组学叠加在布局之上把差异基因、表达量、p 值映射到节点的颜色、大小和悬浮信息上这就是做富集分析时最需要的视图。三种形态不是互斥的。一个完整的 kegg-network-viewer 管线通常是解析 KGML 得到图结构先把官方坐标存下来作为默认视图再提供重布局的开关最后把实验数据映射上去。第 3 章我直接给出一个最小可运行的方案你可以照着把这三层都落地。3. 本地跑通最小方案Python 解析 KGML 并渲染成交互网络讲完数据形态这一章直接上手。我推荐的技术栈是 Python networkx plotly理由很直接networkx 负责图结构和布局计算plotly 负责交互式渲染两者都是成熟库不用额外搭前端。整套代码跑完你会得到一个本地 HTML 文件浏览器打开就能缩放和悬停。3.1 拉取 KGML 并解析成 networkx 图最小代码与逐行说明第一步是从 KEGG API 拉 KGML 并解析成有向图。下面的代码把 KGML 的 entry 变成节点把 relation 和 reaction 拆成边并保留官方坐标import requests import networkx as nx import xml.etree.ElementTree as ET KEGG_URL https://rest.kegg.jp/get/{pathway}/kgml def load_kgml(pathway_id: str, local_path: str ) - nx.DiGraph: 拉取或读取 KGML解析成 networkx 有向图 if local_path: with open(local_path, r, encodingutf-8) as f: xml_text f.read() else: xml_text requests.get(KEGG_URL.format(pathwaypathway_id), timeout30).text # 缓存到本地避免重复请求触发限流 with open(f{pathway_id}.kgml, w, encodingutf-8) as f: f.write(xml_text) root ET.fromstring(xml_text) G nx.DiGraph() # entry 是节点gene 的 name 是 K 号列表compound 的 name 是 C 号 for entry in root.findall(entry): eid entry.get(id) G.add_node(eid, typeentry.get(type, ), namesentry.get(name, ).split( )) for g in entry.findall(graphics): # 官方坐标后续做布局用y 轴方向后面要处理 G.nodes[eid][x] int(g.get(x, 0)) G.nodes[eid][y] int(g.get(y, 0)) # relation 是调控边如 activation / inhibition for rel in root.findall(relation): src, dst rel.get(entry1), rel.get(entry2) rel_type rel.get(type) subtypes [s.get(name) for s in rel.findall(subtype)] G.add_edge(src, dst, kindfrelation:{rel_type}, subtypessubtypes) # reaction 是反应节点连接底物和产物 for react in root.findall(reaction): rid react.get(id) for s in react.findall(substrate): G.add_edge(s.get(id), rid, kindsubstrate) for p in react.findall(product): G.add_edge(rid, p.get(id), kindproduct) return G这个函数返回的 DiGraph 里节点属性有 type、names、x、y边属性有 kind 和 subtypes。逻辑说明我把 relation 和 reaction 分开建边而不是混在一起这样后续可以按 kind 过滤——只想看调控网络时只保留 relation 开头的边想看代谢流时只看 substrate/product 边。参数说明pathway_id 传类似hsa00010的通路号local_path 填本地 KGML 文件路径时走离线分支适合批量跑的时候用图是有向图方向保留语义。注意 relation 边的方向是「调控者 → 被调控者」如果你习惯反着画后面渲染时自行翻转。3.2 布局不是玄学官方坐标、力导向、层次布局怎么选拿到图结构后下一步是决定节点摆在哪。三种布局各有适用场景选择标准是节点数量和语义需求。官方坐标直出是最简单的直接用 KGML 里存好的坐标。但这里有一个坑KGML 的坐标是图像坐标系y 轴向下直接画出来图是上下颠倒的。渲染前把 y 取反即可# 官方坐标直出注意 y 轴翻转 pos {n: (G.nodes[n][x], -G.nodes[n][y]) for n in G.nodes if x in G.nodes[n]}力导向布局适合 100 到 2000 个节点的中等网络它能自然地把高度连接的节点聚在一起# 力导向布局k 控制节点间距seed 保证每次结果一致 pos nx.spring_layout(G, k0.8, seed42, iterations300)层次布局适合代谢通路这种方向性明显的网络按节点离起点的拓扑距离分层# 层次布局先算节点所在层再按层排布 layer {} for n in G.nodes: try: layer[n] nx.shortest_path_length(G, source33) # 选一个入口节点 except nx.NetworkXNoPath: layer[n] 0 pos nx.multipartite_layout(G, subsetlayer)我的经验阈值是节点少于 100 用官方坐标直出100 到 2000 用力导向超过 2000 先做子图提取再布局直接布局必然成一团黑。力导向的参数里 seed 一定要固定不然每次跑出来的图都不一样项目汇报时同一个通路长两个样会非常尴尬。3.3 用 plotly 把图变成可交互 HTML节点信息、缩放与悬停布局算完最后一步是渲染。plotly 的做法很直接把边拆成一段段线段把节点拆成散点然后用 Scatter 轨迹画出来。下面这个函数接收图和布局输出交互式 Figureimport plotly.graph_objects as go def draw_kegg_graph(G, pos, node_size18, node_color#4C78A8): # 边拆线段每条边画一条从 src 到 dst 的线 edge_x, edge_y [], [] for u, v, d in G.edges(dataTrue): x0, y0 pos[u] x1, y1 pos[v] edge_x [x0, x1, None] edge_y [y0, y1, None] # 节点散点text 里放节点 id 和类型悬浮可看 node_x [pos[n][0] for n in G.nodes] node_y [pos[n][1] for n in G.nodes] node_text [f{n}br{G.nodes[n].get(type, )} for n in G.nodes] fig go.Figure() fig.add_trace(go.Scatter(xedge_x, yedge_y, modelines, linedict(width1, color#A0A0A0), hoverinfonone)) fig.add_trace(go.Scatter(xnode_x, ynode_y, modemarkerstext, textnode_text, textpositionbottom center, markerdict(sizenode_size, colornode_color))) fig.update_layout(titleKEGG Pathway Network, height800, showlegendFalse, templateplotly_white) return fig渲染函数的逻辑说明第一条轨迹画边None用来断开不同线段第二条轨迹画节点节点 id 和类型作为悬浮文本。参数说明node_size可以传标量也可以传列表后面叠加表达量时传列表实现差异化大小node_color同理传颜色列表就能实现上调红色、下调蓝色。plotly 渲染出的 HTML 自带缩放、平移和悬浮查看不需要额外写前端代码。把这个函数和前面的 load_kgml 串起来输入一个通路号输出一个可交互 HTML最小方案就跑通了。4. 把差异基因和富集结果叠到 KEGG 网络上上色、定大小、加信息最小方案跑通后大多数人的下一步需求是把差异表达基因叠到通路上。这一步做得好不好直接决定这张图能不能放进论文或汇报。核心思路是三个映射——颜色映射表达变化方向大小映射显著性悬浮信息映射基因身份和数值。但映射之前数据对齐是绕不过去的一道坎。4.1 数据对齐是第一步K 号转基因符号的正确姿势KGML 里基因节点存的是 K 号如hsa:2597而你的差异表达表里通常是基因符号如GAPDH或 Entrez ID。不对齐就映射图上会出现一大片「找不到」的灰点。我一般会准备一个 K 号到基因符号的映射表来源可以是 KEGG 的 gene 数据库也可以自己用biopython批量查def build_symbol_map(pathway_id: str) - dict: 从 KEGG gene API 构建 K号 - 基因符号 映射 import requests symbol_map {} gene_list requests.get( fhttps://rest.kegg.jp/link/{pathway_id.split(hsa)[0]}/pathway:{pathway_id}, timeout30 ).text.strip().splitlines() # 返回格式pathway:hsa00010\thsa:2597 for line in gene_list: _, kegg_id line.split(\t) gene_detail requests.get( fhttps://rest.kegg.jp/get/{kegg_id}, timeout30 ).text for para in gene_detail.splitlines(): if para.startswith(NAME): # NAME 行格式NAME GAPDH (phosphoglyceraldehyde dehydrogenase) symbol para.split()[1].split(()[0] symbol_map[kegg_id] symbol break return symbol_map这段代码的逻辑说明link接口返回通路下所有基因的 K 号列表然后逐个查 gene 详情从 NAME 字段里取第一个符号。参数说明pathway_id.split(hsa)[0]提取物种前缀因为 link 接口的物种参数只接受hsa、mmu这类简称requests.get要加超时避免某个基因查询挂起拖垮整个脚本。注意这里逐基因查询比较慢几十个基因没问题几百个基因建议保存成文件缓存后面避坑章会细说。4.2 让节点“说话”颜色映射 FC大小映射 p 值形状映射类型对齐之后映射规则就很直接了。我给出一套经过多次项目验证的默认规则上调基因log2FC 1标红色下调基因log2FC -1标蓝色不显著标灰色显著性用-log10(padj)映射到节点大小越显著越大节点形状区分类型基因用圆点化合物用方块反应节点用三角。代码如下def map_expr_to_nodes(G, exp_df, symbol_map): exp_df 必须包含三列gene_symbol, log2FC, padj 返回值是三个列表colors, sizes, labels直接传给 draw_kegg_graph exp_dict exp_df.set_index(gene_symbol)[[log2FC, padj]].T.to_dict() colors, sizes, labels [], [], [] for n, data in G.nodes(dataTrue): if data.get(type) ! gene: # 化合物和反应节点用固定样式不参与表达映射 colors.append(#CCCCCC) sizes.append(10) labels.append(f{n}br{data.get(type)}) continue kegg_id data[names][0] symbol symbol_map.get(kegg_id, kegg_id) rec exp_dict.get(symbol) if rec is None or pd.isna(rec[padj]) or rec[padj] 0.05: colors.append(#999999) sizes.append(12) else: fc rec[log2FC] colors.append(#D62728 if fc 1 else #1F77B4 if fc -1 else #999999) sizes.append(14 26 * min(1.0, -np.log10(rec[padj]) / 10)) labels.append(f{symbol}br{kegg_id}brFC{rec.get(log2FC, NA)}brpadj{rec.get(padj, NA)}) return colors, sizes, labels这段映射的逻辑说明基因节点取names列表的第一个 K 号去查符号找到后再从差异表里取数值化合物和反应节点跳过映射用灰色固定大小避免它们过度抢眼。参数说明padj 0.05是显著性阈值按你的实验标准可改14 26 * min(1.0, -log10(padj)/10)把显著性线性映射到 14 到 40 像素/10是缩放因子如果你们的 p 值普遍极小可以把 10 调大到 20避免所有点都变成最大号。4.3 多通路批量出图一个循环输出整份通路视图单条通路做好后批量就是水到渠成的事。富集分析通常会给你 20 到 50 条显著通路一条条手动跑显然不现实。把前面所有函数串进一个循环import os def batch_build(pathway_list, exp_df, symbol_map, out_dirkegg_html): os.makedirs(out_dir, exist_okTrue) index_links [] for pid in pathway_list: # 缓存已存在的 KGML 文件避免重复请求 kgml_file fcache/{pid}.kgml if os.path.exists(fcache/{pid}.kgml) else G load_kgml(pid, kgml_file) # 布局按节点数选择少于100用官方坐标 if G.number_of_nodes() 100: pos {n: (G.nodes[n][x], -G.nodes[n][y]) for n in G.nodes if x in G.nodes[n]} else: pos nx.spring_layout(G, k0.8, seed42, iterations200) colors, sizes, labels map_expr_to_nodes(G, exp_df, symbol_map) fig draw_kegg_graph(G, pos, node_sizesizes, node_colorcolors) # 把 labels 写回 fig 的第二个 trace fig.data[1].text labels out_file os.path.join(out_dir, f{pid}.html) fig.write_html(out_file) index_links.append(fa href{pid}.html{pid}/a) with open(os.path.join(out_dir, index.html), w, encodingutf-8) as f: f.write(br.join(index_links))批量脚本的逻辑说明每个通路独立成 HTML最后生成一个 index.html 做汇总入口汇报时打开 index 就能逐条点进所有通路。参数说明cache/目录用来存 KGML脚本第二次跑时不再请求 API布局的节点数阈值、力导向的 seed 都在这里集中控制。到这里你已经拥有一个能直接用于项目交付的 KEGG 网络可视化管线了。5. KEGG 网络可视化避坑指南五个高频翻车现场与解决方案这条管线看着简单实际跑起来我几乎每次都要排掉一两个坑。下面五个问题是我在多个项目里反复遇到的按「现象 → 原因 → 解决」写清楚希望你不用再走一遍。5.1 拿到的通路号是 map 开头解析后网络形态完全不对现象富集结果表里通路 ID 是map00010、map04110这种传入代码后解析出的网络只有二三十个节点而且全是化合物没有基因。原因KEGG 里map开头的是 reference pathway只包含通用代谢物和反应骨架不含具体物种的基因而富集分析真正应该用的是hsa00010、mmu04110这类物种特异通路。很多富集工具默认输出 map 号直接拿来用必然出错。解决写代码时强制校验通路前缀遇到 map 开头就按物种前缀替换或者在富集分析的工具里设置organismhsa让它直接输出物种特异 ID。这个坑最隐蔽因为程序不报错图也能画出来但你拿到的是没有基因信息的空壳网络。5.2 K 号转基因名后节点变少或一个点代表多个基因现象映射完表达量后图上基因节点少了三分之一或者悬浮信息里好几个基因名挤在同一个点上。原因一是 K 号与基因符号之间存在多对一和一对多的关系多个 K 号映射到同一个 symbol导致按 symbol 查表达量时重复二是 KGML 的names字段里本身就有多个 K 号比如hsa:2597 hsa:2599对应同一个酶的多个亚基如果只取第一个另一个基因的信息就丢了。解决解析时把names字段按空格全部分割所有 K 号都保留映射表达量时按 symbol 去重同一个 symbol 的多条记录取平均或取最显著的那条并在悬浮信息里标注「该节点代表 N 个基因」。不要只取第一个 K 号也不要拿到重复记录后整行丢弃。5.3 基因和化合物混图统一配色后整张图失去可读性现象节点全部按表达量上色后化合物节点也变成红色蓝色看起来像化合物也在差异表达外行 reviewer 会直接误读。原因映射逻辑没按节点类型分流把所有节点一视同仁地套用 FC 配色。解决严格按节点类型分流——基因节点参与表达映射化合物节点固定灰色或浅黄色反应节点用三角形状单独标识。如果一定要给化合物上色那就单独映射代谢组数据不要和转录组数据混用同一套色标。这个问题的本质是视觉变量和语义没对齐改起来很简单但影响很大。5.4 网络一大浏览器就白屏十万级节点图的性能陷阱现象跑某个大通路或物种间整合网络时生成的 HTML 有几十 MB浏览器打开后缩放拖动都卡死最后直接白屏。原因plotly 的 HTML 把每个点的坐标和样式都内联进页面几千节点没感觉几万以上节点就成了灾难更糟的是如果每条边都拆成三段线边的数量直接翻三倍。解决先做子图再渲染不要一上来就画全图。常见策略有两种——只保留差异基因的 2 跳邻域用nx.ego_graph(G, seed_node, radius2)或者按连通分量拆成多个子图每个子图单独渲染成一张 HTML。节点超过 2000、边超过 5000 时我一般不做全网渲染。这不是 plotly 的问题是网络规模本身不适合单图展示。5.5 并发请求 KEGG API 被限流脚本跑到一半集体失败现象批量跑 30 条通路前面 5 条正常第 6 条开始requests连续报超时或 403。原因KEGG API 对短时间请求次数有限制批量脚本里每拉一个 KGML、每查一个基因都算一次请求几十个请求并发打过去必然被限。解决三个手段组合——一是所有请求加time.sleep(0.3)或更大间隔二是 KGML 和基因详情都缓存到本地二次运行不再请求网络三是失败重试机制捕获requests.exceptions.RequestException后等 5 秒重试最多重试三次。我现在的习惯是任何 KEGG 相关脚本永远留一个cache/目录跑完第一次后后续所有重跑都走离线模式既快又稳。6. 进阶把布局选型、子图提取和批量报告固化成本地管线做到这一步你已经不是「能画图」而是「有一套自己的出图流程」。最后一章分享我现在固定下来的三个习惯它们帮我省掉了大量重复劳动。第一个习惯是布局优先级写死进代码。我现在跑任何通路都先看节点数和连通分量数少于 100 个节点直接官方坐标直出100 到 2000 个节点用力导向布局超过 2000 个节点先按连通分量拆开只渲染包含差异基因的那个分量。这条规则我放在一个choose_layout函数里每次跑新数据都不用重新想。第二个习惯是邻域优先差异基因只有十几个的时候我几乎永远只用nx.ego_graph(G, gene_node, radius2)提取局部子图再渲染这样图面干净、信息聚焦也避开了大网络卡顿。第三个习惯是自动化报告批量脚本跑完所有通路后除了 index.html我还会生成一个summary.tsv里面记录每条通路的节点数、边数、差异基因命中数这样组会汇报时先看表格再点进感兴趣的图。这些习惯的核心只有一句话KEGG 网络可视化不是一次性脚本而是反复跑、反复改的项目资产。把缓存、异常处理、布局逻辑固化下来你每次拿到新数据只需替换差异表剩下的全是流水线。我以前也吃过不设 seed 导致布局每次不一样的亏后来所有随机性参数一律固定也吃过不缓存 KGML 导致限流中断的亏现在每个项目都有一个 cache 目录。希望这些经验能帮你在 KEGG 网络可视化上少走一段路希望帮到你。本文还有配套的精品资源点击获取
