STHD — 单点细胞类型解卷积
概述
STHD（Spatial Transcriptomics High Definition）是用于高分辨率空间转录组数据的概率机器学习方法，可在 2μm 级别生成每个 spot 的细胞类型标签和概率。STHD 特别适合 Visium HD、Stereo-seq 等高分辨率平台。
核心特性：
- 单点分辨率：可生成 2μm 级别的细胞类型标签（比 8µm Visium HD 更精细）
- 概率输出：输出每个 spot 的细胞类型概率分布
- 多平台支持：Visium HD、Visium、Stereo-seq 等
- Python 3.9-3.11：使用较新 Python 特性
- 交互式可视化：内置 Shiny/Tornado 应用支持交互分析
适用场景
当用户需要执行以下任务时使用此 Skill：
- 使用 STHD 对高分辨率空间转录组数据进行反卷积
- 生成 2μm 级别的细胞类型标签
- 处理 Visium HD、Visium、Stereo-seq 数据
- 需要概率性反卷积结果（而非点估计）
安装
参考 references/安装指南.md。
环境要求
- Python: 3.9 - 3.11（重要：STHD 依赖 pygam 等包，对 Python 版本敏感）
- 操作系统: Linux (推荐), Windows, macOS
安装步骤
python -m venv sthd_env
source sthd_env/bin/activate # Linux/Mac
# 或 Windows:
sthd_env\Scripts\activate
# 推荐使用 mamba/conda 管理依赖
conda install -c conda-forge pygam
pip install sthd
依赖
- scanpy, anndata, pandas, numpy, matplotlib
- pygam（条件分布拟合）
- jupyter（交互式可视化）
输入数据要求
| 数据 | 格式 | 说明 |
|---|---|---|
| scRNA-seq 表达矩阵 | AnnData (.h5ad) | 行=基因，列=细胞；obs 中需包含细胞类型注释列 |
| 空间表达数据 | AnnData (.h5ad) | Visium HD（8µm/16µm）或 Visium；obsm['spatial'] 含空间坐标 |
> 前置要求：输入数据为 AnnData (.h5ad) 格式，包含空间坐标和细胞类型注释。
完整脚本列表
| 脚本 | 说明 |
|---|---|
| scripts/run_sthd_workflow.py | STHD 完整工作流脚本（从参考数据准备到可视化） |
> STHD 官方推荐使用交互式 R Shiny 应用（STHD::run_shiny_STHD()），本 Skill 提供 Python 版命令行工作流。
推荐工作流
1. 运行 STHD 完整工作流
python scripts/run_sthd_workflow.py
工作流脚本包含以下步骤：
1. 准备参考数据（从 scRNA-seq 中提取细胞类型）
2. 训练 STHD 模型
3. 在空间数据上预测细胞类型
4. 生成可视化
2. 自定义参数调用
编辑 run_sthd_workflow.py，按需修改：
- sc_data_path：scRNA-seq 数据路径
- spatial_data_path：空间数据路径
- output_dir：输出目录
- 模型参数（如 n_neighbors、smooth_lambda 等）
3. R Shiny 交互式分析（推荐）
STHD 官方提供 R Shiny 应用，支持交互式分析：
# 在 R 中
install.packages("STHD")
STHD::run_shiny_STHD()
输出文件清单
数据文件
sthd_predictions.csv：每个 spot 的细胞类型概率sthd_cell_type_labels.csv：每个 spot 的最可能细胞类型sthd_model.pkl：训练好的 STHD 模型（可复用）
图形文件
cell_type_spatial.png：每种细胞类型的空间分布dominant_cell_types.png：主导细胞类型分布uncertainty_map.png：预测不确定性空间分布cell_type_probability_heatmap.png：细胞类型概率热图
STHD 与其他方法的区别
| 特性 | STHD | RCTD / cell2location / Tangram |
|---|---|---|
| 输出分辨率 | 2μm | spot 级（8µm/16µm） |
| 输出类型 | 概率分布 + 标签 | 比例矩阵 |
| 适用平台 | Visium HD、Stereo-seq | Visium / Visium HD |
| 速度 | 中等 | 取决于方法 |
| 概率信息 | ✅ | ❌（仅点估计） |
性能优化建议
| 场景 | 建议 |
|---|---|
| Visium HD（大数据集） | 降低 n_neighbors，使用 chunked_prediction |
| Stereo-seq（千万级 spot） | 分块预测，逐块保存结果 |
| 精度优先 | 增加 smooth_lambda 值 |
| 速度优先 | 减小 smooth_lambda，跳过平滑步骤 |
故障排除
参考 references/故障排除.md。常见问题：
Python 版本不兼容
错误：SyntaxError 或 TypeError 在导入 STHD 时
解决：STHD 仅支持 Python 3.9-3.11，更换 Python 版本。
pygam 安装失败
错误：pip install pygam 失败
解决：使用 conda 安装：conda install -c conda-forge pygam
内存不足
错误：MemoryError 在处理 Visium HD 全数据时
解决：
1. 分块预测（chunked prediction）
2. 降低分辨率（用 16µm 代替 8µm）
3. 使用更强内存机器
基因名不匹配
错误：训练时基因数过少
解决：确保 scRNA-seq 与空间数据的基因名使用同一来源（GENCODE/Ensembl 等）。
资源链接
- STHD 源码：github.com/songfd2018/STHD
- 论文：Song F, et al. Spatial Transcriptomics High Definition (STHD): A probabilistic machine learning method for cell type deconvolution at single-spot resolution. （请查阅 GitHub 获取最新引用）
许可证
遵循原作者的开源许可证（详见 GitHub 仓库）。
