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 — isscan.tsv, isscan.gff (GFF3), isscan.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 $ISSCAN_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 ISSCAN_DB=/path/to/isscan_db          # extracted DB directory

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 ISSCAN_DB=/path/to/isscan_db          # or pass --db each run
rust-ise -i contigs.fasta -o out_dir -t 16

Output columns (isscan.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/isscan_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/isscan_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.

Changelog

0.2.2

• Tightened the significance gate for higher precision. The primary E-value floor (SIG_EVALUE) in family_call was tightened 1e-10 → 1e-30 — the empirical knee on the E. coli MG1655 vs RefSeq truth set (removes ~5 low-significance false positives while retaining every true IS element: precision 0.72 → 0.76, recall unchanged at 0.98). Added a conservative query-coverage floor (SIG_QCOV = 0.35) that trims only extreme fragmentary hits without harming recall. Both gates are covered by new unit tests.

0.2.1

• New IS profile DB + recalibrated thresholds. Per-profile percent-identity thresholds (data/rep_thresholds.tsv, compiled into the binary via phf) were recalibrated on GTDB and matched to a new poasta-MSA-built IS profile database, with false-positive control tightened against a GTDB regression set. The DB itself is built/distributed separately and supplied at runtime via --db / $ISSCAN_DB (the build-db tooling lives in the dev tree, not in the published scanner crate).
• rustygal now resolves from crates.io (>= 0.2.0, the meta_api ORF finder) rather than a local path.

0.2.0 / 0.1.x

• Earlier crates.io releases: the pure-Rust ISEScan-equivalent IS scanner (rustygal ORFs + MMseqs2 profile search + native affine-SW terminal inverted repeats) with the in-process rust_ise::run library API and the rust-ise CLI.

License

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