第4章 输入数据格式：支持的工具与输出文件解析
咱们这一章聊的是MultiQC真正干活儿的基础——它到底能吃哪些工具的输出。说白了，MultiQC就是个“文件嗅探器”，它不认识原始的FASTQ、BAM，它只认特定工具写出来的总结文件。我最早做审计项目时，第一周就把精力花在了理解这些输出文件的结构上。你想想看，如果连MultiQC怎么找到、怎么解析都不知道，后面写SOP、做验证都是空中楼阁。
4.1 FastQC——最基础的质检输出
FastQC大概是每个生信项目碰到的第一个工具。它检查测序质量，输出一堆HTML和压缩包。MultiQC真正吃的是那个_fastqc.zip文件，或者更准确地说，是zip里面的fastqc_data.txt。我习惯在项目里保留所有zip，但审计时经常会有人只给了HTML，那MultiQC就完全读不了——血的教训。
关键文件匹配模式：
*_fastqc.zip # MultiQC按这个glob找到文件
*/fastqc_data.txt # 如果zip被提前解压，也能读
*/fastqc_report.html # MultiQC不读HTML！别只存这个FastQC会输出几十个统计值，比如总读长、GC含量、过表达序列比例。MultiQC把这些字段整理到一张表里。你在审计时需要知道：FastQC输出文件中的>Per base sequence quality部分不是数字表格，而是文本格式，MultiQC会按行解析。我曾经见过有人手动修改了zip里的文本，结果解析出来的quality warning数全是错的。
✅ 审计必查项：确认FastQC zip未被手动篡改，校验文件的MD5。
💡 如果你的项目用了多个版本的FastQC，输出的文本格式略有差异（比如旧版没有total sequences那行），MultiQC都能自动容错。但别指望它能处理完全改写的文件格式。
4.2 STAR——比对工具的日志才是宝藏
STAR输出很多文件：BAM、SJ.out.tab、Log.final.out。嗯，MultiQC只认那个Log.final.out。我理解很多人喜欢看SJ文件，但MultiQC从日志里提取的是比对率、多比对率、剪切位点统计等宏观指标。审计场景下，这些数据比剪切位点详情更敏感——可以直接反映比对异常。
| STAR输出文件 | MultiQC是否读取 | 关键信息 |
|---|---|---|
| Log.final.out | 是 | 总reads、唯一比对率、多比对率、总比对长度 |
| Log.out | 否 | 运行详细日志（不用于报告） |
| SJ.out.tab | 否 | 剪切位点（支持者少，MultiQC暂不纳入） |
| Log.progress.out | 否 | 运行进度（无汇总价值） |
举一个我实际遇到的坑：有一次审计时发现某个样本的比对率异常低（40%），但STAR的Log.final.out文件显示是“0 mapped”。后来查实是用户把两个样本的Log.final.out文件名写反了。MultiQC按文件名排序，导致数据张冠李戴。嗯，所以文件名规则特别重要。
STAR的Log.final.out格式是固定的键值对，MultiQC按行解析。你可以在终端里直接用cat看一下：
cat Log.final.out | head -20
Started job on | 2023-07-15 14:30:22
Started mapping on | 2023-07-15 14:33:10
Finished on | 2023-07-15 14:35:44
Mapping speed, Million of reads per hour | 782.45
Number of input reads | 12345678
Average input read length | 151
Uniquely mapped reads number | 11223344
Uniquely mapped reads % | 90.94%
注意，这个文件没有表头，MultiQC靠键名识别。一旦有人把“Uniquely mapped reads %”改成了“Unique %”，MultiQC就认不出来了。所以版本变更或自定义修改都是审计风险点。
4.3 Salmon——定量工具的多文件命名规范
Salmon比STAR复杂一点，它输出一个目录，里面有quant.sf、aux_info、libParams等。MultiQC直接从quant.sf里提取reads数、映射率、有效长度等。关键点：Salmon输出的cmd_info.json包含了运行参数，MultiQC也读这个。
实际项目中，我见过有人把Salmon输出目录和STAR输出目录混放在一起。MultiQC怎么区分？靠glob模式——它会搜索**/quant.sf，跟STAR的**/Log.final.out完全不冲突。但如果你改动了文件名或路径结构，就会漏掉。
文件搜索优先级：
# Salmon
**/quant.sf # 主计数文件
**/cmd_info.json # 参数信息（可选）
**/libParams/flenDist.txt # 插入片段长度分布（可选）
# 注意：MultiQC不会读salmon的meta_info.json，只读cmd_info.json⚠️ Salmon有两种模式：--libType为A（自动检测）时，libParams目录里会包含推断的文库类型。MultiQC只读取它，不会去校验一致性。如果你需要审计文库类型是否被正确推断，建议额外检查Salmon日志，不要完全信任MultiQC的报告。
4.4 其他工具输出格式一览
除了FastQC、STAR、Salmon，MultiQC还支持50多种工具。我挑几个审计里最高频的说。
- HISAT2：读
*.hisat2.log，包含比对率和时间。 - Bowtie2：读
*.bowtie2.log，类似HISAT2但键名不同。 - featureCounts：读
*.summary文件，每行对应一个统计类别。 - RSEM：读
*.stat或*.cnt，与Salmon格式不同。 - Picard：读各种
*metrics.txt，比如alignment_summary_metrics。
每个工具的输出格式都有细微差异。我在写SOP时，习惯建一个对照表，列出MultiQC能解析的字段原文。这样审计员可以对报告里的数字回溯源文件，确认没有失真。
4.5 MultiQC如何“找到”这些文件？
MultiQC不是漫无目的地遍历整个项目。它有一份预置的“文件搜索模式”列表（由每个工具的模块定义）。你使用multiqc .时，它会在当前目录递归匹配所有已知模式。你可以通过-m参数指定只加载某些模块，加快速度。
我习惯用--data-dir把中间文件保存下来，方便审计回溯。
# 只分析FastQC和STAR，并保留解析后的中间JSON
multiqc . -m fastqc -m star --data-dir这个命令会生成multiqc_data/目录，里面每个样本对应的原始数值都存成了JSON。审计时直接对那个JSON做版本控制特别好用。
✅ 建议：在SOP中要求CI/CD job里必须用--data-dir，这样如果有人质疑报告的数值，可以直接找中间JSON，而不是去翻几千个原始输出文件。
好了，咱们现在有了数据源。下一章我会演示怎么把这些文件正确喂给MultiQC，以及怎么用multiqc_config.yaml控制搜索行为。但今天不说了，先消化这些文件格式的知识吧。