学习笔记：TCGAutils — TCGA 多组学数据处理完整教程

1. 安装与依赖

# 未安装 BiocManager 则先安装
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("TCGAutils")

配套依赖包（教程全程用到）：

library(TCGAutils)
library(curatedTCGAData)      # 一键下载标准化 TCGA 多组学 MAE 对象
library(MultiAssayExperiment) # 多组学统一存储/操作容器
library(RTCGAToolbox)         # Firehose 数据获取
library(rtracklayer)          # liftOver 基因组版本转换
library(R.utils)
library(GenomeInfoDb)

2. 七大功能模块速查表（Cheatsheet）

一、MultiAssayExperiment 多组学对象工具

二、curatedTCGAData 配套工具

三、TCGA 条码解析工具

四、Bioconductor 标准对象构建工具

五、基因组版本转换工具

六、内置参考数据集

七、其他工具

3. 核心实战流程

3.1 curatedTCGAData 配套工具

3.1.1 下载 MAE 对象（先预览，再下载）

预览：dry.run = TRUE 只列资源不下载，assays = "*" 查看该癌种全部可用组学：

curatedTCGAData("LIHC", "*", dry.run = TRUE, version = "2.1.1")

返回 13 个 assay 的资源表（ah_id / title / file_size / rdataclass / 添加日期），例如：

正式下载（CNV + GISTIC + 突变 + RNA + RPPA 五类组学）：

lihc <- curatedTCGAData(
    "LIHC",
    c("CN*", "GISTIC*", "Mutation", "RNASeq*", "RPPA*"),
    version = "2.1.1",
    dry.run = FALSE
)

3.1.2 LIHC 各 assay 数据类详解（为什么用不同的 R 对象）

数据类选择原则速记：
- SummarizedExperiment = 规整矩阵（行×列）
- RangedSummarizedExperiment = 规整矩阵 + 基因组坐标
- RaggedExperiment = 不规则区间数据（每样本区间数/长度不一）
- DFrame = 数据框（版本兼容产物）

3.1.3 sampleTables：统计各组学样本类型数量

sampleTables(lihc)

配合内置 sampleTypes 数据集解读样本编码：

data("sampleTypes")
head(sampleTypes)
## Code 定义           简写
## 01   实体原发肿瘤    TP
## 02   实体复发肿瘤    TR
## 03   外周血原发血液癌 TB
## 04   骨髓复发血液癌  TRBM
## 05   新增原发癌对照  TAP
## 06   转移肿瘤        TM

3.1.4 TCGAsplitAssays：按样本类型拆分组学 + 配对样本

TCGA 常把肿瘤/癌旁/转移混合存储，按样本编码拆分（如 "01" 肿瘤、"11" 癌旁）：

(tnmae <- TCGAsplitAssays(lihc, c("01", "11")))

⚠️ 拆分后才可 mergeReplicates 合并同一患者重复样本；拆分前直接合并会平均肿瘤与正常样本数值。

MatchedAssayExperiment 配对样本对象——筛选所有组学均存在的匹配样本（肿瘤-癌旁配对）：

(matchmae <- as(tnmae[, , c(4, 6, 7)], "MatchedAssayExperiment"))

3.1.5 getSubtypeMap / getClinicalNames

# 提取人工注释分子亚型（TCGA 原始论文补充材料整理；LIHC 无亚群数据时返回空）
getSubtypeMap(lihc)

# 提取各癌种通用的 4 级标准化临床变量（生存、分期、年龄等）
getClinicalNames("LIHC")

# 注意部分变量类型：vital_status 是 integer，0=存活 1=死亡
class(colData(lihc)[["vital_status"]])  # integer
table(colData(lihc)[["vital_status"]])  # 0=存活 1=死亡

3.2 组学对象转为基因组标准 SE/RSE

3.2.1 CpGtoRanges：甲基化探针转基因组区间

依托 minfi 包的 Illumina 甲基化芯片注释，27k/450k 探针 → GRanges，返回可映射/不可映射两套数据：

methlihc <- CpGtoRanges(lihc)

3.2.2 qreduceTCGA：突变 RaggedExperiment → RangedSummarizedExperiment（含 liftOver）

基于 Variant_Classification 区分沉默/非同义突变，汇总到基因区间。必须先完成基因组版本 liftOver（hg18 → hg19）：

rag <- "LIHC_Mutation-20160128"

# ① 设置原始基因组版本 hg18 (NCBI36)，染色体命名转 UCSC 格式 (chr1)
genome(lihc[[rag]]) <- "NCBI36"
seqlevelsStyle(rowRanges(lihc[[rag]])) <- "UCSC"
seqlevels(rowRanges(lihc[[rag]]))
genome(rowRanges(lihc[[rag]]))

# ② 从 AnnotationHub 获取 hg18 → hg19 链文件，坐标映射
library(AnnotationHub)
ah <- AnnotationHub()
chain <- ah[["AH14220"]]
ranges19 <- rtracklayer::liftOver(rowRanges(lihc[[rag]]), chain)   # 原文此处为 coad，系笔误

# ③ 过滤无匹配区间，替换原突变对象坐标
re19 <- lihc[[rag]][as.logical(lengths(ranges19))]
ranges19 <- unlist(ranges19)
genome(ranges19) <- "hg19"
rowRanges(re19) <- ranges19

# ④ 写回 MAE 对象
lihc[["LIHC_Mutation-20160128"]] <- re19
rowRanges(re19)

# ⑤ 版本统一后运行 qreduceTCGA
lihc <- qreduceTCGA(lihc, keep.assay = TRUE)

3.2.3 symbolsToRanges：基因名转基因组区间

mRNA、miRNA 矩阵基因符号批量转换 hg19 基因组区间，生成 RangedSummarizedExperiment：

symbolsToRanges(lihc)

3.3 本地 TCGA 文本文件导入 Bioconductor 对象

3.3.1 makeGRangesListFromExonFiles：外显子定量文件 → GRangesList

适配 Windows 超长文件名问题；示例包内置外显子定量文件：

pkgDir <- system.file("extdata", package = "TCGAutils", mustWork = TRUE)
exonFile <- list.files(pkgDir, pattern = "cation\\.txt$", full.names = TRUE)
# 拼接文件 UUID 前缀，不自动解析条码（GDC 旧版 API 已不支持旧文件名查询 UUID）
filePrefix <- "unc.edu.32741f9a-9fec-441f-96b4-e504e62c5362.1755371."
makeGRangesListFromExonFiles(exonFile, getBarcodes = FALSE,
  fileNames = paste0(filePrefix, basename(exonFile)))

3.3.2 makeGRangesListFromCopyNumber：拷贝数文件 → GRangesList

读取 GDC 下载的 CNV 分段文件，按样本分组：

grlFile <- system.file("extdata", "blca_cnaseq.txt", package = "TCGAutils")
grl <- read.table(grlFile)
# 基础版本，仅保留坐标
makeGRangesListFromCopyNumber(grl, split.field = "Sample")
# 保留 Segment_Mean 等数值信息
makeGRangesListFromCopyNumber(grl, split.field = "Sample", keep.extra.columns = TRUE)

3.3.3 makeSummarizedExperimentFromGISTIC：GISTIC 结果 → SE

转换 RTCGAToolbox 导出的 FirehoseGISTIC 对象，获取扩增缺失峰、基因阈值数据：

tempDIR <- tempdir()
co <- getFirehoseData("COAD", clinical = FALSE, GISTIC = TRUE, destdir = tempDIR)
gisticObj <- selectType(co, "GISTIC")
makeSummarizedExperimentFromGISTIC(gisticObj, "Peaks")

3.3.4 mergeColData：扩充 MAE 临床元数据

将外部患者信息表格合并进 MAE 的 colData：

race_df <- DataFrame(race_f = factor(colData(coad)[["race"]]),
                     row.names = rownames(colData(coad)))
coad <- mergeColData(coad, race_df)

3.4 TCGA 标识符转换与解析

3.4.1 GDC 版本说明 + UUIDhistory

GDC v32.0 后淘汰旧 UUID 文件，旧标识符需通过 UUIDhistory 查询新版本 UUID；/legacy 旧数据接口已废弃。

UUIDhistory("0001801b-54b-4551-8d7a-d66fb59429bf")
## uuid            版本 文件状态   发布日期    数据版本
## 0001801b-54b... 1    superseded 2018-08-23 12.0
## b4bce3ff-7fd... 2    released  2022-03-29 32.0

3.4.2 条码 ↔ UUID 双向转换

# 取 COAD_CNASeq assay 的前 4 个样本条码作为演示
xbarcode <- head(colnames(coad[["COAD_CNASeq-20160128_simplified"]]), 4)

# 条码 → UUID
barcodeToUUID(xbarcode)

# 病例 UUID → TCGA 患者 ID（case_id / file_id / aliquot_ids 三种来源类型）
UUIDtoBarcode("ae55b2d3-62a1-419e-9f9a-5ddfac356db4", from_type = "case_id")
UUIDtoBarcode("b4bce3ff-7fdc-4849-880b-56f2b348ceac", from_type = "file_id")
UUIDtoBarcode("d85d8a17-8aea-49d3-8a03-8f13141c163b", from_type = "aliquot_ids")

# UUID 互转（病例 ↔ 文件，一对多：一个病例对应多个测序文件 UUID）
head(UUIDtoUUID("ae55b2d3-62a1-419e-9f9a-5ddfac356db4", to_type = "file_id"))

3.4.3 条码拆解 / 样本筛选 / 一键原发肿瘤 / 条码表格化

```r

TCGAbarcode：分离患者 ID、样本类型、等分产物等分段信息

TCGAbarcode(xbarcode, participant = TRUE) # 仅患者 ID
TCGAbarcode(xbarcode, participant = FALSE, sample = TRUE) # 仅样本编码 (01/10)
TCGAbarcode(xbarcode, participant = TRUE, sample = TRUE) # 患者 + 样本
TCGAbarcode(xbarcode, participant = TRUE, sample = TRUE, portion = TRUE) # 完整分段

TCGAsampleSelect：逻辑向量批量筛选样本类型

TCGAsampleSelect(xbarcode, "01") # 原发肿瘤
TCGAsampleSelect(xbarcode, "10") # 血液正常对照

一键提取全部原发肿瘤 MAE

primaryTumors <- TCGAprimaryTumors(lihc)
sampleTables(primaryTumors)

TCGAbiospec：条码各分段信息转

4. 💡 核心可复用模式

套路一：配对样本（肿瘤-癌旁）标准工作流

mae <- curatedTCGAData("癌种", c("组学通配符"), dry.run = FALSE)
tnmae  <- TCGAsplitAssays(mae, c("01", "11"))     # 按样本类型拆分
tnmae  <- mergeReplicates(tnmae)                  # 合并同患者重复样本（拆分后！）
matched <- as(tnmae[, , c(assay索引)], "MatchedAssayExperiment")  # 全组学配对样本

套路二：突变数据标准化（Ragged → RSE）

genome(obj[[rag]]) <- "NCBI36"; seqlevelsStyle(...) <- "UCSC"   # 定版本
ranges19 <- liftOver(rowRanges(...), ah[["AH14220"]])           # hg18→hg19
# 过滤无匹配 → 替换 rowRanges → 写回 MAE
lihc <- qreduceTCGA(lihc, keep.assay = TRUE)

套路三：标识符互转（遇到"条码对不上"先查这个）

TCGAbarcode(barcode, participant = TRUE, sample = TRUE, portion = TRUE)  # 拆条码
barcodeToUUID(barcode) / UUIDtoBarcode(uuid, from_type = "case_id|file_id|aliquot_ids")
UUIDhistory(uuid)   # 旧 UUID 查新版本（GDC v32.0 后）

套路四：一键提取原发肿瘤 + 临床变量

tumors <- TCGAprimaryTumors(mae)
getClinicalNames("癌种")    # 找标准临床变量名
mergeColData(mae, extra_df) # 追加外部临床/分组信息

5. 关键技术包清单

6. 备忘

• 教程中 coad 变量在 qreduceTCGA / oncoPrintTCGA / mergeColData 示例中出现但未在教程内定义，整理时保留并注释；实际使用时替换为自己的 MAE 对象名。
• 速查表"TCGAbiopsec"为原文拼写，实际函数名为 TCGAbiospec。
• 甲基化 assay 巨大（1.28 GB），用 HDF5 后端按需读取，勿整体载入内存。