kseq.h是Heng Li开发的轻量级C头文件库，专为高效解析FASTA/FASTQ设计，天然支持gzip压缩文件，一次kseq_read()自动完成四行结构解析与解压，性能远超手写逐行读取；需正确使用KSEQ_INIT、校验双端ID配对、区分Phred编码体系，并注意内存管理与错误返回值处理。
用kseq.h读取FASTQ比手写解析快十倍
直接用C++标准库逐行读、手动切分四行结构，不仅容易漏掉换行符或gzip流边界，还会在大文件上严重拖慢速度。kseq.h是Heng Li开发的轻量级头文件，专为FASTA/FASTQ设计，底层调用zlib，天然支持.gz文件，且一次调用kseq_read()就自动完成四行解析和解压。
关键点在于初始化方式：KSEQ_INIT(gzFile, gzread)必须放在全局或函数外，否则编译报错；kseq_t结构体里seq.s存序列，qual.s存质量字符串，name.s是ID行（不含@）。
常见错误包括：
- 忘记
gzclose(fp)导致文件句柄泄漏，尤其批量处理时很快耗尽系统限制 - 误把
qual.s当整数数组用——它只是ASCII字符指针，需转Phred值时得减去33（Phred+33） - 没检查
kseq_read()返回值：-1表示EOF，0表示成功，负数其他值代表读取错误（如损坏的gzip）
双端FASTQ必须同步读取，不能各自open两个文件
双端数据（R1/R2）的每条read在物理上是配对的，但文件里顺序完全独立。如果分别打开R1.fastq.gz和R2.fastq.gz并各自kseq_read()，极大概率在某一轮中R1读到第1001条而R2还在第1000条，配对关系彻底错乱。正确做法是用同一个循环体，交替调用两次kseq_read()，并严格校验ID是否匹配。
立即学习“C++免费学习笔记（深入）”；
校验ID不能只比前半段——Illumina的/1和/2后缀必须一致，且中间坐标部分（如1101:12345:67891）要完全相同。示例代码片段中常犯的错是用strcmp(ks1->name.s, ks2->name.s)直接比较，这会因/1和/2不同而失败，应先截断后缀再比对。
性能影响明显：同步读取虽增加一次字符串处理开销，但避免了后续所有配对纠错逻辑，整体耗时反而降低30%以上。
内存敏感场景下，别用std::string存每条read
一条250bp的read，加上质量字符串和ID，单条占用约1KB内存。1亿条read就是100GB——远超多数服务器内存。kseq.h默认用realloc动态扩容seq.s，但频繁分配释放小块内存会产生大量碎片。
更稳妥的做法是预分配缓冲区：用ks->seq.l = 0清空长度后，直接memcpy到自定义大缓冲区，并记录每条read在其中的偏移。这样1GB内存可缓存百万级read，配合OpenMP做批处理时效率更高。
注意两点：
-
kseq_destroy()仍需调用，否则内部seq.s等指针未释放，造成内存泄漏 - 若启用
zlib的多线程解压（如zlib-ng），需确保每个线程独占一个kseq_t实例，共享会导致崩溃
质量值转换必须确认Phred编码体系
FASTQ第四行的质量字符对应Phred分数，但编码方式有Phred+33（主流）和Phred+64（老Illumina）之分。直接按qual[i] - 33算，遇到Phred+64数据会得到负数质量值，后续过滤逻辑全崩。
可靠判断方法只有两种：
- 查测序中心提供的元数据文档，明确写明
encoding: Sanger或encoding: Illumina 1.3+ - 用
head -n 40000 file.fastq | awk 'NR%4==0' | fold -w1 | sort | uniq -c | sort -nr | head -5看质量字符分布——若高频字符集中在!–~（ASCII 33–126），是Phred+33；若集中在@–h（64–104），则是Phred+64
fastp这类工具能自动检测，但纯C++解析时没人帮你兜底。一旦编码判错，Q20/Q30统计、滑窗修剪都会失效，这是后期分析偏差的隐形源头。
