# 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):
```sh
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`](https://crates.io/crates/poasta), replacing the reference pipeline's external
`clustalo`), and emit the profile DB via `mmseqs convertmsa + msa2profile`.
```sh
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
```sh
# 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
```sh
export RUSTISE_DB=/path/to/rust-ise_db # or pass --db each run
rust-ise -i contigs.fasta -o out_dir -t 16
```
| `-i, --seqfile` | input contigs FASTA (required) |
| `-o, --output` | output directory (required) |
| `-t, --threads` | CPU threads (default 16) |
| `--db <dir>` | IS database dir (else `$RUSTISE_DB`) |
| `--keep` | keep intermediate files |
| `--strict` | drop `fpFlag=host` calls (host-lineage false positives) from the output |
## 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:
| `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):
```sh
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
```sh
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](LICENSE).