Amplirust

A high-performance in-silico PCR tool for primer matching and product extraction from FASTA and GenBank sequences.

• Fast approximate primer matching using SIMD-accelerated algorithms (via sassy)
• IUPAC ambiguity code support (R, Y, S, W, K, M, B, D, H, V, N) in primers
• FASTA and GenBank input with automatic format detection
• Circular genome support for plasmids and bacterial chromosomes
• Reverse complement strand search for comprehensive primer detection
• Multi-threaded processing for parallel file reading, searching, and compression
• Gzip/BGZF support for both input and output files (parallel decompression for BGZF)
• Primer pool mode for all-vs-all multiplex primer screening
• Flexible primer input via command line or CSV file

conda install bioconda::amplirust

Requires Rust 1.85+ (2024 edition).

# Clone the repository
git clone https://github.com/erdikilic/amplirust.git
cd amplirust

# Build with SIMD optimizations (recommended)
RUSTFLAGS="-C target-cpu=native" cargo build --release

# The binary will be at target/release/amplirust

RUSTFLAGS="-C target-cpu=native" cargo install --path .

Amplirust supports two FASTA parsers via feature flags:

# Build with default parser (seq_io)
RUSTFLAGS="-C target-cpu=native" cargo build --release

# Build with needletail parser (potentially faster for large files)
RUSTFLAGS="-C target-cpu=native" cargo build --release --no-default-features --features parser_needletail

# Install with needletail
RUSTFLAGS="-C target-cpu=native" cargo install --path . --no-default-features --features parser_needletail

amplirust [OPTIONS] --input <INPUT> --primers <PRIMERS>

# Simple PCR with inline primer
amplirust -i genome.fasta -p "16S:AGAGTTTGATCMTGGCTCAG:TACGGYTACCTTGTTACGACTT" -o products.fasta

# Multiple input files with glob pattern
amplirust -i "genomes/*.fna.gz" -p primers.csv -o results.fasta

# Circular genome (e.g., plasmid)
amplirust -i plasmid.fasta -p "ori:ACGTACGT:TGCATGCA" --circular -o products.fasta

# Search both strands with detailed output
amplirust -i genome.fasta -p primers.csv --search-rc -o products.fasta --tsv stats.tsv

# Gzip compressed output
amplirust -i genome.fasta.gz -p primers.csv -o products.fasta.gz

# Pool mode: find products between any primer combination
amplirust --pool -i genome.fasta -p "p1:AGAGTTTGATCMTGGCTCAG;p2:GWATTACCGCGGCKGCTG;p3:CCTACGGGNGGCWGCAG" -o products.fasta

# GenBank input
amplirust -i sequence.gbk -p "16S:AGAGTTTGATCMTGGCTCAG:TACGGYTACCTTGTTACGACTT" -o products.fasta

# Mixed formats via glob (FASTA and GenBank files auto-detected)
amplirust -i "data/*" -p primers.csv -o products.fasta

Amplirust shows a progress bar while reading multiple input files (suppressed with --quiet or any -v flag). It always prints a run summary to stderr after processing.

⠋ [00:00:02] [########################################] 15/15 files (0s)

=== Amplirust Summary ===
Input sequences:  1250
Primer pairs:     3
Products found:   47

Products by primer:
  16S: 45
  ITS: 2

Products by reference:
  genome_1: 30
  genome_2: 17

Output written to: products.fasta
TSV written to: stats.tsv

Use --quiet to suppress the progress bar (useful for scripting). Progress bars are also disabled when any verbosity flag is set (-v, -vv, -vvv).

Single primer pair:

-p "primer_name:FORWARD_SEQ:REVERSE_SEQ"

Multiple primer pairs (semicolon-separated):

-p "16S:AGAGTTTGATCMTGGCTCAG:TACGGYTACCTTGTTACGACTT;ITS:TCCGTAGGTGAACCTGCGG:TCCTCCGCTTATTGATATGC"

Create a CSV file with header:

name,forward,reverse
16S_V1V3,AGAGTTTGATCMTGGCTCAG,ATTACCGCGGCTGCTGG
16S_V3V4,CCTACGGGNGGCWGCAG,GACTACHVGGGTATCTAATCC
ITS1,TCCGTAGGTGAACCTGCGG,GCTGCGTTCTTCATCGATGC

Then use:

-p primers.csv

With --pool, primers are individual sequences instead of forward/reverse pairs.

Single primer:

--pool -p "primer_name:SEQUENCE"

Multiple primers (semicolon-separated):

--pool -p "p1:AGAGTTTGATCMTGGCTCAG;p2:GWATTACCGCGGCKGCTG"

Pool CSV file (2 columns):

name,sequence
27F,AGAGTTTGATCMTGGCTCAG
519R,GWATTACCGCGGCKGCTG
1492R,TACGGYTACCTTGTTACGACTT

Products are found between any two primers that match in correct orientation and distance. Product names use the primerA+primerB format.

Products are written with descriptive headers:

>reference_id:primer_name:1	pos=0-123	strand=+	len=124
ACGTACGTACGT...
>reference_id:primer_name_rc:2	pos=200-324	strand=-	len=125
TGCATGCATGCA...

Header format: {reference_id}:{primer_name}[_rc][_wrap]:{case_number}\tpos={start}-{end}\tstrand={+|-}\tlen={length}

• reference_id is the first whitespace-delimited token of the FASTA header, or the LOCUS name for GenBank records (with fallback to accession, definition, or unknown_N)
• _rc suffix indicates product from reverse complement strand
• _wrap suffix indicates product wraps around circular genome
• case_number increments per reference header (resets for each reference)
• Output sequences retain their strand orientation; strand indicates match orientation.

The TSV output contains detailed information for each product:

1. Use native CPU optimizations for best performance:

   RUSTFLAGS="-C target-cpu=native" cargo build --release

2. Adjust thread count based on your system:

   amplirust -t 8 -i large_genome.fasta -p primers.csv -o out.fasta

3. Use BGZF compression for large single files (enables parallel decompression):

   # Compress with bgzip (from htslib) instead of gzip
   bgzip -c large_genome.fasta > large_genome.fasta.gz
   
   # Amplirust auto-detects BGZF and uses parallel decompression
   amplirust -i large_genome.fasta.gz -p primers.csv -o products.fasta.gz  # input: bgzf

   Output .gz files are written in BGZF format (gzip-compatible).

4. Increase max-errors for degenerate primers or divergent sequences:

   amplirust -k 3 -i genome.fasta -p primers.csv -o out.fasta

amplirust \
  -i bacterial_genomes/*.fasta \
  -p "16S:AGAGTTTGATCMTGGCTCAG:TACGGYTACCTTGTTACGACTT" \
  -k 2 \
  --min-len 1400 \
  --max-len 1600 \
  -o 16s_sequences.fasta \
  --tsv 16s_stats.tsv \
  -v

amplirust \
  -i plasmid.fasta \
  -p primers.csv \
  --circular \
  --search-rc \
  -o plasmid_products.fasta \
  -vv

amplirust \
  -i divergent_genome.fasta \
  -p primers.csv \
  -k 4 \
  --min-identity 0.75 \
  --search-rc \
  -o products.fasta

MIT License