kackle

Kmer Artifact Correction (KACkle) -- A small python utility for eliminating k-mer artifacts caused by primer mismatching.

Installation

Install with pip:

pip install kackle
kackle --help

Or with uv:

uv add kackle
uv run kackle --help

Execution

Run with precomputed BED6 motif sites:

kackle -i plus.bw -I minus.bw -b sites.bed6 -o out.plus.bw -O out.minus.bw -c chrom.sizes

Or let kackle locate the original artifact motifs directly from FASTA. By default, FASTA mode corrects exact TGG matches first, then TGGAA matches with up to one mismatch:

kackle -i plus.bw -I minus.bw -f genome.fa -o out.plus.bw -O out.minus.bw -c chrom.sizes

FASTA mode locates motif sites one chromosome at a time to avoid materializing whole-genome BED tables for common short motifs. It uses indexed pyfastx FASTA access and ahocorasick-rs multi-pattern matching by default:

kackle -i plus.bw -I minus.bw -f genome.fa \
  --fasta-backend pyfastx --motif-match-backend ahocorasick \
  -o out.plus.bw -O out.minus.bw -c chrom.sizes

Custom motif order can be supplied with repeated --motif KMER[:MISMATCHES] flags.

Benchmarking

To reproduce motif-backend timings:

uv run python benchmarks/motif_backends.py