PREMISE: A probabilistic framework for source assignment of viral Illumina reads

Authors: Sriram Vijendran, Karin Dorman, Tavis Anderson, Oliver Eulenstein

Introduction

PREMISE is an EM-based metagenomic classifier for paired-end Illumina short reads. Given a set of reference sequences and a paired-end FASTQ dataset, PREMISE:

1. Builds a compressed FM-index over the reference sequences.
2. Seeds and extends alignments for each read pair against all references.
3. Runs a penalized Expectation-Maximization algorithm to estimate the posterior probability of each read originating from each reference (assignments) and the relative abundance of each reference in the sample (proportions).

The tool is implemented in Rust and ships with an optional browser-based GUI (served locally) for interactive use.

Requirements

• Rust / Cargo ≥ 1.70
• Paired-end Illumina reads in FASTQ or FASTQ.gz format
• Reference sequences in FASTA format

Installation

Install from crates.io / GitHub:

# via Cargo (recommended)
cargo install --git https://github.com/sriram98v/premise

# or build from source
git clone https://github.com/sriram98v/premise
cd premise
cargo install --path .

Usage

Step 1 — Build an FM-index

premise build -s <reference.fasta>

Produces <reference>.fmidx. This index is required for both the CLI and GUI query steps.

Step 2 — Classify reads (CLI)

premise query \
  -s <reference.fmidx>     \  # FM-index built in Step 1
  -1 <R1.fastq.gz> \
  -2 <R2.fastq.gz> \
  -p <min_seed_length>     \  # minimum MEM seed length, e.g. 22
  --eps_1 <float>          \  # alignment likelihood cutoff (default 1e-64)
  --eps_2 <float>          \  # minimum match log-probability (default 1e-18)
  --rho   <float>          \  # EM penalty weight ρ (default 20)
  --omega <float>          \  # EM penalty weight ω (default 1e-20)
  --iter  <int>            \  # EM iterations (default 100)
  --em_threshold <float>   \  # EM convergence threshold (default 1e-6)
  --no-penalty             \  # disable the L1 penalty (plain EM)
  -t <threads>             \  # default 2; 0 = all available cores
  -o <output_prefix>

Outputs:

File	Contents
<output>.matches	Per-read assignments (TSV)
<output>.posteriors	Per-read posterior probabilities (TSV)
<output>.props	Reference abundance proportions (TSV)
<output>.aligns	Raw per-alignment likelihoods, one row per (read, reference) (TSV)

Run premise query -h for the full option list.

Step 3 — Interactive GUI (optional)

premise server

Opens a browser UI at http://localhost:8080 with drag-and-drop file upload, interactive results tables, pie chart, and EM convergence plot. Supports light/dark mode.

Algorithm

PREMISE seeds each read with Super-Maximal Exact Matches (SMEMs) found via the reference FM-index. Each seed is projected onto a reference diagonal, and the full read is then rescored ungapped against that offset — there is no chaining and no gapped extension. Read-level alignment log-likelihoods are computed from base quality scores (Phred-scaled error probabilities in natural log space); -p/--mem sets the minimum seed length.

The EM step solves a penalized likelihood maximization:

• ρ controls an L1-style sparsity penalty on the proportion vector.
• ω is a small regularization floor.
• Convergence is tracked by the total data log-likelihood across iterations.

Parameters ε₁ and ε₂ control alignment filtering: ε₁ is a minimum alignment likelihood threshold (linear space); ε₂ is a minimum match log-probability per read.

Project Structure

premise/
├── src/
│   ├── main.rs          # CLI, HTTP server, EM algorithm, alignment logic
│   ├── utils.rs         # Quality-score utilities, match log-probability
│   └── templates/
│       ├── index.html   # Browser GUI markup (embedded at compile time)
│       ├── styles.css   # Pico.css overrides (embedded at compile time)
│       └── app.js       # Frontend logic — D3 charts, dropzones, dark mode
├── tests/               # Integration tests (CLI + local server)
├── Cargo.toml
└── README.md

Output Format

.matches (TSV)

Column	Description
read_id	Read identifier
ref_id	Assigned reference sequence ID
posterior	Posterior probability of assignment

.posteriors (TSV)

Full posterior probability matrix: one row per read, one column per reference.

.props (TSV)

Column	Description
ref_id	Reference sequence ID
proportion	Estimated relative abundance

Citation

If you use PREMISE in your research, please cite:

Vijendran S. PREMISE: Probabilistic Read-level Expectation Maximization for Integrated Source Estimation. (manuscript in preparation)

License

See LICENSE.