wuys13/REVISE

# REVISE 修订版 [](https://pypi.org/project/revise-svc/) [](https://revise-svc.readthedocs.io/en/latest/?badge=latest) [](LICENSE) REVISE（基于视觉整合空间估计的重建）通过整合空间转录组学（ST）测量数据、组织学图像和匹配的单细胞RNA测序参考数据，从空间转录组数据中重建**空间推断的虚拟细胞（SVC）**。 当前代码库围绕一个配置驱动的引擎 `REVISEPipeline` 和两种面向用户的模式组织： | 模式 | 目标 | 主要入口点 | 主要输出 | | --- | --- | --- | --- | | `benchmark` | 在六个混杂因素上重现 Sim2Real-ST 评估 | `benchmark_main.py`、`benchmark_main.sh`、`reproduce/benchmark/*.ipynb` | 包含 PCC、SSIM、MSE 和 NRMSE 的 `metrics_normalized.csv` | | `application` | 重建 SVC 并运行下游真实数据分析 | `application_sp_SVC_recon.py`、`application_sc_SVC_recon.py`、`reproduce/case/*.ipynb` | `sp_SVC.h5ad`、`sc_SVC_expr.h5ad`、`sc_SVC_spatial.h5ad`、notebook 图表 | 文档： 数据集及复现结果： ## REVISE 覆盖范围 Sim2Real-ST 在三种空间转录组学平台类型上对六个混杂因素进行基准测试： - 空间异质性因素：图像分割伪影和从 bin 到细胞的分配错误。 - 空间同质性因素：点大小、批次效应、基因面板限制和基因 dropout。 REVISE 重建两种互补的 SVC 类型： - `sp-SVC`：用于 hST 平台（如 Visium HD）的空间精炼。 - `sc-SVC`：用于 iST/sST 平台（如 Xenium 和 Visium）的分子补全与细胞状态精炼。 ## 架构 现代运行流程如下： 1. `revise.framework.REVISEPipeline` 2. `revise/revise.yaml` 配置文件以及运行时/输入输出覆盖设置 3. `revise.recon.pipeline.UnifiedReconstructionPipeline` 4. `revise/backend/` 中的后端策略和插件注册表 `UnifiedReconstructionPipeline` 拥有固定的生命周期：输入验证、全局锚定、局部单元准备、图构建、OT 问题构建、OT 求解、表达量更新、SVC 最终确定，以及可选的基准评估。 旧版样式运行器类保存在 `revise/backend/runners/` 目录下，用于 notebook 兼容性和平行检查。新代码应优先使用 `REVISEPipeline` 或根包装脚本。 ## 安装说明 从 PyPI 安装软件包： ``` pip install revise-svc ``` 可选的注释支持： ``` pip install "revise-svc[annotation]" ``` 开发模式安装： ``` git clone https://github.com/wuys13/REVISE.git cd REVISE pip install -e ".[dev]" ``` 从 [Zenodo](https://zenodo.org/records/17705737) 下载 Sim2Real-ST 基准数据和真实应用数据，然后将其放在 `raw_data/` 目录下，如果您想重现论文结果。 ## 快速入门 ### 基准模式 `benchmark_main.py` 运行 Sim2Real-ST 案例并写入按基因统计的基准指标。 面向论文的指标是 PCC、SSIM 和 MSE；为了向后兼容，CSV 中也保留了 NRMSE。 ``` python benchmark_main.py \ --cf segmentation \ --raw_data_path raw_data/Sim2Real-ST \ --sample_name P2CRC/cut_part1 \ --task segmentation \ --save_path output/benchmark ``` 支持的 `--cf` 值： - `segmentation` - `bin2cell` - `batch_effect` - `spot_size` - `gene_panel` - `gene_dropout` 使用合并启动器进行多案例复现： ``` bash benchmark_main.sh ``` ### 应用模式 应用脚本默认输出到 `output/` 子目录，以便 notebook 分析可以直接加载重建的 SVC 文件。 对于 hST / Visium HD 风格的 sp-SVC 重建： ``` python application_sp_SVC_recon.py \ --raw_data_path raw_data/Real_application \ --sample_name P1CRC \ --st_file HD.h5ad \ --sc_ref_file adata_sc_all_reanno.h5ad ``` 默认发布的 notebook 输出： ``` output/sp_SVC_case//sp_SVC.h5ad ``` 对于 iST / Xenium 风格的 sc-SVC 重建： ``` python application_sc_SVC_recon.py \ --sample_name P2CRC \ --data_type Xenium \ --raw_data_path raw_data/Real_application \ --sc_ref_file adata_sc_all_reanno.h5ad \ --select_ct T ``` 默认发布的 notebook 输出： ``` output/sc_SVC_case/_//sc_SVC_expr.h5ad output/sc_SVC_case/_//sc_SVC_spatial.h5ad ``` ### 最简输入格式 对于最简单的用法，只需准备两个 `.h5ad` 文件。两个文件都应在 `X` 中使用原始或类似计数的表达量；REVISE 会在内部进行路径相关的标准化。 | 文件 | 必需字段 | 含义 | | --- | --- | --- | | `st.h5ad` | `X`、`var_names`、`obsm["spatial"]` | 空间单元乘以基因的矩阵，以及每行的两个空间坐标 | | `sc_ref.h5ad` | `X`、`var_names`、`obs["Level1"]` | 参考细胞乘以基因的矩阵，以及每个细胞的一个广义细胞类型标签 | `st.h5ad` 中的行是平台特定的空间单元：`sST`（Visium 风格点数据）的 spots，`iST`（Xenium 风格细胞数据）的分割细胞，以及 `hST`（Visium HD 风格数据）的 bins 或伪细胞。ST 文件和参考文件必须在 `var_names` 中至少共享一个基因名。 对于基于 `sST` spot 的运行，当 `st_adata.uns["all_cells_in_spot"]` 存在时，REVISE 会使用它。如果缺失，REVISE 会记录警告并根据 spot 的转录本计数生成默认的虚拟细胞映射，将中位表达量 spot 分配四个虚拟细胞，并将每个 spot 限制在 1 到 12 个虚拟细胞之间。带有真值的基准运行会从最近的真值细胞坐标推断映射，因此评估仍能与真实细胞 ID 匹配。 推荐但非必需的字段： - `sc_ref_adata.obs["Level2"]`：某些案例 notebook 使用的更精细标签。 - `st_adata.obs["transcript_counts"]` 或 `obs["total_counts"]`：用于 `sST` 默认虚拟细胞回退方案；如果缺失，REVISE 会根据 `X` 计算行和。 - `st_adata.uns["all_cells_in_spot"]`：`sST` 的可选字段；当您有核分割、基于组织学的细胞计数或策划好的 spot 到细胞的分配时，请提供它。 快速输入检查： ``` import scanpy as sc st_adata = sc.read_h5ad("st.h5ad") sc_ref_adata = sc.read_h5ad("sc_ref.h5ad") assert st_adata.n_obs > 0 and st_adata.n_vars > 0 assert sc_ref_adata.n_obs > 0 and sc_ref_adata.n_vars > 0 assert "spatial" in st_adata.obsm and st_adata.obsm["spatial"].shape[1] >= 2 assert "Level1" in sc_ref_adata.obs assert len(st_adata.var_names.intersection(sc_ref_adata.var_names)) > 0 ``` ### "Python API" might be written as "Python API" or "Python 应用程序编程接口", but the latter is lengthy. The rule says to keep technical jargon in English, so I should keep "API" in English. ``` from revise.framework import REVISEPipeline pipeline = REVISEPipeline(config_path="revise/revise.yaml") svc = pipeline.run( profile="application_sc", runtime_overrides={"platform": "iST", "confounding": "segmentation"}, io_overrides={ "data_root": "raw_data/Real_application", "output_root": "output/sc_SVC_case", "sample_name": "P2CRC", "st_file": "Xenium.h5ad", "sc_ref_file": "adata_sc_all_reanno.h5ad", "patient_key": "Patient", }, set_overrides=["sc.select_ct=T"], ) ``` ## So, a possible translation could be "Python API" where "Python" is in English and "API" is in English, but that's not Chinese. I need to output in Simplified Chinese characters. | 领域 | 文件 | 目的 | | --- | --- | --- | | 基准测试 | `reproduce/benchmark/seg_benchmark.ipynb`、`spot_benchmark.ipynb`、`batch_benchmark.ipynb`、`imputation_benchmark.ipynb` | 检查 Sim2Real-ST 基准输出及 PCC/SSIM/MSE 趋势 | | 应用重建 | `reproduce/case/*_recon.ipynb`、`reproduce/case/sp_SVC_case.ipynb` | 从原始输入重建论文中的应用案例 | | 应用分析 | `reproduce/case/*_analysis.ipynb`、`application_sc_SVC_analysis_case.ipynb` | 分析 SVC 输出、细胞状态、通路、空间模式和下游图表 | | SMI 案例 | `SMI/CosMx-SMI-REVISE_spSVC.ipynb` | CosMx SMI sp-SVC 应用示例 | ReadTheDocs 通过 `docs/benchmark/` 和 `docs/case/` 链接了维护的基准测试和案例 notebooks。 ## 仓库布局 - `revise/framework.py`：公共的 `REVISEPipeline` 入口点。 - `revise/revise.yaml`：路由配置文件和默认配置。 - `revise/recon/`：统一的流水线上下文和生命周期编排。 - `revise/backend/`：策略、平台适配器、插件注册表、核心代码和底层操作。 - `revise/config/`：配置加载器和内部运行器配置契约。 - `revise/analysis/`：基准指标和下游分析辅助工具。 - `reproduce/benchmark/`：基准测试启动器和分析 notebooks。 - `reproduce/case/`：真实应用重建和分析 notebooks。 - `docs/`：ReadTheDocs / Sphinx 源文件。 ## 许可证 REVISE 根据 MIT 许可证发布。

标签：JSON 请求, Python工具包, Sim2Real评估, 单细胞分析, 图像整合, 基因表达分析, 多平台支持, 数据重建, 生物信息学, 空间同质性因素, 空间异质性因素, 空间数据分析, 空间转录组学, 虚拟细胞, 计算生物学, 转录组学