Handling of ambiguous bases

[lv43apo91]

Hi @eric9n, thanks again for your hard work on this tool!

I was trying v0.7.5 on some reads with Ns (or other IUPAC bases, or x as seems to be inserted with --minimum-quality-score) and got a classification string that looked like:
0:6 1236:1 0:1 590:1 0:1 590:2 0:15 91347:1 0:6 91347:1 0:2 |:|

(note this is not truncated via copy/paste and looked like that)

Here are the reads:
R1: CTGTGTTCCGGCTGAAGATCTGATTGAGGCGACATCTGACTGTGGCGCATATGTTATGGTTCACAGCGCGCTGAAACGTCTGGCAGTGAAGATGTCCAAAATCTGTAACGACCTGCGCTTGCTCTCTTCTGGTCCTCGTGCCGGCCTGAAC

R2:
GTTCACTTTGGCTGGCATGATGGAAGAGCCCNNNNGCAGTTCCGGCAGGTTGATNNCNTNCAGGCCGGCACGAGGACCNNNNGNGAGCAANCGCNGGNCGNNANNNATNTTGGACATCTTCACTGCCANNCGTTTCAGCGCGCTGTGAACC

How are ambiguous bases handled? The docs would suggest the output follows Kraken's format and should have an A: for k-mers with ambiguous bases, but that does not seem to be the case here and instead got a blank for the R2 k-mer string. Thanks!

[eric9n]

Hi, thanks for reporting this! Could you please provide:
• the database you used,
• the sample file (or a minimal example),
• the exact command/output,
• and the expected result?

[lv43apo91]

wget https://github.com/eric9n/Kun-peng/releases/download/v0.7.5/kun_peng-v0.7.5-x86_64-unknown-linux-gnu
chmod +x kun_peng-v0.7.5-x86_64-unknown-linux-gnu

# Prep DB
mkdir db
cd db
wget https://genome-idx.s3.amazonaws.com/kraken/k2_standard_08_GB_20250714.tar.gz
tar xzvf k2_standard_08_GB_20250714.tar.gz
cd ..

./kun_peng-v0.7.5-x86_64-unknown-linux-gnu hashshard --db db/

# Create reads
printf "@test/1\nCTGTGTTCCGGCTGAAGATCTGATTGAGGCGACATCTGACTGTGGCGCATATGTTATGGTTCACAGCGCGCTGAAACGTCTGGCAGTGAAGATGTCCAAAATCTGTAACGACCTGCGCTTGCTCTCTTCTGGTCCTCGTGCCGGCCTGAAC\n+\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n" > r1.fastq
printf "@test/2\nGTTCACTTTGGCTGGCATGATGGAAGAGCCCNNNNGCAGTTCCGGCAGGTTGATNNCNTNCAGGCCGGCACGAGGACCNNNNGNGAGCAANCGCNGGNCGNNANNNATNTTGGACATCTTCACTGCCANNCGTTTCAGCGCGCTGTGAACC\n+\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n" > r2.fastq

# Run
./kun_peng-v0.7.5-x86_64-unknown-linux-gnu classify --db db/ --chunk-dir chunks --output-dir output --num-threads 3 -P r1.fastq r2.fastq

cat output/output_1.txt

Expected output (as generated by Kraken2):

kraken2 --db db/ --paired --output k2.txt r1.fastq r2.fastq
cat k2.txt

C       test    590     151|151 0:16 1236:5 0:5 590:4 0:2 590:9 0:48 91347:5 0:15 91347:1 0:7 |:| A:117

[lv43apo91]

Also I found a potential other or related issue through the above exercise: for R1, Kun-peng only reports 37 k-mers whereas Kraken2 reports 117.

[eric9n]

Thanks for pointing this out! This difference is actually one of the key distinctions between Kun-peng and Kraken2. Kraken2’s “sliding window” approach is not a strict windowing algorithm — it tends to inflate sensitivity and produces many repeated k-mers. Kun-peng, by design, avoids these redundancies.

Also, regarding the ambiguous/invalid bases: could you clarify what the expected meaning or utility of reporting them in the result file would be for your workflow? That will help us evaluate whether and how we should handle them explicitly.

[lv43apo91]

Got it. The nice thing about Kraken2's k-mer classification string is that all k-mers in the read are represented so there is a direct mapping between the k-mers and sequence. I can "zip" the k-mer classifications and sequence to figure out the classification of each tiling 35bp. For example, if I want to know, "what is the sequence of the k-mer which led to the classification?" or "what is the longest stretch of unclassified sequence?", I can answer these questions.

Even if Kun-peng only assesses certain k-mers (see below), I think Kraken2's reporting of the read classification is more favorable because it contains more information. I can't think of a way to support the above queries without:

1. Adding ambiguous ("A") k-mer reporting
2. Adding a new "S" (skipped) or "N" (non-unique) classification k-mers, i.e. those which Kun-peng did not use. So something like 0:6 S:10 1236:1

That way, Kun-peng would also retain the 1:1 mapping.

With regards to the repeated k-mers, I have reviewed your preprint and found this line:

Kun-peng optimizes the sliding window algorithm by counting minimizers from the same sequence position only once, effectively reducing false positives.

If I understand correctly, if there are two overlapping 35bp k-mers with the same 31bp minimizer, the k-mers are only counted once? I almost wonder if there should be a "legacy" mode for k-mer search. I also wonder if you have benchmarks on the incremental benefit of using this approach compared with your other optimizations? On the flipside to considering these repeated k-mers as biased and therefore should be skipped, one could consider them as additional sources of signal for classification. Finally, it seems like you also do something similar when building the database, although this is less clear to me:

Unlike Kraken2, Kun-peng implements a uniqueness check during minimizer generation to retain only unique ℓ bp minimizers, preventing over-counting from identical sequence regions that could lead to false positives.

Thanks again for your help and consideration!

[eric9n]

I can "zip" the k-mer classifications and sequence to figure out the classification of each tiling 35bp. For example, if I want to know, "what is the sequence of the k-mer which led to the classification?" or "what is the longest stretch of unclassified sequence?", I can answer these questions.

in Kraken2, the k-mer string is not actually a one-to-one trace back to the literal sequence. Kraken2 uses minimizers within its “sliding window” scheme, so although positions can be inferred, the k-mers reported are not always the exact subsequences of bases at those locations. In other words, the mapping you describe (“this exact 35 bp tile caused the hit”) is not guaranteed in Kraken2 either.

[eric9n]

we consider this a design flaw in Kraken2’s implementation. Its sliding window algorithm artificially inflates sensitivity by repeatedly counting the same minimizer bp, which does not provide real classification signal. This was likely intended to preserve traceability of k-mer positions, but in practice it introduces redundancy and false positives — a trade-off that we think is not worth it. Kun-peng avoids this redundant expansion by design.

[eric9n]

If the goal is to keep every base position and preserve full bp traceability, then that would be a different type of tool altogether. Both Kraken2 and Kun-peng are designed with a different purpose: not per-bp tracing, but rather to sample representative bp through minimizers in order to reduce data scale, and to provide annotations at a statistical level. This is my understanding of how this class of tools is intended to work.