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

ORF prediction — rustygal (a Rust port of Prodigal) META gene-finding, linked as a library (no external binary), plus strand-aware edge-ORF recovery.
Homology search — MMseqs2 profile search against a union IS database (ISOSDB ∪ ISfinder), calling the system mmseqs.
Classification — 4-tier family call (plain / -like / -chimera / novel).
TIR — native affine Smith-Waterman-Gotoh on the flanks; boundary + complete/partial.
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

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 8

flag	meaning
`-i, --seqfile`	input contigs FASTA (required)
`-o, --output`	output directory (required)
`-t, --threads`	CPU threads (default 8)
`--db <dir>`	IS database dir (else `$RUSTISE_DB`)
`--keep`	keep intermediate files
`--strict`	drop `fpFlag=host` calls (host-lineage false positives) from the output
`-h, --help`	print help and exit

MMseqs2-GPU acceleration is under development and not yet available (see the note in src/main.rs).

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`	meaning
`IS`	call DNA matches the IS reference — homology-confirmed
`putative`	no nt homology either way, but a TIR/TSD is present — structure suggests IS (e.g. a divergent IS)
`shared`	nt leans host (matches both, host closer), or structure-vs-nt conflict — borderline, kept
`host`	matches host reference only, no IS or structural support — likely false positive
`unresolved`	no nt match and no structure — IS-vs-host undecided (keep; divergent IS or off-reference host gene)

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.

rust-ise 0.1.0