R语言ComplexHeatmap包实战：从矩形到圆形热图的复现与定制

这次我们来看一个R语言绘图实战项目使用ComplexHeatmap包复现一篇文献中的圆形热图。对于经常做生物信息学分析或数据可视化的研究者来说在顶级期刊上看到一张设计精良、信息丰富的热图并想在自己的文章中重现是常有的事。ComplexHeatmap是R语言中功能最强大、最灵活的热图绘制包之一尤其擅长处理复杂的注释和布局。本文将带你一步步拆解这个复现过程从数据准备、包安装、参数解读到最终图形调整让你不仅能复现文献案例更能掌握这套工具的通用方法。本文的重点不是空谈概念而是提供一套可执行、可验证的流程。无论你是刚接触R语言的新手还是有一定基础想深入掌握ComplexHeatmap的用户都能从中找到可操作的步骤。我们会重点关注1如何解析目标热图的结构2ComplexHeatmap的核心函数与参数3从矩形热图到圆形热图的转换技巧4以及如何调整颜色、注释、标签等细节以达到出版级质量。1. 核心能力速览在开始动手之前我们先快速了解完成这个任务所需的核心工具与能力边界。能力项说明核心工具R语言 ComplexHeatmap包主要功能绘制高度定制化的热图支持行/列注释、分面、复杂布局、交互式需配合其他包及圆形布局。硬件门槛极低。普通个人电脑即可无需GPU。性能主要取决于数据矩阵大小和图形的复杂程度。环境依赖R环境 3.6.0 推荐Bioconductor包管理工具。学习曲线中等。基础热图函数易用但高级定制如圆形热图需要理解其绘图逻辑和图层系统。适合场景生物信息学基因表达、甲基化、组学数据分析、任何需要展示矩阵数据并附加丰富注释信息的科研绘图。输出格式支持PDF, PNG, SVG, EPS等多种矢量/位图格式出版级质量。关键点ComplexHeatmap的“圆形热图”并非一个独立的函数而是通过circular TRUE参数将标准的矩形热图“弯曲”成环形并配合circular相关的主题设置来实现。理解这一点是成功复现的关键。2. 适用场景与使用边界这个教程适合谁生物信息学分析师/生信工程师需要为论文或报告制作专业热图。生命科学领域的研究生/博士后在阅读文献时希望复现或借鉴其中的可视化方法。数据科学家/数据分析师处理任何矩阵形式的数据如相关性矩阵、用户-物品评分矩阵并需要增强可视化。R语言可视化爱好者希望超越pheatmap或ggplot2的热图功能实现更复杂的布局。它能解决什么问题精准复现将文献中看到的复杂热图尤其是带有环形布局、多层注释的在自己的环境中重现。深度定制完全控制热图的每一个视觉元素包括颜色、字体、间距、注释条的形状和位置。信息整合将样本分组信息、基因集注释、数值分布如箱线图等多元信息无缝整合到一张图中。流程化输出将绘图代码封装成函数或脚本便于对不同数据集进行批量出图保证风格一致。它的能力边界与注意事项非交互式ComplexHeatmap本身生成的是静态图片。如需交互如鼠标悬停显示数值需结合InteractiveComplexHeatmap等扩展包。编程要求需要一定的R语言编程基础特别是对数据框data.frame、矩阵matrix和列表list的操作。审美主观包提供了极大的自由度但如何设计出美观、清晰的图需要使用者具备一定的数据可视化审美。数据规模虽然能处理较大矩阵但当行或列数极大如数万时渲染和保存可能会较慢且细节无法辨认。此时应考虑先进行聚类筛选。3. 环境准备与前置条件在开始绘制圆形热图前请确保你的工作环境已就绪。3.1 软件与平台操作系统Windows, macOS, 或 Linux 均可。本文示例在Windows 11 / R 4.3.2环境下测试。R语言请安装较新版本的R建议4.0以上。前往 R语言官网 下载安装。R集成开发环境IDE强烈推荐使用RStudio它提供了代码编辑、控制台、绘图预览和文件管理的集成环境能极大提升效率。3.2 安装ComplexHeatmap及相关包ComplexHeatmap是一个Bioconductor项目因此需要通过BiocManager来安装。打开R或RStudio在控制台Console中依次执行以下命令# 1. 安装BiocManager如果尚未安装 if (!requireNamespace(BiocManager, quietly TRUE)) install.packages(BiocManager) # 2. 通过BiocManager安装ComplexHeatmap BiocManager::install(ComplexHeatmap) # 3. 安装常用的辅助包用于数据操作和颜色配置 install.packages(c(dplyr, circlize, RColorBrewer))安装可能遇到的问题与解决方案网络问题由于Bioconductor镜像位于海外安装可能较慢或失败。可以设置国内CRAN和Bioconductor镜像。# 设置CRAN镜像例如清华镜像 options(repos c(CRAN https://mirrors.tuna.tsinghua.edu.cn/CRAN/)) # 设置Bioconductor镜像 options(BioC_mirror https://mirrors.tuna.tsinghua.edu.cn/bioconductor) # 然后再运行 BiocManager::install依赖包编译错误在Linux或macOS上可能需要系统级的开发库如libcurl,libxml2。请根据错误提示安装相应系统依赖。版本冲突如果遇到包版本不兼容可以尝试更新所有包BiocManager::install(ask FALSE)。3.3 准备你的“目标文献热图”这是最关键的一步。你需要找到目标图明确你要复现的是哪篇文献的哪张图。将其保存为高清图片。解构目标图用图片查看器打开仔细观察并回答以下问题最好用笔记下来数据主体热图本身是什么数据基因表达量相关性系数数值范围大致是多少行列信息行通常是基因/特征有多少列通常是样本/条件有多少是否有行/列名聚类情况行和列是否做了聚类树状图聚类树是放在哪一边注释信息图的顶部、左侧或右侧有哪些注释条annotation它们代表什么如样本分组、基因类型、显著性标记分别用了哪些颜色颜色映射热图主色系是什么是从蓝-白-红还是绿-黑-红或是单色渐变特殊布局是否是圆形环形内部和外部有哪些元素如柱状图、点图标签与标题坐标轴标签、图例标题是什么字体大小如何假设案例为了本文演示我们虚构一个目标场景复现一篇癌症研究文献中的图该图展示了5个基因在100个样本50个肿瘤50个正常中的表达谱样本按类型注释基因按通路注释并以圆形布局呈现。4. 数据模拟与包加载由于我们无法获取原文献的真实数据我们将根据上述假设案例模拟一个数据集。这在实际复现中对应着你自己的数据准备过程。# 加载必要的库 library(ComplexHeatmap) library(circlize) # 用于定义颜色映射函数 library(RColorBrewer) # 提供调色板 library(dplyr) # 数据操作 # 设置随机种子保证结果可重复 set.seed(123) # 1. 模拟表达矩阵5个基因 x 100个样本 gene_names - paste0(Gene_, LETTERS[1:5]) sample_names - paste0(Sample_, sprintf(%03d, 1:100)) # 模拟表达数据让肿瘤和正常样本有差异 expr_mat - matrix(rnorm(500, mean 0, sd 1), nrow 5, ncol 100) rownames(expr_mat) - gene_names colnames(expr_mat) - sample_names # 人为制造差异让肿瘤样本中Gene_A, Gene_B高表达Gene_E低表达 tumor_indices - 1:50 # 假设前50个是肿瘤样本 expr_mat[“Gene_A”, tumor_indices] - expr_mat[“Gene_A”, tumor_indices] 2 expr_mat[“Gene_B”, tumor_indices] - expr_mat[“Gene_B”, tumor_indices] 1.5 expr_mat[“Gene_E”, tumor_indices] - expr_mat[“Gene_E”, tumor_indices] - 1 # 2. 创建样本注释列注释 # 样本分组肿瘤 vs 正常 sample_group - factor(c(rep(“Tumor”, 50), rep(“Normal”, 50))) # 样本性别另一个注释维度 sample_gender - factor(sample(c(“Male”, “Female”), 100, replace TRUE)) # 3. 创建基因注释行注释 # 基因所属通路 gene_pathway - c(“Pathway_A”, “Pathway_A”, “Pathway_B”, “Pathway_C”, “Pathway_B”) names(gene_pathway) - gene_names # 基因是否差异表达根据我们模拟的差异 gene_de - c(“Up”, “Up”, “No”, “No”, “Down”) names(gene_de) - gene_names # 查看数据概览 print(dim(expr_mat)) head(expr_mat[, 1:6]) table(sample_group) table(gene_pathway)5. 构建矩形热图理解基础在挑战圆形布局前我们先构建一个标准的矩形热图这是理解所有组件的基础。我们将逐步添加注释。# 步骤1定义热图主体的颜色映射 # 使用circlize::colorRamp2函数可以精准控制数值到颜色的映射 col_fun - colorRamp2(c(-2, 0, 2), c(“blue”, “white”, “red”)) # 步骤2构建列注释样本注释 # 创建注释对象可以同时添加多个注释条 column_ha - HeatmapAnnotation( “Group” sample_group, “Gender” sample_gender, col list( “Group” c(“Tumor” “firebrick2”, “Normal” “steelblue”), “Gender” c(“Male” “darkgreen”, “Female” “goldenrod”) ), annotation_name_side “left”, # 注释名称的位置 simple_anno_size unit(4, “mm”) # 注释条的宽度 ) # 步骤3构建行注释基因注释 row_ha - rowAnnotation( “Pathway” gene_pathway, “DE Status” gene_de, col list( “Pathway” c(“Pathway_A” “darkorchid”, “Pathway_B” “darkorange”, “Pathway_C” “cyan4”), “DE Status” c(“Up” “red3”, “Down” “blue3”, “No” “grey80”) ), simple_anno_size unit(4, “mm”) ) # 步骤4绘制基础热图不带聚类 ht_rect - Heatmap( expr_mat, name “Expr”, # 图例标题 col col_fun, # 颜色映射函数 top_annotation column_ha, # 将列注释放在热图上方 left_annotation row_ha, # 将行注释放在热图左侧 row_title “Genes”, column_title “Samples (Tumor vs Normal)”, row_names_side “left”, column_names_gp gpar(fontsize 7), # 调整列名字体大小 show_column_names FALSE, # 样本太多先不显示列名 heatmap_legend_param list( title_gp gpar(fontsize 10, fontface “bold”), labels_gp gpar(fontsize 9) ) ) # 步骤5绘制图形 draw(ht_rect)运行上述代码你将得到一个带有上下注释的矩形热图。此时你可以通过调整show_column_names、row_dend_width、column_dend_height等参数来改变树状图、标签的显示方式。这是你复现文献图的“草图”确保所有数据层和注释层都正确映射。6. 转换为圆形热图圆形热图的核心参数是circular TRUE。但直接添加这个参数可能会让布局混乱需要同步调整其他设置。# 在基础Heatmap对象中添加 circular 参数 ht_circular - Heatmap( expr_mat, name “Expr”, col col_fun, top_annotation column_ha, left_annotation row_ha, row_title “Genes”, column_title “Samples (Tumor vs Normal)”, show_column_names FALSE, # 启用圆形布局 circular TRUE, # 圆形布局的特定参数 gap unit(5, “mm”), # 扇区之间的间隙 start_degree 90, # 起始角度12点钟方向为 -90 3点钟为 0。这里90表示从12点开始需测试 # 调整聚类树如果存在在圆形布局中的显示 cluster_rows FALSE, # 圆形布局下行聚类树显示可能不理想可先关闭 cluster_columns FALSE, # 圆形布局下的标签旋转 row_names_side “outside”, # 行名放在圆环外侧 column_names_side “outside”, # 列名放在圆环外侧如果显示 row_names_max_width max_text_width(rownames(expr_mat)), # 避免行名被截断 heatmap_legend_param list( title_gp gpar(fontsize 10, fontface “bold”), labels_gp gpar(fontsize 9), direction “horizontal” # 图例方向可调整 ) ) # 绘制圆形热图 draw(ht_circular)第一次转换可能遇到的问题图形元素错位或重叠圆形布局改变了所有元素的坐标系统。注释条、标题、图例的位置可能需要手动调整。行/列标签拥挤在圆形布局中内侧的标签会变得非常拥挤且难以阅读。通常需要隐藏内侧标签show_row_names FALSE或只显示部分标签。聚类树显示异常矩形下的树状图在弯曲后可能看起来很奇怪。对于圆形热图有时会放弃聚类树或使用dendrogram包绘制环状树另行添加。优化策略简化显示隐藏所有样本名show_column_names FALSE基因名如果较多也可考虑隐藏或仅显示关键基因。调整注释top_annotation在圆形中会变成外环注释left_annotation会变成内环注释。可以通过annotation_legend_param控制图例用annotation_height或annotation_width调整环的厚度。使用circlize布局ComplexHeatmap的圆形布局底层依赖于circlize包。更复杂的环形图如多轨道、连线可能需要直接使用circlize::circos.heatmap等函数但学习成本更高。对于大多数文献复现Heatmap(circularTRUE)已足够。7. 高级定制与细节打磨复现的精髓在于对细节的把握。我们需要对照目标文献图逐一调整参数。7.1 精确控制颜色文献中的颜色往往不是默认调色板。使用colorRamp2()可以精确匹配。# 假设文献中使用的是“紫-白-绿”渐变 col_fun_literature - colorRamp2(c(-3, 0, 3), c(“purple”, “white”, “green”)) # 或者使用特定的Brewer调色板 library(RColorBrewer) my_brewer_pal - rev(brewer.pal(11, “RdBu”)) # 反转红蓝调色板 col_fun_brewer - colorRamp2(seq(-2, 2, length.out 11), my_brewer_pal)7.2 调整注释条样式# 创建更复杂的列注释包含连续型数据和点图 column_ha_advanced - HeatmapAnnotation( “Group” sample_group, “Gender” sample_gender, “Score” anno_points(runif(100, 0, 10), # 模拟一个连续型评分 gp gpar(col “black”), size unit(1, “mm”)), “Bar” anno_barplot(colSums(expr_mat), # 模拟一个柱状图 bar_width 0.8, gp gpar(fill “grey70”, col “black”)), col list( “Group” c(“Tumor” “firebrick2”, “Normal” “steelblue”), “Gender” c(“Male” “darkgreen”, “Female” “goldenrod”) ), annotation_name_gp gpar(fontsize 9, fontface “italic”), # 注释名称字体 annotation_legend_param list( # 控制注释图例 “Group” list(title “Sample Group”, title_gp gpar(fontsize9)), “Gender” list(title “Gender”, title_gp gpar(fontsize9)) ), height unit(1.5, “cm”) # 注释区域总高度 )7.3 控制图形尺寸与输出# 绘制最终图形并保存为PDF矢量图出版质量 pdf(“My_Circular_Heatmap.pdf”, width 10, height 8) # 宽10英寸高8英寸 draw(ht_circular, padding unit(c(20, 5, 5, 5), “mm”), # 调整图形边距上、右、下、左 heatmap_legend_side “bottom”, # 主图例放在底部 annotation_legend_side “right” # 注释图例放在右侧 ) dev.off() # 关闭图形设备保存文件 # 也可以保存为PNG位图用于网页或PPT png(“My_Circular_Heatmap.png”, width 3000, height 2400, res 300) # 高分辨率 draw(ht_circular, …) # 参数同上 dev.off()8. 完整复现代码整合将以上步骤整合成一个完整的、可运行的脚本并添加必要的注释。这是你最终可以保存和复用的资产。# 完整脚本复现文献圆形热图 # 作者Your Name # 日期2024-05-20 # 描述使用ComplexHeatmap包绘制带注释的圆形热图 # 1. 加载库 ---------------------------------------------------------------- library(ComplexHeatmap) library(circlize) library(RColorBrewer) library(dplyr) # 2. 模拟/加载数据 --------------------------------------------------------- set.seed(123) # … [此处插入你的实际数据加载代码或上述模拟数据代码] … # 假设 expr_mat, sample_group, gene_pathway 等变量已存在 # 3. 定义颜色与注释 -------------------------------------------------------- # 3.1 热图主体颜色 col_fun - colorRamp2(c(-2, 0, 2), c(“blue”, “white”, “red”)) # 3.2 列注释 column_ha - HeatmapAnnotation( Group sample_group, col list(Group c(“Tumor” “red”, “Normal” “blue”)), annotation_name_side “left”, simple_anno_size unit(4, “mm”), annotation_legend_param list(Group list(title “Sample Type”)) ) # 3.3 行注释 row_ha - rowAnnotation( Pathway gene_pathway, col list(Pathway brewer.pal(3, “Set2”) %% setNames(unique(gene_pathway))), simple_anno_size unit(4, “mm”), annotation_legend_param list(Pathway list(title “Gene Pathway”)) ) # 4. 构建圆形热图对象 ------------------------------------------------------ ht - Heatmap( expr_mat, name “Expression Z-score”, col col_fun, top_annotation column_ha, left_annotation row_ha, # 圆形布局核心参数 circular TRUE, gap unit(3, “mm”), start_degree 0, # 从3点钟方向开始 # 行列设置 show_row_names TRUE, show_column_names FALSE, row_names_side “outside”, row_names_gp gpar(fontsize 10, fontface “italic”), # 聚类与分割根据文献图决定 cluster_rows FALSE, cluster_columns FALSE, # row_split gene_pathway, # 如果需要按通路分割行 # column_split sample_group, # 如果需要按组分割列 # 图例设置 heatmap_legend_param list( title_position “topcenter”, legend_direction “horizontal”, title_gp gpar(fontsize 10), labels_gp gpar(fontsize 9) ) ) # 5. 绘制与保存 ------------------------------------------------------------ # 5.1 在RStudio中预览 draw(ht) # 5.2 保存为PDF用于投稿 pdf(“Literature_Style_Circular_Heatmap.pdf”, width 9, height 7) draw(ht, padding unit(c(2, 2, 2, 2), “cm”), # 增加边距 heatmap_legend_side “bottom”, annotation_legend_side “right”, merge_legend TRUE # 合并图例 ) dev.off() cat(“圆形热图已生成并保存为 PDF 文件。\n”)9. 常见问题与排查方法在复现过程中你几乎一定会遇到一些问题。下表列出了常见问题及其解决方案。问题现象可能原因排查方式解决方案安装BiocManager::install失败网络连接问题或R版本太旧。检查网络尝试ping mirrors.tuna.tsinghua.edu.cn。运行R.version查看版本。1. 设置国内镜像。2. 升级R到最新稳定版。3. 手动下载源码包安装。Error: could not find function “Heatmap”ComplexHeatmap包未成功加载。运行library(ComplexHeatmap)看是否有错误。重新安装包BiocManager::install(“ComplexHeatmap”, forceTRUE)。图形元素重叠、错位圆形布局下默认边距和位置不适用。检查padding,gap,start_degree参数。逐步调整padding绘图区域边距和gap扇区间隙的单位和数值。使用draw(ht, padding …)进行微调。颜色映射不符合预期colorRamp2的断点break与数据范围不匹配。用summary(c(expr_mat))查看数据实际范围。根据数据实际最小、中值、最大值调整colorRamp2的断点向量。例如数据范围是[-1, 5]则用c(-1, 2, 5)。注释条颜色/图例不正确注释因子水平与颜色映射向量名称不匹配。检查table(sample_group)和颜色向量names。确保颜色向量的名称与因子水平完全一致。使用names(your_color_vector) - levels(your_factor)。保存的PDF/PNG空白或只有部分图形设备未正确关闭或保存代码在draw()之前。确认代码顺序为1. 打开设备(pdf())。2. 绘制(draw())。3. 关闭设备(dev.off())。将绘图代码包裹在pdf(); draw(); dev.off()中。确保dev.off()被执行。圆形布局下聚类树显示异常圆形坐标与树状图矩形坐标冲突。尝试先绘制不带圆形的热图查看聚类树。对于圆形热图考虑1. 关闭聚类(cluster_* FALSE)。2. 使用dendextend包美化环形树并单独添加。3. 接受当前显示。字体在PDF中无法显示或乱码PDF设备未嵌入字体或使用了系统不支持的字体。在RStudio中预览正常但PDF异常。在pdf()中指定字体pdf(“file.pdf”, family“Arial”)。或使用showtext包加载自定义字体。图形渲染速度极慢数据矩阵过大行或列 2000。检查dim(expr_mat)。1. 在绘制前对数据降采样或筛选。2. 先保存为PDF矢量图可能很大或降低PNG分辨率。3. 关闭实时预览直接保存。10. 最佳实践与使用建议掌握工具后如何高效、专业地使用它以下是一些经验之谈。从简到繁迭代开发不要试图一步到位复现出完美的圆形热图。先从矩形热图开始确保数据、注释、颜色映射全部正确。然后添加circular TRUE参数再逐步调整布局和美学细节。代码模块化将数据准备、注释定义、热图构建、图形输出写成独立的函数或代码块。这样便于调试也方便应用到新的数据集。参数文档是你的朋友遇到不理解的参数随时使用?Heatmap或?HeatmapAnnotation查看官方文档。ComplexHeatmap的文档非常详尽并配有大量示例。保存中间结果在调整图形参数时每完成一个满意的步骤就将Heatmap对象保存为R数据文件saveRDS(ht, “heatmap_object.rds”)。这样如果后续调整失败可以快速回滚。版本控制使用Git管理你的绘图脚本。每次重大修改都做一次提交并写好注释。这能让你清晰地回溯每一次调整的效果。关注性能对于超大矩阵在正式绘制前先用子集例如前100行前50列测试代码和参数确认无误后再用全数据运行。这能节省大量等待时间。合规使用如果你复现的图形最终用于发表请务必遵守版权复现思路和方法是学习过程但直接使用文献中的图形作为你自己的成果是侵权行为。你的产出应基于自己的数据。注明灵感来源在论文的方法或图注中可以提及“热图绘制参考了[文献X]的可视化风格并使用ComplexHeatmap包实现”。数据隐私与安全确保你使用的数据是经过授权、脱敏的。特别是临床样本数据必须符合相关伦理和隐私规定。通过本文的步骤你应该已经能够将文献中那张令人印象深刻的圆形热图在自己的R环境中重现出来。更重要的是你获得了一套方法论如何解构一张复杂的热图如何用ComplexHeatmap的语法将其构建出来以及如何解决过程中遇到的各种问题。这套方法不仅适用于圆形热图也适用于任何你需要高度定制化可视化的场景。建议将本文的示例代码保存为模板在遇到新的复现任务时以此为起点进行修改和拓展。