3. 快速入门：运行第一个MultiQC报告
说实话，很多人第一次接触 MultiQC，都是被一堆杂乱的质量报告逼的。
一个测序项目下来，几十上百个样本，每个样本对应一份 FastQC 报告。你点开一个看看，还行；再点开另一个，有点累了；等到第十个，你只想摔鼠标。我当时就在想，有没有一个工具能把它们全部合并起来，生成一份统一的报告？
MultiQC 就是干这个的。
3.1 安装 MultiQC：三句话的事
安装这一步没什么好纠结的。我个人习惯用 pip，干净利落。你只需要打开终端，敲一行命令：
pip install multiqc如果你在隔离环境里做审计工作，也可以用 conda：
conda install -c bioconda multiqc装完后验证一下：
multiqc --version看到版本号输出了，就没问题。
3.2 运行你的第一个报告
假设你手头有一个生信分析流程跑完了，目录结构大概是这样的：
project/
├── sample1_fastqc.html
├── sample1_fastqc.zip
├── sample2_fastqc.html
├── sample2_fastqc.zip
└── sample3_fastqc.html
sample3_fastqc.zip你进到这个目录，执行：
cd project
multiqc .就这样。
MultiQC 会自动扫描当前目录下所有的生信报告文件，然后生成一份整合后的 HTML 报告。默认情况下，它会输出两个文件：
multiqc_report.html— 主要成果，可交互的 HTML 报告multiqc_data/— 存放所有解析后的原始数据，供进一步分析或脚本处理
关键点：MultiQC 默认会递归扫描子目录。你只需要指定一个根目录，它会找到所有能被识别的报告文件。
怎么样，是不是比一个个点开 FastQC 报告省事多了？
3.3 理解输出结构
跑完第一个报告后，你肯定想打开看看里面到底有什么。我来带你过一遍核心结构。
3.3.1 报告主页面
用浏览器打开 multiqc_report.html。你会看到一个类似面板式的布局，自上而下依次是：
- 报告标题和元数据 — 显示 MultiQC 版本、运行时间、分析的总样本数。
- 工具栏 — 搜索、过滤、清除选择，方便你快速定位特定样本。
- 概要表格（General Stats） — 所有样本的核心指标汇总，一眼能看到每个样本的 reads 数、GC 含量、质量分数等。
- 模块章节 — 每个被识别的工具（如 FastQC、STAR、Picard）对应一个独立的章节，展示该工具特有的图表和表格。
- 自定义内容 — 如果你配置了自定义报告，这里会显示。
我记得最早做审计时，最头疼的就是逐份翻看 FastQC 报告找异常样本。有了 General Stats 表格，你只要快速扫一遍，明显偏离均值的样本就会突显出来。
3.3.2 目录与搜索面板
报告左侧有一个固定的工具条，点击图标可以打开搜索面板。你可以：
- 按样本名称搜索
- 按指标过滤（如只显示 GC 含量超出 40%~60% 的样本）
- 高亮特定样本，方便跨图表追踪
multiqc . --no-data-dir，就不会生成 multiqc_data 文件夹。虽然报告能正常打开，但以后需要用脚本重新提取数据时就麻烦了。我一般都会保留数据目录，除非存储空间极其有限。
3.3.3 核心输出文件清单
下表总结了运行后生成的主要文件和各自用途：
| 文件名 / 目录名 | 用途 | 审计场景下的重要性 |
|---|---|---|
multiqc_report.html |
可视化整合报告，包含所有图表和表格 | 主要交付物，可存档、打印为 PDF |
multiqc_data/multiqc_data.json |
所有解析后的原始数据，JSON 格式 | 可供后期脚本验证或导入其他系统 |
multiqc_data/multiqc_general_stats.txt |
概要统计的制表符分隔文本 | 直接导入 Excel 或 LIMS 系统 |
multiqc_data/multiqc_sources.txt |
记录每个样本数据的来源文件 | 可追溯原始文件路径，审计必须 |
3.4 学会使用 --force 参数
你可能会遇到这样的情况：在一次流程结束后生成了报告，之后又补充了几个样本的数据。再次运行 multiqc 时，它会提示：
Report already exists. Use --force to overwrite.这时加上 -f 或 --force 参数即可：
multiqc . --force我个人建议：在非交互式环境（如批量运行脚本）中，始终加上 --force，不然脚本会被卡住。我在一次审计项目中发现，不加 force 参数，流水线在报告生成这一步直接中断了，导致后续质检全部延后，值得警惕。
3.5 定制报告标题
默认报告标题是 "MultiQC Report"。但在审计场景下，你往往需要标清项目 ID、批次号等信息。用 -t 参数即可：
multiqc . --title "PJ2024-08_QCBATCH_01" --force这样生成的报告顶部会显示 "PJ2024-08_QCBATCH_01"，在存档管理时一目了然。
3.6 知识体系总览
下面这张图概括了本章的核心逻辑：从原始报告出发，经过 MultiQC 扫描解析，最终生成结构化输出。每个阶段都有对应产出和审计价值。
3.7 快速检查清单
每次跑完第一个报告，我都会按这个清单过一遍，确保一切正常：
- ✔ 样本数正确 — 报告顶部显示的样本数与你预期的一致吗？
- ✔ General Stats 表无空值 — 某个样本的指标为空，说明 MultiQC 可能没解析到数据。
- ✔ 数据目录已生成 —
multiqc_data/目录内的 JSON 和 TXT 文件都在。 - ✔ 报告标题可辨识 — 没有用默认标题，至少包含项目或批次标识。
说实话，这一步虽然基础，但恰恰是审计流程中容易被忽略的环节。我见过不少团队直接拿默认报告存档，后来核对时发现标题对不上，费了很大功夫去回溯。所以，跑完第一个报告，就把这些习惯养成，后面会顺利很多。