FASTQ Format Notes

FASTQ 格式规范

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

---

FASTQ 格式概述

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

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

关键约束

规则	说明
序列与质量等长	第 2 行和第 4 行的字符数必须相等
质量编码	Phred+33（Sanger/Illumina 1.8+）为主流，Phred+64 已淘汰
标识符唯一	同一文件内 @SEQ_ID 应唯一
多行序列	规范允许序列/质量跨多行，但现代工具通常假设单行

---

质量编码

Phred+33 (Sanger / Illumina 1.8+)

ASCII 33 ('!') = Q0
ASCII 73 ('I') = Q40
ASCII 126 ('~') = Q93 (理论最大)

常用范围: '!' (Q0) 到 'I' (Q40)

质量分数含义

质量值	错误概率	准确度
Q10	10%	90%
Q20	1%	99%
Q30	0.1%	99.9%
Q40	0.01%	99.99%

FastQTools 默认使用 Phred+33 编码（参数 qualityEncoding = 33）。

---

边界情况处理

空文件

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

空序列记录

@empty_read
                    ← 空序列
+
                    ← 空质量

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

极长序列

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

包含 N 碱基的序列

@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，忽略非标准字符

---

压缩格式支持

格式	扩展名	说明
纯文本	.fastq, .fq	直接读取
gzip	.fastq.gz, .fq.gz	zlib-ng / libdeflate 解压

解压策略

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

---

已知异常文件处理

截断文件

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

分隔符行含标识符

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

• 符合规范，FastQTools 正确解析（separator 字段保留完整内容）

Windows 换行符 (CRLF)

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

@ 字符出现在质量行

@read1
ACGT
+
@!''          ← 质量行以 @ 开头（Q31）

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

---

性能相关的格式考量

批量解析优势

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

压缩文件 I/O 瓶颈

• 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 性能数据