用途
该技能用于对单细胞 RNA 测序（scRNA-seq）数据进行质量控制（QC），遵循 scverse 最佳实践。适用于以下场景：用户请求对单细胞 RNA-seq 数据进行 QC、希望过滤低质量细胞或评估数据质量、需要 QC 可视化或指标、要求遵循 scverse/scanpy 最佳实践、或需要基于 MAD 的过滤或离群值检测。
支持的输入格式：
- .h5ad 文件（来自 scanpy/Python 工作流的 AnnData 格式）
- .h5 文件（10X Genomics Cell Ranger 输出）
默认建议使用方式一（完整流程），除非用户有特定自定义需求或明确要求非标准过滤逻辑。
主要能力
方式一：完整 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：计数/基因/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/ 供用户访问，请复制单个文件（而非整个目录），以便用户直接预览。
工作流步骤：
- 计算 QC 指标——计数深度、基因检出、线粒体/核糖体/血红蛋白含量
- 应用基于 MAD 的过滤——对计数/基因/MT% 使用 MAD 阈值进行宽松的离群值检测
- 过滤基因——移除在少数细胞中检出的基因
- 生成可视化——包含阈值叠加的过滤前后综合图表
方式二：模块化构建块（用于自定义工作流）
对于自定义分析工作流或非标准需求，使用 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='Initial QC')
print_qc_summary(adata, label='Before filtering')
示例 2：仅应用 MT% 过滤，其他指标保持宽松
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='>')
最佳实践
- 过滤宜宽松——默认阈值有意保留大多数细胞，以避免丢失稀有群体
- 检查可视化——始终审阅过滤前后图表，确保过滤在生物学上合理
- 考虑数据集特异性因素——某些组织天然具有较高线粒体含量（如神经元、心肌细胞）
- 检查基因注释——线粒体基因前缀因物种而异（小鼠为 mt-，人类为 MT-）
- 必要时迭代——QC 参数可能需要根据具体实验或组织类型调整
参考材料
关于详细 QC 方法、参数依据和故障排除指导，参见 references/scverse_qc_guidelines.md。该参考提供：
- 每个 QC 指标的详细解释及其重要性
- 基于 MAD 阈值的依据，以及为何优于固定截断值
- 解读 QC 可视化（直方图、小提琴图、散点图）的指南
- 基因注释的物种特异性考虑
- 何时及如何调整过滤参数
- 高级 QC 考虑（环境 RNA 校正、双细胞检测）
当用户需要更深入理解方法或排查 QC 问题时，加载此参考。
QC 后的下一步
典型下游分析步骤：
- 环境 RNA 校正（SoupX、CellBender）
- 双细胞检测（scDblFinder）
- 归一化（log-normalize、scran）
- 特征选择与降维
- 聚类与细胞类型注释
限制
资料未提供关于收费、价格、平台支持范围、性能效果或具体使用步骤之外的额外限制信息。