Skip to content
Dsadd4Public

Repository files navigation

UltraMS

CI PyPI Python License MSnLib benchmark DOI SpectraVerse dataset DOI

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.

Install

python -m pip install ultrams
  • Reads MGF and .mgf.gz out 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; torch and transformers are installed as dependencies.
  • From a checkout: python -m pip install -e .

Quick start

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 rendered as a spiral galaxy of metabolite structure: chemical-class spiral arms with representative molecules as bright stars

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.

Embed a spectrum

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.

Embed a spectrum file

ultrams-embed spectra.mgf embeddings.npz --model unsupervised

The 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.

Fine-tune with PyTorch

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.

Choose a model

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.

Data and models

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

Pretraining

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.

Benchmarks

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 source data

Figure data and plotting scripts are provided in the accompanying Supplementary Source Data archive, organized by the panel numbers in the manuscript.

Repository layout

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

Documentation

Hardware

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).

Contributing

Bug reports, benchmark issues and pull requests are welcome; see CONTRIBUTING.md. Release notes are in CHANGELOG.md.

License

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).

Cite

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}
}

Releases

Packages

Contributors

Languages