> 作者 (author): LKP <kunpeng.liao@abiosciences.com>
> Skill 及脚本参数来源: Chen et al., 2025, Cancer Cell 43, 1656–1676, <https://doi.org/10.1016/j.ccell.2025.06.020>
TCR VDJ 重建与 Startrac 指数
Cell Ranger filtered_contig_annotations.csv.gz 逐细胞克隆重建 + Startrac 扩张/迁移指数手工实现（不依赖 immunarch/Startrac 包）。
1. 样本与 contig 过滤
# 样本名解析（Cell Ranger 目录名）：
# ^(GSM[0-9]+)_PA_([0-9]+)-(Tumor|Normal|PBMC)-VDJ_ → gsm/patient/tissue
# contig 严格过滤：
# is_cell == TRUE & high_confidence == TRUE & productive == TRUE
# 链 ∈ {TRA, TRB}；每细胞必须同时具备 TRA 与 TRB
# raw_clonotype_id 非空；barcode→多 clonotype 视为 ambiguous 剔除
keep <- dt[is_cell == TRUE & high_confidence == TRUE & productive == TRUE &
chain %in% c("TRA", "TRB") & raw_clonotype_id != ""]
valid <- keep[, .(chains = list(unique(chain))), by = barcode][
sapply(chains, function(x) all(c("TRA","TRB") %in% x))]$barcode
2. 跨组织 clonotype 定义（严格按原文）
# tcr_signature：每条链 "chain|v_gene|j_gene|cdr3|cdr3_nt" 拼接，链内排序去重
# 全局 clonotype_id = patient::canonical_cdr3s_nt
# 其中 cdr3s_nt 按 ";" 拆分→排序→去重→回拼
# 作用：同一患者 PBMC 与 Tumor 的相同配对序列可跨组织追踪
sig <- paste(chain, v_gene, j_gene, cdr3, cdr3_nt, sep = "|")
clonotype_id <- paste0(patient, "::",
sapply(strsplit(cdr3s_nt, ";"),
function(x) paste(sort(unique(x)), collapse = ";")))
3. 克隆大小分级
# n>=3（克隆型）/ n=2 / n=1（单个）
classify_clone_size <- function(n) if (n >= 3) "n>=3" else if (n == 2) "n=2" else "n=1"
4. Startrac 指数（手工公式）
# 扩张指数 expa（仅 Tumor 细胞克隆计数）：
# 1 - shannon_entropy / log2(n_clones)
startrac_expa <- function(clone_counts) {
p <- clone_counts / sum(clone_counts)
1 - (-sum(p * log2(p))) / log2(length(clone_counts))
}
# 迁移指数 pairwise_migr（如 PBMC↔Tumor）：
# Σ (clone_size / total) × clone_entropy
startrac_pairwise_migr <- function(cells, tissue1 = "PBMC", tissue2 = "Tumor") {
# 每个克隆：在两组织的细胞数的熵，按克隆大小加权求和
}
5. 分组分析（NI Low vs High）
# 分析域：tissue ∈ {PBMC, Tumor} 且 compartment ∈ {CD4T, CD8T}
# compartment 判定：grepl("^T0|^T1[01]", majorCluster) → CD4，否则 CD8
# 迁移指数口径（严格按作者）：先每位配对患者内逐 cluster 计算，NA 记 0，
# 再组内平均并求 sd
# 排名：frank(-expa) / frank(-migr)（ties.method="min"，按 NI 分组）
输出表约定
tcr_final_reconstructed.csv.gz：逐细胞（cell_id, patient, tissue, compartment, cluster, clonotype_id, clone_size, size_class…）vdj_startrac_group_indices.csv：expa/migr 按 NI 分组汇总vdj_startrac_patient_migration.csv：逐患者逐 cluster 迁移值
常见坑
- 必须 TRA+TRB 双链：单链细胞剔除，避免假克隆
- 跨组织追踪靠 canonical_cdr3s_nt：不要直接用 Cell Ranger 的 raw_clonotype_id（各样本独立编号）
- expa 只算 Tumor：扩张指数限定肿瘤内克隆计数
- NA 记 0 的口径：迁移指数组内聚合时先补 0 再平均，与作者脚本一致
- 对照论文值：作者报告 6,503 clonotype，复现时输出全量/扩增型(≥2)/克隆型(≥3)与论文值差
