FastQTools

一个面向 FASTQ 文件的现代 C++ 高性能处理工具集，用于生物信息学场景中的质控、过滤和统计分析。

🧬 项目概览

FastQTools 专注于对高通量测序产生的 FASTQ 文件做高效、可组合的批处理，目标是：

• 更快：利用 C++20 与并行流水线模型，显著提升 I/O 与计算的吞吐。
• 更稳：采用工业级依赖与构建工具，保证在多平台上的可复现构建与运行。
• 更易扩展：通过清晰的接口与模块划分，让 CLI、库调用和二次开发都保持简单。

当前主要提供：

• stat 子命令：对单个 FASTQ 文件进行统计分析，输出碱基/质量分布等统计结果。
• filter 子命令：对 FASTQ 读段执行过滤与剪切（按质量、长度、N 比例等），并输出新的 FASTQ。

二次开发者也可以直接通过 include/fqtools/ 下的公共 API，将核心统计与处理能力集成到自己的 C++ 应用中。

---

🏗 架构设计

FastQTools 的整体架构围绕三个层次展开：

架构设计图

flowchart LR
    User[用户 / 调用者] --> CLI[CLI 层<br/>src/cli]
    CLI --> Commands[应用命令层<br/>src/cli/commands]
    Commands --> Core[核心库层<br/>Pipeline & Statistics]
    Core --> Pipeline[处理流水线模块<br/>src/pipeline]
    Core --> Stats[统计模块<br/>src/statistics]
    Core --> Common[通用工具模块<br/>src/modules/common]
    Commands -->|调用公共接口| API[公共 API<br/>include/fqtools]
    API --> Pipeline
    API --> Stats

Loading

1. CLI 层（Command-Line Interface）

   • 位置：src/cli/
   • 职责：
     • 解析命令行参数（使用 cxxopts）。
     • 将子命令名称（如 stat、filter）分派到对应的命令实现类。
     • 统一输出帮助信息与错误日志（使用 spdlog）。
   • 核心入口：src/cli/main.cpp
     • 初始化日志、打印软件信息与计时器。
     • 注册所有可用子命令（StatCommand、FilterCommand）。

2. 应用命令层（App Commands）

   • 位置：src/cli/commands/
   • 抽象接口：ICommand（i_command.h）
     • 提供统一的 execute(argc, argv) / getName() / getDescription() 接口。
     • 所有具体命令都实现该接口，便于 CLI 统一管理与扩展。
   • 典型实现：
     • StatCommand：
       • 解析 --input、--output、--threads 等参数。
       • 构造 fq::statistic::StatisticOptions，通过工厂函数 make_statistic_calculator 创建统计计算器。
       • 调用 run() 执行统计，生成统计结果文件。
     • FilterCommand：
       • 解析输入/输出 FASTQ、线程数、质量截断、最小/最大长度、最大 N 比例等参数。
       • 使用处理流水线接口 ProcessingPipelineInterface：
         • 设置输入/输出文件与并发配置。
         • 根据命令行选项装配一系列 谓词（Predicates） 与 变换器（Mutators），如：
           • MinQualityPredicate：按平均质量过滤读段。
           • MinLengthPredicate / MaxLengthPredicate：按读长过滤。
           • MaxNRatioPredicate：按 N 碱基比例过滤。
           • QualityTrimmer：对读段两端进行质量截断。
         • 调用 run() 启动流水线处理并返回统计信息。

3. 核心库层（Core Library / Pipeline & Statistics）

   • 位置：
     • 公开头文件：include/fqtools/
     • 实现文件：src/pipeline/、src/statistics/、src/modules/ 等。
   • 公共 API：
     • fqtools/processing_pipeline.h：
       • 暴露 ProcessingPipelineInterface 及其工厂函数：
         • create_processing_pipeline()：默认顺序/基础流水线。
         • create_tbb_processing_pipeline(...)：基于 Intel oneTBB 的高性能并行流水线。
     • fqtools/statistic_calculator.h：
       • 暴露 StatisticCalculatorInterface 与工厂函数 create_statistic_calculator() / make_statistic_calculator()。
   • 并发模型：
     • 使用 Intel oneTBB 的 parallel_pipeline 作为核心并发抽象。
     • 典型流水线阶段：
       • 读取 FASTQ 记录（I/O 阶段）。
       • 执行一系列过滤与变换（CPU 计算阶段）。
       • 写回结果和统计信息。
     • tbb::parallel_pipeline 能自动在不同阶段之间做背压控制，平衡 I/O 和计算速度，提高整体吞吐。
   • 通用工具模块：
     • 位置：src/modules/common/
     • 示例：
       • Timer：简单的 RAII 风格计时器，用于测量主流程与关键阶段的耗时。
       • 其他通用工具函数与基础数据结构。

整体上，FastQTools 通过：

• 清晰的三层结构（CLI → 命令层 → 核心库） 解耦界面与核心能力；
• 接口驱动设计（面向 *Interface 与工厂函数编程），便于替换实现与单元测试；
• 现代 CMake + Conan 管理构建与依赖，使工程在不同环境中保持一致性。

---

📁 目录结构（简要）

以下结构仅展示与使用和理解架构最相关的目录：

FastQTools/
├── include/
│   └── fqtools/                 # 公共 API 头文件（processing_pipeline, statistic_calculator, fq.h 等）
├── src/
│   ├── cli/                     # 命令行入口与子命令
│   │   ├── main.cpp             # 程序入口，注册并调度子命令
│   │   └── commands/            # 具体子命令实现（stat, filter 等）
│   ├── pipeline/                # 处理流水线实现（顺序版与 TBB 并行版工厂等）
│   ├── statistics/              # FASTQ 统计计算实现
│   ├── modules/                 # 通用模块（common 工具等）
│   └── ...
├── docs/
│   ├── user/                    # 使用文档
│   ├── design/                  # 架构与设计文档（如 architecture.md）
│   └── development/             # 开发相关指南
├── scripts/                     # 构建、测试、CI 辅助脚本
├── tests/                       # 单元测试
├── tools/                       # 性能基准与辅助工具
└── CMakeLists.txt 等            # 构建配置与依赖管理文件

---

🔧 核心技术栈

• 语言：C++20
• 构建系统：CMake（配合 Ninja）
• 依赖管理：Conan（或其他受支持的包管理器）
• 并发模型：Intel oneTBB parallel_pipeline
• 命令行解析：cxxopts
• 日志：spdlog
• 测试：GoogleTest

在早期版本中，项目曾尝试全面使用 C++20 模块，但由于当时编译器与工具链支持度的限制，目前采用传统 .h/.cpp 结构 + 逻辑模块化的 CMake 目标拆分，在保持稳定构建的前提下，仍旧按照“高内聚、低耦合”的模块化原则组织代码。

---

🚀 构建与运行

环境要求

• CMake ≥ 3.20
• 支持 C++20 的编译器（GCC 11+ / Clang 12+ / MSVC 2019+）
• Ninja（推荐）
• Conan（用于自动拉取依赖，推荐）

构建示例

# 推荐：使用脚本一键构建
./scripts/build.sh clang Release

# 或手动使用 CMake + Conan
conan install config/dependencies/ --output-folder=build/conan-release --build=missing -s build_type=Release
cmake -S . -B build-clang-release \
  -G "Ninja" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE=build/conan-release/conan_toolchain.cmake
cmake --build build-clang-release

运行 CLI

./build-clang-release/FastQTools --help

查看某个子命令的帮助（如 filter）：

./build-clang-release/FastQTools filter --help

---

✅ 主要功能与使用场景

• FASTQ 质量统计（stat）

  • 读取 FASTQ 文件，生成读段数量、长度分布、碱基组成、质量值分布等统计信息。
  • 适用于：测序数据质控、上游/下游工具性能评估、数据特征快速浏览等场景。

• FASTQ 过滤与剪切（filter）

  • 按以下条件过滤读段：
    • 最小平均质量（--min-quality）
    • 最小/最大读长（--min-length / --max-length）
    • 最大 N 比例（--max-n-ratio）
  • 对读段进行质量截断（--trim-quality + --trim-mode），去除低质量尾部/两端碱基。
  • 自动利用多线程与并行流水线提高处理速度。
  • 适用于：下游比对/组装前的数据清洗、构建高质量数据子集、快速预处理大规模 FASTQ 数据。

• 库级别集成能力

  • 通过 include/fqtools/ 暴露的接口，可以在其他 C++ 项目中：
    • 嵌入 FASTQ 统计流程。
    • 作为一个可配置的数据处理流水线组件进行复用。

---

🧪 测试

运行测试用例：

./scripts/test.sh
# 或
ctest --preset release

---

📄 许可证

本项目基于 MIT License 发布，详情参见根目录下的 LICENSE 文件。