Siamese neural network architecture design

siamese-neural-network-architecture-design

Summary

Design and implement a Siamese neural network architecture with twin branches and shared weights to predict molecular structural similarities (Tanimoto scores) from paired mass spectrometry spectra. This skill applies deep learning to MS/MS spectral comparison by learning embeddings that capture chemical similarity.

When to use

When you have pairs of mass spectrometry spectra and need to predict their molecular structural similarity as a scalar Tanimoto score in the range [0, 1]. Use this skill when you want to move beyond traditional spectrum similarity metrics and learn similarity patterns directly from spectral data, particularly when you have access to >100,000 diverse spectra for training or wish to leverage a pre-trained model.

When NOT to use

• Input spectra are not preprocessed or lack m/z and intensity values; the model requires standardized peak lists.
• You have fewer than ~100,000 diverse training spectra and no pre-trained model available; training from scratch on small datasets risks poor feature learning.
• You need interpretable or rule-based similarity rather than a learned neural score; Siamese outputs are not easily decomposable into human-readable chemical rules.

Inputs

• Pair of preprocessed mass spectrometry spectra (peak intensities and m/z values)
• Training corpus: >100,000 MS/MS spectra in mgf, msp, mzml, or json format
• Metadata fields: ionization mode, precursor m/z, or other categorical/continuous attributes

Outputs

• Scalar Tanimoto similarity score per spectrum pair (range [0, 1])
• Spectral embedding vectors (for dimensionality reduction and chemical space visualization)
• Trained Siamese model checkpoint (.pt file)

How to apply

Construct a Siamese neural network with two identical branches that process each spectrum in a pair through shared weight layers, learning spectral embeddings. The input layer accepts preprocessed mass spectrometry spectral data (peak intensities and m/z values). Build shared feature extraction layers that learn discriminative spectral representations, then implement a similarity computation layer that compares the paired embeddings and outputs a scalar Tanimoto similarity score. For a pre-trained model, load it via ms2deepscore.models.load_model() and wrap it in MS2DeepScore class; for custom training, prepare cleaned spectra in mgf or msp format, configure SettingsMS2Deepscore with metadata fields (e.g., ionization mode, precursor m/z), and invoke train_ms2deepscore_wrapper(). Validate that predictions fall within [0, 1] and that the model accepts spectrum pairs with compatible preprocessing (normalization, peak filtering).

Related tools

• ms2deepscore (Library providing Siamese neural network model, training wrapper, and prediction interface for spectral similarity) — https://github.com/matchms/ms2deepscore
• matchms (Spectrum preprocessing, filtering, and data loading for ms2deepscore; provides DEFAULT_FILTERS and Pipeline interface) — https://github.com/matchms/matchms
• Python (Runtime environment for training and inference; required version 3.11 or 3.12)
• PyTorch (Underlying deep learning framework (implicit dependency of ms2deepscore))

Examples

from ms2deepscore.models import load_model; from ms2deepscore import MS2DeepScore; model = load_model('ms2deepscore_model.pt'); ms2ds = MS2DeepScore(model); similarity_scores = ms2ds(spectrum_pairs); embeddings = ms2ds.get_embedding_array(cleaned_spectra)

Evaluation signals

• Verify model accepts spectrum pairs and produces scalar outputs in range [0, 1]; check with test spectra from example dataset.
• Confirm shared weights: inspect model parameters to ensure twin branches share identical weight tensors before and after forward pass.
• Validate embedding dimensionality: confirm embedding_array output shape matches number of input spectra and embedding size (typically 256–512 dims).
• Cross-ionization predictions: if training with both ionization modes, verify model can score spectra across positive and negative modes without mode mismatch errors.
• Inspect training loss convergence: plot loss curves across epochs to confirm stable descent and no divergence; check validation loss plateau as sign of convergence.

Limitations

• Model performance depends heavily on training data diversity and size; <100,000 spectra may yield suboptimal embeddings, particularly for rare chemical classes.
• Pre-trained models are optimized for spectra from GNPS, Mona, MassBank, and MSnLib; transfer to highly specialized or non-standard spectral libraries may degrade accuracy.
• Pair sampling strategy significantly affects training quality; inadequate or biased pair sampling can result in poor similarity learning regardless of architecture.
• Spectra must be preprocessed (noise removal, normalization, peak alignment) before input; the model does not handle raw, unfiltered spectra.
• No interpretability: Siamese embeddings are high-dimensional black-box representations; chemical insight requires downstream visualization (e.g., UMAP) and manual annotation.

Evidence

• [other] MS2DeepScore implements a Siamese neural network architecture designed to take pairs of mass spectrometry spectra as input and output predicted molecular structural similarities expressed as Tanimoto scores.: "MS2DeepScore implements a Siamese neural network architecture designed to take pairs of mass spectrometry spectra as input and output predicted molecular structural similarities expressed as Tanimoto"
• [other] Build the shared feature extraction layers that learn spectral embeddings. Implement the similarity computation layer that outputs Tanimoto similarity scores from paired embeddings.: "Build the shared feature extraction layers that learn spectral embeddings. 4. Implement the similarity computation layer that outputs Tanimoto similarity scores from paired embeddings."
• [other] Validate that the model can accept spectrum pairs and produce scalar similarity scores in the range [0, 1].: "Validate that the model can accept spectrum pairs and produce scalar similarity scores in the range [0, 1]."
• [readme] ms2deepscore provides a Siamese neural network that is trained to predict molecular structural similarities (Tanimoto scores) from pairs of mass spectrometry spectra.: "ms2deepscore provides a Siamese neural network that is trained to predict molecular structural similarities (Tanimoto scores) from pairs of mass spectrometry spectra."
• [readme] The library provides intuitive classes to prepare data, train a Siamese model, and compute similarities between pairs of spectra.: "The library provides intuitive classes to prepare data, train a Siamese model, and compute similarities between pairs of spectra."
• [readme] MS2DeepScore first calculates an embedding (vector) representing each spectrum. This intermediate product can also be used to visualize spectra in chemical space by using a dimensionality reduction technique, like UMAP.: "MS2DeepScore first calculates an embedding (vector) representing each spectrum. This intermediate product can also be used to visualize spectra in chemical space by using a dimensionality reduction"
• [readme] You can train a new model on a dataset of your choice. That, however, should contain a substantial amount of spectra to learn relevant features, say > 100,000 spectra of sufficiently diverse types.: "You can train a new model on a dataset of your choice. That, however, should contain a substantial amount of spectra to learn relevant features, say > 100,000 spectra of sufficiently diverse types."
• [readme] The pair sampling has to be checked and potentially re-optimized for new datasets. Particularly for smaller training sets, the pair sampling can be suboptimal if not checked.: "The pair sampling has to be checked and potentially re-optimized for new datasets. Particularly for smaller training sets, the pair sampling can be suboptimal if not checked."