批次校正 - 单细胞最佳实践

步骤

yml

安装 conda：
- 在创建环境之前，请确保 conda 已安装在你的系统中。
保存 yml 内容：
- 将 yml 选项卡中的内容保存为文件 environment.yml。
创建环境：
- 打开终端或命令提示符。
- 运行以下命令：
```
conda env create -f environment.yml
```
激活环境：
- 创建好环境后，使用以下命令激活它：
```
conda activate <environment_name>
```
- 请将 <environment_name> 替换为 environment.yml 文件中指定的环境名称。该名称在 yml 文件中如下所示：
```
name: <environment_name>
```
验证安装：
- 通过运行以下命令，检查环境是否创建成功：
```
conda env list
```

surface_protein.yml

name: surface-protein
channels:
  - conda-forge
dependencies:
  - python=3.13
  - scanpy=1.12
  - muon=0.1.9
  - python-igraph=1.0.0
  - ipykernel=7.2.0
  - pip==26.0.1
  - pip:
      - lamindb==2.3.1
      - harmonypy==0.0.9
      - ipywidgets==8.1.8

本书使用 lamindb 存储、共享和加载数据集与笔记本，托管实例为 theislab/sc-best-practices。感谢提供免费托管的 Lamin Labs。

安装 lamindb
- 安装 lamindb Python 软件包：
```
pip install lamindb
```
可选择创建 Lamin 账户
- 按照说明注册并登录
验证你的设置
- 下面用 Python API 检查连接；命令行方式可使用 lamin connect：
```
import lamindb as ln

ln.Artifact.connect("theislab/sc-best-practices").df()
```
运行后应显示最多 100 条已保存的数据集记录。
访问数据集（Artifact）
- 在 Artifacts 页面搜索数据集
- 加载一个 Artifact 及其对应的对象：
```
import lamindb as ln
af = ln.Artifact.connect("theislab/sc-best-practices").get(key="key_of_dataset", is_latest=True)
obj = af.load()
```
加载后的对象可直接在内存中分析。如需指定数据版本，可调整 lamindb.Artifact.connect("theislab/sc-best-practices").get("SOMEIDXXXX") 中的 ID。
访问笔记本（Transform）
- 在 Transforms 页面搜索笔记本
- 加载笔记本：
```
lamin load <notebook url>
```
该命令将笔记本下载到当前工作目录。与 Artifacts 类似，可通过指定 ID 获取旧版本。

研究动机¶

前一章的抗体衍生标签（Antibody-Derived Tags, ADTs）可视化显示明显的供体相关分离，详见降维（dimensionality reduction）。本章尝试批次校正（batch correction），以减轻技术因素造成的批次效应（batch effect），同时保留生物学差异。

本例使用 Harmony。该方法在单细胞 RNA 测序（Single-Cell RNA Sequencing, scRNA-seq）整合中经过独立基准评估，但这些结果不能直接证明它在 ADT 中同样最优。本章没有对 ADT 校正方法进行系统比较。

针对蛋白数据的其他方法包括 ADTnorm Zheng et al., 2025 和 CytoVI Ingelfinger et al., 2025，可根据实验与数据特点考虑。本教程沿用 Harmony 作为演示；方法选择应依据实际验证，而非仅凭其在其他模态的声誉或成绩。

环境设置¶

import warnings

import scanpy as sc

warnings.filterwarnings("ignore")
sc.settings.verbosity = 0
sc.set_figure_params(
    dpi=80,
    facecolor="white",
    frameon=False,
)

import lamindb as ln

ln.track()

→ connected lamindb: theislab/sc-best-practices
→ found notebook batch_correction.ipynb, making new version -- anticipating changes
→ created Transform('4LJehi0GPRuj0006', key='batch_correction.ipynb'), started new Run('nxVysIoDJ9QSryHS') at 2026-07-29 11:11:33 UTC
→ notebook imports: lamindb-core==2.3.1 muon==0.1.9 scanpy==1.12.3
• recommendation: to identify the notebook across renames, pass the uid: ln.track("4LJehi0GPRuj")

加载数据¶

加载前一章保存的 MuData 对象，参见降维：

af = ln.Artifact.connect("theislab/sc-best-practices").get(
    key="surface-protein/cite_dimensionality_reduction.h5mu", is_latest=True
)
mdata = af.load()
mdata

Harmony¶

本例将 Harmony Korsunsky et al., 2019 应用于蛋白数据的主成分分析（Principal Component Analysis, PCA）坐标，并以 donor 作为校正变量。该步骤产生校正后的嵌入（Embedding），不会直接改写蛋白表达矩阵。ADT 的最佳校正方案仍需针对数据比较。

sc.external.pp.harmony_integrate(adata=mdata["prot"], key="donor", random_state=0)

2026-07-29 13:11:39,225 - harmonypy - INFO - Computing initial centroids with sklearn.KMeans...

2026-07-29 13:11:44,476 - harmonypy - INFO - sklearn.KMeans initialization complete.
2026-07-29 13:11:44,822 - harmonypy - INFO - Iteration 1 of 10
2026-07-29 13:12:05,457 - harmonypy - INFO - Iteration 2 of 10
2026-07-29 13:12:26,440 - harmonypy - INFO - Iteration 3 of 10
2026-07-29 13:12:48,434 - harmonypy - INFO - Iteration 4 of 10
2026-07-29 13:13:13,239 - harmonypy - INFO - Iteration 5 of 10
2026-07-29 13:13:34,590 - harmonypy - INFO - Iteration 6 of 10
2026-07-29 13:13:55,834 - harmonypy - INFO - Iteration 7 of 10
2026-07-29 13:14:13,482 - harmonypy - INFO - Converged after 7 iterations

使用 Harmony 校正后的前 20 个主成分（principal component, PC）构建邻接图，再计算统一流形逼近与投影（Uniform Manifold Approximation and Projection, UMAP），展示校正后的细胞关系。

sc.pp.neighbors(mdata["prot"], n_pcs=20, use_rep="X_pca_harmony", random_state=0)
sc.tl.umap(mdata["prot"], random_state=0)

sc.pl.umap(mdata["prot"], color=["donor", "batch"])

不同供体的细胞在新 Embedding 中混合得更充分，可与降维章节的图比较。

sc.pl.umap(mdata["prot"], color=["CD4-1", "CD8", "CD3"])
sc.pl.umap(mdata["prot"], color=["CD14-1", "CD16"])

继续查看蛋白标记，检查不同细胞类型是否仍可区分。T 细胞仍形成相对独立的群体，并可进一步区分 CD4 与 CD8 T 细胞；CD4 T 细胞中的供体混合也有所改善。这支持本例校正的可用性，但二维图和少数标记只能提供初步证据，还应评估批次混合与生物学差异保留是否平衡。

af_batch_correction = ln.Artifact.from_mudata(
    mdata,
    key="surface-protein/cite_batch_correction.h5mu",
    description="CITE-seq data after batch correction",
)
af_batch_correction.save()

→ creating new artifact version for key 'surface-protein/cite_batch_correction.h5mu' in storage 's3://lamin-eu-central-1/VPwcjx3CDAa2'

... uploading uu6lLafald9WnYWL0006.h5mu: 100.0%
• replacing the existing cache path /var/cache/user/marchena/.cache/lamindb/lamin-eu-central-1/VPwcjx3CDAa2/surface-protein/cite_batch_correction.h5mu

Artifact(uid='uu6lLafald9WnYWL0006', key='surface-protein/cite_batch_correction.h5mu', description='CITE-seq data after batch correction', suffix='.h5mu', kind='dataset', otype='MuData', size=1449791144, hash='aYPsyP7ViUyvXh9Ss2YpzB', n_files=None, n_observations=105907, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=114, schema_id=None, created_by_id=7, created_at=2026-07-29 11:15:27 UTC, is_locked=False, version_tag=None, is_latest=True)

ln.finish()

贡献者¶

我们衷心感谢以下人员的贡献：

作者¶

Javier Marchena-Hurtado
Daniel Strobl
Ciro Ramírez-Suástegui

审阅者¶

Lukas Heumos
Anna Schaar

References¶

Zheng, Y., Caron, D. P., Kim, J. Y., Jun, S.-H., Tian, Y., Mair, F., Stuart, K. D., Sims, P. A., & Gottardo, R. (2025). ADTnorm: robust integration of single-cell protein measurement across CITE-seq datasets. Nature Communications, 16(1), 5852.
Ingelfinger, F., Levy, N., Ergen, C., Bakulin, A., Becker, A., Boyeau, P., Kim, M., Ditz, D., Dirks, J., Maaskola, J., & others. (2025). CytoVI: Deep generative modeling of antibody-based single cell technologies. bioRxiv, 2025–09.
Korsunsky, I., Millard, N., Fan, J., Slowikowski, K., Zhang, F., Wei, K., Baglaenko, Y., Brenner, M., Loh, P., & Raychaudhuri, S. (2019). Fast, sensitive and accurate integration of single-cell data with Harmony. Nature Methods, 16(12), 1289–1296. 10.1038/s41592-019-0619-0