1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | spatial-data-io-gptomics-bioskills |
| 项目自述名称 | SKILL.md front matter name 字段为 bio-spatial-transcriptomics-spatial-data-io；正文标题为 Spatial Data I/O |
| 作者/维护者 | GPTomics Organization |
| 来源链接 | https://github.com/GPTomics/bioSkills/tree/main/spatial-transcriptomics/spatial-data-io |
| 许可证 | MIT（数据来源：GitHub API，仓库级） |
| GitHub Stars / Forks | 所属合集仓库 bioSkills 整体 1,165 / 195（数据来源：GitHub API；⚠️ 为整个合集的数字，不代表本技能自身热度） |
| 最新版本 | 仓库整体最新 release 为 3.0（2026-02-14）；本子技能内容最近一次提交于 2026-07-10（数据来源：GitHub API commits，按该子目录路径查询） |
| 安装方式 | 复制 spatial-transcriptomics/spatial-data-io/ 整个目录（含 SKILL.md、examples/、usage-guide.md）到 agent 的 skills 目录，或用仓库自带安装脚本按分类批量安装 |
2. 功能介绍与亮点
- 核心功能：为空间转录组数据的九种主流平台（Visium、Visium HD、Xenium、MERFISH/MERSCOPE、CosMx、Slide-seq/Curio、Stereo-seq）选择正确的读取器，加载进 AnnData 或 SpatialData 对象
- 核心论点（“governing principle”）：成像/原位类平台（Xenium、MERSCOPE、CosMx）会产出两个物理上不同的主对象——逐分子的分子表（source of truth，可用于重新分割）与经分割派生的逐细胞矩阵（经质量过滤，继承一切分割误差）；测序/捕获类平台（Visium、Slide-seq、Stereo-seq）则完全没有分子表，一个 spot/bin 本身就是多细胞混合信号，不存在“缺失的分子表”可找
- 第二个陷阱：坐标系配准——图像、spot/细胞坐标、分子点各自处在自己的像素或阵列坐标系中，叠加组织学图像或以微米为半径构建邻居图前必须先确认并对齐坐标系（SpatialData 用显式的 intrinsic→global 变换，传统 AnnData 布局则把换算因子藏在
uns['spatial']里） - 完整的“平台→读取器”对照表，标注关键 I/O 细节（如
squidpy.read只覆盖 visium/vizgen/nanostring 三种、不存在merfish专用读取器需用merscope兼容处理 MERFISH 与 MERSCOPE、Visium HD 的tissue_positions是 PARQUET 而非 CSV、scanpy.read_visium已废弃） - 五种主流对象模型框架（SpatialData/scverse、Squidpy+AnnData、Seurat v5、SpatialExperiment/SFE-Voyager、Giotto Suite）横向对比表，覆盖 Python 与 R 生态
- 11 行症状-成因-修复常见错误对照表、9 篇文献引用（SpatialData、Squidpy、Scanpy、anndata、Seurat 等原始论文）
- 示例脚本
load_visium.py使用 Squidpy 内置 Visium H&E 演示数据集，无需用户数据即可运行，且不写入磁盘
3. 适用场景
所属分类：数据分析与可视化
面向刚拿到某个空间转录组平台原始输出（Space Ranger 目录、Xenium experiment 目录、MERSCOPE/CosMx 平面文件、Slide-seq/Stereo-seq 数据等）、需要选对读取器并确认是否保留了分子级检测记录的生物信息学分析者。典型场景：不确定某个平台该用 spatialdata_io 还是 squidpy.read；担心用错读取器只拿到派生的细胞矩阵而丢失可重新分割用的分子表；在叠加组织学图像或构建邻居图之前需要先确认坐标单位是像素还是微米。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库提供
install-claude.sh，标准 SKILL.md（YAML front matter + 指令正文）可直接安装 - Codex：原生支持——仓库同时提供
install-codex.sh - OpenClaw：原生支持——仓库提供专用
install-openclaw.sh，保留原始目录结构，也可直接从 ClawHub 安装 - Hermes Agent：需适配——Hermes 官方生物信息学技能网关页面按名列出该技能，但明确说明这类技能“不是 Hermes 格式的技能”，只作为参考材料被引用，非原生 Hermes 技能格式
5. 推荐理由
空间转录组分析里最容易出错、却最少被主动讨论的环节往往发生在最开始的加载步骤——选错读取器，或者把成像平台派生出的“细胞矩阵”误当作“分子表”来用，会让后续所有下游分析（反卷积、邻居图、空间域划分）都建立在残缺甚至错误的数据结构之上而分析者本人并不知情。该技能把“这个平台属于哪一类”“该用哪个读取器”“这批数据到底有没有分子表”这几个原本容易被跳过的判断显式化为加载阶段必须先回答的问题，并把坐标系配准这个容易被忽略的陷阱前置成一个确认步骤，帮助分析者在分析管线最上游就避免建立在一个悄悄错误的假设上。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 合集仓库整体约 1,165 stars 不代表本技能自身热度；LobeHub 独立市场页单独收录本技能（标识符 gptomics-bioskills-spatial-data-io，独立展示安装计数等字段），为技能级独立第三方证据 |
| 可用性 | 9 | 依赖为标准科学计算/生信包（pip install spatialdata spatialdata-io squidpy scanpy anndata），无付费依赖；文档完整含独立 usage-guide 与可运行示例脚本；最近一次提交为 2026-07-10 |
| 安全性 | 9 | 纯 Python 本地数据加载/格式转换代码，无 shell 越权；示例脚本仅调用 Squidpy 内置演示数据集加载函数，脚本注释明确说明不写入任何文件，不涉及用户数据外发或凭据需求；MIT 许可证明确；通读全文与示例脚本未见混淆逻辑或可疑指令 |
安全检查清单：①无 shell 命令执行，全部为标准 Python 库函数调用（读取本地文件、构建内存对象） ②示例脚本仅通过 Squidpy 内置数据集加载器获取公开演示数据，不涉及用户数据外发 ③无凭据或 API key 要求 ④通读 SKILL.md、usage-guide.md 与示例脚本未见可疑指令或混淆代码 ⑤GPTomics 为持续维护的组织账号，未见刷量或造假迹象 ⑥MIT 许可证清晰 ⑦最近一次提交 2026-07-10
7. 跟同类 Skills 相比的优势
| 维度 | 本技能（spatial-data-io） | spatial-preprocessing（同合集） | 直接查阅各工具官方文档 |
|---|---|---|---|
| 定位 | 覆盖“该用哪个平台读取器、这批数据有没有分子表”的加载阶段决策，是同合集下游分析技能的公共前置步骤 | 覆盖数据加载完成之后的 QC 阈值与归一化，是本技能的下游步骤，默认数据已被正确加载 | API 参数分别记录在 squidpy、spatialdata-io、scanpy 各自文档中，需要读者自行拼出跨平台全景 |
| 跨平台覆盖面 | 单份文档统一覆盖 9 种主流平台的读取器选型，并标注彼此之间的版本演进细节 | 不涉及平台间的读取器差异 | 每个工具的官方文档独立维护，版本更新节奏不同步，跨平台对比需要读者自己拼接 |
| 独有陷阱覆盖 | 分子表与派生细胞矩阵的物理区别、squidpy.read 覆盖不全需要切换到 spatialdata_io、Visium HD 用 PARQUET 而非 CSV 等版本迁移细节 |
不涉及读取器选型陷阱，聚焦已加载数据的质量控制 | 版本迁移细节（如 scanpy.read_visium 弃用）通常只出现在各自的 changelog 里，不会被主动整合提示 |
三者互补而非替代：spatial-data-io 解决“怎么把原始平台输出正确装进内存对象”这一起点问题，spatial-preprocessing 处理装载完成后的质控与归一化，直接查阅官方文档能获得最新最全的参数细节，但不会主动指出跨平台读取器选型与对象结构上的系统性陷阱。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；LobeHub 与 Hermes 官方网关均为收录性质的列表页，不构成使用评价。
9. 其他补充
无。
10. 安装使用方式
- 通用方式：克隆
GPTomics/bioSkills仓库后，复制spatial-transcriptomics/spatial-data-io/整个目录到目标 agent 的 skills 目录 - Claude Code：
./install-claude.sh --categories "spatial-transcriptomics"（或不带参数安装全部分类） - Codex：
./install-codex.sh --categories "spatial-transcriptomics" - OpenClaw：
./install-openclaw.sh --categories "spatial-transcriptomics"，或直接从 ClawHub 安装 - 安装后无需重启 agent；下次对话中用自然语言描述需求（如“帮我加载这份 Xenium 数据，并保留分子表”）即可触发
11. 注意事项
- 覆盖范围止于“加载与读取器选型”，不包含加载后的质控、归一化与下游统计分析（参见同合集内 spatial-preprocessing 等技能）
- 依赖的具体 Python 包（spatialdata、spatialdata-io、squidpy）版本迭代较快，文档已注明遇到 ImportError/AttributeError/TypeError 时应比对已安装版本的实际 API 而非直接重试
- 该子技能是同合集内多个下游分析技能（预处理、反卷积、邻居图、空间域划分等）的公共前置依赖，建议与这些技能配合安装使用