OrgHeatmap入门教程

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

OrgHeatmap入门教程

1. 包简介

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.