用途：Harmony 是一种快速、可扩展的单细胞数据批次整合算法。输入为 PCA 嵌入（细胞×主成分），输出校正后的嵌入，用于计算近邻、UMAP 和下游聚类；原始计数矩阵不被修改。适用于 scRNA-seq、ATAC-seq 等具备 PCA 类嵌入的组学模态。
主要能力：整合不同样本、供体、测序批次的数据；去除文库制备、10x 化学版本、测序深度与平台等技术变异，同时保留细胞类型与条件间的生物学差异；可同时校正多个混杂变量（批次、供体、平台、组织处理方案）；支持百万级细胞规模；为 UMAP、Leiden 聚类或标签转移准备校正嵌入。
使用方式：需先完成质控、标准化、高变基因选择与 PCA。Python 依赖 harmonypy、scanpy>=1.10、leidenalg、igraph、anndata、pandas、matplotlib，安装命令为 pip install harmonypy "scanpy[leiden]" anndata pandas matplotlib。可通过 scanpy 封装 sc.external.pp.harmony_integrate(adata, key="batch") 将结果存入 adata.obsm["X_pca_harmony"]，再用 use_rep="X_pca_harmony" 构建近邻图、UMAP 与 Leiden 聚类；也可直接调用 harmonypy.run_harmony 获得更细控制。R 用户可用 harmony 与 Seurat>=4.0，通过 RunHarmony() 整合。
关键参数：theta 默认 2.0，控制混合强度，批次大小不均时可提高至 4–6；sigma 默认 0.1；nclust 默认自动 min(100, 细胞数/30)；max_iter_harmony 默认 10；tau 默认 0，用于保护小簇；block_size 默认 0.05。
适用场景与限制：适合需快速、可扩展批次校正且保留原始计数矩阵的分析。若需概率化批次校正、带不确定性的差异表达或多模态整合，应改用 scVI/scvi-tools；若希望直接构建跨批次近邻图而不生成校正嵌入，可用 BBKNN；若已在 Seurat 工作流中，可用 Seurat Integration/CCA。注意 Harmony 只校正嵌入而非计数矩阵，差异表达仍应使用原始或标准化计数。过度校正可能连同真实处理效应一并去除，提高 theta 前需确认批次变量与哪些因素混杂。环境要求 Python 3.9+，约 50 万细胞需 8 GB 内存，内存线性增长。