FastK v1.1 安装与使用-生信工具59

1. 概览

FastK 是面向高质量 DNA 组装数据（Illumina、PacBio HiFi）的 k-mer 计数器，特点是速度快、内存占用低、可扩展性强。相较 KMC3，在 50× HiFi 数据计 40-mer 时约快 2 倍（误差率升高或 k 增大时相对优势会下降）。得益于磁盘外排序设计，FastK 能在有限内存下处理超大数据集（如 32 Gb axolotl 基因组 100× 数据，只需 ~12 GB 内存但需要 ~6.5 TB 磁盘）。

1.1 输出产物

• .hist：k-mer 频率直方图（默认总会生成）

• .ktab：排序后的**规范（canonical）**k-mer 计数表（-t 开启）

• .prof：每条序列的 k-mer 计数剖面（profile）（-p 开启）

• 相对 profile：基于另一数据集的 .ktab 对当前读段计数（-p:<table>）

规范 k-mer：将 k-mer 与其 Watson-Crick 互补序列按字母序较小者作为代表（a<c<g<t）。

1.2 典型用途

• 估算基因组大小、重复度（直方图 + GeneScope2.0）

• 读段/组装纠错与过滤（低频 k-mer）

• 跨数据集比较、逻辑组合（Logex）

• 区域覆盖与注释（KmerMap）

• 下游分析所需的 k-mer 表/剖面

2. 安装

2.1 源码编译（推荐）

git clone https://github.com/thegenemyers/FASTK.git
cd FASTK
# 依赖
sudo apt-get install -y libbz2-dev liblzma-dev libcurl4-openssl-dev
make clean && make
# 可将可执行文件路径加入 PATH

注：bioconda 渠道存在环境冲突概率，常见失败，优先源码编译。

3. 快速上手

# 计数 + 直方图（默认）
FastK -T12 -k31 C_heu.R1.clean.fastq C_heu.R2.clean.fastq# 查看直方图（ASCII），并导出给 GeneScope
Histex -G C_heu.R1.clean.hist > data.hist# 生成 k-mer 表（≥阈值）
FastK -k40 -t4 sample.fastq   # 仅保留出现次数≥4的 k-mer# 生成 profile
FastK -k40 -p sample.fastq# 基于外部表生成“相对 profile”
FastK -k40 -p:full sample_part1.fastq

参数建议

• -T：设为物理核心数

• -k：Illumina/HiFi 常用 21–41；复杂/重复基因组可加大

• -t：过滤错误 k-mer（HiFi/Illumina常见阈值 2–4 起）

• -c：同聚物压缩（hoco，PacBio 推荐开启）

• -M：默认 12 GB 已足够；更大内存会略快

• -P：大规模排序临时目录（SSD 更佳）

• -bc：有条形码等前缀时忽略相应长度

4. 核心命令与选项

4.1 FastK

FastK [-k<int(40)>] [-t[<int(1)>]] [-p[:<table>[.ktab]]] [-c] [-bc<int>][-v] [-N<out_prefix>] [-P<tmp_dir(/tmp)>] [-M<int(12)>] [-T<int(4)>]<source>[.cram|.[bs]am|.db|.dam|.f[ast][aq][.gz]] ...

• 输入类型：CRAM/BAM/SAM/FASTA/FASTQ（可 .gz），或 Dazzler 数据库；一次运行的所有输入类型需一致

• -N：指定输出前缀与目录；默认沿用首个输入的目录与根名

• 计数细节：非 A/C/G/T 的位置会导致覆盖该区域的 k-mer 无效；profile 中对应为2k−1 个以上的 0

4.2 辅助文件管理：Fastrm / Fastmv / Fastcp

• 统一对 .hist/.ktab/.prof 及其隐藏分片文件进行 删除 / 重命名 / 复制

• 选项：-i 交互确认（仅对 stub 文件），-n 不覆盖，-f 强制

4.3 分布式合并：Fastmerge

Fastmerge [-ht] [-T<int(4)>] [-#<parts_per_thread(1)>][-P<node_tmp>] [-S<N:int>of<D:int>] <target> <source>...

• 合并多个 .ktab 并可生成最终直方图（-h）；直方图和 profile 不能直接合并

• -#：单线程产出多个分片（合并超多文件时更高并发）

• -P：HPC 下将源文件缓存到本地盘以缓解分布式文件系统压力

• -S NofD：切片合并（极大数据时分 D 片，第 N 片），后续用 Fastcat 拼接

4.4 拼接切片/相对剖面：Fastcat

Fastcat [-vk] [-htp] <target> <slice_or_part>...

• -h/-t：拼接由 Fastmerge -S 生成的直方图/表

• -p：拼接基于同一目标表的相对 profile（不同数据分块跑出的 .prof）

• -k：保留源切片（默认拼接后删除源）

5. HPC 作业范式

5.1 方案 A（能放得下所有 part 的表到节点本地盘）

1. 并行计数出 4 个分表：

   FastK -k40 -t part1.fasta
   ...
   FastK -k40 -t part4.fasta
   

2. 单节点本地盘合并并出直方图与总表：

   Fastmerge -ht -P/tmp full part1 part2 part3 part4
   

3. 若需 profile：对每个 part 基于总表生成相对 profile，再拼接：

   FastK -k40 -p:full part1 ... part4
   Fastcat -p full part1 part2 part3 part4
   

5.2 方案 B（极大规模，100 份输入 + 本地盘装不下总表）

1. 100 份并行计数：

   FastK -k40 -t part1.fasta ... part100.fasta
   

2. 切片合并（例如 25 片，并行）：

   Fastmerge -ht -P/tmp -S1of25 slice1 part1 ... part100
   ...
   Fastmerge -ht -P/tmp -S25of25 slice25 part1 ... part100
   

3. 拼接得到最终表与直方图：

   Fastcat -ht full slice1 ... slice25
   

4. 生成并拼接相对 profile（同上，100 份 → Fastcat -p）。

权衡：总 CPU 时间会增加（~3×），但总历时可显著缩短（取决于队列与并发）。

6. 配套工具（Core Applications）

6.1 Histex（直方图查看/导出）

Histex [-1] [-kAG] [-h[<lo(1)>:]<hi(-G?1000:100)>] <source>[.hist]

• -h：指定频率区间；-k：输出实例数直方图 I(f)，默认为唯一 k-mer 数 U(f)

• -A：制表符 ASCII；-G：输出 GeneScope2.0 友好格式（默认上限 1000）

• -1：输出 1-code .khist

6.2 Tabex（表查看/范围导出/阈值过滤/校验）

Tabex [-1AC] [-t<int>] <source>[.ktab] [<addr>[-<addr>]]
# <addr> 可为序号或 DNA 前缀

• 支持按序号区间或前缀取子表；-t：按计数阈值过滤

• -A：k-mer\tcount；-C：检查排序；-1：导出 1-code .kmr

6.3 Profex（读取序列 profile）

Profex [-1Az] <source>[.prof] <id>[-(<id>|#)] ...

• 支持区间、# 表示最后一个；-z：游程压缩输出；-A：制表符；-1：1-code .prf

6.4 Logex（k-mer 表的逻辑组合与计数调制）

Logex [-T<int(4)>] [-[hH][<lo(1)>:]<hi(32767)>] <name=expr> ... <tabA> <tabB> ...

• 表达式里 A..H 代表依次传入的表；支持 | & ^ - 与计数调制符：

  • 逻辑运算的计数合成：+(和)、-(右减左)、<(最小)、>(最大)、*(平均)、.(左优先)

  • 前缀 #：把子表达式产出的 k-mer 计数改为 1（如“出现在几张表”的统计）

  • 后缀 [a,b]：对计数范围过滤；{gc%}：对GC 含量百分比过滤

• 产物：新 .ktab（可选 -h 出直方图；-H 仅直方图）

6.5 Symmex（生成对称表）

• 把规范表扩展为正向 + 反向互补均出现（回文只出现一次），便于顺序扫描提速

6.6 KmerMap（k-mer 覆盖到 BED）

KmerMap [-vm] [-T<int(4)>] [-P<tmp>] <kmers>[.ktab] <target>[."dna"] <out>

• 输出 <out>.<target>.kmers.bed 或合并区间版 <out>.<target>.merged.kmers.bed（-m）

Haplex / Homex / Vennex 已弃用（代码仍在但不维护）

7. C 接口（libfastk.c / libfastk.h）

7.1 Histogram

• Load_Histogram/Modify_Histogram/Write_Histogram/Free_Histogram

• 支持 U(f)/I(f) 转换与区间裁剪；边界项含累积计数以保证求和一致性

7.2 K-mer Table

• 简单装载到内存的 Kmer_Table：

  • Load_Kmer_Table(name, cut_off)（内存可能 10~50 GB 量级；设置 cut_off 可省内存）

  • Fetch_Kmer/Fetch_Count/Find_Kmer

• 流式扫描的 Kmer_Stream（推荐大表）：

  • Open/Clone/Free，First/Next 顺序访问

  • Current_Kmer/Current_Count/Current_Entry

  • GoTo_* 随机跳转（较慢，供分片并行等高级用法）

7.3 Profile

• Open_Profiles/Clone_Profiles/Free_Profiles/Fetch_Profile

• 内部通过 .pidx 偏移 + .prof 压缩块实现按需解压

8. 文件编码要点

8.1 .hist

固定头部：k, l, h, I(l), I(h) + U(l..h) 向量
FastK 默认 l=1, h=32767，文件大小固定 262,164 字节。边界项含累积意义。

8.2 .ktab

• stub：k, N(parts), min_count, prefix_bytes(p), IDX[...]

• 隐藏分片：.<base>.ktab.#（#=1..N），每条记录为截去前 p 字节的 2-bit 编码 + uint16 计数
  合并拼接即全表，且分片之间严格有序不交叉。

8.3 .prof / .pidx

• .pidx：每条 profile 的起始偏移数组（最后一个为文件末尾）

• .prof：首个计数（7 或 15 位编码）+ 一阶差分序列（支持 0-run、正/负单字节、双字节二补码）

9. 已知限制 / 注意事项

• 一次运行的输入文件类型必须一致（FASTA 与 CRAM 不能混用）

• 内存 >128 GB 时存在已知问题（实务中 16 GB 足够；更大内存仅略快）

• k > ~128 时可能失效（后续计划提升）

• 最高计数封顶 32767（uint16）；更高会被截断

• 含非 A/C/G/T 的区域：对应 k-mer 不计入；profile 中表现为**≥2k−1 的 0 段**

10. 实战配方与小贴士

10.1 Illumina/HiFi 基本流程

1. FastK -T <cores> -k31 -t2 -v -P <ssd_tmp> sample_R1.fq.gz sample_R2.fq.gz

2. Histex -G sample.hist > sample.genescope.tsv（送 GeneScope2.0）

3. 若下游需要 k-mer 表：直接消费 .ktab 或用 Tabex -t 再次阈值化

4. 需要按读段分析：FastK -k31 -p sample.fq.gz 生成 .prof，Profex 选取子集检查

10.2 PacBio HiFi 加分项

• 开启 -c（同聚物压缩，hoco）显著减少错误 k-mer

• -t 适度提高（如 3–5）以剔除残余错误

10.3 跨样本比较

• 先用合并后的 A 数据 .ktab，对 B 数据跑 -p:<A.ktab> 得到相对 profile，评估来源/批次差异或用于 merfin、三体分型等。

10.4 超大数据的 I/O 优化

• -P 指向本地 NVMe/SSD；HPC 上用 Fastmerge -P 先缓存切片

• 超大合并用 -S NofD 切片 + Fastcat -ht 拼接

10.5 常见坑

• 忘记清理隐藏分片 → 用 Fastrm/Fastmv/Fastcp

• 计数溢出（>32767）被截断 → 若关心高丰度区域，配合直方图/逻辑组合而非单看原始计数

• 输入含 N → profile 中长串 0 合理；不是程序错误

11. 命令速查表

FastK最常用

1. FastK

Usage: FastK [-k<int(40)>] [-t[<int(1)>]] [-p[:<table>[.ktab]]] [-c] [-bc<int>][-v] [-N<path_name>] [-P<dir(/tmp)>] [-M<int(12)>] [-T<int(4)>]<source>[.cram|.[bs]am|.db|.dam|.f[ast][aq][.gz] ...-v: 详细模式，进程中输出统计信息-T: 使用-T个线程-N: 使用指定路径作为输出目录并将其作为根名的前缀-P: 将块级排序结果放入目录-P中-M: 在KMcount的后续排序步骤中使用-M GB内存-k: k-mer大小-t: 生成排序的k-mer表及计数，≥指定的阈值-p: 生成序列计数概况（如果给定表格则依据表格生成）-bc: 忽略每个读段的给定长度前缀（例如条形码）-c: 对每个序列进行同聚物压缩

1. Histex

Usage: Histex [-1] [-kAG] [-h[<int(1)>:]<int(-G?1000:100)>] <source_root>[.hist]-h: 输出在给定范围内计数的直方图-k: 输出k-mer实例计数的直方图（与唯一k-mers比较）-A: 以简单的制表符分隔的ASCII格式输出-G: 输出适用于GeneScope.FK的ASCII格式直方图-1: 以1-code格式输出

1. 例如：

/FASTK/FastK -T12 -k19 XXX.R1.fq.gz XXX.R2.fq.gz
/FASTK/Histex XXX.hist > data.hist