RADS – Recombinase Associated Defense Search

Release Notes: Snakemake Pipeline (snakemake-pipeline branch)

Overview

This release introduces a fully redesigned Snakemake-based pipeline for RADS, replacing the original monolithic RADS.sh bash script. The new pipeline brings reproducible environments, modular rule structure, parallelized genome processing, and an interactive results dashboard to the RADS workflow.

What's New

Pipeline Architecture

• Full rewrite of the RADS workflow as a Snakemake pipeline with modular rule files organized under workflow/rules/
• Dynamic genome discovery via a Snakemake checkpoint (discover_genomes), enabling the pipeline to scale automatically to any number of input genomes without manual configuration
• Phase-based execution: genome download and translation (Phase 1), contig extraction and annotation (Phase 2), DefenseFinder and metrics (Phase 3), and optional analyses including binomial enrichment (Phase 4)

Environment Management

• Reproducible environments now supported via Pixi (pixi.toml) as the primary installation method
• Full Conda/Mamba fallback provided via environment.yaml for HPC systems where Pixi is unavailable
• SLURM profile included under profiles/slurm/ for HPC cluster submission (experimental)

Genome Download

• Automated genome download from NCBI using accession lists, toggled in config/config.yaml (download: enabled: true/false)
• Supports local genome input when download is disabled via genomes_path config key

Defense Scoring

• New defense_score.py script scores each co-transcribed ORF for defense island proximity using two components:
  • Proximity score: exponential decay from the nearest DefenseFinder-identified gene (configurable scale, default 2000 bp)
  • Density score: count of defense genes within a sliding window (default 10 kb), normalized and capped at 10 genes
  • Composite score weighted 60% proximity / 40% density by default; weights are user-configurable
• Graceful handling of missing or empty DefenseFinder output — affected columns are set to NA rather than failing
• InterPro domain annotations are joined to each scored ORF in the output TSV

Results and Reporting

• New interactive dashboard (pixi run dashboard / pixi run dashboard-hpc) for exploring results at http://localhost:8000
• Shareable self-contained HTML report generated via workflow/scripts/generate_report.py — no server required for distribution
• Optional --include-locus-viewer flag embeds gene-arrow diagrams in the HTML report
• Standardized output structure under results/{sample}/ including blast results, contigs, co-transcription data, InterProScan annotations, DefenseFinder output, binomial analysis, defense scores, and pipeline metrics

Configuration

• Single config/config.yaml controls all pipeline parameters: sample name, query file, upstream/downstream flanking sizes, DIAMOND identity threshold, thread counts, and optional binomial analysis toggle
• Flanking region size defaults to 5 kb upstream + 5 kb downstream (10 kb total) and is fully configurable

Bug Fixes and Improvements over Legacy RADS.sh

• Eliminated manual step ordering — Snakemake handles dependency resolution and reruns only incomplete or failed steps (--rerun-incomplete)
• Parallel genome processing replaces serial shell loops
• Pipeline metrics now written to metrics/pipeline_metrics.json for programmatic inspection
• ORF ID parsing regularized in defense_score.py to handle Prodigal header formats with regex fallback

Known Limitations

• SLURM profile is experimental; manual adjustment of resource limits in profiles/slurm/ may be required for your cluster
• InterProScan requires a separate installation (~15 GB); see docs/Installation.md
• DefenseFinder models must be updated after installation (defense-finder update)

Quick Start

git clone https://github.com/Seandersen/RADS.git
cd RADS
git checkout snakemake-pipeline
pixi install
# Edit config/config.yaml, then:
pixi run snakemake --cores 8

For Conda/Mamba users:

mamba env create -f environment.yaml
conda activate rads
pip install mdmparis-defense-finder
defense-finder update
snakemake --cores 8

Citation

Andersen SE, Kirsch JM, Hesselberth JR, Duerkop BA. RADS: Recombinase Associated Defense Search. [Publication details pending]

MIT License. See LICENSE for details.