ultrams 0.2.0__tar.gz → 0.3.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ultrams-0.3.1/CHANGELOG.md +47 -0
- ultrams-0.3.1/CITATION.cff +26 -0
- ultrams-0.3.1/CONTRIBUTING.md +47 -0
- ultrams-0.3.1/MANIFEST.in +6 -0
- ultrams-0.3.1/PKG-INFO +222 -0
- ultrams-0.3.1/README.md +190 -0
- ultrams-0.3.1/cookbook/tutorials/MASSSPECGYM_CONTRASTIVE.md +22 -0
- ultrams-0.3.1/cookbook/tutorials/README.md +13 -0
- ultrams-0.3.1/cookbook/tutorials/embed.ipynb +83 -0
- ultrams-0.3.1/cookbook/tutorials/massspecgym_contrastive.py +301 -0
- ultrams-0.3.1/cookbook/tutorials/pytorch_finetune.ipynb +97 -0
- ultrams-0.3.1/cookbook/tutorials/spectrum_search.ipynb +69 -0
- ultrams-0.3.1/docs/api.md +117 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/docs/data-format.md +15 -0
- ultrams-0.3.1/docs/faq.md +64 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/README.md +9 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/pytorch_finetune.py +7 -1
- ultrams-0.3.1/pyproject.toml +46 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/__init__.py +8 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/inference.py +18 -1
- ultrams-0.3.1/src/ultrams.egg-info/PKG-INFO +222 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/SOURCES.txt +11 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/tests/test_model_api.py +15 -0
- ultrams-0.2.0/MANIFEST.in +0 -2
- ultrams-0.2.0/PKG-INFO +0 -102
- ultrams-0.2.0/README.md +0 -84
- ultrams-0.2.0/pyproject.toml +0 -30
- ultrams-0.2.0/src/ultrams.egg-info/PKG-INFO +0 -102
- {ultrams-0.2.0 → ultrams-0.3.1}/LICENSE +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/docs/model-selection.md +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/batch_embeddings.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/data/NOTICE.md +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/data/example_5_spectra.mgf +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/examples/spectrum_search.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/setup.cfg +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/_architecture.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/cli.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/finetune.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/spectra.py +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/dependency_links.txt +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/entry_points.txt +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/requires.txt +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/top_level.txt +0 -0
- {ultrams-0.2.0 → ultrams-0.3.1}/tests/test_spectra.py +0 -0
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to UltraMS are documented here. The package follows semantic
|
|
4
|
+
versioning; the GitHub releases correspond to the PyPI versions.
|
|
5
|
+
|
|
6
|
+
## 0.3.1 — 2026-11-07
|
|
7
|
+
|
|
8
|
+
- Benchmark packages for spectral properties and molecular identification, including saved
|
|
9
|
+
outputs, metric recalculation scripts and the task documentation.
|
|
10
|
+
- Public benchmark releases: the UltraMS MSnLib benchmark (formula-level 80/10/10 and
|
|
11
|
+
strict-adduct molecule-level 70/15/15 partitions; Zenodo DOI 10.5281/zenodo.23963489) and
|
|
12
|
+
the UltraMS SpectraVerse dataset (molecule-level 8:1:1 split; Zenodo DOI
|
|
13
|
+
10.5281/zenodo.23964105).
|
|
14
|
+
- Manuscript figure source data and rendered panels for Figures 2 and 3 with per-file
|
|
15
|
+
provenance ledgers.
|
|
16
|
+
- Documentation: API/CLI reference, FAQ, contributing guide and repository layout.
|
|
17
|
+
|
|
18
|
+
## 0.3.0 — 2026-09-24
|
|
19
|
+
|
|
20
|
+
- Researcher tutorials: MGF embeddings, PyTorch fine-tuning and spectral search notebooks.
|
|
21
|
+
- A MassSpecGym contrastive tutorial that keeps the released folds and evaluates the held-out
|
|
22
|
+
test fold after reloading the selected checkpoint.
|
|
23
|
+
- Verification of all three public checkpoints against the installable package.
|
|
24
|
+
|
|
25
|
+
## 0.2.0 — 2026-09-24
|
|
26
|
+
|
|
27
|
+
- MGF reading with the base install and mzML with `ultrams[io]`.
|
|
28
|
+
- Ordered embedding export with `ultrams-embed` and `model.encode_batch()`.
|
|
29
|
+
- Complete examples for batch embeddings, PyTorch fine-tuning and spectrum similarity search.
|
|
30
|
+
- Documented checkpoint dimensions and input limits for `unsupervised`, `mona` and `search`.
|
|
31
|
+
|
|
32
|
+
## 0.1.3 — 2026-09-24
|
|
33
|
+
|
|
34
|
+
- Clear installation, embedding and fine-tuning instructions; aligned model cards.
|
|
35
|
+
|
|
36
|
+
## 0.1.2 — 2026-09-23
|
|
37
|
+
|
|
38
|
+
- Runnable README examples with self-contained sample spectra.
|
|
39
|
+
|
|
40
|
+
## 0.1.1 — 2026-09-23
|
|
41
|
+
|
|
42
|
+
- `pip install ultrams` release with the Unsupervised, MoNA contrastive and Search models.
|
|
43
|
+
- PyTorch-module interface and one-call fine-tuning.
|
|
44
|
+
|
|
45
|
+
## 0.1.0 — 2026-09-23
|
|
46
|
+
|
|
47
|
+
- Initial UltraMS inference package and pretraining source.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use UltraMS in your research, please cite this software."
|
|
3
|
+
type: software
|
|
4
|
+
title: UltraMS
|
|
5
|
+
abstract: "Pretrained transformer models for tandem mass spectra: spectrum and peak embedding, spectrum similarity search, fine-tuning, pretraining code, and benchmark code and results."
|
|
6
|
+
version: 0.3.1
|
|
7
|
+
date-released: 2026-11-07
|
|
8
|
+
authors:
|
|
9
|
+
- family-names: Li
|
|
10
|
+
given-names: Yifan
|
|
11
|
+
- family-names: Zhong
|
|
12
|
+
given-names: Yunhua
|
|
13
|
+
- family-names: Liu
|
|
14
|
+
given-names: Pan
|
|
15
|
+
- family-names: Xia
|
|
16
|
+
given-names: Jun
|
|
17
|
+
repository-code: https://github.com/Dsadd4/UltraMS
|
|
18
|
+
url: https://pypi.org/project/ultrams/
|
|
19
|
+
license: Apache-2.0
|
|
20
|
+
keywords:
|
|
21
|
+
- mass spectrometry
|
|
22
|
+
- tandem mass spectra
|
|
23
|
+
- MS/MS
|
|
24
|
+
- spectrum embedding
|
|
25
|
+
- metabolomics
|
|
26
|
+
- deep learning
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Contributing to UltraMS
|
|
2
|
+
|
|
3
|
+
Thanks for helping improve UltraMS. This repository contains the inference package,
|
|
4
|
+
pretraining code, benchmark code, and the source data behind the manuscript figures.
|
|
5
|
+
|
|
6
|
+
## Development setup
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
git clone https://github.com/Dsadd4/UltraMS.git
|
|
10
|
+
cd UltraMS
|
|
11
|
+
python -m venv .venv
|
|
12
|
+
source .venv/bin/activate
|
|
13
|
+
python -m pip install -e .
|
|
14
|
+
python -m unittest discover -s tests -v
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The checkpoint verification test (`tests/check_released_models.py`) downloads the three
|
|
18
|
+
released checkpoints from Hugging Face and is also run by the PyPI publish workflow.
|
|
19
|
+
|
|
20
|
+
## What to work on
|
|
21
|
+
|
|
22
|
+
- **Bug reports** — use the bug report issue template. Include the package version
|
|
23
|
+
(`python -c "import ultrams; print(ultrams.__version__)"`), Python version, OS, device,
|
|
24
|
+
and a minimal reproduction (spectrum input or file excerpt).
|
|
25
|
+
- **Features** — open an issue describing the use case before a large pull request.
|
|
26
|
+
- **Benchmarks** — benchmark results belong in `benchmarks/` with their saved outputs and a
|
|
27
|
+
`reproduce.py` path; see `benchmarks/README.md` for the conventions and the input
|
|
28
|
+
licensing requirements.
|
|
29
|
+
- **Documentation and tutorials** — `docs/`, `examples/`, and `cookbook/` are good starting
|
|
30
|
+
points.
|
|
31
|
+
|
|
32
|
+
## Data and repository policy
|
|
33
|
+
|
|
34
|
+
- Large spectra, embeddings, model weights and evaluation arrays are not committed to Git.
|
|
35
|
+
Use the released Hugging Face datasets and checkpoint repositories and document the
|
|
36
|
+
source, byte size and SHA-256 in the relevant README.
|
|
37
|
+
- Do not add credentials, private hosts or absolute paths.
|
|
38
|
+
- Third-party code keeps its original license; add the license text next to the code.
|
|
39
|
+
|
|
40
|
+
## Pull requests
|
|
41
|
+
|
|
42
|
+
1. Keep changes focused and include or update tests where behavior changes.
|
|
43
|
+
2. Run the test suite locally (`python -m unittest discover -s tests -v`).
|
|
44
|
+
3. Update documentation and `CHANGELOG.md` for user-visible changes.
|
|
45
|
+
4. Describe the motivation, the change and how it was verified.
|
|
46
|
+
|
|
47
|
+
By contributing you agree that your contributions are licensed under the Apache License 2.0.
|
ultrams-0.3.1/PKG-INFO
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ultrams
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Pretrained UltraMS models for mass spectrometry
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/Dsadd4/UltraMS
|
|
7
|
+
Project-URL: Source, https://github.com/Dsadd4/UltraMS
|
|
8
|
+
Project-URL: Documentation, https://github.com/Dsadd4/UltraMS/blob/main/docs/api.md
|
|
9
|
+
Project-URL: Changelog, https://github.com/Dsadd4/UltraMS/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Issue Tracker, https://github.com/Dsadd4/UltraMS/issues
|
|
11
|
+
Project-URL: Datasets, https://huggingface.co/datasets/dsadd4
|
|
12
|
+
Keywords: mass spectrometry,tandem mass spectra,MS/MS,spectrum embedding,metabolomics,deep learning
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: numpy<3,>=1.24
|
|
26
|
+
Requires-Dist: torch>=2.1
|
|
27
|
+
Requires-Dist: transformers<5,>=4.33
|
|
28
|
+
Requires-Dist: huggingface-hub<1,>=0.23
|
|
29
|
+
Provides-Extra: io
|
|
30
|
+
Requires-Dist: pyteomics>=4.6; extra == "io"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# UltraMS
|
|
34
|
+
|
|
35
|
+
[](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml)
|
|
36
|
+
[](https://pypi.org/project/ultrams/)
|
|
37
|
+
[](https://github.com/Dsadd4/UltraMS/blob/main/pyproject.toml)
|
|
38
|
+
[](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE)
|
|
39
|
+
[](https://doi.org/10.5281/zenodo.23963489)
|
|
40
|
+
[](https://doi.org/10.5281/zenodo.23964105)
|
|
41
|
+
|
|
42
|
+
**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 161 million experimental MS/MS spectra (UltraMSdata) and released with pretrained weights, pretraining code, benchmark code, and the source data behind the manuscript figures.
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
python -m pip install ultrams
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- Reads MGF and `.mgf.gz` out of the box; `python -m pip install 'ultrams[io]'` adds mzML support.
|
|
51
|
+
- CPU, CUDA and Apple MPS devices are supported (`device="cuda"`, `device="mps"`).
|
|
52
|
+
- Python 3.10 or newer; `torch` and `transformers` are installed as dependencies.
|
|
53
|
+
- From a checkout: `python -m pip install -e .`
|
|
54
|
+
|
|
55
|
+
## Quick start
|
|
56
|
+
|
|
57
|
+
| I want to… | Start here |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| Embed one spectrum | [Python example](#embed-a-spectrum) |
|
|
60
|
+
| Embed an MGF or mzML file | [File command](#embed-a-spectrum-file) |
|
|
61
|
+
| Train on my labelled spectra | [PyTorch example](#fine-tune-with-pytorch) · [complete MGF example](https://github.com/Dsadd4/UltraMS/blob/main/examples/pytorch_finetune.py) |
|
|
62
|
+
| Compare spectra | [Search example](https://github.com/Dsadd4/UltraMS/blob/main/examples/spectrum_search.py) |
|
|
63
|
+
| Learn in a notebook | [UltraMS tutorials](https://github.com/Dsadd4/UltraMS/tree/main/cookbook/tutorials) |
|
|
64
|
+
| Inspect or run pretraining | [Training code](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) |
|
|
65
|
+
| Reproduce the paper benchmarks | [Spectral properties and molecular identification](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md) |
|
|
66
|
+
| Inspect manuscript figure source data | [Figure 2 and Figure 3 source data and rendered panels](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md) |
|
|
67
|
+
| Use the public API / CLI reference | [API and CLI](https://github.com/Dsadd4/UltraMS/blob/main/docs/api.md) |
|
|
68
|
+
|
|
69
|
+
<p align="center">
|
|
70
|
+
<img src="assets/ultrams_banner.png" alt="The UltraAtlas rendered as a spiral galaxy of metabolite structure: chemical-class spiral arms with representative molecules as bright stars" width="880">
|
|
71
|
+
</p>
|
|
72
|
+
|
|
73
|
+
<p align="center"><em>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.</em></p>
|
|
74
|
+
|
|
75
|
+
## Embed a spectrum
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from ultrams import UltraMS
|
|
79
|
+
|
|
80
|
+
model = UltraMS.from_pretrained("unsupervised")
|
|
81
|
+
embedding = model.encode(
|
|
82
|
+
mz=[100.1, 121.1, 150.0],
|
|
83
|
+
intensity=[20, 100, 35],
|
|
84
|
+
precursor_mz=301.2,
|
|
85
|
+
).embedding
|
|
86
|
+
print(embedding.shape) # (1024,)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
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.
|
|
90
|
+
|
|
91
|
+
The three checkpoints are collected on [Hugging Face](https://huggingface.co/collections/dsadd4/ultrams-6ab4cfaa860cbbd1f9a6b9b6).
|
|
92
|
+
|
|
93
|
+
## Embed a spectrum file
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
ultrams-embed spectra.mgf embeddings.npz --model unsupervised
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
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](https://github.com/Dsadd4/UltraMS/tree/main/examples) includes five real MS/MS spectra and a complete Python batch workflow.
|
|
100
|
+
|
|
101
|
+
## Fine-tune with PyTorch
|
|
102
|
+
|
|
103
|
+
`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.
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
import torch
|
|
107
|
+
from torch.utils.data import DataLoader
|
|
108
|
+
from ultrams import UltraMS
|
|
109
|
+
|
|
110
|
+
dataset = [
|
|
111
|
+
{"mz": [100.1, 121.1, 150.0], "intensity": [20, 100, 35], "precursor_mz": 301.2, "target": 0.5},
|
|
112
|
+
{"mz": [102.1, 135.2, 167.3], "intensity": [40, 100, 25], "precursor_mz": 315.3, "target": 0.7},
|
|
113
|
+
]
|
|
114
|
+
device = "cuda" if torch.cuda.is_available() else "cpu"
|
|
115
|
+
model = UltraMS.from_pretrained("unsupervised", device=device).train()
|
|
116
|
+
head = torch.nn.Linear(model.embedding_dim, 1).to(device)
|
|
117
|
+
loader = DataLoader(dataset, batch_size=2, collate_fn=model.batch_converter())
|
|
118
|
+
optimizer = torch.optim.AdamW([*model.parameters(), *head.parameters()], lr=1e-5)
|
|
119
|
+
|
|
120
|
+
for batch in loader:
|
|
121
|
+
batch = {name: value.to(device) for name, value in batch.items()}
|
|
122
|
+
prediction = head(model(batch["peaks"], batch["attention_mask"], batch["precursor_mz"]))
|
|
123
|
+
loss = torch.nn.functional.mse_loss(prediction.squeeze(-1), batch["target"])
|
|
124
|
+
optimizer.zero_grad()
|
|
125
|
+
loss.backward()
|
|
126
|
+
optimizer.step()
|
|
127
|
+
print(f"loss: {loss.item():.4f}")
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The [complete fine-tuning example](https://github.com/Dsadd4/UltraMS/blob/main/examples/pytorch_finetune.py) 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](https://github.com/Dsadd4/UltraMS/blob/main/docs/data-format.md) for the input format.
|
|
131
|
+
|
|
132
|
+
For measured molecular labels, the [MassSpecGym contrastive tutorial](https://github.com/Dsadd4/UltraMS/blob/main/cookbook/tutorials/MASSSPECGYM_CONTRASTIVE.md) downloads the dataset, keeps its train/validation/test folds, fine-tunes the encoder, and reloads the selected checkpoint.
|
|
133
|
+
|
|
134
|
+
## Choose a model
|
|
135
|
+
|
|
136
|
+
| Model name | Representation | Dimension | Spectral peak limit | Weights |
|
|
137
|
+
| --- | --- | ---: | ---: | --- |
|
|
138
|
+
| `unsupervised` | Encoder spectrum embedding | 1024 | 150 | [Unsupervised](https://huggingface.co/dsadd4/UltraMS-Unsupervised) |
|
|
139
|
+
| `mona` | MoNA contrastive projection | 1024 | 100 | [MoNA contrastive](https://huggingface.co/dsadd4/UltraMS-MoNA-Contrastive) |
|
|
140
|
+
| `search` | UltraAtlas search projection | 512 | 150 | [Search](https://huggingface.co/dsadd4/UltraMS-Search) |
|
|
141
|
+
|
|
142
|
+
Load any of them with `UltraMS.from_pretrained("name")`, or load a downloaded `model.pt` with `UltraMS.from_checkpoint(path)`. [Model selection](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md) explains the training purpose and output of each checkpoint. The Search checkpoint is the **UltraAtlas application `best.pt`**.
|
|
143
|
+
|
|
144
|
+
## Data and models
|
|
145
|
+
|
|
146
|
+
Pre-trained checkpoints:
|
|
147
|
+
|
|
148
|
+
| Checkpoint | Training data | Size | Weights |
|
|
149
|
+
| --- | --- | ---: | --- |
|
|
150
|
+
| Unsupervised | UltraMSdata pretraining + retention time | ~0.8 GB | [HF](https://huggingface.co/dsadd4/UltraMS-Unsupervised) |
|
|
151
|
+
| MoNA contrastive | MoNA contrastive | ~1.2 GB | [HF](https://huggingface.co/dsadd4/UltraMS-MoNA-Contrastive) |
|
|
152
|
+
| Search | UltraAtlas spectrum-to-spectrum contrastive | ~1.0 GB | [HF](https://huggingface.co/dsadd4/UltraMS-Search) |
|
|
153
|
+
|
|
154
|
+
Released reference data (the paper's benchmark inputs are downloadable from public sources; see each benchmark page):
|
|
155
|
+
|
|
156
|
+
| Dataset | Contents | DOI | Mirror |
|
|
157
|
+
| --- | --- | --- | --- |
|
|
158
|
+
| 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](https://doi.org/10.5281/zenodo.23963489) | [HF](https://huggingface.co/datasets/dsadd4/UltraMS-MSnLib-Benchmark) |
|
|
159
|
+
| 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](https://doi.org/10.5281/zenodo.23964105) | [HF](https://huggingface.co/datasets/dsadd4/UltraMS-Spectraverse-Dataset) |
|
|
160
|
+
|
|
161
|
+
Manuscript figure source data and rendered panels (Figure 2 and Figure 3, including the supplementary NPLIB1, MassSpecGym and MSnLib comparisons) are in [`paper_figures/`](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md). The plotting scripts are not redistributed; filenames are kept as provenance references.
|
|
162
|
+
|
|
163
|
+
## Pretraining
|
|
164
|
+
|
|
165
|
+
The [UltraMSdata pretraining package](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) contains the current model architecture, training entry points, configuration and history outputs. It installs separately from the inference package.
|
|
166
|
+
|
|
167
|
+
## Benchmarks
|
|
168
|
+
|
|
169
|
+
The [benchmark code and results](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md) cover spectral properties and molecular identification. The task pages link to public input downloads, training and test commands, and the measured results.
|
|
170
|
+
|
|
171
|
+
## Paper figures
|
|
172
|
+
|
|
173
|
+
[`paper_figures/`](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md) 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.
|
|
174
|
+
|
|
175
|
+
## Repository layout
|
|
176
|
+
|
|
177
|
+
| Path | Contents |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| `src/ultrams/` | Installable inference package (`UltraMS`, `UltraMSPredictor`, spectrum readers, CLI) |
|
|
180
|
+
| `training/` | Pretraining and adaptation package (model architecture, data tools, configs, entry points) |
|
|
181
|
+
| `benchmarks/` | Benchmark input preparation, training/evaluation code, saved outputs and metric recalculation |
|
|
182
|
+
| `paper_figures/` | Plotted source data, rendered panels and provenance ledgers for Figures 2 and 3 |
|
|
183
|
+
| `examples/` | Runnable embedding, fine-tuning and spectrum-search examples |
|
|
184
|
+
| `cookbook/` | Tutorials and notebooks |
|
|
185
|
+
| `docs/` | Spectrum input format, model selection, API/CLI reference, FAQ |
|
|
186
|
+
| `hub/` | Model cards for the released checkpoints |
|
|
187
|
+
| `tests/` | Unit tests and released-checkpoint verification |
|
|
188
|
+
|
|
189
|
+
## Documentation
|
|
190
|
+
|
|
191
|
+
- [Spectrum input and preprocessing](https://github.com/Dsadd4/UltraMS/blob/main/docs/data-format.md)
|
|
192
|
+
- [Model selection](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md)
|
|
193
|
+
- [Python API and CLI](https://github.com/Dsadd4/UltraMS/blob/main/docs/api.md)
|
|
194
|
+
- [FAQ and troubleshooting](https://github.com/Dsadd4/UltraMS/blob/main/docs/faq.md)
|
|
195
|
+
- [Examples](https://github.com/Dsadd4/UltraMS/blob/main/examples/README.md) · [Tutorials](https://github.com/Dsadd4/UltraMS/blob/main/cookbook/tutorials/README.md) · [Training](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) · [Benchmarks](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md)
|
|
196
|
+
|
|
197
|
+
## Hardware
|
|
198
|
+
|
|
199
|
+
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](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md)).
|
|
200
|
+
|
|
201
|
+
## Contributing
|
|
202
|
+
|
|
203
|
+
Bug reports, benchmark issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/Dsadd4/UltraMS/blob/main/CONTRIBUTING.md). Release notes are in [CHANGELOG.md](https://github.com/Dsadd4/UltraMS/blob/main/CHANGELOG.md).
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
UltraMS is released under the [Apache License 2.0](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE). 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).
|
|
208
|
+
|
|
209
|
+
## Cite
|
|
210
|
+
|
|
211
|
+
Citation metadata for this software is in [CITATION.cff](https://github.com/Dsadd4/UltraMS/blob/main/CITATION.cff). If you use the released benchmark data, cite the corresponding dataset DOIs listed under [Data and models](#data-and-models).
|
|
212
|
+
|
|
213
|
+
```bibtex
|
|
214
|
+
@software{ultrams,
|
|
215
|
+
title = {UltraMS: pretrained models for tandem mass spectra},
|
|
216
|
+
author = {Li, Yifan and Zhong, Yunhua and Liu, Pan and Xia, Jun},
|
|
217
|
+
year = {2026},
|
|
218
|
+
version = {0.3.0},
|
|
219
|
+
url = {https://github.com/Dsadd4/UltraMS},
|
|
220
|
+
license = {Apache-2.0}
|
|
221
|
+
}
|
|
222
|
+
```
|
ultrams-0.3.1/README.md
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# UltraMS
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/ultrams/)
|
|
5
|
+
[](https://github.com/Dsadd4/UltraMS/blob/main/pyproject.toml)
|
|
6
|
+
[](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE)
|
|
7
|
+
[](https://doi.org/10.5281/zenodo.23963489)
|
|
8
|
+
[](https://doi.org/10.5281/zenodo.23964105)
|
|
9
|
+
|
|
10
|
+
**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 161 million experimental MS/MS spectra (UltraMSdata) and released with pretrained weights, pretraining code, benchmark code, and the source data behind the manuscript figures.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
python -m pip install ultrams
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- Reads MGF and `.mgf.gz` out of the box; `python -m pip install 'ultrams[io]'` adds mzML support.
|
|
19
|
+
- CPU, CUDA and Apple MPS devices are supported (`device="cuda"`, `device="mps"`).
|
|
20
|
+
- Python 3.10 or newer; `torch` and `transformers` are installed as dependencies.
|
|
21
|
+
- From a checkout: `python -m pip install -e .`
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
| I want to… | Start here |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| Embed one spectrum | [Python example](#embed-a-spectrum) |
|
|
28
|
+
| Embed an MGF or mzML file | [File command](#embed-a-spectrum-file) |
|
|
29
|
+
| Train on my labelled spectra | [PyTorch example](#fine-tune-with-pytorch) · [complete MGF example](https://github.com/Dsadd4/UltraMS/blob/main/examples/pytorch_finetune.py) |
|
|
30
|
+
| Compare spectra | [Search example](https://github.com/Dsadd4/UltraMS/blob/main/examples/spectrum_search.py) |
|
|
31
|
+
| Learn in a notebook | [UltraMS tutorials](https://github.com/Dsadd4/UltraMS/tree/main/cookbook/tutorials) |
|
|
32
|
+
| Inspect or run pretraining | [Training code](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) |
|
|
33
|
+
| Reproduce the paper benchmarks | [Spectral properties and molecular identification](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md) |
|
|
34
|
+
| Inspect manuscript figure source data | [Figure 2 and Figure 3 source data and rendered panels](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md) |
|
|
35
|
+
| Use the public API / CLI reference | [API and CLI](https://github.com/Dsadd4/UltraMS/blob/main/docs/api.md) |
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<img src="assets/ultrams_banner.png" alt="The UltraAtlas rendered as a spiral galaxy of metabolite structure: chemical-class spiral arms with representative molecules as bright stars" width="880">
|
|
39
|
+
</p>
|
|
40
|
+
|
|
41
|
+
<p align="center"><em>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.</em></p>
|
|
42
|
+
|
|
43
|
+
## Embed a spectrum
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from ultrams import UltraMS
|
|
47
|
+
|
|
48
|
+
model = UltraMS.from_pretrained("unsupervised")
|
|
49
|
+
embedding = model.encode(
|
|
50
|
+
mz=[100.1, 121.1, 150.0],
|
|
51
|
+
intensity=[20, 100, 35],
|
|
52
|
+
precursor_mz=301.2,
|
|
53
|
+
).embedding
|
|
54
|
+
print(embedding.shape) # (1024,)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
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.
|
|
58
|
+
|
|
59
|
+
The three checkpoints are collected on [Hugging Face](https://huggingface.co/collections/dsadd4/ultrams-6ab4cfaa860cbbd1f9a6b9b6).
|
|
60
|
+
|
|
61
|
+
## Embed a spectrum file
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
ultrams-embed spectra.mgf embeddings.npz --model unsupervised
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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](https://github.com/Dsadd4/UltraMS/tree/main/examples) includes five real MS/MS spectra and a complete Python batch workflow.
|
|
68
|
+
|
|
69
|
+
## Fine-tune with PyTorch
|
|
70
|
+
|
|
71
|
+
`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.
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
import torch
|
|
75
|
+
from torch.utils.data import DataLoader
|
|
76
|
+
from ultrams import UltraMS
|
|
77
|
+
|
|
78
|
+
dataset = [
|
|
79
|
+
{"mz": [100.1, 121.1, 150.0], "intensity": [20, 100, 35], "precursor_mz": 301.2, "target": 0.5},
|
|
80
|
+
{"mz": [102.1, 135.2, 167.3], "intensity": [40, 100, 25], "precursor_mz": 315.3, "target": 0.7},
|
|
81
|
+
]
|
|
82
|
+
device = "cuda" if torch.cuda.is_available() else "cpu"
|
|
83
|
+
model = UltraMS.from_pretrained("unsupervised", device=device).train()
|
|
84
|
+
head = torch.nn.Linear(model.embedding_dim, 1).to(device)
|
|
85
|
+
loader = DataLoader(dataset, batch_size=2, collate_fn=model.batch_converter())
|
|
86
|
+
optimizer = torch.optim.AdamW([*model.parameters(), *head.parameters()], lr=1e-5)
|
|
87
|
+
|
|
88
|
+
for batch in loader:
|
|
89
|
+
batch = {name: value.to(device) for name, value in batch.items()}
|
|
90
|
+
prediction = head(model(batch["peaks"], batch["attention_mask"], batch["precursor_mz"]))
|
|
91
|
+
loss = torch.nn.functional.mse_loss(prediction.squeeze(-1), batch["target"])
|
|
92
|
+
optimizer.zero_grad()
|
|
93
|
+
loss.backward()
|
|
94
|
+
optimizer.step()
|
|
95
|
+
print(f"loss: {loss.item():.4f}")
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The [complete fine-tuning example](https://github.com/Dsadd4/UltraMS/blob/main/examples/pytorch_finetune.py) 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](https://github.com/Dsadd4/UltraMS/blob/main/docs/data-format.md) for the input format.
|
|
99
|
+
|
|
100
|
+
For measured molecular labels, the [MassSpecGym contrastive tutorial](https://github.com/Dsadd4/UltraMS/blob/main/cookbook/tutorials/MASSSPECGYM_CONTRASTIVE.md) downloads the dataset, keeps its train/validation/test folds, fine-tunes the encoder, and reloads the selected checkpoint.
|
|
101
|
+
|
|
102
|
+
## Choose a model
|
|
103
|
+
|
|
104
|
+
| Model name | Representation | Dimension | Spectral peak limit | Weights |
|
|
105
|
+
| --- | --- | ---: | ---: | --- |
|
|
106
|
+
| `unsupervised` | Encoder spectrum embedding | 1024 | 150 | [Unsupervised](https://huggingface.co/dsadd4/UltraMS-Unsupervised) |
|
|
107
|
+
| `mona` | MoNA contrastive projection | 1024 | 100 | [MoNA contrastive](https://huggingface.co/dsadd4/UltraMS-MoNA-Contrastive) |
|
|
108
|
+
| `search` | UltraAtlas search projection | 512 | 150 | [Search](https://huggingface.co/dsadd4/UltraMS-Search) |
|
|
109
|
+
|
|
110
|
+
Load any of them with `UltraMS.from_pretrained("name")`, or load a downloaded `model.pt` with `UltraMS.from_checkpoint(path)`. [Model selection](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md) explains the training purpose and output of each checkpoint. The Search checkpoint is the **UltraAtlas application `best.pt`**.
|
|
111
|
+
|
|
112
|
+
## Data and models
|
|
113
|
+
|
|
114
|
+
Pre-trained checkpoints:
|
|
115
|
+
|
|
116
|
+
| Checkpoint | Training data | Size | Weights |
|
|
117
|
+
| --- | --- | ---: | --- |
|
|
118
|
+
| Unsupervised | UltraMSdata pretraining + retention time | ~0.8 GB | [HF](https://huggingface.co/dsadd4/UltraMS-Unsupervised) |
|
|
119
|
+
| MoNA contrastive | MoNA contrastive | ~1.2 GB | [HF](https://huggingface.co/dsadd4/UltraMS-MoNA-Contrastive) |
|
|
120
|
+
| Search | UltraAtlas spectrum-to-spectrum contrastive | ~1.0 GB | [HF](https://huggingface.co/dsadd4/UltraMS-Search) |
|
|
121
|
+
|
|
122
|
+
Released reference data (the paper's benchmark inputs are downloadable from public sources; see each benchmark page):
|
|
123
|
+
|
|
124
|
+
| Dataset | Contents | DOI | Mirror |
|
|
125
|
+
| --- | --- | --- | --- |
|
|
126
|
+
| 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](https://doi.org/10.5281/zenodo.23963489) | [HF](https://huggingface.co/datasets/dsadd4/UltraMS-MSnLib-Benchmark) |
|
|
127
|
+
| 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](https://doi.org/10.5281/zenodo.23964105) | [HF](https://huggingface.co/datasets/dsadd4/UltraMS-Spectraverse-Dataset) |
|
|
128
|
+
|
|
129
|
+
Manuscript figure source data and rendered panels (Figure 2 and Figure 3, including the supplementary NPLIB1, MassSpecGym and MSnLib comparisons) are in [`paper_figures/`](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md). The plotting scripts are not redistributed; filenames are kept as provenance references.
|
|
130
|
+
|
|
131
|
+
## Pretraining
|
|
132
|
+
|
|
133
|
+
The [UltraMSdata pretraining package](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) contains the current model architecture, training entry points, configuration and history outputs. It installs separately from the inference package.
|
|
134
|
+
|
|
135
|
+
## Benchmarks
|
|
136
|
+
|
|
137
|
+
The [benchmark code and results](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md) cover spectral properties and molecular identification. The task pages link to public input downloads, training and test commands, and the measured results.
|
|
138
|
+
|
|
139
|
+
## Paper figures
|
|
140
|
+
|
|
141
|
+
[`paper_figures/`](https://github.com/Dsadd4/UltraMS/blob/main/paper_figures/README.md) 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.
|
|
142
|
+
|
|
143
|
+
## Repository layout
|
|
144
|
+
|
|
145
|
+
| Path | Contents |
|
|
146
|
+
| --- | --- |
|
|
147
|
+
| `src/ultrams/` | Installable inference package (`UltraMS`, `UltraMSPredictor`, spectrum readers, CLI) |
|
|
148
|
+
| `training/` | Pretraining and adaptation package (model architecture, data tools, configs, entry points) |
|
|
149
|
+
| `benchmarks/` | Benchmark input preparation, training/evaluation code, saved outputs and metric recalculation |
|
|
150
|
+
| `paper_figures/` | Plotted source data, rendered panels and provenance ledgers for Figures 2 and 3 |
|
|
151
|
+
| `examples/` | Runnable embedding, fine-tuning and spectrum-search examples |
|
|
152
|
+
| `cookbook/` | Tutorials and notebooks |
|
|
153
|
+
| `docs/` | Spectrum input format, model selection, API/CLI reference, FAQ |
|
|
154
|
+
| `hub/` | Model cards for the released checkpoints |
|
|
155
|
+
| `tests/` | Unit tests and released-checkpoint verification |
|
|
156
|
+
|
|
157
|
+
## Documentation
|
|
158
|
+
|
|
159
|
+
- [Spectrum input and preprocessing](https://github.com/Dsadd4/UltraMS/blob/main/docs/data-format.md)
|
|
160
|
+
- [Model selection](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md)
|
|
161
|
+
- [Python API and CLI](https://github.com/Dsadd4/UltraMS/blob/main/docs/api.md)
|
|
162
|
+
- [FAQ and troubleshooting](https://github.com/Dsadd4/UltraMS/blob/main/docs/faq.md)
|
|
163
|
+
- [Examples](https://github.com/Dsadd4/UltraMS/blob/main/examples/README.md) · [Tutorials](https://github.com/Dsadd4/UltraMS/blob/main/cookbook/tutorials/README.md) · [Training](https://github.com/Dsadd4/UltraMS/blob/main/training/README.md) · [Benchmarks](https://github.com/Dsadd4/UltraMS/blob/main/benchmarks/README.md)
|
|
164
|
+
|
|
165
|
+
## Hardware
|
|
166
|
+
|
|
167
|
+
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](https://github.com/Dsadd4/UltraMS/blob/main/docs/model-selection.md)).
|
|
168
|
+
|
|
169
|
+
## Contributing
|
|
170
|
+
|
|
171
|
+
Bug reports, benchmark issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/Dsadd4/UltraMS/blob/main/CONTRIBUTING.md). Release notes are in [CHANGELOG.md](https://github.com/Dsadd4/UltraMS/blob/main/CHANGELOG.md).
|
|
172
|
+
|
|
173
|
+
## License
|
|
174
|
+
|
|
175
|
+
UltraMS is released under the [Apache License 2.0](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE). 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).
|
|
176
|
+
|
|
177
|
+
## Cite
|
|
178
|
+
|
|
179
|
+
Citation metadata for this software is in [CITATION.cff](https://github.com/Dsadd4/UltraMS/blob/main/CITATION.cff). If you use the released benchmark data, cite the corresponding dataset DOIs listed under [Data and models](#data-and-models).
|
|
180
|
+
|
|
181
|
+
```bibtex
|
|
182
|
+
@software{ultrams,
|
|
183
|
+
title = {UltraMS: pretrained models for tandem mass spectra},
|
|
184
|
+
author = {Li, Yifan and Zhong, Yunhua and Liu, Pan and Xia, Jun},
|
|
185
|
+
year = {2026},
|
|
186
|
+
version = {0.3.0},
|
|
187
|
+
url = {https://github.com/Dsadd4/UltraMS},
|
|
188
|
+
license = {Apache-2.0}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Contrastive fine-tuning with MassSpecGym
|
|
2
|
+
|
|
3
|
+
This tutorial fine-tunes the **UltraMS Unsupervised** encoder on MassSpecGym. Two distinct MS/MS spectra with the same `inchikey` are a positive pair; spectra from different molecules in a batch are negatives. The dataset's `train`, `val`, and `test` folds are retained, and the script checks that no molecular key appears in more than one fold. It keeps spectra with at least three positive-intensity, positive-m/z peaks and records the source and selected row and molecule counts in `data_audit.json`.
|
|
4
|
+
|
|
5
|
+
Install UltraMS, then run the small teaching subset from the repository root:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
python -m pip install -e .
|
|
9
|
+
python cookbook/tutorials/massspecgym_contrastive.py --output-dir /path/to/my_run
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The default selects up to 64 train molecules and 24 molecules from each evaluation fold, with two distinct spectra per molecule. Selection is deterministic. To use every training molecule with at least two distinct spectra and all valid evaluation spectra, after removing exact spectral duplicates:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
python cookbook/tutorials/massspecgym_contrastive.py --full --output-dir /path/to/full_run
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The full run can take substantially longer. `--data-file /path/to/MassSpecGym.tsv` reuses a local copy; otherwise the script downloads the pinned file through Hugging Face Hub. In both cases it checks SHA-256 before reading. The source is [`roman-bushuiev/MassSpecGym`](https://huggingface.co/datasets/roman-bushuiev/MassSpecGym), revision `d2e86d0c3bd905a6d578c0dd6053ed2bd41f9c2a`, file `data/MassSpecGym.tsv`, SHA-256 `0c9cc50450def3f0d4fe2dc09dea1105fc15e635db8c6656bc3e3be37a3bcd95`.
|
|
19
|
+
|
|
20
|
+
The script writes `best.pt`, `config.json`, `data_audit.json`, `history.json`, and `test.json`. Validation selects the checkpoint; the held-out test fold is evaluated once afterward. Top1 means nearest *other spectrum* within the same fold has the same `inchikey`; singleton molecules are candidates but cannot be queries. This is a **tutorial retrieval task**, not an official MassSpecGym benchmark or a reported UltraMS result. The label is molecular identity from the dataset, not measured retention time or logP.
|
|
21
|
+
|
|
22
|
+
For the original dataset and citation, see [MassSpecGym](https://github.com/pluskal-lab/MassSpecGym).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# UltraMS tutorials
|
|
2
|
+
|
|
3
|
+
Each notebook runs from top to bottom on the [five-spectrum MGF example](../../examples/data/NOTICE.md). It installs UltraMS from PyPI and downloads the selected model from Hugging Face on first use.
|
|
4
|
+
|
|
5
|
+
| Tutorial | Notebook | Colab |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| Read MGF and obtain embeddings | [Get embeddings](embed.ipynb) | [Open in Colab](https://colab.research.google.com/github/Dsadd4/UltraMS/blob/main/cookbook/tutorials/embed.ipynb) |
|
|
8
|
+
| Fine-tune in a PyTorch loop | [PyTorch fine-tuning](pytorch_finetune.ipynb) | [Open in Colab](https://colab.research.google.com/github/Dsadd4/UltraMS/blob/main/cookbook/tutorials/pytorch_finetune.ipynb) |
|
|
9
|
+
| Rank spectra with the Search model | [Spectrum search](spectrum_search.ipynb) | [Open in Colab](https://colab.research.google.com/github/Dsadd4/UltraMS/blob/main/cookbook/tutorials/spectrum_search.ipynb) |
|
|
10
|
+
|
|
11
|
+
The fine-tuning labels are placeholders for learning the API. They do not represent measured properties or a model performance result.
|
|
12
|
+
|
|
13
|
+
For a complete fine-tuning example with real molecular labels and the original dataset folds, follow the [MassSpecGym contrastive tutorial](MASSSPECGYM_CONTRASTIVE.md).
|