1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | spatial-deconvolution-gptomics-bioskills |
| 项目自述名称 | Spatial Deconvolution（SKILL.md 内部标题；front matter name 字段为 bio-spatial-transcriptomics-spatial-deconvolution） |
| 作者/维护者 | GPTomics Organization |
| 来源链接 | https://github.com/GPTomics/bioSkills/tree/main/spatial-transcriptomics/spatial-deconvolution |
| 许可证 | MIT（数据来源：GitHub API，仓库级） |
| GitHub Stars / Forks | 所属合集仓库 bioSkills 整体 1,162 / 195（数据来源：GitHub API；⚠️ 为整个合集的数字，不代表本技能自身热度） |
| 最新版本 | 仓库整体最新 release 为 3.0（2026-02-14）；本子技能内容最近一次提交于 2026-06-28（数据来源：GitHub API commits，按该子目录路径查询） |
| 安装方式 | 复制 spatial-transcriptomics/spatial-deconvolution/ 整个目录（含 SKILL.md、examples/、usage-guide.md）到 agent 的 skills 目录，或用仓库自带安装脚本按分类批量安装 |
2. 功能介绍与亮点
- 从带注释的 scRNA-seq 参考出发，估算 Visium、GeoMx、Stereo-seq 等空间转录组混合捕获单元中每个 spot 的细胞类型组成，覆盖 cell2location（绝对丰度）、RCTD、SPOTlight、stereoscope、SpatialDWLS、CARD、Tangram（比例）与无参考的 STdeconvolve 共 8 种方法
- 核心决策框架“分辨率分岔”（resolution fork）：先判断平台捕获单元本身是否是多细胞混合物——Visium 55μm spot、GeoMx ROI 属混合物需要反卷积；Xenium、MERFISH、CosMx 已是单细胞分辨率，此时反卷积在概念上是错的（会在纯细胞内部凭空捏造出并不存在的细胞比例），该做的是分割与标注；Visium HD、Stereo-seq、Slide-seqV2 处于模糊过渡带，需按是否有配准图像具体判断
- 强调“参考质量比方法选择更决定结果”：引用 Sang-Aram 2024 eLife、Li 2022 Nat Methods 等基准研究说明，参考中缺失的细胞类型会被静默错配到最近邻类型且没有任何报错提示，纯 NNLS 基线方法在近半数场景下反而跑赢专用方法
- 含 cell2location 两步完整 Python 代码（参考特征训练 + 空间映射）、STdeconvolve 无参考 R 代码、CLR 组成型数据转换代码、marker 基因交叉验证代码
- 附带可直接运行的
examples/deconvolve_spatial.py（用合成数据端到端跑通 cell2location 全流程，运行完自动清理临时产物）与独立usage-guide.md；SKILL.md 内含“Common Errors”症状-成因-修复对照表（如误传对数标准化数据而非原始计数导致报错、use_gpu参数在新版 scvi-tools 中已弃用等）
3. 适用场景
所属分类：数据分析与可视化
面向处理空间转录组数据、需要先判断“这份数据到底要不要反卷积”再据此估算每个 spot 或区域细胞类型组成的生物信息学分析者。典型场景包括：Visium/GeoMx 混合捕获数据的细胞组成解析、肿瘤微环境中免疫细胞浸润比例估算、识别 Xenium/MERFISH 等单细胞分辨率数据不应误用反卷积而应转向分割标注、以及缺少匹配 scRNA-seq 参考时的无参考探索性反卷积。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库提供
install-claude.sh，标准 SKILL.md（YAML front matter + 指令正文）可直接安装 - Codex：原生支持——仓库同时提供
install-codex.sh - OpenClaw：原生支持——仓库提供专用
install-openclaw.sh，保留原始目录结构 - Hermes Agent：需适配——Hermes 官方文档的生物信息学技能网关页面把 bioSkills 列为 385 个参考技能来源之一，并按名列出
spatial-deconvolution，但明确说明这类技能“不是 Hermes 格式的技能”，只作为专家领域参考指南（含正确参数与代码模式，非可直接执行的流水线）被引用，而非以原生 Hermes 技能格式安装
5. 推荐理由
反卷积是空间转录组分析中最容易踩错的一步——同一份数据，如果在“要不要反卷积”这道分岔上判断错误，后续所有分析都建立在概念错误之上。该技能把这道判断框架化，并把“参考质量决定结果”这条容易被忽视的原则、8 种方法的选型依据、以及常见报错的症状-成因-修复对照表打包成可直接调用的方法论，帮助 agent 在拿到空间数据的第一步就走对方向，而不是套用一个视觉上合理、实则概念错误的流程。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 所属合集仓库整体约 1,162 stars 不代表本技能自身热度；LobeHub 独立市场页单独收录本技能，Hermes Agent 官方生物信息学技能网关按名列出该技能，均为技能级独立第三方证据 |
| 可用性 | 9 | pip install cell2location（或 R 方案 BiocManager::install）一条命令即可装好，无付费依赖；SKILL.md + usage-guide.md + 可直接运行示例脚本 + Common Errors 对照表文档齐全；本子技能内容最近一次提交为 2026-06-28，在近 3 个月维护窗口内 |
| 安全性 | 9 | 纯 Python/R 本地分析代码，无 shell 越权执行，无网络外发，无需 API key 或凭据；MIT 许可证明确；通读全文与示例脚本未见混淆逻辑或可疑指令 |
安全检查清单：①无 shell 命令执行，内容为标准科学计算库调用与本地数据处理代码 ②不联网外发数据，全部计算在本地完成 ③无凭据或 API key 要求 ④SKILL.md 与示例脚本经通读未见可疑指令 ⑤GPTomics 为持续维护该开源合集的组织账号，未见刷星等造假迹象 ⑥MIT 许可证清晰 ⑦最近一次提交为 2026-06-28
7. 跟同类 Skills 相比的优势
| 维度 | 本技能（spatial-deconvolution） | image-analysis（同合集） | spatial-preprocessing（同合集） |
|---|---|---|---|
| 定位 | 判断是否需要反卷积并执行反卷积估算细胞组成，覆盖 8 种方法选型 | 处理已是单细胞分辨率的成像平台数据（Xenium/MERFISH/CosMx），做细胞分割与图像特征提取，是反卷积的替代路径而非重叠 | 空间转录组数据的质控、过滤与标准化，是反卷积之前的上游预处理步骤 |
| 核心价值 | 分辨率分岔判断框架、参考质量优先原则、跨方法选型对比、常见报错对照表 | 分割策略选型（核扩张 vs 全细胞膜染色 vs 转录本感知分割）与转录本溢出风险判断 | QC 阈值设定（避免用 scRNA 的计数下限误删成像平台的低表达真实细胞）、是否该标准化的判断 |
| 适用数据类型 | Visium/GeoMx 等多细胞混合捕获平台为主 | Xenium/MERFISH/CosMx 等单细胞分辨率成像平台 | 覆盖全部平台，服务于反卷积、分割等下游步骤之前 |
三者在 SKILL.md 的“Related Skills”章节互相交叉引用，分工覆盖空间转录组分析流水线的不同阶段，属互补而非重叠关系。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；LobeHub 与 Hermes Agent 官方网关均为收录/索引性质的列表页，不构成使用评价。
9. 其他补充
SKILL.md 的“Related Skills”章节交叉引用同合集内的 spatial-domains（区域检测，与细胞类型概念不同）、high-resolution-binning（Visium HD/Stereo-seq 等模糊过渡带的处理）、single-cell/cell-annotation（成像平台分割后细胞的标注）、single-cell/preprocessing（构建反卷积所需的干净参考）、spatial-preprocessing（反卷积前的 QC 与标准化）与 spatial-visualization（把反卷积结果映射回组织图像），可见本技能在合集内承担“混合捕获平台细胞组成解析”这一专项角色。
10. 安装使用方式
- 从 GitHub 下载或克隆仓库子目录：
spatial-transcriptomics/spatial-deconvolution/ - 复制整个目录（含
SKILL.md、examples/、usage-guide.md）到所用 agent 的 skills 目录（如 Claude Code 的~/.claude/skills/或项目内.claude/skills/）；也可克隆整个仓库后用./install-claude.sh --categories "spatial-transcriptomics"批量安装同分类下全部技能 - 安装依赖：Python 用户执行
pip install cell2location（或pip install tangram-sc）；R 用户执行BiocManager::install(c('spacexr', 'SPOTlight', 'STdeconvolve')) - 无需重启 agent，安装后下次对话即可通过自然语言描述需求触发（如“用 cell2location 反卷积我的 Visium 数据，给出每个 spot 的绝对细胞丰度”）
11. 注意事项
- 分辨率分岔是前置判断：Xenium/MERFISH/CosMx 等单细胞分辨率成像平台数据不应做反卷积，误用会在纯细胞内部捏造出并不存在的细胞比例，应转向分割与标注
- 参考不是中立输入：参考中缺失或与目标组织/病理状态不匹配的细胞类型会被静默错配到最近邻类型，且没有任何报错提示，结果仍会“看起来干净”但实际是错的
- cell2location 训练默认建议 GPU，虽支持
accelerator='cpu'但在大型图谱上会明显变慢 - 输出为组成型数据（各细胞类型比例和为 1），下游比较须用 CLR/ILR 等组成型统计方法，直接对原始比例做逐类型 t 检验在统计上是错误的
- 仓库为社区维护的生物信息学技能合集，非任何厂商官方出品，选用前建议自行核对示例代码与当前环境包版本是否匹配