🌌 FlowMeta 完整教程

项目名称： FlowMeta - 自动化宏基因组学分析流水线

代码仓库： https://github.com/SkinMicrobe/FlowMeta

作者： 曾东强 (Dongqiang Zeng) · 南方医科大学

邮箱： interlaken@smu.edu.cn

📊 一、技术路线总览

FlowMeta 是一个端到端的宏基因组学分析流水线，整合了 10 个处理步骤，从原始 FASTQ 文件到最终的物种丰度矩阵。

完整流水线流程图

1
fastp 质控
🧬 fastp
01-raw → 02-qc
→
2
完整性验证
✓ pigz
02-qc 检查
→
3
宿主去除
🧬 Bowtie2
02-qc → 03-hr/04-bam
4
验证
✓ pigz
03-hr 检查
→
5
宿主提取
🧬 samtools
04-bam → 05-host
→
6
数据库缓存
💾 /dev/shm
Kraken2 → RAM
7
物种分类
🧬 Kraken2
03-hr → 06-ku/07-bracken
→
8
验证
✓ 内置验证
06-ku 检查
→
9
宿主过滤
🧬 Kraken2
06-ku → 08-ku2
10
矩阵合并
🐍 pandas
08-ku2 → 09-mpa

数据流向总览

原始数据输入 01-raw/ ├── SAMPLE001_1.fastq.gz ├── SAMPLE001_2.fastq.gz ├── SAMPLE002_1.fastq.gz └── SAMPLE002_2.fastq.gz ↓ 步骤 1: fastp 质量控制与修剪 02-qc/ ├── SAMPLE001_1.fastq.gz # 修剪后的序列 ├── SAMPLE001_2.fastq.gz ├── SAMPLE001_fastp.html # 质控报告 ├── SAMPLE001_fastp.json # 质控统计 └── SAMPLE001.task.complete # 完成标记 ↓ 步骤 3: Bowtie2 宿主序列去除 03-hr/ 04-bam/ ├── SAMPLE001_host_remove_R1.fastq.gz ├── SAMPLE001_host_remove_R2.fastq.gz ├── SAMPLE001.task.complete └── ... ├── SAMPLE001.bam # 比对文件 ├── SAMPLE001.bam.bai # 索引文件 └── ... ↓ 步骤 5 (可选): 宿主序列提取 05-host/ ├── SAMPLE001_host_R1.fastq.gz # 用于 HLA/mtDNA 分析 └── SAMPLE001_host_R2.fastq.gz ↓ 步骤 7: Kraken2 物种分类 06-ku/ 07-bracken/ ├── SAMPLE001.kraken.report.std.txt # 分类报告 ├── SAMPLE001.kraken.output.std.txt # 分类详情 ├── SAMPLE001.kraken.task.complete └── ... ↓ 步骤 9: 宿主分类过滤 + 重新分类 08-ku2/ ├── SAMPLE001.nohuman.kraken.mpa.std.txt # MPA 格式 ├── SAMPLE001.nohuman.kraken.report.std.txt # 过滤后报告 ├── SAMPLE001.nohuman.bracken # Bracken 丰度 └── SAMPLE001.task.complete ↓ 步骤 10: 结果矩阵合并 09-mpa/ ├── prefix_combined.otu.tsv # OTU 表 (物种 × 样本) ├── prefix_combined.mpa.tsv # MPA 表 (分类路径 × 样本) ├── prefix_combined.bracken.tsv # Bracken 合并表 └── step6.task.complete

🔬 二、详细技术路线图

1
FASTQ 质量控制与修剪 (fastp)

📝 功能描述

使用 fastp 对原始 FASTQ 文件进行质量控制，包括：

  • 接头序列去除
  • 低质量碱基修剪
  • 长度过滤
  • 质量过滤
  • 生成质控报告（HTML/JSON）

🔧 关键参数

参数默认值说明
--fastp_length_required50最小读长
--fastp_retries3失败重试次数
--skip_integrity_checksFalse跳过完整性检查
输入: 01-raw/SAMPLE001_1.fastq.gz, SAMPLE001_2.fastq.gz ↓ fastp 处理 中间文件 (in-place 生成) ├── fastp.json # JSON 质控报告 ├── fastp.html # HTML 质控报告 ├── fastp.fastq.gz # 修剪后的 R1 (重命名为 sample_1.fastq.gz) └── fastp.fastq.gz # 修剪后的 R2 (重命名为 sample_2.fastq.gz) ↓ 输出: 02-qc/SAMPLE001_1.fastq.gz, SAMPLE001_2.fastq.gz SAMPLE001_fastp.html, SAMPLE001_fastp.json SAMPLE001.task.complete
💡 批处理模式： 使用 --batch 参数控制并行处理的样本数，默认为 2。每个样本使用 --threads 指定的线程数运行 fastp。
2
fastp 结果完整性验证

验证 fastp 输出文件的完整性，确保 FASTQ 文件未损坏。使用 pigz 进行压缩测试。

检查内容: ├── 文件存在性检查 ├── 文件大小非空检查 └── pigz -t 压缩测试 ↓ 返回: (有效样本数, 无效样本数) 无效样本处理: ├── 记录到 0-corrupted-samples.tsv ├── 移动文件到 00-corrupted/ 目录 └── 从流水线中排除
⚠️ 注意： 步骤 2 默认不启用，需要使用 --check_result 参数。如果使用 --skip_integrity_checks，则即使指定 --check_result 也会跳过此步骤。
3
宿主序列去除 (Bowtie2)

📝 功能描述

使用 Bowtie2 将序列比对到宿主参考基因组，去除宿主序列：

  • 双端序列比对
  • 未比对序列输出
  • BAM 文件生成
  • 支持敏感模式

🔧 关键参数

参数默认值说明
--host_retries3失败重试次数
--suffix1_1.fastq.gzR1 文件后缀
--suffix2_2.fastq.gzR2 文件后缀
输入: 02-qc/SAMPLE001_1.fastq.gz, SAMPLE001_2.fastq.gz ↓ Bowtie2 --very-sensitive 比对过程: ├── 比对模式: --very-sensitive ├── 线程数: --threads (默认 32) ├── 输入: R1 + R2 FASTQ └── 参考: $db_bowtie2 索引 ↓ 输出文件: 03-hr/ ├── SAMPLE001_host_remove_R1.fastq.gz # 未比对 R1 ├── SAMPLE001_host_remove_R2.fastq.gz # 未比对 R2 └── SAMPLE001.task.complete 04-bam/ ├── SAMPLE001.bam # 比对 BAM ├── SAMPLE001.bam.bai # 索引 └── ...
💡 性能优化： 使用 --very-sensitive 模式确保最大比对敏感度。调整 --threads 以匹配可用 CPU 核心数。
4
宿主去除结果验证

验证步骤 3 输出的 FASTQ 文件完整性，确保所有文件均正确生成。

检查: ├── R1 文件: *_host_remove_R1.fastq.gz ├── R2 文件: *_host_remove_R2.fastq.gz └── 验证工具: pigz -t ↓ 返回: (有效样本数, 无效样本数) 验证失败的文件会被重新处理
5
宿主序列提取 (samtools fastq, 可选)

📝 功能描述

从 BAM 文件中提取比对到宿主基因组的序列，用于后续分析：

  • HLA 分型分析
  • 线粒体 DNA 分析
  • 宿主基因组变异检测

🔧 关键参数

参数默认值说明
--skip_host_extractFalse跳过此步骤
modemapped_anypair提取模式
输入: 04-bam/SAMPLE001.bam ↓ samtools fastq -F 0x2 提取模式: ├── mapped_anypair: 任一端比对 ├── mapped_all: 两端均比对 ├── unmapped: 未比对 └── ... ↓ 输出: 05-host/SAMPLE001_host_R1.fastq.gz SAMPLE001_host_R2.fastq.gz
💡 跳过此步骤： 如果不需要宿主序列进行下游分析，使用 --skip_host_extract 可以节省时间。
6
Kraken2 数据库缓存 (共享内存)

📝 功能描述

将 Kraken2 数据库复制到共享内存（/dev/shm/），显著加速分类步骤：

  • 减少 I/O 等待时间
  • 利用 RAM 高速访问
  • 可选 vmtouch 预加载

🔧 关键参数

参数默认值说明
--copy_db_to_shmTrue启用缓存
--shm_path/dev/shm/k2ppf缓存路径
--no_shm-禁用缓存
检查: 数据库已存在? ├── 是: 跳过复制 └── 否: 执行复制 ↓ 数据库文件验证: ├── hash.k2d # 哈希索引 ├── opts.k2d # 选项文件 └── taxo.k2d # 分类学信息 ↓ 复制到: /dev/shm/k2ppf/ 可选: vmtouch -t 预加载到内存
💡 内存要求： 标准数据库约 100GB，确保共享内存足够大。使用 df -h /dev/shm 检查可用空间。
⚠️ 注意： 如果共享内存不足，流水线会自动回退到使用磁盘上的数据库。
7
物种分类 (Kraken2 + Bracken)

📝 功能描述

使用 Kraken2 进行物种分类，可选运行 Bracken 丰度估计：

  • k-mer 精确匹配分类
  • 快速分类速度
  • Bracken 丰度校正
  • 支持多分类级别

🔧 关键参数

参数默认值说明
--kraken_retries3失败重试次数
--enable_bracken_step7False步骤 7 运行 Bracken
--batch2并行样本数
输入: 03-hr/SAMPLE001_host_remove_R1.fastq.gz SAMPLE001_host_remove_R2.fastq.gz ↓ Kraken2 分类 Kraken2 命令: kraken2 --db $db_kraken \ --threads 32 \ --report SAMPLE001.kraken.report.std.txt \ --output SAMPLE001.kraken.output.std.txt \ --paired 03-hr/SAMPLE001_host_remove_R1.fastq.gz \ 03-hr/SAMPLE001_host_remove_R2.fastq.gz ↓ 输出: 06-ku/ ├── SAMPLE001.kraken.report.std.txt # 分类报告 ├── SAMPLE001.kraken.output.std.txt # 分类详情 └── SAMPLE001.kraken.task.complete 如果启用 Bracken: 07-bracken/ ├── SAMPLE001.S.bracken # 种级 ├── SAMPLE001.G.bracken # 属级 └── SAMPLE001.F.bracken # 科级
💡 批处理模式： Kraken2 分类对内存需求较高，建议 --batch 设置为 1-2。每个样本使用 --threads 指定的线程数。
8
Kraken 报告验证

验证 Kraken2 报告文件的格式和内容完整性。

验证项: ├── 文件存在性 ├── 文件格式正确性 ├── 报告头格式 └── 至少有一条分类记录 ↓ 返回: (有效样本数, 无效样本数) 无效样本: ├── 记录日志警告 └── 继续处理其他样本
9
宿主分类过滤 + 重新分类

📝 功能描述

从 Kraken 报告中移除宿主相关分类（如人类），重新运行 Bracken：

  • 移除人类/宿主 taxid
  • 保留微生物分类
  • 重新估计丰度
  • 计算多样性指数（可选）

🔧 关键参数

参数默认值说明
--min_count4Bracken 最小计数
输入: 06-ku/SAMPLE001.kraken.report.std.txt ↓ 过滤宿主分类 处理: ├── 移除人类 taxid (9606, 9605, ...) ├── 保留微生物分类 ├── 生成 MPA 格式 └── 生成过滤后报告 ↓ 输出: 08-ku2/ ├── SAMPLE001.nohuman.kraken.mpa.std.txt # MPA 格式 ├── SAMPLE001.nohuman.kraken.report.std.txt # 过滤后报告 └── SAMPLE001.task.complete ↓ 重新运行 Bracken Bracken 输出: ├── SAMPLE001.nohuman.bracken # 重新估计的丰度 ├── SAMPLE001.nohuman.S.bracken ├── SAMPLE001.nohuman.G.bracken └── SAMPLE001.nohuman.F.bracken 可选: 计算多样性指数 ├── Shannon's diversity ├── Simpson's index ├── Berger-Parker dominance └── Fisher's alpha (需要 scipy)
💡 为什么需要步骤 9： 步骤 7 的 Kraken 报告包含宿主分类，这会影响微生物群落分析。步骤 9 移除宿主分类后重新运行 Bracken，获得更准确的微生物丰度估计。
10
结果矩阵合并

📝 功能描述

合并所有样本的结果为统一矩阵，便于下游分析：

  • OTU 表生成
  • MPA 格式合并
  • Bracken 表合并
  • 支持项目前缀

🔧 关键参数

参数默认值说明
--project_prefix""输出文件前缀
输入: 所有样本的 08-ku2/ 目录 ├── SAMPLE001.nohuman.kraken.mpa.std.txt ├── SAMPLE001.nohuman.bracken ├── SAMPLE002.nohuman.kraken.mpa.std.txt ├── SAMPLE002.nohuman.bracken └── ... ↓ 调用 helper 脚本 helper/kreport2mpa.py ├── 转换 Kraken 报告为 MPA 格式 └── 生成物种路径 helper/combine_mpa.py ├── 合并所有样本的 MPA 文件 └── 生成 combined.mpa.tsv helper/combine_bracken_outputs.py ├── 合并所有样本的 Bracken 表 └── 生成 combined.bracken.tsv helper/kraken2otu.py ├── 生成 OTU 表 └── 生成 combined.otu.tsv ↓ 输出: 09-mpa/ ├── prefix_combined.mpa.tsv # 物种路径 × 样本矩阵 ├── prefix_combined.bracken.tsv # Bracken 丰度表 ├── prefix_combined.otu.tsv # OTU 表 └── step6.task.complete 格式示例: # combined.mpa.tsv k__Bacteria|...|g__Escherichia|m_coli|s__coli 1000 500 0 k__Bacteria|...|g__Lactobacillus|... 500 2000 100 ...
💡 步骤 10 前置条件： 需要步骤 9 的输出文件：*.nohuman.kraken.mpa.std.txt 和 *.bracken。流水线启动时会检查这些文件是否存在。
⚠️ pandas/numpy 依赖： 步骤 10 需要 pandas 和 numpy。如果这些包未安装，run_merge_step 将为 None，流水线会在步骤 10 之前停止。

🧰 三、环境准备

3.1 系统要求

项目最低要求推荐配置
操作系统Linux / WSLUbuntu 20.04+, CentOS 7+, Rocky Linux 8+
Python 版本≥ 3.83.9 或 3.10
内存32 GB128 GB+（大规模样本）
存储SSDNVMe SSD（加速 I/O）
CPU8 核心32+ 核心（支持并行）
共享内存≥ 100 GB≥ 200 GB（标准数据库）

3.2 创建 Conda 环境

# 方法 1：使用项目提供的 environment.yml
conda env create -f environment.yml
conda activate meta

# 方法 2：手动创建环境
conda create -n flowmeta python=3.10 -y
conda activate flowmeta

# 安装生物信息学工具
conda install -c bioconda fastp bowtie2 samtools kraken2 bracken -y
conda install -c conda-forge scipy pandas numpy pigz seqkit -y

# 验证安装
fastp --version
bowtie2 --version
samtools --version
kraken2 --version
bracken --version
python -c "import pandas, numpy; print('Python OK')"

3.3 安装 FlowMeta

# 方式 1：从 PyPI 安装（推荐）
pip install flowmeta

# 方式 2：从本地 wheel 文件安装
pip install dist/flowmeta-0.1.5-py3-none-any.whl

# 方式 3：开发模式安装
git clone https://github.com/SkinMicrobe/FlowMeta.git
cd FlowMeta
pip install -e .

# 验证安装
flowmeta_base --help

🧬 四、数据库准备

4.1 Kraken2 标准数据库

# 创建数据库目录
mkdir -p /mnt/db/kraken2
cd /mnt/db/kraken2

# 下载标准数据库（约 100GB）
wget https://benlangmead.github.io/aws-indexes/k2/k2_standard_20240112.tar.gz
tar -xzf k2_standard_20240112.tar.gz

# 验证数据库文件
ls k2_standard_20240112/
# 应包含：hash.k2d, opts.k2d, taxo.k2d, database.k2d, read_library.bin

4.2 Bowtie2 宿主索引（GRCh38）

# 创建索引目录
mkdir -p /mnt/db/bowtie2
cd /mnt/db/bowtie2

# 下载人类参考基因组
wget https://ftp.ncbi.nlm.nih.gov/genomes/all/\
GCA/000/001/405/GCA_000001405.28_GRCh38.p13/\
GCA_000001405.28_GRCh38.p13_genomic.fna.gz

# 可选：去除替代序列和补丁序列
seqkit grep -rvp "alt|PATCH" GCA_000001405.28_GRCh38.p13_genomic.fna.gz \
  > GRCh38_noalt.fna

# 构建 Bowtie2 索引
bowtie2-build GRCh38_noalt.fna /mnt/db/bowtie2/GRCh38_noalt_as/GRCh38_noalt_as

# 验证索引文件
ls /mnt/db/bowtie2/GRCh38_noalt_as/
# 应包含：*.bt2 文件（6 个文件）

🚀 五、快速开始

5.1 基本命令

# 完整流水线运行
flowmeta_base \
  --input_dir /mnt/data/flowmeta/01-raw \
  --output_dir /mnt/data/flowmeta/results \
  --db_bowtie2 /mnt/db/bowtie2/GRCh38_noalt_as/GRCh38_noalt_as \
  --db_kraken /mnt/db/kraken2/k2_standard_20240112 \
  --threads 32 \
  --batch 2

5.2 从步骤 10 恢复（仅合并结果）

# 这正是您之前运行的命令
flowmeta_base \
  --input_dir /mnt/cephfs/s2z4/01-smooth/01-mg/01-raw \
  --output_dir /mnt/cephfs/s2z4/01-smooth/01-mg \
  --db_bowtie2 $db_bowtie2 \
  --db_kraken $db_kraken \
  --threads 32 \
  --step 10 \
  --batch 1

5.3 参数速查表

参数默认值说明
--input_dir-原始 FASTQ 目录
--output_dir-输出目录
--db_bowtie2-Bowtie2 索引前缀
--db_kraken-Kraken2 数据库目录
--threads32每进程线程数
--batch2并行样本批次
--stepNone从步骤 N 恢复 (1-10)
--step_onlyFalse仅运行指定步骤
--forceFalse强制重新运行
--project_prefix""步骤 10 输出前缀
--seFalse单端测序模式
--skip_integrity_checksFalse跳过完整性检查
--skip_host_extractFalse跳过步骤 5
--no_shm-禁用共享内存缓存
--fastp_length_required50fastp 最小读长
--enable_bracken_step7False步骤 7 运行 Bracken
--min_count4Bracken 最小计数

🛡️ 六、检查点与恢复机制

FlowMeta 使用 .task.complete 文件标记每个样本的处理状态，支持断点续跑：

标记文件位置对应步骤
*.task.complete02-qc/步骤 1: fastp 质控完成
*.task.complete03-hr/步骤 3: 宿主去除完成
*.kraken.task.complete06-ku/步骤 7: Kraken 分类完成
*.task.complete08-ku2/步骤 9: 宿主过滤完成
💡 恢复策略：
  • 使用 --step N 从步骤 N 开始运行
  • 已完成的样本会被自动跳过
  • 使用
  • --force 强制重新运行所有样本
  • 删除特定样本的 .task.complete 文件可单独重新处理该样本

❓ 七、常见问题

7.1 技术问题

问题解决方案
如何从特定步骤恢复？使用 --step N 参数
如何强制重新运行某个步骤？使用 --step N --force
共享内存缓存有什么作用？将 Kraken2 数据库复制到 /dev/shm/ 加速分类
如何处理单端测序数据？使用 --se 标志
如何跳过完整性检查？使用 --skip_integrity_checks
步骤 10 依赖什么？需要步骤 9 的输出文件
如何增加并行处理的样本数？调整 --batch 参数

7.2 性能优化建议

场景优化方法
Kraken2 分类慢使用共享内存缓存 /dev/shm
大量小文件增加 --batch 值
I/O 瓶颈使用 NVMe SSD 存储
内存不足减少 --batch 和 --threads
需要快速结果使用 --skip_integrity_checks

🤝 八、支持与引用

📧 技术支持

维护者： 曾东强 (Dongqiang Zeng)

机构： 南方医科大学 (Southern Medical University)

邮箱： interlaken@smu.edu.cn

引用

如果 FlowMeta 对您的研究有帮助，请引用我们的代码仓库：

@software{flowmeta2025,
  title = {FlowMeta: Automated End-to-End Metagenomic Profiling Pipeline},
  author = {Zeng, Dongqiang},
  year = {2025},
  url = {https://github.com/SkinMicrobe/FlowMeta},
  institution = {Southern Medical University}
}

相关工具

🎉 祝您分析顺利！Happy Sequencing!