UltraMS pretrained MS/MS models, PyTorch fine-tuning, and pretraining code
  • Python 96.8%
  • Shell 2.6%
  • Jupyter Notebook 0.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-15 08:12:19 -08:00
.github Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
assets Remove the tagline from the repository banner 2026-11-15 08:12:19 -08:00
benchmarks Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
cookbook/tutorials Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
docs Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
examples Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
hub Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
paper_figures Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
src/ultrams Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
tests Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
training Point the UltraMSdata manifest link to the official record 2026-11-15 01:19:42 -08:00
.gitignore Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
CHANGELOG.md Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
CITATION.cff Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
CONTRIBUTING.md Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
LICENSE Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
MANIFEST.in Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
pyproject.toml Release UltraMS with the current UltraMSdata training workflow 2026-11-14 09:47:00 -08:00
README.md Point the UltraMSdata manifest link to the official record 2026-11-15 01:19:42 -08:00

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
Inspect manuscript figure source data Figure 2 and Figure 3 source data and rendered panels
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). 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 ~1.2 GB HF
Search UltraAtlas spectrum-to-spectrum contrastive ~1.0 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 UltraMS formula-level 80/10/10 split; strict-adduct molecule-level 70/15/15 split with queries and libraries for library search 10.5281/zenodo.23963489 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 —
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

Manuscript figure source data and rendered panels (Figure 2 and Figure 3, including the supplementary NPLIB1, MassSpecGym and MSnLib comparisons) are in paper_figures/. The plotting scripts are not redistributed; filenames are kept as provenance references.

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; the complete processed pretraining shard bundle is not yet available as a public download.

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.

Paper figures

paper_figures/ contains the plotted source data and rendered panels for Figure 2 and Figure 3, including the supplementary NPLIB1, MassSpecGym and MSnLib comparison panels. The plotting scripts themselves are not redistributed; filenames are kept as provenance references. Each figure has a panel-by-panel README and a panel_manifest.json provenance ledger; large evaluation arrays are not redistributed and their sources are documented.

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
paper_figures/ Plotted source data, rendered panels and provenance ledgers for Figures 2 and 3
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}
}