坤鹏

我们开发了坤鹏，这是一种用于分类宏基因组序列的精确且高度可扩展的低内存工具。

受 Kraken2 的基于 k-mer 的方法的启发，坤鹏在样本分类期间结合了先进的滑动窗口算法，并在构建参考数据库时采用了一种关键的有序块方法。这种方法允许数据库以任意所需块大小的子数据库格式构建，从而显著降低了运行内存的使用量。这些改进使得坤鹏可以在个人计算机和 HPC 平台上运行。实际上，对于任何较大的索引，坤鹏都允许在几乎所有计算平台上执行分类任务，而无需传统上昂贵且罕见的内存密集型节点。

重要的是，参考索引的灵活结构还允许构建和利用由于计算限制而以前不可行的超大规模索引。超大规模索引包含原核生物和真核生物的增长基因组数据以及宏基因组组装，对于研究更多样化和复杂的环境宏基因组，如外暴露组研究至关重要。

“坤鹏”这个名字来自中国神话中的一种巨大神兽，能够从水中的巨鱼（鲲）变为天上的巨鸟（鹏），反映了该软件灵活的性质和高效地导航宏基因组数据广阔而复杂景观的能力。

开始使用

按照以下步骤安装坤鹏并运行示例。

方法 1：下载预构建的二进制文件（推荐）

如果您不希望从源代码构建，您可以从 GitHub 发布页面 下载您平台上的预构建二进制文件。

mkdir kun_peng_v0.6.10
tar -xvf Kun-peng-v0.6.10-centos7.tar.gz -C kun_peng_v0.6.10
# Add environment variable
echo 'export PATH=$PATH:~/biosoft/kun_peng_v0.6.10' >> ~/.bashrc
source ~/.bashrc

运行 kun_peng 示例

我们将以GitHub主页上一个非常小的病毒数据库为例

1. 下载数据库

git clone https://github.com/eric9n/kun_peng.git
cd kun_peng

2. 构建数据库

kun_peng build --download-dir data/ --db test_database

merge fna start...
merge fna took: 29.998258ms
estimate start...
estimate count: 14080, required capacity: 31818.0, Estimated hash table requirement: 124.29KB
convert fna file "test_database/library.fna"
process chunk file 1/1: duration: 29.326627ms
build k2 db took: 30.847894ms

3. 分类

# temp_chunk is used to store intermediate files
mkdir temp_chunk
# test_out is used to store output files
mkdir test_out
kun_peng classify --db test_database --chunk-dir temp_chunk --output-dir test_out data/COVID_19.fa

hash_config HashConfig { value_mask: 31, value_bits: 5, capacity: 31818, size: 13051, hash_capacity: 1073741824 }
splitr start...
splitr took: 18.212452ms
annotate start...
chunk_file "temp_chunk/sample_1.k2"
load table took: 548.911µs
annotate took: 12.006329ms
resolve start...
resolve took: 39.571515ms
Classify took: 92.519365ms

方法2：克隆存储库并构建项目

先决条件

1. Rust：如果您计划从源代码构建，则此项目需要Rust编程环境。

构建项目

首先，将此存储库克隆到您的本地计算机上

git clone https://github.com/eric9n/kun_peng.git
cd kun_peng

确保两个项目都已构建。您可以从工作空间根目录运行以下命令来完成此操作

cargo build --release

这将使用发布模式构建kr2r和ncbi项目。

运行 kun_peng 示例

接下来，运行示例脚本，该脚本演示了如何使用kun_peng二进制文件。从工作空间根目录执行以下命令

cargo run --release --example build_and_classify --package kr2r

这将运行位于kr2r项目示例目录中的build_and_classify.rs示例。

示例输出您应该看到类似以下输出

Executing command: /path/to/workspace/target/release/kun_peng build --download-dir data/ --db test_database
kun_peng build output: [build output here]
kun_peng build error: [any build errors here]

Executing command: /path/to/workspace/target/release/kun_peng direct --db test_database data/COVID_19.fa
kun_peng direct output: [direct output here]
kun_peng direct error: [any direct errors here]

此输出确认kun_peng命令已成功执行，文件已按预期处理。

kun_peng工具

Usage: kun_peng <COMMAND>

Commands:
  estimate   estimate capacity
  build      build `k2d` files
  hashshard  Convert Kraken2 database files to Kun-peng database format for efficient processing and analysis.
  splitr     Split fast(q/a) file into ranges
  annotate   annotate a set of sequences
  resolve    resolve taxonomy tree
  classify   Integrates 'splitr', 'annotate', and 'resolve' into a unified workflow for sequence classification. classify a set of sequences
  direct     Directly load all hash tables for classification annotation
  merge-fna  A tool for processing genomic files
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

构建数据库

像Kraken2一样构建kun_peng数据库，指定从NCBI下载的数据文件目录以及数据库目录。

./target/release/kun_peng build -h
build database

Usage: kun_peng build [OPTIONS] --download-dir <DOWNLOAD_DIR> --db <DATABASE>

Options:
  -d, --download-dir <DOWNLOAD_DIR>
          Directory to store downloaded files
      --db <DATABASE>
          ncbi library fna database directory
  -k, --k-mer <K_MER>
          Set length of k-mers, k must be positive integer, k=35, k cannot be less than l [default: 35]
  -l, --l-mer <L_MER>
          Set length of minimizers, 1 <= l <= 31 [default: 31]
      --minimizer-spaces <MINIMIZER_SPACES>
          Number of characters in minimizer that are ignored in comparisons [default: 7]
  -T, --toggle-mask <TOGGLE_MASK>
          Minimizer ordering toggle mask [default: 16392584516609989165]
      --min-clear-hash-value <MIN_CLEAR_HASH_VALUE>

  -r, --requested-bits-for-taxid <REQUESTED_BITS_FOR_TAXID>
          Bit storage requested for taxid 0 <= r < 31 [default: 0]
  -p, --threads <THREADS>
          Number of threads [default: 10]
      --cache
          estimate capacity from cache if exists
      --max-n <MAX_N>
          Set maximum qualifying hash code [default: 4]
      --load-factor <LOAD_FACTOR>
          Proportion of the hash table to be populated (build task only; def: 0.7, must be between 0 and 1) [default: 0.7]
  -h, --help
          Print help
  -V, --version
          Print version

转换Kraken2数据库

此工具将Kraken2数据库文件转换为Kun-peng数据库格式，以便更高效地处理和分析。通过指定数据库目录和哈希文件容量，用户可以控制结果数据库索引文件的大小。

./target/release/kun_peng hashshard -h
Convert Kraken2 database files to Kun-peng database format for efficient processing and analysis.

Usage: kun_peng hashshard [OPTIONS] --db <DATABASE>

Options:
      --db <DATABASE>                  The database directory for the Kraken 2 index. contains index files(hash.k2d opts.k2d taxo.k2d)
      --hash-capacity <HASH_CAPACITY>  Specifies the hash file capacity.
                                       Acceptable formats include numeric values followed by 'K', 'M', or 'G' (e.g., '1.5G', '250M', '1024K').
                                       Note: The specified capacity affects the index size, with a factor of 4 applied.
                                       For example, specifying '1G' results in an index size of '4G'.
                                       Default: 1G (capacity 1G = file size 4G) [default: 1G]
  -h, --help                           Print help
  -V, --version                        Print version

分类

分类过程分为三种模式

1. 直接处理模式

• 描述：在此模式下，同时加载所有数据库文件，这需要大量的内存。在运行此模式之前，您需要使用提供的脚本检查数据库目录中hash_*.k2d文件的总大小。确保您的可用内存达到或超过此大小。

bash cal_memory.sh $database_dir

• 特点
  • 高内存需求
  • 比直接处理模式快

命令帮助

./target/release/kun_peng direct -h
Directly load all hash tables for classification annotation

Usage: kun_peng direct [OPTIONS] --db <DATABASE> [INPUT_FILES]...

Arguments:
  [INPUT_FILES]...  A list of input file paths (FASTA/FASTQ) to be processed by the classify program. Supports fasta or fastq format files (e.g., .fasta, .fastq) and gzip compressed files (e.g., .fasta.gz, .fastq.gz)

Options:
      --db <DATABASE>
          database hash chunk directory and other files
  -P, --paired-end-processing
          Enable paired-end processing
  -S, --single-file-pairs
          Process pairs with mates in the same file
  -Q, --minimum-quality-score <MINIMUM_QUALITY_SCORE>
          Minimum quality score for FASTQ data [default: 0]
  -T, --confidence-threshold <CONFIDENCE_THRESHOLD>
          Confidence score threshold [default: 0]
  -K, --report-kmer-data
          In comb. w/ -R, provide minimizer information in report
  -z, --report-zero-counts
          In comb. w/ -R, report taxa w/ 0 count
  -g, --minimum-hit-groups <MINIMUM_HIT_GROUPS>
          The minimum number of hit groups needed for a call [default: 2]
  -p, --num-threads <NUM_THREADS>
          The number of threads to use [default: 10]
      --output-dir <KRAKEN_OUTPUT_DIR>
          File path for outputting normal Kraken output
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

2. 分块处理模式

• 描述：此模式以分块的形式处理样本数据，每次只加载一小部分数据库文件。这减少了内存需求，需要至少4GB的内存加上一对样本文件的大小。
• 特点
  • 低内存消耗
  • 与直接处理模式相比，性能较慢

命令帮助

./target/release/kun_peng classify -h
Integrates 'splitr', 'annotate', and 'resolve' into a unified workflow for sequence classification. classify a set of sequences

Usage: kun_peng classify [OPTIONS] --db <DATABASE> --chunk-dir <CHUNK_DIR> [INPUT_FILES]...

Arguments:
  [INPUT_FILES]...  A list of input file paths (FASTA/FASTQ) to be processed by the classify program. Supports fasta or fastq format files (e.g., .fasta, .fastq) and gzip compressed files (e.g., .fasta.gz, .fastq.gz)

Options:
      --db <DATABASE>

      --chunk-dir <CHUNK_DIR>
          chunk directory
      --output-dir <KRAKEN_OUTPUT_DIR>
          File path for outputting normal Kraken output
  -P, --paired-end-processing
          Enable paired-end processing
  -S, --single-file-pairs
          Process pairs with mates in the same file
  -Q, --minimum-quality-score <MINIMUM_QUALITY_SCORE>
          Minimum quality score for FASTQ data [default: 0]
  -p, --num-threads <NUM_THREADS>
          The number of threads to use [default: 10]
     --buffer-size <BUFFER_SIZE>
          [default: 16777216]
      --batch-size <BATCH_SIZE>
          The size of each batch for processing taxid match results, used to control memory usage
          [default: 16]
  -T, --confidence-threshold <CONFIDENCE_THRESHOLD>
          Confidence score threshold [default: 0]
  -g, --minimum-hit-groups <MINIMUM_HIT_GROUPS>
          The minimum number of hit groups needed for a call [default: 2]
      --kraken-db-type
          Enables use of a Kraken 2 compatible shared database
  -K, --report-kmer-data
          In comb. w/ -R, provide minimizer information in report
  -z, --report-zero-counts
          In comb. w/ -R, report taxa w/ 0 count
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

3. 逐步处理模式

• 描述：此模式将分块处理模式分解为单个步骤，在管理整个分类过程中提供了更大的灵活性。
• 特点
  • 灵活的处理步骤
  • 与分块处理模式的内存消耗相似
  • 性能根据执行步骤而变化

输出

• test_out/output_1.txt：

标准Kraken输出格式

1. “C”/“U”：一个字母代码，表示序列已被分类或未分类。
2. 从FASTA/FASTQ标题中获得的序列ID。
3. Kraken 2用于标记序列的taxonomy ID；如果序列未分类，则为0。
4. 序列的长度（bp）。对于配对读取数据，这将是一个包含两个序列长度的字符串，以管道字符分隔，例如“98|94”。
5. 用空格分隔的列表，表示序列（s）中每个k-mer的LCA映射。例如，“562:13 561:4 A:31 0:1 562:3”表示
   • 前13个k-mer映射到分类ID #562
   • 下一个4个k-mer映射到分类ID #561
   • 下一个31个k-mer包含一个模糊的核苷酸
   • 下一个k-mer不在数据库中
   • 最后一个3个k-mer映射到分类ID #562 注意，配对读取数据将包含一个“|:|”标记在此列表中，表示一个读取的结束和另一个读取的开始。

• test_out/output_1.kreport2：

100.00  1   0   R   1   root
100.00  1   0   D   10239     Viruses
100.00  1   0   D1  2559587     Riboviria
100.00  1   0   O   76804         Nidovirales
100.00  1   0   O1  2499399         Cornidovirineae
100.00  1   0   F   11118             Coronaviridae
100.00  1   0   F1  2501931             Orthocoronavirinae
100.00  1   0   G   694002                Betacoronavirus
100.00  1   0   G1  2509511                 Sarbecovirus
100.00  1   0   S   694009                    Severe acute respiratory syndrome-related coronavirus
100.00  1   1   S1  2697049                     Severe acute respiratory syndrome coronavirus 2

示例报告输出格式

1. 该分类单元下被覆盖的片段百分比
2. 该分类单元下被覆盖的片段数量
3. 直接分配给该分类单元的片段数量
4. 排名代码，表示（U）未分类、（R）根、（D）域、（K）界、（P）门、（C）纲、（O）目、（F）科、（G）属或（S）种。不在上述10个等级中的分类单元，其排名代码由最近的祖先等级代码加上表示距离该等级的数字组成。例如，“G2”是一个表示物种位于属和种之间，而其祖父母分类单元位于属等级的排名代码。
5. NCBI分类学ID号
6. 缩进的科学名称