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 --manifest-path rust/Cargo.toml --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.

To predict an explicit list, pass a tab-separated file with proforma and protein_ids columns:

proforma	protein_ids
PEC[UNIMOD:4]TIDEK/2	P1;P2
PECTIDEK/2	P1
PEK[UNIMOD:259]TIDEK/3	PRTC

Each proforma value includes the modification and charge to predict. The builder preserves both in the library, so modified, unmodified, and heavy peptides can coexist. Protein IDs are separated by semicolons. To supply a decoy, add decoy and decoy_group columns; mark the decoy true and give it the same integer group ID and charge as its target. A group contains one target and at most one decoy, so targets may be unpaired. Targets without a group ID get unique numeric IDs.

cargo run --manifest-path rust/Cargo.toml --release -p msspeculator-cli -- \
  library --model builtin:small-v0 \
  --peptides peptides.tsv --out library.mzspeclib.txt \
  --decoys --decoy-method pseudo-reverse --decoy-seed 42

Peptide TSV output must be mzSpecLib so decoy groups survive. --decoys generates decoys for targets without supplied decoys; omit it to keep only the supplied rows. Use --decoy-method shuffle for seeded shuffling. Pseudo-reverse tries successively shorter interior spans if a candidate matches a target; shuffle retries with the chosen seed. If no candidate is distinct, the builder warns and keeps the target unpaired. The builder assigns generated decoy flags and groups.

Use an exported checkpoint instead:

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

FASTA builds write 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 --manifest-path rust/Cargo.toml -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 --manifest-path rust/Cargo.toml --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 --manifest-path rust/Cargo.toml --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.