single-cell-rna-qc

单细胞 RNA-seq 质量控制

遵循 scverse 最佳实践的单细胞 RNA-seq 数据自动化质控流程。

何时使用本技能

当用户有以下需求时使用：

• 请求对单细胞 RNA-seq 数据进行质量控制或 QC
• 希望过滤低质量细胞或评估数据质量
• 需要 QC 可视化或指标
• 要求遵循 scverse/scanpy 最佳实践
• 请求基于 MAD 的过滤或离群值检测

支持的输入格式：

• .h5ad 文件（来自 scanpy/Python 工作流的 AnnData 格式）
• .h5 文件（10X Genomics Cell Ranger 输出）

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

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

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

python3 scripts/qc_analysis.py input.h5ad
# or for 10X Genomics .h5 files:
python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5

该脚本会自动检测文件格式并进行相应加载。

何时使用此方法：

• 使用可调阈值的标准 QC 工作流（所有细胞采用相同的过滤方式）
• 批量处理多个数据集
• 快速探索性分析
• 用户希望获得"开箱即用"的解决方案

依赖要求： anndata、scanpy、scipy、matplotlib、seaborn、numpy

参数：

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

• --output-dir - 输出目录
• --mad-counts、--mad-genes、--mad-mt - 计数/基因数/线粒体百分比的 MAD 阈值
• --mt-threshold - 硬性线粒体百分比截断值
• --min-cells - 基因过滤阈值
• --mt-pattern、--ribo-pattern、--hb-pattern - 适用于不同物种的基因名称模式

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

输出：

默认情况下，所有文件保存至 <input_basename>_qc_results/ 目录（或由 --output-dir 指定的目录）：

• qc_metrics_before_filtering.png - 过滤前可视化
• qc_filtering_thresholds.png - 基于 MAD 的阈值叠加图
• qc_metrics_after_filtering.png - 过滤后质量指标
• <input_basename>_filtered.h5ad - 可用于下游分析的干净过滤数据集
• <input_basename>_with_qc.h5ad - 保留 QC 注释的原始数据

如需为用户复制输出结果，请逐个复制文件（而非整个目录），以便用户直接预览。

工作流步骤

该脚本执行以下步骤：

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

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

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

# Run from scripts/ directory, or add scripts/ to sys.path if needed
import anndata as ad
from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
from qc_plotting import plot_qc_distributions  # Only if visualization needed

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
# ... custom analysis logic here

何时使用此方法：

• 需要不同的工作流（跳过步骤、更改顺序、对子集应用不同阈值）
• 条件逻辑（例如，对神经元的过滤方式与其他细胞不同）
• 部分执行（仅计算指标和可视化，不进行过滤）
• 与更大流程中的其他分析步骤集成
• 超出命令行参数所支持范围的自定义过滤条件

可用的工具函数：

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

• calculate_qc_metrics(adata, mt_pattern, ribo_pattern, hb_pattern, inplace=True) - 计算 QC 指标并标注 adata
• detect_outliers_mad(adata, metric, n_mads, verbose=True) - 基于 MAD 的异常值检测，返回布尔掩码
• apply_hard_threshold(adata, metric, threshold, operator='>', verbose=True) - 应用硬截断，返回布尔掩码
• filter_cells(adata, mask, inplace=False) - 应用布尔掩码过滤细胞
• filter_genes(adata, min_cells=20, min_counts=None, inplace=True) - 按检出情况过滤基因
• print_qc_summary(adata, label='') - 打印汇总统计信息

来自 qc_plotting.py（可视化）：

• plot_qc_distributions(adata, output_path, title) - 生成综合 QC 图
• plot_filtering_thresholds(adata, outlier_masks, thresholds, output_path) - 可视化过滤阈值
• plot_qc_after_filtering(adata, output_path) - 生成过滤后的图

自定义工作流示例：

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

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
plot_qc_distributions(adata, 'qc_before.png', title='Initial QC')
print_qc_summary(adata, label='Before filtering')

示例 2：仅应用线粒体比例（MT%）过滤，其他指标保持宽松

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

# Only filter high MT% cells
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)

# Apply type-specific QC (assumes cell_type metadata exists)
neurons = adata.obs['cell_type'] == 'neuron'
other_cells = ~neurons

# Neurons tolerate higher MT%, other cells use stricter threshold
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 指标的详细解释及其重要性
• 基于 MAD 阈值的依据，以及它优于固定截断值的原因
• 解读 QC 可视化图（直方图、小提琴图、散点图）的指南
• 针对物种的基因注释注意事项
• 何时以及如何调整过滤参数
• 高级 QC 考虑因素（环境 RNA 校正、双细胞检测）

当用户需要更深入地理解方法论，或在排查 QC 问题时，请加载该参考文档。

QC 之后的后续步骤

常见的下游分析步骤：

• 环境 RNA 校正（SoupX、CellBender）
• 双细胞检测（scDblFinder）
• 归一化（对数归一化、scran）
• 特征选择与降维
• 聚类与细胞类型注释