单细胞 RNA-seq 质量控制

遵循 scverse 最佳实践的单细胞 RNA-seq 数据自动化 QC 工作流。

何时使用此技能

在用户以下情况下使用：

支持的输入格式：

默认推荐：除非用户有特定的自定义需求或明确要求非标准过滤逻辑，否则使用方法 1（完整流程）。

方法 1：完整 QC 流程（推荐用于标准工作流）

对于遵循 scverse 最佳实践的标准 QC，使用便捷脚本 scripts/qc_analysis.py：

python3 scripts/qc_analysis.py input.h5ad
# 或对于 10X Genomics .h5 文件：
python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5

该脚本自动检测文件格式并适当加载。

何时使用此方法：

要求： anndata, scanpy, scipy, matplotlib, seaborn, numpy

参数：

使用命令行参数自定义过滤阈值和基因模式：

使用 --help 查看当前默认值。

输出文件：

所有文件默认保存到 <input_basename>_qc_results/ 目录（或 --output-dir 指定的目录）：

如果需要复制输出供用户访问，请复制单个文件（而非整个目录），以便用户可以直接预览。

工作流步骤

该脚本执行以下步骤：

  1. 计算 QC 指标 - 计数深度、基因检测、线粒体/核糖体/血红蛋白含量
  2. 应用基于 MAD 的过滤 - 使用计数/基因/线粒体百分比的 MAD 阈值进行宽松异常值检测
  3. 过滤基因 - 移除在极少细胞中检测到的基因
  4. 生成可视化 - 带有阈值叠加的综合前后对比图

方法 2：模块化构建块（用于自定义工作流）

对于自定义分析工作流或非标准需求，使用 scripts/qc_core.py 和 scripts/qc_plotting.py 中的模块化工具函数：

# 从 scripts/ 目录运行，或根据需要将 scripts/ 添加到 sys.path
import anndata as ad
from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
from qc_plotting import plot_qc_distributions  # 仅当需要可视化时

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
# ... 此处为自定义分析逻辑

何时使用此方法：

可用的工具函数：

来自 qc_core.py（核心 QC 操作）：

来自 qc_plotting.py（可视化）：

自定义工作流示例：

示例 1：仅计算指标和可视化，暂不进行过滤

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
plot_qc_distributions(adata, 'qc_before.png', title='初始 QC')
print_qc_summary(adata, label='过滤前')

示例 2：仅应用线粒体百分比过滤，其他指标保持宽松

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# 仅过滤高 MT% 细胞
high_mt = apply_hard_threshold(adata, 'pct_counts_mt', 10, operator='>')
adata_filtered = filter_cells(adata, ~high_mt)
adata_filtered.write('filtered.h5ad')

示例 3：对不同子集使用不同阈值

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# 应用类型特定的 QC（假设存在 cell_type 元数据）
neurons = adata.obs['cell_type'] == 'neuron'
other_cells = ~neurons

# 神经元可耐受更高的 MT%，其他细胞使用更严格的阈值
neuron_qc = apply_hard_threshold(adata[neurons], 'pct_counts_mt', 15, operator='>')
other_qc = apply_hard_threshold(adata[other_cells], 'pct_counts_mt', 8, operator='>')

最佳实践

  1. 过滤时要宽松 - 默认阈值有意保留大多数细胞，以避免丢失稀有群体
  2. 检查可视化结果 - 始终查看过滤前后的图，确保过滤在生物学上有意义
  3. 考虑数据集特定因素 - 某些组织天然具有较高的线粒体含量（如神经元、心肌细胞）
  4. 检查基因注释 - 线粒体基因前缀因物种而异（小鼠为 mt-，人类为 MT-）
  5. 必要时迭代 - 可能需要根据具体实验或组织类型调整 QC 参数

参考资料

有关详细的 QC 方法论、参数理由和故障排除指南，请参见 references/scverse_qc_guidelines.md。该参考资料提供：

当用户需要更深入理解方法论或排查 QC 问题时，请加载此参考资料。

QC 后的后续步骤

典型的下游分析步骤：