MultiQC 质控报告¶

MultiQC 是一个一键式质控报告汇总工具，能自动扫描目录下 150+ 种生信工具的日志文件，生成一份漂亮的交互式 HTML 报告，一眼看清所有样本的质量状况。

核心知识点¶

知识点	说明
工具定位	多工具、多样本质控结果汇总，生成统一 HTML 报告
最新版本	v1.34（2026.04，Seqera 维护）
开发者	Phil Ewels（Seqera Labs）
支持工具数	150+ 种（FastQC、STAR、Salmon、Picard、Samtools 等）
核心优势	零配置扫描、交互式图表、支持暗色模式、AI 摘要
输出格式	HTML 报告 + JSON/YAML/TSV 数据导出 + Parquet 文件
新功能	AI 报告摘要、Apache Parquet 输出、WebAssembly 浏览器端运行

安装配置¶

方法一：pip 安装（推荐）¶

# 用 pip 安装
pip install multiqc            # 安装 multiqc

# 或者用 uv（更快，不需要单独装 Python）
# uv tool install multiqc

multiqc --version              # 验证版本

方法二：Conda 安装¶

conda install -c bioconda multiqc  # 安装
multiqc --version                   # 验证

方法三：Docker¶

# 用 Docker 运行（不需要安装任何依赖）
docker run -v $PWD:/data ewels/multiqc /data  # 挂载当前目录并运行

基本使用¶

1. 最简单的用法（一条命令搞定）¶

# 扫描当前目录及子目录下所有工具的日志
multiqc .                      # 扫描当前目录

# 扫描指定目录
multiqc results/               # 扫描 results 目录下的所有文件

# 指定输出目录
multiqc results/ -o qc_report/ # 报告输出到 qc_report 目录

# 输出文件：
# multiqc_report.html          交互式 HTML 报告（用浏览器打开）
# multiqc_data/                包含解析后的数据文件

2. 常用参数¶

# 完整参数的常用命令
multiqc \
  -f \                          # 覆盖已有报告（force overwrite）
  -n "项目质控报告" \            # 自定义报告标题
  -o qc_reports/ \              # 输出目录
  --dirs \                      # 在报告中显示目录路径
  --dirs-depth 1 \              # 目录路径深度
  results/                      # 要扫描的目录

# 其他常用参数
multiqc results/ --ignore "*.bam"    # 忽略某些文件
multiqc results/ --module fastqc     # 只运行 FastQC 模块
multiqc results/ --exclude picard    # 排除 Picard 模块

3. 查看报告¶

# 用浏览器打开报告
# Linux
xdg-open multiqc_report.html   # 默认浏览器打开

# WSL（Windows 子系统）
explorer.exe multiqc_report.html  # 用 Windows 浏览器打开

# Mac
open multiqc_report.html        # 打开

高级用法¶

1. 自定义配置文件¶

# 创建 multiqc_config.yaml 文件
# 放在运行目录下会自动加载

# 报告标题和描述
title: "宏基因组项目质控报告"
subtitle: "2型糖尿病肠道菌群研究"
intro_text: "本报告汇总了所有样本的质控指标"

# 自定义模块顺序
module_order:
  - fastqc        # FastQC 放最前
  - fastp          # fastp 结果
  - star           # STAR 比对统计
  - featurecounts  # 计数统计

# 自定义报告外观
plots_force_flat: false   # 使用交互式图表（默认）
plots_force_interactive: true

# 导出格式
export_plots: true        # 导出图表为静态图片
data_format: "tsv"        # 数据导出格式

# 样本名清理（去掉文件扩展名等）
fn_clean_exts:
  - ".sorted"
  - ".bam"
  - ".fq.gz"
  - "_R1"
  - "_001"

2. 批量项目质控流程¶

#!/bin/bash
# qc_pipeline.sh - 完整的质控流程

RAWDIR="raw_data"           # 原始数据目录
QCDIR="qc_results"         # 质控结果目录
THREADS=8

mkdir -p $QCDIR/fastqc $QCDIR/fastp

# 第一步：FastQC 原始数据质控
fastqc -t $THREADS -o $QCDIR/fastqc $RAWDIR/*.fq.gz

# 第二步：fastp 数据预处理
for R1 in $RAWDIR/*_R1.fq.gz; do
    SAMPLE=$(basename $R1 _R1.fq.gz)
    R2=${R1/_R1/_R2}

    fastp \
      -i $R1 -I $R2 \
      -o $QCDIR/fastp/${SAMPLE}_R1.fq.gz \
      -O $QCDIR/fastp/${SAMPLE}_R2.fq.gz \
      -j $QCDIR/fastp/${SAMPLE}_fastp.json \
      -h $QCDIR/fastp/${SAMPLE}_fastp.html
done

# 第三步：MultiQC 汇总所有结果
multiqc $QCDIR/ \
  -o $QCDIR/multiqc/ \
  -n "全流程质控报告" \
  -f

echo "报告生成完毕: $QCDIR/multiqc/全流程质控报告.html"

3. AI 摘要功能（v1.29+）¶

# 生成带 AI 摘要的报告（需要 AI API 配置）
multiqc results/ --ai           # 启用 AI 摘要

# AI 会自动分析报告中的关键指标
# 告诉你哪些样本可能有问题、整体数据质量如何

4. 与 Nextflow/Snakemake 集成¶

# Snakemake 中使用 MultiQC
rule multiqc:
    input:
        expand("qc/{sample}_fastqc.zip", sample=SAMPLES),  # FastQC 结果
        expand("aligned/{sample}.sorted.bam", sample=SAMPLES)  # BAM 文件
    output:
        "reports/multiqc_report.html"  # 输出报告
    shell:
        "multiqc qc/ aligned/ -o reports/ -f"  # 运行 MultiQC

5. 自定义内容¶

# 在 multiqc_config.yaml 中添加自定义部分
custom_data:
  my_section:
    plot_type: "bargraph"        # 图表类型
    pconfig:
      title: "自定义统计"
      ylab: "数量"
    data:
      sample1:
        metric_a: 100
        metric_b: 200
      sample2:
        metric_a: 150
        metric_b: 180

常见报错与解决¶

报错信息	原因	解决方法
`No analysis results found`	目录下没有可识别的日志文件	确认路径正确，检查是否有支持的工具输出
`ModuleNotFoundError`	Python 依赖缺失	`pip install multiqc --upgrade` 升级
报告中缺少某个工具	该工具日志格式不对或被忽略	检查 `--ignore` 参数，或查看日志
样本名混乱	文件名太长或含特殊字符	用 `fn_clean_exts` 配置清理样本名
报告太慢	样本或文件太多	用 `--dirs-depth` 限制扫描深度
`Permission denied`	输出目录无写权限	检查目录权限或换输出路径

速查表¶

# ===== MultiQC 速查表 =====

# 安装
pip install multiqc                    # pip 安装
conda install -c bioconda multiqc      # conda 安装

# 基本用法
multiqc .                              # 扫描当前目录
multiqc results/ -o report/            # 指定输入和输出
multiqc results/ -f                    # 覆盖已有报告
multiqc results/ -n "项目报告"          # 自定义报告名

# 过滤控制
multiqc . --module fastqc              # 只运行指定模块
multiqc . --exclude picard             # 排除指定模块
multiqc . --ignore "*.bam"             # 忽略文件

# 报告定制
multiqc . --flat                       # 静态图表（非交互式）
multiqc . --interactive                # 强制交互式
multiqc . --export                     # 导出图片
multiqc . --ai                         # AI 摘要

# 数据导出
multiqc . --data-format tsv            # TSV 格式数据导出
multiqc . --data-format json           # JSON 格式

# 支持的主要工具
# FastQC, fastp, Trimmomatic          质控
# STAR, HISAT2, BWA, Salmon           比对/定量
# Picard, Samtools                     BAM处理
# featureCounts, HTSeq                 计数
# GATK, bcftools                       变异检测
# Kraken, Bracken, MetaPhlAn          宏基因组
# Bismark                              甲基化
# 更多见: https://multiqc.info