Bulk–scRNA 一致性分析 Wanner122333/dsh-bulk-scrna-concordance

Bulk–scRNA 一致性比较

把 bulk RNA-seq 表达量与单细胞 RNA-seq 的组级伪 bulk 图谱做对比。提供三种用法：DSH Host 插件、Python 命令行、MCP 服务器（供 Claude、ChatGPT 及其他 MCP 客户端使用）。

工具输出 Pearson 与 Spearman 相关系数、线性回归、可选的组匹配诊断，以及图表。每次运行都会记录参数、输入/输出哈希和包版本。

输入与分析

- 单细胞原始计数：.h5ad，或基因 × 细胞的 CSV 加细胞元数据。
- Bulk 表达量：基因 × 样本的 CSV/TSV。
- 每个细胞要有组标签；bulk 样本名必须包含对应组名，且组名作为独立分隔 token 精确匹配。

按组对细胞求和，再按组对 bulk 样本取平均。默认归一化为 CPM，再做 log2(x+1)。回归和图表以 bulk 为 x、伪 bulk 为 y，使用相同的基因和变换。

对 .h5ad，默认计数来源是 layers['counts']（若存在），否则用 X。用 --sc-layer <name> 选择层，或用 --sc-use-raw 显式选择 raw.X。基因元数据跟随所选矩阵。所有单细胞输入都必须含原始计数：非有限值、负值、非整数值一律拒绝。这些检查无法证明整数值数据未经变换；运行前请确认数据来源。

这是描述性比较。按组汇总并不能估计生物学重复间的变异。可选的匹配–错配相关性差距能提示意外匹配，但不能证明生物学一致。

参数、归一化和限制见 docs/usage.md。

环境要求

Python 及 numpy、pandas、scipy、matplotlib；.h5ad 输入还需 anndata 和 h5py。

python -m pip install -r requirements.txt

真实数据示例：人 iPSC（GSE77288）

本示例比较三位供体的 bulk 与单细胞读数，两者独立测得，来自 Tung et al. (2017)，数据编号 GSE77288。使用作者提供的 564 个通过 QC 的细胞和八个匹配的 bulk 文库。QC 列表排除了所有 NA19098.r2 细胞，因此该批次的 bulk 文库也一并排除。两份输入都用未变换的读数；92 个 ERCC spike-in 列已移除。

三位真实 iPSC 供体的 bulk 与单细胞表达一致性

| 供体 | 细胞数 | Bulk 文库数 | 使用基因数 | Pearson r | Spearman ρ |
| NA19098 | 142 | 2 | 15,844 | 0.966628 | 0.963411 |
| NA19101 | 201 | 3 | 16,440 | 0.968652 | 0.967269 |
| NA19239 | 221 | 3 | 16,247 | 0.972792 | 0.970065 |

图中使用默认共享坐标轴、六边形基因密度分箱、对数基因计数色条、网格线、回归线和各面板统计量。参考运行使用的分析提交为 7478bde。
原始计数与相关性/回归结果已分别独立核验。

PDF · SVG ·统计 CSV ·跨供体相关性 ·结果、参数与源码哈希

在仓库根目录下，准备公开输入数据并运行同一套分析：

python examples/gse77288/prepare.py --out-dir results/gse77288/input-data
python python/bulk_scrna_concordance.py \
--sc-h5ad results/gse77288/input-data/sc_read_counts.h5ad \
--bulk-csv results/gse77288/input-data/bulk_read_counts.csv \
--group-col individual --gene-id-key var_names --discriminability \
--out-dir results/gse77288 --out-prefix GSE77288_real \
--results-json results/gse77288/GSE77288_real_results.json

准备脚本会下载约 13 MB 的压缩计数和样本注释，校验固定的 SHA-256 哈希，并写出原始计数输入与来源信息。后续运行时，它会复用已校验的缓存下载。底层计数从公开来源下载，不随仓库打包。过滤、缓存与参考环境的说明见示例说明。三个供体都是 iPSC：这些按基因计算的相关性描述的是表达一致性，不代表生物学重复推断，也不代表通用分类准确率。统计 CSV 中 Pearson p 值下溢为零，图中显示为 p < 1e-300。

命令行

运行自带的合成测试数据：

python python/bulk_scrna_concordance.py \
--sc-matrix-csv examples/synthetic/sc_expr.csv \
--sc-meta-csv examples/synthetic/sc_meta.csv \
--bulk-csv examples/synthetic/bulk.csv \
--group-col Group --discriminability \
--out-dir results --out-prefix example \
--results-json results/example_results.json

处理真实 .h5ad 数据：

python python/bulk_scrna_concordance.py \
--sc-h5ad /path/to/counts.h5ad --sc-layer counts \
--bulk-csv /path/to/bulk.csv --group-col Group \
--out-dir results --out-prefix my_run \
--results-json results/my_run_results.json

DSH 插件

克隆仓库：

git clone https://github.com/Wanner122333/dsh-bulk-scrna-concordance.git

在 DSH 中打开 Settings → Plugins，用包含 package.json 的检出目录的绝对路径安装该 bundle。注册的工具名为 bulk_scrna_concordance。查看安装结果；若提示 restart-required，请重启 DSH。

通过命令行管理配置档时：

dsh plugin --profile <profile> add /absolute/path/to/dsh-bulk-scrna-concordance
如果所需的 Python 解释器不在配置档插件配置的 PATH 上，就在该配置里设置 pythonPath：

- id: bulk-scrna-concordance
name: "@local/dsh-bulk-scrna-concordance"
config:
pythonPath: /absolute/path/to/python
defaultTimeoutMs: 1800000
maxLogLines: 40

Desktop 自带的配置档请使用应用内安装器。

通过 MCP 接入 ChatGPT 和 Claude

安装可选的 MCP 依赖：

python -m pip install -r requirements-mcp.txt
python python/mcp_server.py --transport stdio --workspace /path/to/data

服务器通过 stdio 暴露 bulk_scrna_concordance，供 Claude Desktop、Claude Code 等本地客户端调用。也支持 Streamable HTTP。ChatGPT 可以通过 Secure MCP Tunnel 或运维部署的 HTTPS 端点连接；账号与工作区策略仍然适用。客户端配置和部署要求见 MCP setup。

输入文件必须位于服务器机器上。服务器返回统计结果和产物路径；它不上传聊天附件，也不提供文件下载。HTTP 服务器没有内置身份认证，默认绑定回环地址。请保持私有，或放在带认证的 HTTPS 代理后面。

输出

文件写入 --out-dir 指定的目录：

| 文件 | 内容 |
| <prefix>_results.json | 参数、分组统计、诊断信息和警告；命令行调用时必须提供 --results-json |
| <prefix>_bulk_scrna_correlation_stats.csv | 分组统计 |
| <prefix>_discriminability.csv | 伪 bulk × bulk 相关性矩阵，按需生成 |
| <prefix>_bulk_scrna_correlation.{png,pdf,svg} | 散点图，含回归线和 y=x 线 |
| <prefix>_manifest.json | 代码、输入、输出的哈希值，以及记录的环境版本 |
| <prefix>_run.log | 通过 DSH 或 MCP 调用时的分析日志 |

manifest 的 environment_lock 字段记录已安装的版本；它不是可安装的依赖锁文件。

检查

python -m unittest discover -s tests -v
node --check index.js

这些合成回归检查覆盖输入处理和数值行为。它们不能证明生物学有效性，也不能确认已安装主机的配置是否正确。