本页面记录 FASTQ 格式的规范细节、边界情况处理,以及 FastQTools 在实现中遇到的已知异常文件处理策略。

FASTQ 文件由四行一组的记录构成:

@SEQ_ID ← 第1行:标识符(以 @ 开头)
GATTTGGGGTTCAAAG... ← 第2行:DNA 序列
+ ← 第3行:分隔符(+ 开头,后接可选标识)
!''*((((***+))%%%... ← 第4行:质量分数(ASCII 编码)

ASCII 33 ('!') = Q0
ASCII 73 ('I') = Q40
ASCII 126 ('~') = Q93 (理论最大)
常用范围: '!' (Q0) 到 'I' (Q40)

FastQTools 默认使用 Phred+33 编码(参数 qualityEncoding = 33)。

• FastQTools 的 FastqReader 对空文件返回 nextBatch() == false,不抛异常
• stat 命令输出全零统计结果
• filter 命令生成空输出文件

@empty_read
 ← 空序列
+
 ← 空质量

• FastqRecord::length() 返回 0
• 被 MinLengthPredicate 过滤(任何阈值 > 0 即过滤)

• FastqBatch 使用连续 buffer_ 存储,单条记录长度仅受 maxBufferBytes 限制
• 默认 batchCapacityBytes 足以容纳 PacBio/ONT 长读段

@read_with_N
GATNNNNTTCAAAG
+
!''****+))%%%!

• FastqRecord::nRatio() 计算 N 碱基占比
• MaxNRatioPredicate 按阈值过滤高 N 比例读段

• 序列中可能出现 IUPAC 简并碱基(R/Y/S/W/K/M 等)
• fq::core::SequenceUtils::isValidBase() 仅认可 A/T/C/G/N
• GC 含量计算仅统计 G 和 C,忽略非标准字符

• 读取: 根据文件扩展名自动选择解压模式
• 写入: .gz 后缀自动启用 gzip 压缩
• 缓冲区: readChunkBytes(读取块大小)和 zlibBufferBytes(zlib 缓冲区)可调

• 文件在记录中间截断时,FastqReader 丢弃不完整记录
• 记录日志警告,不抛异常(保证已读取的完整记录可用)

@read1
ACGT
+read1 ← 分隔符行重复标识符
!''*

• 符合规范,FastQTools 正确解析(separator 字段保留完整内容)

• FastqReader 自动处理 \r\n 换行符
• 在解析时 strip 尾部 \r

@read1
ACGT
+
@!'' ← 质量行以 @ 开头(Q31)

• 这是合法的 Phred+33 质量值(@ = ASCII 64 = Q31)
• FastQTools 通过四行一组的严格解析避免与标识符行混淆

• FastqBatch 连续内存 + string_view 零拷贝设计
• 避免每条记录的独立 std::string 分配
• 典型场景下,10K 条记录共享一个连续缓冲区

• gzip 解压为单线程(zlib 限制)
• 建议使用 libdeflate 加速解压
• 解压速度通常是整个流水线的瓶颈

• FASTQ format - Wikipedia
• Cock et al., 2009 - The Sanger FASTQ file format
• Illumina FASTQ Format

• API Reference — FastqReader / FastqRecord API
• Architecture — 数据模型设计
• Performance Benchmarks — I/O 性能数据