rust-ise

Fast, Rust-native ISEScan-equivalent insertion-sequence (IS) scanner for bacterial genomes and metagenome assemblies. Reports IS family (ISfinder taxonomy), genomic coordinates, terminal inverted repeats (TIR), and complete/partial status — much faster than ISEScan, with concordant results.

Pipeline

1. ORF prediction — rustygal (a Rust port of Prodigal) META gene-finding, linked as a library (no external binary), plus strand-aware edge-ORF recovery.
2. Homology search — MMseqs2 profile search against a union IS database (ISOSDB ∪ ISfinder), calling the system mmseqs.
3. Classification — 4-tier family call (plain / -like / -chimera / novel).
4. TIR — native affine Smith-Waterman-Gotoh on the flanks; boundary + complete/partial.
5. Output — rust-ise.tsv, rust-ise.gff (GFF3), rust-ise.sum (per-family summary).

Output is deterministic across runs.

Prerequisites (NOT installed by cargo)

• MMseqs2 — mmseqs must be on your PATH (conda: conda install -c bioconda mmseqs2).
• IS database — the union profile DB (ISOSDB ∪ ISfinder MMseqs2 profiles) is external data, released as a prebuilt artifact paired with the matching per-profile thresholds the binary embeds. Download it, then point rust-ise at it via --db <dir> or $RUSTISE_DB. The dir must contain mmdb_union/profileDb* and manifest_union.tsv.

Database

The profile DB is distributed as a versioned download (it is calibrated together with the thresholds baked into the matching binary release — the two are a locked pair, so use the DB that ships with your binary version):

export RUSTISE_DB=/path/to/rust-ise_db          # extracted DB directory

Building the DB from source (build-db)

The prebuilt DB is the recommended path, but the union IS profile DB can be rebuilt reproducibly from its two upstream sources with the build-db subcommand. It ports the canonical pipeline: ingest ISOSDB + ISfinder transposase ORFs (rustygal META gene-finding), cluster with MMseqs2 (--min-seq-id 0.4 -c 0.8), relabel (unknown propagation + ISfinder authority), align each cluster with an in-process partial-order MSA (poasta, replacing the reference pipeline's external clustalo), and emit the profile DB via mmseqs convertmsa + msa2profile.

rust-ise build-db \
  --isosdb-fna ISOSDB.V3.fna --fam-annot fam_annot.tsv \
  --isfinder-faa isfinder.faa --isfinder-csv isfinder.csv \
  --out rust-ise_db [--work tmp_dir] [--strict-mmseqs-version]

Requires mmseqs on PATH (used for clustering and msa2profile); no clustalo or other external aligner is needed. The output directory is a drop-in --db / $RUSTISE_DB.

Install

# from a local checkout (path build):
cargo install --path rust-ise

# or from git (the repo must include the sibling `rustygal/` crate):
cargo install --git https://github.com/necoli1822/rust-ise rust-ise

RUSTFLAGS="-C target-cpu=native" is optional (~few % faster, stays result-identical).

crates.io note: a registry (cargo install rust-ise) release additionally requires the rustygal crate to be published to crates.io and the path dependency switched to a version.

Usage

export RUSTISE_DB=/path/to/rust-ise_db          # or pass --db each run
rust-ise -i contigs.fasta -o out_dir -t 16

Output columns (rust-ise.tsv)

seqID family tier isBegin isEnd isLen ncopy4is orfBegin orfEnd strand E-value qcov pident type irLen irId start2 end2 tir fpFlag

Coordinates are 1-based inclusive. type is c (complete) or p (partial).

fpFlag — nucleotide false-positive control

The HTH/DDE/ATPase folds of IS transposases are shared with host proteins (transcriptional regulators, recombinases, IstB-like ATPases), so the protein-profile search alone mis-calls them as IS (e.g. marA/soxS → IS4, dnaA → IS21). fpFlag runs a nucleotide neg-pos discriminator per call — the call's DNA is compared to an IS-lineage reference and a host-lineage reference — and reports which lineage it resembles:

The verdict combines the nt homology signal with two homology-independent structural signals — a terminal inverted repeat (TIR) and a target-site duplication (TSD, the short direct repeat an IS leaves flanking itself on insertion). Structure lets a divergent/novel IS (nt homology silent) still be recognized, and protects a structurally-supported call from being dropped as a false positive:

fpFlag is advisory (all calls are retained); use --strict to drop host calls (the only tier with no IS support of any kind). The .sum file carries an #fpControl count line. Requires the fpc/refset DB (see below); if absent the module is skipped and every call is flagged IS.

FP-control database

Build the fpc/refset reference into the DB dir once (ships with the DB):

MMSEQS=mmseqs ./build_fpc_db.sh POS.fna NEG.fna /path/to/rust-ise_db
# POS.fna = IS-lineage nt reference, NEG.fna = host-lineage nt reference

Testing

cargo test --release                       # hermetic unit tests: fpFlag 5-tier verdict, TSD, codon/revcomp, E-value fmt
./tests/golden_e2e.sh /path/to/rust-ise_db   # end-to-end golden: 17-contig fixture -> diff vs tests/golden/expected.tsv

The golden test locks the whole pipeline (ORF → search → family call → TIR → dedup/merge → TSD → fpFlag) including all five fpFlag tiers; it needs mmseqs + the DB, so it is a shell test rather than cargo test. rust-ise output is byte-stable across runs.

License

GPL-3.0-or-later (same as the bundled rustygal). See LICENSE.