Dragon Documentation

A cloud-native, signal-aware aligner for surveillance-scale microbial genomics.

Dragon aligns query sequences (genes, plasmids, long/short reads, raw nanopore current) against millions of prokaryotic genomes while using dramatically less disk and RAM than existing tools. It exploits redundancy among related genomes through a coloured compacted de Bruijn graph, an FM-index over concatenated unitigs, ML-weighted graph-aware chaining, and a streaming on-disk format that mmaps the index in O(1).

Key features

• ~50× less disk than LexicMap (~100 GB vs 5.46 TB for 2.34 M genomes).

• <4 GB query RAM at million-genome scale; --profile laptop further restricts use to consumer hardware.

• Multi-shard search (--shard) for indices split across files or quotas.

• Cloud-native Zarr v3 backend (dragon export-zarr / dragon search-zarr) — chunked + Zstd-compressed; reads run against s3:// or gs:// directly via zarr-python.

• Mmap-friendly paths.bin v2 — O(1) cold-load, per-genome lazy decoding from a fixed offset table.

• Raw nanopore signal search (dragon signal-index / dragon signal-search) — pore-model–driven discretisation indexed by the same FM-index machinery, no basecalling required.

• ML-weighted seed scoring — logistic regression over six anchor features; pure Rust inference.

• Surveillance-ready summaries (dragon summarize, --format summary) — per-species prevalence + identity tables built into the CLI.

• Incremental updates (dragon update / dragon compact) — overlay new genomes without a full rebuild.

• Variable-length seeds via FM-index backward search.

• Outputs in PAF, BLAST-tabular, surveillance summary, and graph-context GFA formats.

A 16,000-genome demo index is hosted at s3://dragon-zarr/saureus/b1/ (eu-west-2, public-read). Anyone can read it with no AWS credentials:

pip install 'zarr>=3.0' s3fs numcodecs
python scripts/zarr_demo.py s3://dragon-zarr/saureus/b1

Contents

Getting Started

• Installation
  • Requirements
  • From source (recommended)
  • Optional dependencies
  • Troubleshooting
• Quick start
  • Step 1: Prepare genome files
  • Step 2: Build the index
  • Step 3: Search
  • Step 4: Inspect results
  • Example output
  • Step 5 (optional): Multi-shard search
  • Step 6 (optional): Cloud-native deployment
  • Step 7 (optional): Surveillance summary
• Tutorial: AMR gene search
  • Scenario
  • Step 1: Download test data
  • Step 2: Build index
  • Step 3: Search AMR genes
  • Step 4: BLAST-tabular output
  • Step 5: Batch analysis
  • Performance notes

User Guide

• Indexing
  • Overview
  • Command
  • Input format
  • Choosing k-mer size
  • Index files
  • Resource requirements
  • GGCAT integration
• Searching
  • Overview
  • Command
  • Query types
  • Seed finding details
  • Candidate filtering
  • Chaining
  • Memory management
• Output formats
  • PAF (Pairwise Alignment Format)
  • BLAST tabular (outfmt 6)
  • Parsing output
• Performance tuning
  • Hardware recommendations
  • SSD vs HDD
  • Tuning parameters
  • Scaling guidelines
  • Distributing pre-built indices

Architecture

• Architecture overview
  • The redundancy problem
  • Pipeline overview
  • Why this is efficient
  • Module map
• Coloured compacted de Bruijn graph
  • What is a de Bruijn graph?
  • Why use a de Bruijn graph?
  • Construction
  • Colour storage
• Run-length FM-index
  • Background
  • Why run-length?
  • Construction
  • Backward search
  • Variable-length seed matching
  • Position-to-unitig mapping
• Graph-aware colinear chaining
  • The chaining problem
  • Why graph-aware?
  • Algorithm
  • Complexity
• Data structures
  • 2-bit DNA encoding
  • Roaring Bitmaps
  • Elias-Fano cumulative length index
  • Fenwick tree (Binary Indexed Tree)
  • Variable-length integers (varint)

Benchmark

• Benchmark datasets
  • Tiered approach
  • Query types
• Benchmark methodology
  • Tools compared
  • Accuracy metrics
  • Resource metrics
  • Scalability metrics
  • Read simulation
  • Statistical analysis
• Benchmark results
  • Sensitivity vs divergence
  • Resource comparison
  • Batch query performance
  • Figures
• Reproducing benchmarks
  • Quick start (synthetic data)
  • Full benchmark (Snakemake)
  • Pipeline structure
  • Adding a new tool

API Reference

• CLI reference
  • dragon index
  • dragon search
  • dragon info
  • dragon download
  • dragon update
  • dragon compact
  • dragon summarize
  • dragon export-zarr
  • dragon search-zarr
  • dragon signal-index
  • dragon signal-search
  • Environment variables
• Module reference
  • Index modules (src/index/)
  • Query modules (src/query/)
  • Data structures (src/ds/)
  • Utilities (src/util/)
  • I/O modules (src/io/)

Citation

Cerdeira, L. (2026). Dragon: a cloud-native, signal-aware aligner for surveillance-scale microbial genomics. In preparation.

Licence

Dragon is released under the MIT Licence.