Tangram — 深度学习空间反卷积（Visium HD）
概述
Tangram 是基于 PyTorch 的深度学习方法，将单细胞参考数据映射到空间 spot 上，通过余弦相似度学习每个 spot 的细胞类型组成。本 Skill 针对 Visium HD（8µm、16µm、Cellbin）三种分辨率优化。
核心特性：
- 多分辨率支持：Visium HD 8µm / 16µm / Cellbin
- 深度学习映射：基于余弦相似度 + PyTorch 优化
- 关键修正：tangram_ct_pred 必须按行归一化才是真实比例
- 完整可视化：从原始预测到归一化比例再到空间分布
- Cellbin 真实坐标：从 cell_segmentations.geojson 提取细胞中心
适用场景
当用户需要执行以下任务时使用此 Skill：
- 使用 Tangram 对 Visium HD 数据进行反卷积
- 在 8µm、16µm、Cellbin 三种分辨率间比较
- 处理 cellbin 单细胞分辨率数据
- 对 Tangram 的
tangram_ct_pred进行正确的归一化
安装
参考 references/安装指南.md。
环境要求
- Python: >= 3.7
- GPU: 推荐 NVIDIA GPU
- 操作系统: Linux (推荐), Windows, macOS
安装 tangram
pip install tangram-sc
安装依赖
pip install torch torchvision scanpy anndata pandas numpy matplotlib seaborn
输入数据要求
| 数据 | 格式 | 说明 |
|---|---|---|
| scRNA-seq 表达矩阵 | AnnData (.h5ad) / 10X mtx | 行=基因，列=细胞；obs 中需包含细胞类型注释列 |
| 空间表达数据（16µm/8µm） | 10X h5 格式 | binned_outputs/square_XXXum/ |
| 空间表达数据（Cellbin） | 10X h5 格式 | segmented_outputs/filtered_feature_cell_matrix.h5 |
| Cellbin 真实坐标（可选） | geojson | segmented_outputs/cell_segmentations.geojson |
配置说明
所有脚本顶部都包含统一配置区域：
# ========== 配置区域（请根据实际数据修改） ==========
USER_DATA_DIR = "your/data/directory" # 数据根目录
SC_FILENAME = "scRNA.h5ad" # 单细胞 h5ad 文件名
SPATIAL_SUBDIR = "binned_outputs/square_016um" # 空间数据子目录
SEGMENTED_SUBDIR = "segmented_outputs" # segmented_outputs 子目录
CELL_TYPE_COL = "cell_type" # scRNA-seq obs 中细胞类型列名
OUTPUT_DIR = "tangram_16um_results" # 输出目录
# =====================================================
路径兼容性
- Windows：
USER_DATA_DIR = "D:/your/data/dir" - WSL/Linux：
USER_DATA_DIR = "/mnt/d/your/data/dir"或"/home/user/data" - macOS：
USER_DATA_DIR = "/Users/yourname/data"
重要：Tangram 归一化修正
Tangram 的 tangram_ct_pred 不是概率分布！ 必须除以行总和进行归一化，使每行比例总和等于 1.0。
tangram_pred = adata.obsm["tangram_ct_pred"]
row_sums = tangram_pred.sum(axis=1)
prop_df = tangram_pred.div(row_sums, axis=0) # 归一化后才能用于分析
完整脚本列表
| 脚本 | 说明 |
|---|---|
| scripts/tangram_visium_hd_16um.py | Tangram 16µm 完整反卷积：训练 + 提取 + 归一化 + 可视化 |
| scripts/tangram_visium_hd_8um.py | Tangram 8µm 完整反卷积 |
| scripts/tangram_visium_hd_cellbin.py | Tangram Cellbin 完整反卷积（含真实坐标提取与匹配） |
| scripts/tangram_generate_all_plots.py | 全套可视化（前 N 种细胞类型热图、综合图、气泡图、对比图、统计图） |
| scripts/tangram_correct_analysis.py | Tangram 归一化修正工具：处理已训练结果的归一化（重要工具） |
推荐工作流
16µm 分辨率
# 1. 完整反卷积（训练 + 归一化 + 基础可视化）
python scripts/tangram_visium_hd_16um.py
# 2. 重新生成全套发表级可视化
python scripts/tangram_generate_all_plots.py
8µm 分辨率
python scripts/tangram_visium_hd_8um.py
python scripts/tangram_generate_all_plots.py
Cellbin 单细胞分辨率
# 1. 提取 Cellbin 真实坐标（如需要）
python scripts/extract_cellbin_coords.py extract \
--geojson data/segmented_outputs/cell_segmentations.geojson \
--output cellbin_coordinates.csv
# 2. 完整反卷积（含真实坐标匹配）
python scripts/tangram_visium_hd_cellbin.py
# 3. 归一化修正（如果之前漏了）
python scripts/tangram_correct_analysis.py
已训练结果的后处理
# 仅做归一化修正
python scripts/tangram_correct_analysis.py
输出文件清单
数据文件
tangram_16um_results/spatial_tangram.h5ad：16µm 反卷积结果tangram_8um_results/spatial_tangram.h5ad：8µm 反卷积结果tangram_cellbin_results/spatial_tangram.h5ad：Cellbin 反卷积结果tangram_*_correct.csv：归一化后的细胞类型比例
图形文件
tangram_top_cell_types.png/pdf：前 N 种细胞类型空间分布tangram_dominant_cell_types.png/pdf：主导细胞类型空间分布tangram_all_cell_types.png/pdf：所有细胞类型综合热图tangram_heatmap_*.png/pdf：单细胞类型热图tangram_all_cell_types_bubble.png/pdf：气泡图tangram_mean_proportions.png/pdf：平均比例条形图tangram_cell_type_correlation.png/pdf：相关性热图
故障排除
参考 references/故障排除.md。常见问题：
tangram_ct_pred不是概率：必须除以行总和进行归一化- CUDA 不匹配：重新安装与 CUDA 版本匹配的 PyTorch
- 内存不足：减小训练批次，使用
device='cpu'切换 - 基因数不匹配：确保 scRNA-seq 与空间数据基因名一致
资源链接
- Tangram 源码：github.com/broadinstitute/Tangram
- 论文：Biancalani T, et al. Deep learning and alignment of spatially resolved single-cell transcriptomes with Tangram. Nature Methods, 2021.
许可证
遵循原作者的开源许可证（详见 GitHub 仓库）。
