# Siamese Network Inference

> Use when you have a collection of cleaned MS/MS spectra (in formats like mzML, mgf, msp, mzxml, or json) and need to predict molecular structural similarities between spectrum pairs without pre-computing RDKit fingerprints.

- Skill: `holobiomicslab/siamese-network-inference-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/siamese-network-inference-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/siamese-network-inference-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/siamese-network-inference-2

---


# siamese-network-inference

> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->
## Summary

Load a pre-trained Siamese neural network and use it to generate spectral embeddings and predict structural similarity scores (Tanimoto or Dice) from pairs of MS/MS spectra without requiring molecular fingerprint computation. This skill enables rapid, scalable chemical similarity assessment directly from mass spectrometry data.

## When to use

You have a collection of cleaned MS/MS spectra (in formats like mzML, mgf, msp, mzxml, or json) and need to predict molecular structural similarities between spectrum pairs without pre-computing RDKit fingerprints. Use this when you want fast, end-to-end predictions of Tanimoto scores or when you need spectral embeddings for clustering or visualization of 'chemical space'.

## When NOT to use

- Your spectra have not been cleaned (missing or malformed metadata, unchecked peak intensities) — apply matchms preprocessing first.
- You require interpretable molecular fingerprint information (e.g., which structural features drove the similarity) — this model predicts end-to-end similarity scores without explicit fingerprint output.
- Your spectra are from ionization modes or chemical classes not well-represented in the training data (>500,000 spectra from GNPS, MoNA, MassBank, MSnLib) — model generalization may be degraded.

## Inputs

- MS/MS spectra in MGF, MSP, mzML, mzXML, JSON, or USI format
- Pre-trained Siamese neural network checkpoint (PyTorch .pt file)
- Cleaned spectrum metadata (parent mass, precursor m/z, ionization mode)

## Outputs

- Predicted Tanimoto or Dice similarity scores for spectrum pairs
- 200-dimensional spectral embeddings per spectrum
- Uncertainty estimates (IQR values) for each prediction when Monte-Carlo Dropout applied
- Similarity matrix (numpy array) for all pairwise comparisons

## How to apply

Load the pre-trained MS2DeepScore model from the checkpoint file (e.g., ms2deepscore_model.pt from zenodo). Clean and prepare input spectra using matchms DEFAULT_FILTERS to ensure consistent metadata and peak intensity normalization. For each spectrum pair or spectrum collection, pass the cleaned spectra to the model's embedding function to generate 200-dimensional spectral embeddings. Compute pairwise cosine similarity between embeddings and convert to predicted Tanimoto scores. Optionally apply Monte-Carlo Dropout uncertainty quantification by sampling multiple forward passes through the model with dropout active, then filter predictions by interquartile range (IQR) thresholds to improve accuracy on high-confidence predictions. The model works across both positive and negative ionization modes simultaneously.

## Related tools

- **ms2deepscore** (Pre-trained Siamese model and inference API; loads embeddings and computes similarities from spectrum pairs) — https://github.com/matchms/ms2deepscore
- **matchms** (Spectrum data I/O, cleaning pipeline (DEFAULT_FILTERS), and metadata standardization before inference) — https://github.com/matchms/matchms
- **PyTorch** (Underlying deep learning framework for model loading and forward pass computation)
- **NumPy** (Numerical operations for cosine similarity computation and similarity matrix creation)
- **RDKit** (Optional: reference Tanimoto score computation from Daylight fingerprints for validation or benchmark)

## Examples

```
from ms2deepscore.models import load_model
from matchms.Pipeline import Pipeline, create_workflow
from matchms.filtering.default_pipelines import DEFAULT_FILTERS
from ms2deepscore import MS2DeepScore

model = load_model('ms2deepscore_model.pt')
pipeline = Pipeline(create_workflow(query_filters=DEFAULT_FILTERS, score_computations=[[MS2DeepScore, {'model': model}]]))
report = pipeline.run('pesticides.mgf')
similarity_matrix = pipeline.scores.to_array()
```

## Evaluation signals

- Predicted Tanimoto scores fall within the expected range [0.0, 1.0] with mean and distribution consistent with publication (mean ~0.15 RMSE on unseen compound test sets)
- Pairwise embeddings show meaningful clustering when visualized with UMAP or t-SNE—structurally similar compounds (high Tanimoto) should co-locate
- Root mean squared error on a held-out test set of 3600+ spectra from unseen compounds matches reported ~0.15 RMSE (or ~0.10 with IQR filtering)
- Uncertainty quantification (IQR) correlates with prediction error: high-uncertainty predictions are less accurate than low-IQR predictions
- Model recovers high structural similarity (Tanimoto > 0.7) for isomeric or very similar compounds, and low similarity for structurally distant compounds

## Limitations

- Model was trained on 109,734 MS/MS spectra representing 15,062 unique molecules; performance may degrade on novel chemical classes or rare compound types not in training distribution.
- Spectrum metadata such as parent mass and elemental formula were not used during training; metadata-only filtering cannot be applied by the model.
- Monte-Carlo Dropout uncertainty estimates require multiple forward passes (computational overhead); without dropout, only point predictions are available.
- Cross-ionization-mode predictions (e.g., positive to negative) are possible with MS2DeepScore 2.0+ but the original 2021 model (task_003) was trained primarily on single-ionization datasets.
- Spectra must be cleaned and binned to consistent peak representations; malformed or uncleaned input will produce unreliable embeddings and similarity scores.

## Evidence

- [methods] Load a pre-trained Siamese model and compute embeddings: "Load the pre-trained MS2DeepScore base network and the test set of 3601 binned spectra"
- [methods] Generate embeddings and compute cosine similarity: "compute 200-dimensional spectral embeddings for each spectrum using the trained base network. 3. Calculate cosine similarity between paired embeddings and convert to predicted Tanimoto scores"
- [methods] Apply uncertainty filtering via Monte-Carlo Dropout: "To estimate the uncertainty of a prediction we used Monte-Carlo Dropout ensembles [17]. At inference time, dropout was applied to all but the first layer of the base network"
- [abstract] Expected RMSE performance benchmark: "predict Tanimoto scores for spectra with a root mean squared error of about 0.15"
- [readme] Model supports multiple ionization modes: "The model works for spectra in both positive and negative ionization modes and even predictions across ionization modes can be made by this model"
- [readme] Data cleaning is prerequisite: "Please first ensure cleaning your spectra. We recommend using the cleaning pipeline in matchms"