Nucleaze 🧬

A high-performance Rust tool for filtering DNA/RNA reads based on a set of reference k-mers. Inspired by BBDuk by Brian Bushnell. Provides performant and memory-efficient read processing with support for both paired and unpaired FASTA/FASTQ files, with multiple files or in interleaved format.

---

Features and Default Behavior

K-mer based read filtering:

• Reads are compared to reference sequences by matching k-mers.
• If a read sequence has at least x k-mers also found in reference dataset, it is a match
  • x is 1 by default, changed with --minhits <int>

Piping:

• Reads from stdin by default (or use --in - explicitly)
• Use --outm/--outu/--outm2/--outu2 stdout.fa/stdout.fq to pipe results to stdout

Paired reads support:

• Paired inputs and outputs can be specified by adding more input/output files
• Interleaved inputs or outputs, signify interleaved input with --interinput
• Automatic detection of input/output mode

Multithreading with Rayon:

• Adjustable thread count via --threads argument
• Defaults to all available CPU cores

Memory Limit:

• Specify maximum memory usage with --maxmem <String> (e.g., 5G for 5 gigabytes, 500M for 500 megabytes)

Automatic Reference Indexing:

• Builds a serialized reference k-mer index using Bincode if --binref <file> is provided from references provided with --ref <file>
• Uses saved index on subsequent runs if --binref <file> is included

---

Installation

1. Install Rust

If using UNIX, run this command and follow the ensuing instructions:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

If using Windows, download the correct installer from Rustup.

2. Download the release executable

brew install nucleaze

3. Run program with necessary arguments

Nucleaze requires at least one of --ref or --binref to be provided. Input defaults to stdin if --in is not specified.

See more parameter documentation at ./src/main.rs

---

Example Usage

./nucleaze --in reads.fq --ref refs.fa --outm matched.fq --outu unmatched.fq --k 21

This command:

1. Builds 21-mer index from refs.fa sequences
2. Reads input reads from reads.fq into chunks of size 10,000
3. Processes each read into 21-mers and checks against reference index
4. Outputs matched reads to matched.fq and unmatched reads to unmatched.fq

---

License

This project is licensed under the MIT License, see LICENSE for details. There is lots of room for improvement here so new additions or suggestions are welcome!

---

Crates Used

• Needletail — FASTA/FASTQ file parsing and bitkmer operations
• Bincode — K-mer hashset serialization/deserialization
• Rayon — Multithreading
• Clap — CLI
• Num-Cpus — detection of available threads
• Sysinfo — system memory information
• Crossbeam — asynchronous channels

---

Please email [email protected] with any questions or feature requests.