DiffPrimer

DiffPrimer is a bioinformatics tool designed to identify unique genomic regions in a reference genome compared to a set of other "background" genomes and automatically design specific PCR primers for these markers.

It combines high-performance k-mer analysis (written in Rust) with standard primer design tools (Primer3) to generate diagnostic markers that are exclusive to your target organism.

Key Features

• Exclusive Region Discovery: Identifies genomic regions present in your reference but absent in a database of other genomes.
• Automated Primer Design: Integrated with Primer3 to design optimal primer pairs for identified unique regions.
• Specificity Check:
  • Validates designed primers against all input background genomes.
  • Uses a hybrid Myers Bit-Vector Algorithm (Global) and Semiglobal Alignment (Local) to detect potential off-target amplification, even with insertions/deletions.
• Annotation Integration: Cross-references unique regions with GFF3 annotation files to identify which genes (if any) the markers overlap with.
• Parallel Processing: Fully parallelized core for fast execution on large datasets.

Installation

Quick install (recommended)

We recommend using uv to install diffprimer because it is incredibly fast and automatically handles virtual environments for you.

(If you don't have uv installed, it takes only a few seconds. Follow the official uv installation guide.)

uv tool install diffprimer

Alternative methods

If you prefer pipx, you can also use it to install diffprimer safely in an isolated environment. (If you don't have pipx installed, follow the official pipx installation guide.)

pipx install diffprimer

Or, using standard pip:

pip install diffprimer

Requirements

• Python 3.13 or newer
• Rust is NOT required for end users

Development install

If you want to contribute or build from source:

1. Clone the repository:

   git clone https://github.com/omatheuspimenta/diffprimer.git
   cd diffprimer
   

2. Create a Virtual Environment:

   # Using uv (Recommended)
   uv venv --python 3.13
   source .venv/bin/activate
   
   # OR using standard python
   python3.13 -m venv .venv
   source .venv/bin/activate
   

3. Install:

   uv pip install -e .
   # OR
   pip install -e .
   

   Note: Rust is required to build the core engine from source. Install via rustup.

Usage

Running diffprimer executes the full pipeline: finding unique regions -> designing primers -> verifying specificity.

Basic Command

diffprimer \
    --reference-file reference.fasta \
    --sequences-path genomes_directory/ \

Complete Example

diffprimer \
    --reference-file data/target_species.fasta \
    --sequences-path data/background_species/ \
    --annotation-path data/target_annotations.gff3 \
    --config-file primer3_config.ini \
    --min-region-length 200 \
    --cpus 8 \
    --check-specificity

Arguments Explained

Output Format

The output is a CSV file containing one row per designed primer pair. Key columns include:

• Sequence_Header: Contig/Region name.
• Region_Start/End: Coordinates of the unique region.
• Forward_Primer / Reverse_Primer (and _Tm, _GC, etc.): Primer details.
• Specificity_Tag: The result of the specificity analysis (if --check-specificity is used).
  • Specific_LowGlobalSim: The region is globally unique; off-targets are extremely dissimilar, so primers are specific.
  • Specific_PositionalMismatches: The region has high global similarity to a background genome, BUT the primers themselves are specific because they have biological mismatches in critical locations (like the 3' end) that prevent binding.
  • NonSpecific_Amplification: The primers bind perfectly or near-perfectly to a similar region in a background genome resulting in cross-reactivity. Do NOT use.
  • Not_Checked: Specificity check was skipped.
• Gene_Name / Product: Annotation info (if GFF3 provided).

Configuration

You can customize Primer3 settings by providing a file with --config-file. Example format:

PRIMER_OPT_SIZE=20
PRIMER_MIN_SIZE=18
PRIMER_MAX_SIZE=27
PRIMER_OPT_TM=60.0
PRIMER_MIN_TM=57.0
PRIMER_MAX_TM=63.0
PRIMER_MIN_GC=20.0
PRIMER_MAX_GC=80.0