mcpField
S
single-cell-rna-qc

single-cell-rna-qc

github.com/anthropics数据与数据库636212 次安装1 天前更新
代码仓库

关于 single-cell-rna-qc

面向采用 scverse 实践的研究人员，用于单细胞 RNA-seq 数据质控的工作流技能。它提供可直接运行的流程，也提供模块化 Python 工具，支持自定义过滤和可视化检查。

主要功能

  1. 01读取 .h5ad 和 10X .h5 文件
  2. 02计算细胞级质控指标
  3. 03基于 MAD 检测并过滤异常值
  4. 04配置阈值和基因模式
  5. 05生成过滤前后质控图

适用场景

  1. 01过滤数据集中的低质量细胞
  2. 02在下游分析前检查质控指标
  3. 03对不同细胞子集应用自定义阈值

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/anthropics/life-sciences --skill single-cell-rna-qc

安装后在 Claude Code 中输入/single-cell-rna-qc确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE.txt
references/
scverse_qc_guidelines.md
scripts/
qc_analysis.py
qc_core.py
qc_plotting.py

详细介绍

单细胞 RNA-seq 质量控制

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

何时使用此技能

在以下情况下使用：

  • 用户要求对单细胞 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 - counts/genes/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 注释的原始数据

如果将输出复制到 /mnt/user-data/outputs/ 供用户访问，请复制单个文件（不要复制整个目录），以便用户可以直接将其作为 Claude.ai 工件预览。

工作流步骤

脚本会执行以下步骤：

  1. 计算 QC 指标 - 计数深度、基因检测情况、线粒体/核糖体/血红蛋白含量
  2. 应用基于 MAD 的筛选 - 使用 counts/genes/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）
  • 特征选择与降维
  • 聚类与细胞类型注释

评论

支持 Markdown