三元图

# ==============================================================================
# 三元图（Ternary plot）可复用模板 — 组间差异可视化
# 对应教程：公众号「Easy科研」三元图组间差异比较（纯肥瘦肉夹馍）
# 原文链接：https://mp.weixin.qq.com/s/_gHhC6Ct-RLryrAmQ7yoOQ
# ------------------------------------------------------------------------------
# 用途：将一群特征（微生物OTU/ASV/属、基因、代谢物、突变等）在三组间的
#       相对丰度/比例可视化。每个点 = 一个特征；离某角越近 = 在该组比例越高。
# 依赖包：ggtern（绘图）、microbiomeutilities::prep_ternary（physeq 数据转换）
# 输入（二选一）：
#   A. phyloseq 对象 + 分组变量（三组）→ prep_ternary() 转数据
#   B. 数据框：每行一个特征，含三列比例/丰度（三组各一列）→ 直接绘图
# 输出：ternary_plot.pdf / .png
# 知识库笔记：03 生信教程与工具库/02_wiki/tools/可视化与配色/
#             三元图-组间差异可视化.md
# ==============================================================================

## ----- 0. 安装/加载包 -----
# install.packages("ggtern")
# install.packages("microbiomeutilities")   # 若用 phyloseq 数据
# BiocManager::install("phyloseq")          # 若用 phyloseq 数据
library(ggtern)
library(ggplot2)
library(dplyr)

## ============================================================================
## 场景 A：phyloseq 对象（微生物组，推荐）
## 适用于：OTU/ASV/属水平丰度表 + 样本元数据，含三组分组
## ============================================================================
if (FALSE) {  # 示例：需要真实 phyloseq 对象，默认不运行
  library(phyloseq)
  library(microbiomeutilities)

  # p0 为 phyloseq 对象，group 分组变量必须有且恰好 3 个水平
  # 例：zackular2014（CRC/H/nonCRC 三组结直肠癌肠道菌群数据）
  # data("zackular2014"); p0 <- zackular2014

  tern_df <- prep_ternary(
    x           = p0,
    group       = "DiseaseState",   # 分组变量（3 组）
    abund.thres = 1e-4,             # 丰度阈值（过滤极低丰度）
    prev.thres  = 0.25,             # 检出率阈值（过滤样本中低频检出）
    level       = "Genus"           # 聚合水平（Genus/OTU 等）
  )
  # tern_df 包含列为三组相对丰度的数据框，可直接进入场景 B 绘图层
}

## ============================================================================
## 场景 B：数据框直接绘图（通用，推荐自备数据）
## 输入格式：每行一个特征，三列 = 三个组的相对丰度/比例（无需归一，自动处理）
## ============================================================================
# 示例数据结构（替换为自己的数据）：
#   feature  groupA  groupB  groupC  label    color
#   g1       0.35    0.45    0.20    enriched A   "#e45756"
#   g2       0.10    0.50    0.40    NA            "grey70"
demo_df <- data.frame(
  feature = paste0("f", 1:20),
  groupA  = runif(20, 0.05, 0.9),
  groupB  = runif(20, 0.05, 0.9),
  groupC  = runif(20, 0.05, 0.9),
  stringsAsFactors = FALSE
)
# 保证三点成比例（不必归一化，ggtern 自动按行归一，仅适用比例型数据）
# 若为计数/丰度，需先转比例：df[c("A","B","C")] <- sweep(df[c("A","B","C")], 1, rowSums(df[c("A","B","C")]), "/")

tern_theme <- theme_minimal(base_size = 10) +
  theme(
    panel.grid.minor = element_blank(),
    panel.grid.major = element_line(color = "grey90", linewidth = 0.3),
    axis.text = element_text(size = 8, color = "black")
  )

p_tern <- ggtern(data = demo_df, aes(x = groupA, y = groupB, z = groupC)) +
  geom_point(aes(color = feature), size = 2.2, alpha = 0.85) +
  scale_color_manual(values = colorRampPalette(c("#4575b4", "#ffffbf", "#d73027"))(20),
                     guide = "none") +
  # 三角标签（三个组名）—— 替换为真实组名
  labs(
    x = "Group A",
    y = "Group B",
    z = "Group C",
    title = "Ternary plot — 三组间特征分布比较"
  ) +
  tern_theme

# 保存
ggsave("ternary_plot.pdf", p_tern, width = 7, height = 6, bg = "white")
ggsave("ternary_plot.png", p_tern, width = 7, height = 6, dpi = 300, bg = "white")

## ============================================================================
## 进阶：标注显著富集特征（对应教程图中彩色圆点 + 文字标签）
## ============================================================================
if (FALSE) {
  # 假设用差异分析（如组间 t 检验 / DESeq2 / ALDEx2）筛选出显著特征后，
  # 在 demo_df 加 label 列，再叠加 geom_text 标注
  demo_df_label <- demo_df |>
    mutate(label = ifelse(feature %in% c("f1", "f5", "f12"), feature, ""))

  p_tern2 <- ggtern(data = demo_df_label, aes(x = groupA, y = groupB, z = groupC)) +
    geom_point(aes(color = feature), size = 2.2, alpha = 0.85) +
    geom_text(aes(label = label), size = 3, vjust = -0.8, color = "black") +
    scale_color_manual(values = colorRampPalette(c("#4575b4", "#ffffbf", "#d73027"))(20),
                       guide = "none") +
    labs(x = "Group A", y = "Group B", z = "Group C",
         title = "Ternary plot — 显著富集特征标注") +
    tern_theme
  ggsave("ternary_plot_labeled.png", p_tern2, width = 7, height = 6, dpi = 300, bg = "white")
}

## ============================================================================
## 关键提醒
## ============================================================================
# 1. 三元图只能展示 3 组；若组数 >3，先做组归并或选 3 个主要比较组。
# 2. 三元图是"比例/构成"可视化，缺统计检验信息。建议与箱线图/柱状图组合：
#    三元图看分布 + 箱线图/柱状图 + 显著性标记（Kruskal-Wallis 等）补检验。
# 3. 点的大小可映射平均丰度：aes(size = mean_abund)。
# 4. 若坐标出现负值报 "Negative coordinates"，检查数据是否已转比例且 >0。
# 5. 三元图与柱状图组合示例：
#    library(patchwork); p_tern + p_bar（柱状图带显著性）
# ==============================================================================