Pretrained models for tandem mass spectra. Turn MS/MS spectra into embeddings, compare spectra, or fine-tune the encoder for a measured property. UltraMS is a ~200 M-parameter transformer encoder pretrained on 160,641,162 experimental MS/MS spectra from GNPS/MassIVE (UltraMSdata) and released with pretrained weights, pretraining code, benchmark code, and the source data behind the manuscript figures.
python -m pip install ultrams- Reads MGF and
.mgf.gzout of the box;python -m pip install 'ultrams[io]'adds mzML support. - CPU, CUDA and Apple MPS devices are supported (
device="cuda",device="mps"). - Python 3.10 or newer;
torchandtransformersare installed as dependencies. - From a checkout:
python -m pip install -e .
| I want to… | Start here |
|---|---|
| Embed one spectrum | Python example |
| Embed an MGF or mzML file | File command |
| Train on my labelled spectra | PyTorch example · complete MGF example |
| Compare spectra | Search example |
| Learn in a notebook | UltraMS tutorials |
| Inspect or run pretraining | Training code |
| Reproduce the paper benchmarks | Spectral properties and molecular identification |
| Use the public API / CLI reference | API and CLI |
The UltraAtlas — a galaxy of metabolite structure. Spiral arms are UltraAtlas chemical classes scaled by their real member counts, with real representative molecules as the bright stars; the spiral layout, core and halo are an artistic rendering.
from ultrams import UltraMS
model = UltraMS.from_pretrained("unsupervised")
embedding = model.encode(
mz=[100.1, 121.1, 150.0],
intensity=[20, 100, 35],
precursor_mz=301.2,
).embedding
print(embedding.shape) # (1024,)The first call downloads the selected checkpoint from Hugging Face. Use device="cuda" or device="mps" with from_pretrained to run on an available accelerator.
The three checkpoints are collected on Hugging Face.
ultrams-embed spectra.mgf embeddings.npz --model unsupervisedThe output has aligned ids and embeddings arrays. To use mzML, first run python -m pip install 'ultrams[io]'; the base installation reads MGF and .mgf.gz without an extra file-format package. The checked-in example includes five real MS/MS spectra and a complete Python batch workflow.
UltraMS is a torch.nn.Module. Each dataset item contains peak mz, peak intensity, precursor_mz, and a measured numeric target. The two rows below are runnable example data; substitute your measured spectra and targets for research.
import torch
from torch.utils.data import DataLoader
from ultrams import UltraMS
dataset = [
{"mz": [100.1, 121.1, 150.0], "intensity": [20, 100, 35], "precursor_mz": 301.2, "target": 0.5},
{"mz": [102.1, 135.2, 167.3], "intensity": [40, 100, 25], "precursor_mz": 315.3, "target": 0.7},
]
device = "cuda" if torch.cuda.is_available() else "cpu"
model = UltraMS.from_pretrained("unsupervised", device=device).train()
head = torch.nn.Linear(model.embedding_dim, 1).to(device)
loader = DataLoader(dataset, batch_size=2, collate_fn=model.batch_converter())
optimizer = torch.optim.AdamW([*model.parameters(), *head.parameters()], lr=1e-5)
for batch in loader:
batch = {name: value.to(device) for name, value in batch.items()}
prediction = head(model(batch["peaks"], batch["attention_mask"], batch["precursor_mz"]))
loss = torch.nn.functional.mse_loss(prediction.squeeze(-1), batch["target"])
optimizer.zero_grad()
loss.backward()
optimizer.step()
print(f"loss: {loss.item():.4f}")The complete fine-tuning example reads an MGF file and saves training history. For a shorter route, use model.finetune(labelled_spectra, task="regression") with a label field; it saves weights, configuration, and losses. See spectrum input for the input format.
For measured molecular labels, the MassSpecGym contrastive tutorial downloads the dataset, keeps its train/validation/test folds, fine-tunes the encoder, and reloads the selected checkpoint.
| Model name | Representation | Dimension | Spectral peak limit | Weights |
|---|---|---|---|---|
unsupervised |
Encoder spectrum embedding | 1024 | 150 | Unsupervised |
mona |
MoNA contrastive projection | 1024 | 100 | MoNA contrastive |
search |
UltraAtlas search projection | 512 | 150 | Search |
Load any of them with UltraMS.from_pretrained("name"), or load a downloaded model.pt with UltraMS.from_checkpoint(path). The released files contain model weights and inference configuration. Model selection explains the training purpose and output of each checkpoint. The Search checkpoint is the UltraAtlas application best.pt.
Pre-trained checkpoints:
| Checkpoint | Training data | Size | Weights |
|---|---|---|---|
| Unsupervised | UltraMSdata pretraining + retention time | ~0.8 GB | HF |
| MoNA contrastive | MoNA contrastive | ~0.8 GB | HF |
| Search | UltraAtlas spectrum-to-spectrum contrastive | ~0.8 GB | HF |
Released reference data (the paper's benchmark inputs are downloadable from public sources; see each benchmark page):
| Dataset | Contents | DOI | Mirror |
|---|---|---|---|
| UltraMS MSnLib benchmark | Full MSnLib library (560,084 spectra) with the formula-level 80/10/10 split used in this study; strict-adduct molecule-level 70/15/15 split with queries and libraries for library search | 10.5281/zenodo.23963488 | HF |
| UltraMSdata file manifest | File-level inventory of the 824,828 open-format MS/MS files (3,062 MassIVE datasets) used as the pretraining-corpus inventory | 10.5281/zenodo.23966050 | — |
| UltraMSdata | Pretraining corpus: 160,641,162 spectra in 816 Parquet shards, plus the 21,586,258-spectrum ion-mode-balanced subset in 48 shards | — | HF |
| UltraMS SpectraVerse dataset | 464,346 SpectraVerse spectra with a frozen molecule-level 8:1:1 split; used for the negative-ion structure-family evaluation and as one of the three structure-annotated sources | 10.5281/zenodo.23964105 | HF |
The UltraMSdata pretraining package contains the current model architecture, training entry points, configuration and history outputs. It installs separately from the inference package.
The pretraining recipe uses the GNPS/MassIVE-only UltraMSdata corpus and an ion-mode-balanced subset drawn from that same corpus. MSnLib, SpectraVerse, MassSpecGym and MoNA support downstream benchmarks, task-specific contrastive training and UltraAtlas reference spectra. The source-file inventory is public, and the complete processed UltraMSdata shards are available at Hugging Face.
The benchmark code and results cover spectral properties and molecular identification. The task pages link to public input downloads, training and test commands, and the measured results.
Figure data and plotting scripts are provided in the accompanying Supplementary Source Data archive, organized by the panel numbers in the manuscript.
| Path | Contents |
|---|---|
src/ultrams/ |
Installable inference package (UltraMS, UltraMSPredictor, spectrum readers, CLI) |
training/ |
Pretraining and adaptation package (model architecture, data tools, configs, entry points) |
benchmarks/ |
Benchmark input preparation, training/evaluation code, saved outputs and metric recalculation |
examples/ |
Runnable embedding, fine-tuning and spectrum-search examples |
cookbook/ |
Tutorials and notebooks |
docs/ |
Spectrum input format, model selection, API/CLI reference, FAQ |
hub/ |
Model cards for the released checkpoints |
tests/ |
Unit tests and released-checkpoint verification |
- Spectrum input and preprocessing
- Model selection
- Python API and CLI
- FAQ and troubleshooting
- Examples · Tutorials · Training · Benchmarks
Embedding is lightweight: a single spectrum encodes in milliseconds on CPU, and batches use the standard torch device selection (cuda, mps or cpu). Checkpoint download requires network access to Hugging Face on first use; subsequent runs use the local Hugging Face cache. Peak limits are 100–150 retained peaks per spectrum depending on the checkpoint (see model selection).
Bug reports, benchmark issues and pull requests are welcome; see CONTRIBUTING.md. Release notes are in CHANGELOG.md.
UltraMS is released under the Apache License 2.0. Third-party components keep their original licenses (for example the MAGMa-derived annotation modules under benchmarks/spectral_properties/magma_support/ carry the MIST MIT notice).
Citation metadata for the current source release is in CITATION.cff. Cite this GitHub repository for the code and the corresponding dataset DOIs under Data and models for released benchmark data.
@software{ultrams,
title = {UltraMS: pretrained models for tandem mass spectra},
author = {Li, Yifan and Zhong, Yunhua and Liu, Pan and Xia, Jun},
year = {2026},
version = {0.3.2},
url = {https://github.com/Dsadd4/UltraMS},
license = {Apache-2.0}
}