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.
Files changed (44) hide show
  1. ultrams-0.3.1/CHANGELOG.md +47 -0
  2. ultrams-0.3.1/CITATION.cff +26 -0
  3. ultrams-0.3.1/CONTRIBUTING.md +47 -0
  4. ultrams-0.3.1/MANIFEST.in +6 -0
  5. ultrams-0.3.1/PKG-INFO +222 -0
  6. ultrams-0.3.1/README.md +190 -0
  7. ultrams-0.3.1/cookbook/tutorials/MASSSPECGYM_CONTRASTIVE.md +22 -0
  8. ultrams-0.3.1/cookbook/tutorials/README.md +13 -0
  9. ultrams-0.3.1/cookbook/tutorials/embed.ipynb +83 -0
  10. ultrams-0.3.1/cookbook/tutorials/massspecgym_contrastive.py +301 -0
  11. ultrams-0.3.1/cookbook/tutorials/pytorch_finetune.ipynb +97 -0
  12. ultrams-0.3.1/cookbook/tutorials/spectrum_search.ipynb +69 -0
  13. ultrams-0.3.1/docs/api.md +117 -0
  14. {ultrams-0.2.0 → ultrams-0.3.1}/docs/data-format.md +15 -0
  15. ultrams-0.3.1/docs/faq.md +64 -0
  16. {ultrams-0.2.0 → ultrams-0.3.1}/examples/README.md +9 -0
  17. {ultrams-0.2.0 → ultrams-0.3.1}/examples/pytorch_finetune.py +7 -1
  18. ultrams-0.3.1/pyproject.toml +46 -0
  19. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/__init__.py +8 -0
  20. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/inference.py +18 -1
  21. ultrams-0.3.1/src/ultrams.egg-info/PKG-INFO +222 -0
  22. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/SOURCES.txt +11 -0
  23. {ultrams-0.2.0 → ultrams-0.3.1}/tests/test_model_api.py +15 -0
  24. ultrams-0.2.0/MANIFEST.in +0 -2
  25. ultrams-0.2.0/PKG-INFO +0 -102
  26. ultrams-0.2.0/README.md +0 -84
  27. ultrams-0.2.0/pyproject.toml +0 -30
  28. ultrams-0.2.0/src/ultrams.egg-info/PKG-INFO +0 -102
  29. {ultrams-0.2.0 → ultrams-0.3.1}/LICENSE +0 -0
  30. {ultrams-0.2.0 → ultrams-0.3.1}/docs/model-selection.md +0 -0
  31. {ultrams-0.2.0 → ultrams-0.3.1}/examples/batch_embeddings.py +0 -0
  32. {ultrams-0.2.0 → ultrams-0.3.1}/examples/data/NOTICE.md +0 -0
  33. {ultrams-0.2.0 → ultrams-0.3.1}/examples/data/example_5_spectra.mgf +0 -0
  34. {ultrams-0.2.0 → ultrams-0.3.1}/examples/spectrum_search.py +0 -0
  35. {ultrams-0.2.0 → ultrams-0.3.1}/setup.cfg +0 -0
  36. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/_architecture.py +0 -0
  37. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/cli.py +0 -0
  38. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/finetune.py +0 -0
  39. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams/spectra.py +0 -0
  40. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/dependency_links.txt +0 -0
  41. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/entry_points.txt +0 -0
  42. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/requires.txt +0 -0
  43. {ultrams-0.2.0 → ultrams-0.3.1}/src/ultrams.egg-info/top_level.txt +0 -0
  44. {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.
@@ -0,0 +1,6 @@
1
+ recursive-include docs *.md
2
+ recursive-include examples *.py *.md *.mgf
3
+ recursive-include cookbook/tutorials *.ipynb *.md *.py
4
+ include CITATION.cff
5
+ include CHANGELOG.md
6
+ include CONTRIBUTING.md
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
+ [![CI](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml/badge.svg)](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml)
36
+ [![PyPI](https://img.shields.io/pypi/v/ultrams)](https://pypi.org/project/ultrams/)
37
+ [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/Dsadd4/UltraMS/blob/main/pyproject.toml)
38
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE)
39
+ [![MSnLib benchmark DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23963489.svg)](https://doi.org/10.5281/zenodo.23963489)
40
+ [![SpectraVerse dataset DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23964105.svg)](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
+ ```
@@ -0,0 +1,190 @@
1
+ # UltraMS
2
+
3
+ [![CI](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml/badge.svg)](https://github.com/Dsadd4/UltraMS/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/ultrams)](https://pypi.org/project/ultrams/)
5
+ [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/Dsadd4/UltraMS/blob/main/pyproject.toml)
6
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/Dsadd4/UltraMS/blob/main/LICENSE)
7
+ [![MSnLib benchmark DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23963489.svg)](https://doi.org/10.5281/zenodo.23963489)
8
+ [![SpectraVerse dataset DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23964105.svg)](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).