⚡

单细胞RNA-seq质量控制Skill single-cell-rna-qc

这个技能用于自动化执行单细胞RNA-seq数据的质量控制流程，采用scverse最佳实践，包括基于MAD的过滤方法来识别和移除低质量细胞，并生成详细的可视化图表以评估数据质量。适用于生物信息学、基因表达分析、数据清洗和预处理等场景。关键词：单细胞RNA-seq、质量控制、QC、过滤、可视化、数据分析、生物信息学。

基因工程 0 次安装 0 次浏览 更新于 3/18/2026

名称: 单细胞rna-qc 描述: 使用scverse最佳实践对单细胞RNA-seq数据（.h5ad或.h5文件）执行质量控制，采用基于MAD的过滤和全面可视化。当用户请求QC分析、过滤低质量细胞、评估数据质量或遵循scverse/scanpy单细胞分析最佳实践时使用。

单细胞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
# 或对于10X Genomics .h5文件：
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的过滤 - 使用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操作）：

  • 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='初始QC')
print_qc_summary(adata, label='过滤前')

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

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

# 仅过滤高线粒体%细胞
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

# 神经元容忍更高线粒体%，其他细胞使用更严格阈值
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）
  • 标准化（log-normalize, scran）
  • 特征选择和降维
  • 聚类和细胞类型注释