# OrgHeatmap入门教程

    library(OrgHeatmap)
    #> Loading required package: ggplot2

## 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`