OrgHeatmap入门教程

2. 安装与数据准备

2.1 安装包

# 从本地安装（替换为你的包文件路径）
install.packages("OrgHeatmap_0.1.0.tar.gz", repos = NULL, type = "source")

# 若已上传到GitHub，可从仓库安装
# devtools::install_github("你的用户名/OrgHeatmap")

# 如果未安装devtools，请先执行：
# install.packages("devtools")

# 安装依赖包（若运行时提示缺失）
install.packages(c("ggpolypath", "patchwork", "dplyr", "stringdist", "ggplot2"))

2.2 加载示例数据

包内置了示例数据，方便快速上手：

# 加载示例数据
data(example_Data3, package = "OrgHeatmap")

# 验证数据是否加载成功
if (!exists("example_Data3")) {
  stop("示例数据加载失败，请检查包是否正确安装。")
}

# 查看数据结构（第一列是器官名称，第二列是数值）
head(example_Data3)

##           organ value
##10   lymph_nodes 0.029
##9           lung 0.041
##5         uterus 0.026
##17 adrenal_gland 0.014
##25        tongue 0.038
##18       stomach 0.050

3. 基础可视化

3.1 简单绘制器官图

使用核心函数OrgHeatmap()，传入数据即可生成基础可视化结果：

# 基础可视化（使用默认参数）
result <- OrgHeatmap(data = example_Data3)
# 显示图形
print(result$plot)

3.2 理解输出结果

函数返回一个列表，包含可视化结果和处理后的数据：

# 查看返回结果的结构
names(result)

## [1] "plot"         "clean_data"   "system_used"  "mapped_organs"
## [5] "missing_organs" "total_value"

关键元素说明： - plot：可视化图表（ggplot2对象，可直接打印） - clean_data：清洗后的数据集（器官名称标准化+数值处理） - missing_organs：没有坐标数据的器官（无法可视化的名称） - total_value：所有器官数值的总和

4. 核心功能详解

4.1 按器官系统过滤

用system参数指定要显示的器官系统（如循环系统、呼吸系统）：

# 只显示循环系统器官
circulatory_plot <- OrgHeatmap(
  data = example_Data3,
  system = "circulatory",  # 指定循环系统
  title = "循环系统数据可视化"  # 自定义标题
)

# 查看所有支持的器官系统
unique(organ_systems$system)

4.2 自定义颜色方案

通过以下参数调整颜色： - fillcolor_organ：器官的颜色方案（支持”plasma”、“viridis”等） - fillcolor_outline：人体轮廓的填充色 - direction：颜色梯度方向（1=默认，-1=反转）

# 自定义颜色示例
custom_color_plot <- OrgHeatmap(
  data = example_Data3,
  fillcolor_organ = "viridis",    # 使用viridis配色
  fillcolor_outline = "#E6F7FF",  # 浅蓝色轮廓
  direction = -1,                 # 反转颜色梯度
  title = "自定义颜色方案"
)

4.3 添加定量条形图

设置organbar = TRUE可在右侧添加条形图，方便数值对比：

# 带条形图的可视化
bar_plot <- OrgHeatmap(
  data = example_Data3,
  organbar = TRUE,               # 启用条形图
  organbar_title = "数值大小",    # 条形图图例标题
  organbar_digit = 1,            # 数值保留1位小数
  title = "带条形图的器官数据展示"
)

4.4 器官名称映射（处理非标准名称）

如果数据中的器官名称不规范（如”Heart Tissue”），可通过organ_name_mapping映射到标准名称：

# 定义名称映射规则
name_mapping <- c(
  "Heart Tissue" = "heart",    # "Heart Tissue"映射为"heart"
  "Liver Cells" = "liver",     # "Liver Cells"映射为"liver"
  "Brain Region" = "brain"     # "Brain Region"映射为"brain"
)

# 应用映射
mapped_plot <- OrgHeatmap(
  data = data.frame(
    organ = c("Heart Tissue", "Liver Cells", "Brain Region"),
    value = c(12, 18, 9)
  ),
  organ_name_mapping = name_mapping,
  title = "器官名称映射示例"
)

4.5 数据聚合（处理重复器官）

当数据中存在重复器官（如多个”heart”条目），用aggregate_method指定聚合方式：

# 对重复器官进行均值聚合
aggregated_plot <- OrgHeatmap(
  data = data.frame(
    organ = c("heart", "heart", "liver"),  # 重复的"heart"
    value = c(10, 20, 15)
  ),
  aggregate_method = "mean",  # 可选："mean"（均值）、"sum"（求和）、"count"（计数）
  title = "重复器官数据聚合（均值）"
)

# 查看聚合结果
aggregated_plot$clean_data

##   organ value
## 1 heart    15  # 两个heart的均值：(10+20)/2=15
## 2 liver    15

4.6 显示所有器官轮廓

设置showall = TRUE可显示所有器官的灰色轮廓，突出目标器官：

OrgHeatmap(
  data = example_Data3,
  showall = TRUE,  # 显示所有器官轮廓
  title = "显示所有器官轮廓的可视化"
)

5. 常见问题解决

5.1 警告：“The following organs have no coordinate data”

原因：部分器官名称在包中没有对应的坐标数据（无法可视化）。
解决：
1. 检查器官名称是否正确（参考unique(organ_systems$organ)中的标准名称）。
2. 用valid_organs参数过滤无效器官：
```
valid_plot <- OrgHeatmap(
  data = example_Data3,
  valid_organs = c("heart", "liver", "brain")  # 只保留这三个器官
)
```

5.2 条形图不显示

原因：数据中没有有效器官，或organbar参数未开启。
解决：确保organbar = TRUE且处理后的clean_data不为空。

5.3 模糊匹配警告

解决：

install.packages("stringdist")  # 安装模糊匹配所需的包

6. 总结

OrgHeatmap简化了人体器官数据的可视化，核心功能对应的参数如下：

功能	关键参数
器官系统过滤	`system`
颜色自定义	`fillcolor_organ`、`direction`
条形图配置	`organbar`、`organbar_digit`
名称标准化	`organ_name_mapping`
数据聚合	`aggregate_method`

查看完整参数说明：?OrgHeatmap