msspeculator

msspeculator predicts peptide retention time, ion mobility, and MS2 spectra, then writes spectral libraries for search. Use the Python commands for quick inference or the Rust path for high-throughput library generation.

Install

From a checkout:

uv sync --locked --no-dev

This installs the Python package and its Rust extension. A Rust toolchain with cargo must be on PATH for the first sync.

Generate a library

The Rust CLI includes a small built-in model, so no checkpoint is needed for a first run:

cargo run --release -p msspeculator-cli -- \
  library --model builtin:small-v0 \
  --fasta proteome.fasta --out library.tsv

Add --decoys for pseudo-reversed target-decoy entries. The CLI skips a decoy when its stripped sequence collides with a target sequence.

Use an exported checkpoint instead:

uv run msspeculator export-rust --model model.ckpt -o model.safetensors
cargo run --release -p msspeculator-cli -- \
  library --model model.safetensors \
  --fasta proteome.fasta --out library.tsv

The output is DIA-NN TSV by default. Use a .mzspeclib.txt suffix for mzSpecLib text and add .gz to compress either format. The CLI also supports single-peptide JSON prediction. Run cargo run -p msspeculator-cli -- --help for all options.

Checking a model

run-doctor asks two questions of a set of weights and needs no corpus, no network, and no Python:

cargo run --release -p msspeculator-cli -- run-doctor --model model.safetensors --out doctor

Retention is scored against the Biognosys iRT standards (slope, intercept, R², MAE). Fragmentation is scored against three vendored experimental spectra, reported as a spectral angle per spectrum; see the panel's provenance. A model that is not trained shows a flat retention slope and a low spectral angle, so the report distinguishes "wrong scale" from "wrong spectrum".

Rust applications can call the same length-batched, queued inference path without spawning a process. See the Rust API guide.

From a training checkpoint

Training writes a .ckpt, which the Rust CLI cannot read. Export it to portable weights first:

uv sync --locked --no-dev --extra torch-cpu
uv run msspeculator export-rust --model model.ckpt -o model.safetensors
cargo run --release -p msspeculator-cli -- \
  library --model model.safetensors --fasta proteome.fasta --out library.tsv

There is no Python prediction command. Inference is Rust so it can run where a Python runtime cannot; see ADR 0001.

More

• Training guide: teacher distillation, prepared experimental data, and context-aware fine-tuning.
• Development guide: contributor setup, tests, linting, and CI.
• Local runbook: a complete local workflow.
• Talus infrastructure: corpus preparation and production jobs.
• Documentation index: design notes, model details, reports, and roadmap.

License

Apache License 2.0. See LICENSE.