📚 课程目录第3章 MultiQC基本使用流程

3. MultiQC 基本使用流程：命令行调用、指定输入目录、输出格式选择，生成第一份报告

说实话，我刚接触 MultiQC 的时候，第一反应是「这东西到底有多神？」。后来发现它的核心其实就一条命令搞定。别急，我们一步步来，从命令行怎么敲开始。

3.1 命令行调用：最简写法

假设你已经装好了 MultiQC（装不上？回头看看第二章）。打开终端，cd 到你放质控结果的那个目录下——比如里面有 sample1_fastqc.html、sample1_fastqc.zip 之类的文件。然后敲下面这行：

multiqc .

对，就这么简单。一个点号代表当前目录。MultiQC 会自动扫描所有支持的文件格式。我建议先不加任何参数跑一次，看看效果。

我的习惯：第一次跑时加个 --verbose，能看到它在哪些文件里找到了数据。如果某样本没被抓到，日志里会写「WARNING: No analysis results found in ...」，方便排查。

如果你想指定别的目录，直接把路径扔上去：

multiqc /path/to/your/fastqc_outputs/

3.2 指定输入目录：别找错地方

MultiQC 不会递归去子目录里翻文件？它会。默认它会在你给的目录里到处找，包括子文件夹。这点挺方便。

但有坑。我曾经把原始 FASTQ 文件和质控结果混在同一个目录里，MultiQC 傻乎乎地去读大 FASTQ……虽然它不会解析它们，但会多花好几秒。我现在的做法是：建一个单独的 qc_results 文件夹，把所有工具的原始输出（FastQC、cutadapt、Trimmomatic、STAR 的 Log 等）都扔进去，然后直接指定这个文件夹。

multiqc ./qc_results/ -o ./multiqc_report/

这里多了一个 -o 参数，咱们下一节讲。

注意：如果目录下没有任何 MultiQC 能解析的文件，它会报错退出。事先确认好你放了哪些工具的输出。

3.3 输出格式选择：不只是 HTML

默认输出是一个 HTML 文件 + 一个 multiqc_data 子目录。HTML 就是咱们日常看的报告。但很多场景下你需要纯数据——比如扔给下游脚本或者传数据库。

表格来了：

输出类型	命令行参数	产物说明
HTML 报告	`--html`（默认）	交互式网页，包含图表和表格
JSON 数据	`--json`	纯 JSON 文件 `multiqc_data.json`，方便程序处理
TSV 表格	`--tsv`	制表符分隔的汇总表，每个模块一个文件
Flat (纯数据目录)	`--flat`	只生成 `multiqc_data` 文件夹，不生成 HTML
全部生成	不加限制或组合使用	比如 `--json --tsv`

  实践经验：我通常这样组合：multiqc ./ -o report/ -f --json --tsv。HTML 直观、JSON 给脚本用、TSV 方便 Excel 打开。——话说回来，-f 是什么意思？接着看。

3.4 常用输出控制参数

你肯定不想每次都手动删旧报告吧？-f 或 --force 允许覆盖已有输出目录。不加它，如果输出目录已存在，MultiQC 会直接拒绝运行。

还有几个实用的：

-n 或 --filename：自定义 HTML 文件名，默认 multiqc_report.html。
-d 或 --data-dir：自定义数据文件夹名，默认 multiqc_data。
--ignore：排除某些文件名模式，比如 --ignore "*.fastq" 避免读原始序列。
--exclude-modules：如果你觉得某个模块没用，比如不想看 FastQ_Screen，可以禁用。

3.5 实战：生成你的第一份报告

我准备了一个简单例子。假设你有一个叫 demo_qc/ 的文件夹，里面有 3 个样本的 FastQC 结果和 1 个 cutadapt 日志：

demo_qc/
├── sample1_fastqc.html
├── sample1_fastqc.zip
├── sample2_fastqc.html
├── sample2_fastqc.zip
├── sample3_fastqc.html
├── sample3_fastqc.zip
└── cutadapt.log

执行命令：

multiqc demo_qc/ -o my_first_report -f -n report_multi.html

运行后你会看到类似这样的日志（节选）：

// 控制台输出示例
[INFO   ]  MultiQC v1.14
[INFO   ]  Searching '/home/user/demo_qc'
[INFO   ]  Found 3 FastQC reports
[INFO   ]  Found 1 Cutadapt report
[INFO   ]  Compressing plot data
[INFO   ]  Report      : my_first_report/report_multi.html
[INFO   ]  Data        : my_first_report/multiqc_data

打开 my_first_report/report_multi.html，你就能看到漂亮的交互式报告了。里面有样本总览、每个质控指标的箱线图、热图、表格……

避坑：我曾有一次报告里只显示了一个样本，找了半天发现是我在 --ignore 参数里误写了文件名模式把其他样本跳过了。--verbose 就能看到它跳过了哪些文件。

下面这张图帮你理清整个调用流程：

3.6 小技巧：快速预览报告结构

第一次生成了报告后，我推荐你做一个动作：在浏览器打开 HTML，然后按 F12（开发者工具）看看它的 DOM 结构。你会发现每个图表都是一个 <div class="mqc-section">，这为我们后面自定义模板打下了基础——你可以用 CSS 直接选中它们。

// 举个 CSS 选择器的例子（别急着用，后面会细讲）
div.mqc-section[data-module="fastqc"] {
  border-left: 4px solid #3498db;
}

警告：如果你用 multiqc . 不加 -o，报告会直接生成在当前目录，把目录搞得乱糟糟。我强烈建议每次都用 -o 指定一个单独的文件夹。

好了，你的第一份报告已经躺在硬盘上了。接下来你会好奇：怎么让这份报告长得更好看？怎么改成公司统一的配色？别急——这些就是我们后面章节要聊的内容。