Tandem mass spectrum decoding

tandem-mass-spectrum-decoding

Summary

Decode neural network outputs from mass spectrum prediction models (e.g., ICEBERG) into structured tandem mass spectra by converting predicted fragment tokens and intensity scores into m/z and intensity pairs. This skill bridges learned molecular fragmentation predictions and interpretable experimental spectrum formats.

When to use

When you have raw predictions from a trained fragment generation or intensity prediction neural network model and need to convert those predictions into a standard spectrum file format (m/z–intensity pairs) for comparison against experimental spectra or for structural elucidation workflows. Specifically triggered when ICEBERG or similar models output fragment tokens and intensity logits that require post-processing into spectrum coordinates.

When NOT to use

• Input is experimental (measured) spectrum data — no decoding needed; import directly.
• Only chemical formula predictions are required; use SCARF instead, which predicts at formula level without fragment decoding.
• Model outputs are already in m/z–intensity format — decoding is redundant.

Inputs

• Fragment generation model predictions (token logits or argmax predictions)
• Intensity predictor model outputs (per-fragment intensity scores)
• Model vocabulary mapping (fragment tokens to molecular structures or m/z values)
• Pretrained ICEBERG model weights (gen_ckpt and inten_ckpt)

Outputs

• Tandem mass spectrum (m/z and intensity pairs)
• Structured spectrum file (MGF, SDF, or JSON format)
• Spectrum object suitable for retrieval or comparison against PubChem candidates

How to apply

After running inference on the trained fragment generator (which predicts molecular fragments via a DAG model) and intensity predictor (which scores those fragments), decode the model outputs by: (1) converting predicted fragment token IDs back to molecular structures or m/z values using the model's vocabulary; (2) retrieving the corresponding predicted intensities from the intensity model output; (3) pairing each decoded m/z with its intensity score; (4) filtering or thresholding low-confidence predictions if needed; (5) formatting the m/z–intensity pairs into a structured spectrum object or MGF/SDF file. The decoding step is essential because ICEBERG predicts at fragment-level granularity (not just chemical formula), requiring explicit reconstruction of the fragmentation graph into observable m/z values.

Related tools

• ICEBERG (Fragment-level tandem mass spectrum prediction model whose outputs are decoded into spectrum format by this skill) — https://github.com/coleygroup/ms-pred
• ms-pred repository (Provides training, inference, and decoding utilities for spectrum prediction and reconstruction) — https://github.com/coleygroup/ms-pred
• ICEBERG WebUI (Web interface that abstracts spectrum decoding and ranking against PubChem candidates) — http://iceberg-ms.mit.edu/

Examples

python src/ms_pred/dag_pred/predict_smis.py --input_smiles 'CCO' --gen_ckpt models/gen.pt --inten_ckpt models/inten.pt --output_spectrum spectrum.json

Evaluation signals

• Decoded spectrum contains non-empty list of m/z–intensity pairs with positive, finite values.
• m/z values fall within expected range for molecular ion and fragment ions (e.g., 50–500 m/z for small molecules).
• Intensity values sum to a normalized total (e.g., sum = 1.0 or max = 100) as per spectrum file format convention.
• Decoded spectrum can be compared against experimental spectra using spectral similarity metrics (e.g., cosine similarity > 0.5 indicates reasonable decoding).
• Spectrum structure is compatible with retrieval pipeline and ranks candidate molecules from PubChem as expected.

Limitations

• Decoding quality depends on model accuracy; poor fragment or intensity predictions will yield uninformative spectra.
• Fragment vocabulary size and coverage determine whether predicted fragments can be mapped to valid m/z values; out-of-vocabulary predictions may be dropped or cause decoding errors.
• ICEBERG predictions are trained on collision-energy-annotated spectra (NIST'20 only); transferring to other collision energies or ionization modes without retraining may degrade decoding fidelity.
• The decoding process assumes a single ionization mode and adduct type; multi-adduct scenarios require separate model runs and post-hoc merging.
• GPU memory constraints during inference (especially on small GPUs) may require batch size reduction, affecting throughput.

Evidence

• [other] Pass the molecular representation through the ICEBERG neural network to generate fragment-level predictions. Decode model outputs to construct predicted tandem mass spectrum (m/z and intensity pairs).: "Pass the molecular representation through the ICEBERG neural network to generate fragment-level predictions. Decode model outputs to construct predicted tandem mass spectrum"
• [intro] ICEBERG predicts spectra at the level of molecular fragments, whereas SCARF predicts spectra at the level of chemical formula.: "ICEBERG predicts spectra at the level of molecular fragments, whereas SCARF predicts spectra at the level of chemical formula"
• [readme] This repository contains implementations for the following spectrum simulator models predicting molecular tandem mass spectra from molecules: ICEBERG: [Inferring CID by Estimating Breakage Events and Reconstructing their Graphs]: "spectrum simulator models predicting molecular tandem mass spectra from molecules: ICEBERG"
• [readme] An example of how to use ICEBERG for structural elucidation campaigns can be found at notebooks/iceberg_2025_biorxiv/iceberg_demo_pubchem_elucidation.ipynb: "An example of how to use ICEBERG for structural elucidation campaigns can be found at notebooks/iceberg_2025_biorxiv/iceberg_demo_pubchem_elucidation.ipynb"
• [readme] Get pretrained ICEBERG model weights. You can either train the model by yourself; Or if you have an NSIT'20 license (or newer), you can email the maintainer with a proof of license; Or you can download the weights trained on the MassSpecGym dataset: "Get pretrained ICEBERG model weights. You can either train the model by yourself"