单细胞RNA-seq数据质控：用MAD过滤低质量细胞并生成可…

当需要对单细胞RNA-seq数据（.h5ad或.h5）做质控、过滤低质量细胞或评估数据质量时使用。

适用场景

解决思路

1. 标准流程优先使用便捷脚本 scripts/qc_analysis.py：`python3 scripts/qc_analysis.py input.h5ad`，对10X Genomics .h5 文件用 `python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5`，脚本会自动检测文件格式并加载。
2. 通过命令行参数自定义过滤阈值和基因模式：`--output-dir`（输出目录）、`--mad-counts`/`--mad-genes`/`--mad-mt`（counts/genes/MT% 的 MAD 阈值）、`--mt-threshold`（线粒体百分比硬截断）、`--min-cells`（基因过滤阈值）、`--mt-pattern`/`--ribo-pattern`/`--hb-pattern`（不同物种的基因名模式）；用 `--help` 查看当前默认值。
3. 脚本默认将结果保存到 `<input_basename>_qc_results/` 目录（或 `--output-dir` 指定目录），输出包括：过滤前可视化 `qc_metrics_before_filtering.png`、MAD阈值叠加图 `qc_filtering_thresholds.png`、过滤后质量指标图 `qc_metrics_after_filtering.png`、过滤后干净数据集 `<input_basename>_filtered.h5ad`、保留QC注释的原始数据 `<input_basename>_with_qc.h5ad`。
4. 若需把输出复制给用户查看，复制单个文件而非整个目录，方便用户直接预览。
5. 脚本执行的流程步骤：1) 计算QC指标——count深度、基因检测数、线粒体/核糖体/血红蛋白含量；2) 应用基于MAD的过滤——对counts/genes/MT%使用MAD阈值做宽松的离群值检测；3) 过滤基因——移除在少数细胞中检测到的基因；4) 生成可视化——带阈值叠加的过滤前后综合图。
6. 自定义或非标准流程时，改用模块化工具函数：从 scripts/qc_core.py 和 scripts/qc_plotting.py 导入，示例：`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)`，再写自定义逻辑。
7. qc_core.py 可用函数：`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='')` 打印汇总统计。
8. 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)` 生成过滤后图。
9. 自定义示例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')`。
10. 自定义示例2（只做MT%过滤、其他指标保持宽松）：`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')`。
11. 自定义示例3（对不同亚群用不同阈值）：`adata = ad.read_h5ad('input.h5ad')`、`calculate_qc_metrics(adata, inplace=True)`、`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='>')`。
12. 最佳实践：过滤要宽松——默认阈值有意保留大多数细胞以避免丢失稀有群体；务必检查可视化——审查过滤前后图以确认过滤在生物学上合理；考虑数据集特异性因素——某些组织天然线粒体含量更高（如神经元、心肌细胞）；检查基因注释——线粒体基因前缀因物种而异（小鼠为 mt-，人类为 MT-）；必要时迭代——QC参数可能需要根据具体实验或组织类型调整。
13. 需要深入理解方法学或排查QC问题时，参阅 `references/scverse_qc_guidelines.md`，其中包含各QC指标的详细解释、MAD阈值优于固定截断的理由、可视化解读指南、物种特异性基因注释注意事项、参数调整时机与方法、以及高级QC考量（环境RNA校正、双细胞检测）。
14. QC后的典型下游步骤：环境RNA校正（SoupX、CellBender）、双细胞检测（scDblFinder）、归一化（log-normalize、scran）、特征选择与降维、聚类与细胞类型注释。

适用边界 · 注意事项

• 用户有特定自定义需求或明确要求非标准过滤逻辑时，不要用完整流程脚本，改用模块化函数。
• 需要跳过步骤、改变顺序、对子集应用不同阈值、条件逻辑、部分执行或集成到更大流程时，不适用标准流程。
• 需要命令行参数无法支持的自定义过滤标准时，不适用标准流程。