nextTANDEM 🚀

nextTANDEM is a next-generation, high-performance, standalone Tandem Repeat (TR / VNTR / Microsatellite / Minisatellite / Megasatellite) identification and PCR primer design platform written in Python. It provides fast parallel CPU multi-processing, optional CUDA GPU hardware acceleration, external TRF (Tandem Repeats Finder) binary wrapper integration, automated thermodynamic PCR primer design, in-silico ePCR validation, transparent .fasta.gz streaming, and complete FAIR compliance (W3C RO-Crate JSON-LD provenance and Sequence Ontology GFF3 annotations).

---

🌟 Key Features

• ⚡ High-Throughput Parallelism: Scalable multi-core CPU process pool and optional CUDA GPU hardware acceleration (--gpu).
• 🔬 Native & TRF Engine Support: Native pattern dynamic scanning engine with support for optional external trf (Tandem Repeats Finder) binary execution.
• 🧬 Automated PCR Primer Design: Integrated thermodynamic primer design engine (SantaLucia 1998 Nearest-Neighbor $T_m$ calculations) for designing $T_m$-optimized primer pairs ready for laboratory synthesis.
• 🔍 In-Silico Electronic PCR (ePCR): Simulates primer binding and validates amplicon specificity directly on target sequences.
• 🗜️ Transparent Gzip Support: Direct streaming analysis of compressed FASTA files (.fasta.gz, .fa.gz, .fna.gz) without manual extraction.
• 🏷️ Sequence Ontology & Classification: Categorizes repeat structures by unit size into Microsatellites ($1-6\text{ bp}$, SO:0000289), Minisatellites ($7-100\text{ bp}$, SO:0001061), and Megasatellites / Tandem Repeats ($>100\text{ bp}$, SO:0000705).
• 🌐 FAIR Compliant: Produces Sequence Ontology annotations in GFF3 and complete W3C RO-Crate (ro-crate-metadata.json) execution provenance graph.
• 🎨 Rich Terminal UI: Formatted summary tables, progress bars, YAML configuration generator (nexttandem init-config), and structured artifact exports (TSV, GFF3, JSON).

---

📊 Benchmark & Comparison with TRF (Tandem Repeats Finder)

nextTANDEM was benchmarked against the official Tandem Repeats Finder (TRF v4.10.0-rc.2) binary. The native nextTANDEM engine achieves 100% concordance in repeat detection while augmenting the analysis with automated PCR primer design, compound repeat classification, and FAIR-compliant provenance exports.

Feature Comparison Matrix

Feature / Metric	Standalone TRF Binary	nextTANDEM (Native Engine)	nextTANDEM (TRF Engine)
Tandem Repeat Identification	✅	✅	✅
Detection Concordance	100%	100%	100%
Automated PCR Primer Design	❌	✅ (SantaLucia 1998 $T_m$)	✅ (SantaLucia 1998 $T_m$)
In-Silico ePCR Simulator	❌	✅	✅
Sequence Ontology GFF3 Export	❌	✅ (SO:0000705, SO:0000289, SO:0001061)	✅
FAIR W3C RO-Crate Metadata	❌	✅ (ro-crate-metadata.json)	✅
Compressed FASTA (.gz) Streaming	❌	✅	✅
GPU Hardware Acceleration	❌	✅ (CUDA / PyTorch / CuPy)	❌
Multi-Core CPU Parallel Processing	❌	✅	✅
Interactive Terminal Rich UI	❌	✅	✅

---

📦 Installation

Option 1: Via PyPI

pip install nexttandem

Option 2: From Source (GitHub)

git clone https://github.com/LaBiOmicS/nextTANDEM.git
cd nextTANDEM

# Install in editable mode
pip install -e .

Option 3: Docker Container

docker build -t nexttandem .
docker run --rm -v $(pwd):/data nexttandem /data/genome.fasta -o /data/results

Option 4: Apptainer / Singularity (HPC Environments)

apptainer build nexttandem.sif Apptainer.def
apptainer run nexttandem.sif genome.fasta -o results/

---

🚀 Quick Start & Usage

Basic Execution

# Run tandem repeat identification and primer design on a FASTA file
nexttandem genome.fasta -o results/

# Run directly on gzipped FASTA files (.fasta.gz)
nexttandem genome.fasta.gz -o results/

# Or run using Python module syntax
python -m nexttandem genome.fasta -o results/

Advanced Execution Options

# Run with 16 parallel workers, GPU acceleration, and custom primer parameters
nexttandem genome.fasta -o results/ --threads 16 --gpu --opt-tm 60.0 --min-product-size 100 --max-product-size 250

# Run using external TRF binary engine wrapper
nexttandem genome.fasta -o results/ --use-trf

# Generate default YAML configuration file
nexttandem init-config -o nexttandem.yaml

# Run using custom YAML configuration file
nexttandem genome.fasta -c nexttandem.yaml -o results/

---

🧬 In Silico e-PCR Simulation

Validate PCR primers electronically against target genomes or transcriptomes with mismatch detection and amplicon sizing:

# Test a specific pair of Forward and Reverse primers against a target genome
nexttandem epcr genome.fasta --fwd ATGCTAGCTAGCTAGC --rev CGATCGATCGATCGAT --max-mismatches 2

---

📂 Project Structure

nextTANDEM/
├── pyproject.toml         # Packaging, metadata & dependencies (PEP 621)
├── MANIFEST.in            # Package distribution manifest
├── README.md              # Documentation
├── LICENSE                # MIT License
├── Dockerfile             # Containerized reproducible execution
├── Apptainer.def          # HPC Singularity / Apptainer definition
├── .github/               # GitHub workflows
│   └── workflows/
│       └── ci.yml         # GitHub Actions CI matrix
├── docs/                  # Web documentation landing page
│   └── index.html
├── paper/                 # JOSS submission manuscript
│   └── paper.md
├── nexttandem/            # Main package source
│   ├── __init__.py
│   ├── __main__.py        # Package execution entrypoint (python -m nexttandem)
│   ├── cli.py             # Rich CLI interface (Click + Rich)
│   ├── config.py          # Configuration management (YAML / JSON)
│   ├── models.py          # Dataclasses (TandemRepeatItem, CompoundTandemRepeat, SequenceAnalysisResult)
│   ├── finder.py          # Native multi-parallel Tandem Repeat detection engine
│   ├── trf_wrapper.py     # External TRF binary wrapper integration
│   ├── compound.py        # Compound tandem repeat grouping logic
│   ├── primer.py          # PCR Primer Design engine (SantaLucia 1998)
│   ├── epcr.py            # In-silico Electronic PCR simulator
│   ├── gpu.py             # GPU hardware acceleration module (CuPy/PyTorch)
│   ├── artifacts.py       # Artifact Manager for structured output directory
│   ├── utils.py           # Memory-efficient FASTA & .gz streaming utilities
│   ├── provenance.py      # FAIR RO-Crate JSON-LD exporter
│   └── outputs/           # Output formatters
│       ├── __init__.py
│       ├── gff3.py        # Sequence Ontology compliant GFF3 exporter
│       ├── tsv.py         # Tab-delimited TSV exporter
│       └── json.py        # JSON summary exporter
└── tests/                 # Unit & integration test suite

---

⚙️ Configuration File (nexttandem.yaml)

nextTANDEM can be configured via a clean YAML file generated with nexttandem init-config:

min_motif_len: 1
max_motif_len: 500
min_repeats: 2.0
match_score: 2
mismatch_penalty: 7
indel_penalty: 7
min_score: 50
max_period: 2000
threads: 16
design_primers: true
flank_len: 150
opt_tm: 58.0
min_product_size: 100
max_product_size: 300
generate_ro_crate: true
use_external_trf: false
use_gpu: false
gpu_device_id: 0

---

📁 Output Artifacts Directory Layout

Every nextTANDEM run produces a structured artifact directory:

results/
├── tandem_repeats.gff3      # Sequence Ontology GFF3 annotation
├── tandem_repeats.tsv       # TSV report with Tandem Repeat locations & scores
├── designed_primers.tsv     # TSV report with designed PCR Primers & Tm calculations
├── summary.json             # Structured JSON execution report
└── ro-crate-metadata.json   # W3C RO-Crate FAIR JSON-LD metadata

---

🌐 FAIR Compliance & Sequence Ontology

nextTANDEM output complies with FAIR (Findable, Accessible, Interoperable, Reusable) principles:

• GFF3 Annotations: Uses official Sequence Ontology (SO) terms:
  • SO:0000705 (tandem_repeat)
  • SO:0000289 (microsatellite)
  • SO:0001061 (minisatellite)
• Execution Provenance: Generates W3C RO-Crate (ro-crate-metadata.json) recording input file SHA-256 hash, configuration hash, environment details, and execution timestamp.

---

🧪 Testing Suite

Run end-to-end integration tests using pytest:

pytest -v

---

✉️ Author & Contact

• Author: Fabiano Menegidio
• Email: labiomics@bioinformatica.com.br
• GitHub: https://github.com/LaBiOmicS/nextTANDEM

---

📜 Citation

If you use nextTANDEM in your research or software pipelines, please cite the repository:

@misc{menegidio2026nexttandem,
  author = {Menegidio, Fabiano},
  title = {nextTANDEM: High-Performance & FAIR-Compliant Tandem Repeat Identification and PCR Primer Design Platform},
  year = {2026},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/LaBiOmicS/nextTANDEM}}
}

---

📄 License

Distributed under the MIT License. See LICENSE for more information.