381 lines
13 KiB
Markdown
381 lines
13 KiB
Markdown
# Matchms Similarity Functions Reference
|
|
|
|
This document provides detailed information about all similarity scoring methods available in matchms.
|
|
|
|
## Overview
|
|
|
|
Matchms provides multiple similarity functions for comparing mass spectra. Use `calculate_scores()` to compute pairwise similarities between reference and query spectra collections.
|
|
|
|
```python
|
|
from matchms import calculate_scores
|
|
from matchms.similarity import CosineGreedy
|
|
|
|
scores = calculate_scores(references=library_spectra,
|
|
queries=query_spectra,
|
|
similarity_function=CosineGreedy())
|
|
```
|
|
|
|
## Peak-Based Similarity Functions
|
|
|
|
These functions compare mass spectra based on their peak patterns (m/z and intensity values).
|
|
|
|
### CosineGreedy
|
|
|
|
**Description**: Calculates cosine similarity between two spectra using a fast greedy matching algorithm. Peaks are matched within a specified tolerance, and similarity is computed based on matched peak intensities.
|
|
|
|
**When to use**:
|
|
- Fast similarity calculations for large datasets
|
|
- General-purpose spectral matching
|
|
- When speed is prioritized over mathematically optimal matching
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum m/z difference for peak matching (Daltons)
|
|
- `mz_power` (float, default=0.0): Exponent for m/z weighting (0 = no weighting)
|
|
- `intensity_power` (float, default=1.0): Exponent for intensity weighting
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import CosineGreedy
|
|
|
|
similarity_func = CosineGreedy(tolerance=0.1, mz_power=0.0, intensity_power=1.0)
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Output**: Similarity score between 0.0 and 1.0, plus number of matched peaks.
|
|
|
|
---
|
|
|
|
### CosineHungarian
|
|
|
|
**Description**: Calculates cosine similarity using the Hungarian algorithm for optimal peak matching. Provides mathematically optimal peak assignments but is slower than CosineGreedy.
|
|
|
|
**When to use**:
|
|
- When optimal peak matching is required
|
|
- High-quality reference library comparisons
|
|
- Research requiring reproducible, mathematically rigorous results
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum m/z difference for peak matching
|
|
- `mz_power` (float, default=0.0): Exponent for m/z weighting
|
|
- `intensity_power` (float, default=1.0): Exponent for intensity weighting
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import CosineHungarian
|
|
|
|
similarity_func = CosineHungarian(tolerance=0.1)
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Output**: Optimal similarity score between 0.0 and 1.0, plus matched peaks.
|
|
|
|
**Note**: Slower than CosineGreedy; use for smaller datasets or when accuracy is critical.
|
|
|
|
---
|
|
|
|
### ModifiedCosine
|
|
|
|
**Description**: Extends cosine similarity by accounting for precursor m/z differences. Allows peaks to match after applying a mass shift based on the difference between precursor masses. Useful for comparing spectra of related compounds (isotopes, adducts, analogs).
|
|
|
|
**When to use**:
|
|
- Comparing spectra from different precursor masses
|
|
- Identifying structural analogs or derivatives
|
|
- Cross-ionization mode comparisons
|
|
- When precursor mass differences are meaningful
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum m/z difference for peak matching after shift
|
|
- `mz_power` (float, default=0.0): Exponent for m/z weighting
|
|
- `intensity_power` (float, default=1.0): Exponent for intensity weighting
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import ModifiedCosine
|
|
|
|
similarity_func = ModifiedCosine(tolerance=0.1)
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Requirements**: Both spectra must have valid precursor_mz metadata.
|
|
|
|
---
|
|
|
|
### NeutralLossesCosine
|
|
|
|
**Description**: Calculates similarity based on neutral loss patterns rather than fragment m/z values. Neutral losses are derived by subtracting fragment m/z from precursor m/z. Particularly useful for identifying compounds with similar fragmentation patterns.
|
|
|
|
**When to use**:
|
|
- Comparing fragmentation patterns across different precursor masses
|
|
- Identifying compounds with similar neutral loss profiles
|
|
- Complementary to regular cosine scoring
|
|
- Metabolite identification and classification
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum neutral loss difference for matching
|
|
- `mz_power` (float, default=0.0): Exponent for loss value weighting
|
|
- `intensity_power` (float, default=1.0): Exponent for intensity weighting
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import NeutralLossesCosine
|
|
from matchms.filtering import add_losses
|
|
|
|
# First add losses to spectra
|
|
spectra_with_losses = [add_losses(s) for s in spectra]
|
|
|
|
similarity_func = NeutralLossesCosine(tolerance=0.1)
|
|
scores = calculate_scores(references_with_losses, queries_with_losses, similarity_func)
|
|
```
|
|
|
|
**Requirements**:
|
|
- Both spectra must have valid precursor_mz metadata
|
|
- Use `add_losses()` filter to compute neutral losses before scoring
|
|
|
|
---
|
|
|
|
## Structural Similarity Functions
|
|
|
|
These functions compare molecular structures rather than spectral peaks.
|
|
|
|
### FingerprintSimilarity
|
|
|
|
**Description**: Calculates similarity between molecular fingerprints derived from chemical structures (SMILES or InChI). Supports multiple fingerprint types and similarity metrics.
|
|
|
|
**When to use**:
|
|
- Structural similarity without spectral data
|
|
- Combining structural and spectral similarity
|
|
- Pre-filtering candidates before spectral matching
|
|
- Structure-activity relationship studies
|
|
|
|
**Parameters**:
|
|
- `fingerprint_type` (str, default="daylight"): Type of fingerprint
|
|
- `"daylight"`: Daylight fingerprint
|
|
- `"morgan1"`, `"morgan2"`, `"morgan3"`: Morgan fingerprints with radius 1, 2, or 3
|
|
- `similarity_measure` (str, default="jaccard"): Similarity metric
|
|
- `"jaccard"`: Jaccard index (intersection / union)
|
|
- `"dice"`: Dice coefficient (2 * intersection / (size1 + size2))
|
|
- `"cosine"`: Cosine similarity
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import FingerprintSimilarity
|
|
from matchms.filtering import add_fingerprint
|
|
|
|
# Add fingerprints to spectra
|
|
spectra_with_fps = [add_fingerprint(s, fingerprint_type="morgan2", nbits=2048)
|
|
for s in spectra]
|
|
|
|
similarity_func = FingerprintSimilarity(similarity_measure="jaccard")
|
|
scores = calculate_scores(references_with_fps, queries_with_fps, similarity_func)
|
|
```
|
|
|
|
**Requirements**:
|
|
- Spectra must have valid SMILES or InChI metadata
|
|
- Use `add_fingerprint()` filter to compute fingerprints
|
|
- Requires rdkit library
|
|
|
|
---
|
|
|
|
## Metadata-Based Similarity Functions
|
|
|
|
These functions compare metadata fields rather than spectral or structural data.
|
|
|
|
### MetadataMatch
|
|
|
|
**Description**: Compares user-defined metadata fields between spectra. Supports exact matching for categorical data and tolerance-based matching for numerical data.
|
|
|
|
**When to use**:
|
|
- Filtering by experimental conditions (collision energy, retention time)
|
|
- Instrument-specific matching
|
|
- Combining metadata constraints with spectral similarity
|
|
- Custom metadata-based filtering
|
|
|
|
**Parameters**:
|
|
- `field` (str): Metadata field name to compare
|
|
- `matching_type` (str, default="exact"): Matching method
|
|
- `"exact"`: Exact string/value match
|
|
- `"difference"`: Absolute difference for numerical values
|
|
- `"relative_difference"`: Relative difference for numerical values
|
|
- `tolerance` (float, optional): Maximum difference for numerical matching
|
|
|
|
**Example (Exact matching)**:
|
|
```python
|
|
from matchms.similarity import MetadataMatch
|
|
|
|
# Match by instrument type
|
|
similarity_func = MetadataMatch(field="instrument_type", matching_type="exact")
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Example (Numerical matching)**:
|
|
```python
|
|
# Match retention time within 0.5 minutes
|
|
similarity_func = MetadataMatch(field="retention_time",
|
|
matching_type="difference",
|
|
tolerance=0.5)
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Output**: Returns 1.0 (match) or 0.0 (no match) for exact matching. For numerical matching, returns similarity score based on difference.
|
|
|
|
---
|
|
|
|
### PrecursorMzMatch
|
|
|
|
**Description**: Binary matching based on precursor m/z values. Returns True/False based on whether precursor masses match within specified tolerance.
|
|
|
|
**When to use**:
|
|
- Pre-filtering spectral libraries by precursor mass
|
|
- Fast mass-based candidate selection
|
|
- Combining with other similarity metrics
|
|
- Isobaric compound identification
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum m/z difference for matching
|
|
- `tolerance_type` (str, default="Dalton"): Tolerance unit
|
|
- `"Dalton"`: Absolute mass difference
|
|
- `"ppm"`: Parts per million (relative)
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import PrecursorMzMatch
|
|
|
|
# Match precursor within 0.1 Da
|
|
similarity_func = PrecursorMzMatch(tolerance=0.1, tolerance_type="Dalton")
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
|
|
# Match precursor within 10 ppm
|
|
similarity_func = PrecursorMzMatch(tolerance=10, tolerance_type="ppm")
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Output**: 1.0 (match) or 0.0 (no match)
|
|
|
|
**Requirements**: Both spectra must have valid precursor_mz metadata.
|
|
|
|
---
|
|
|
|
### ParentMassMatch
|
|
|
|
**Description**: Binary matching based on parent mass (neutral mass) values. Similar to PrecursorMzMatch but uses calculated parent mass instead of precursor m/z.
|
|
|
|
**When to use**:
|
|
- Comparing spectra from different ionization modes
|
|
- Adduct-independent matching
|
|
- Neutral mass-based library searches
|
|
|
|
**Parameters**:
|
|
- `tolerance` (float, default=0.1): Maximum mass difference for matching
|
|
- `tolerance_type` (str, default="Dalton"): Tolerance unit ("Dalton" or "ppm")
|
|
|
|
**Example**:
|
|
```python
|
|
from matchms.similarity import ParentMassMatch
|
|
|
|
similarity_func = ParentMassMatch(tolerance=0.1, tolerance_type="Dalton")
|
|
scores = calculate_scores(references, queries, similarity_func)
|
|
```
|
|
|
|
**Output**: 1.0 (match) or 0.0 (no match)
|
|
|
|
**Requirements**: Both spectra must have valid parent_mass metadata.
|
|
|
|
---
|
|
|
|
## Combining Multiple Similarity Functions
|
|
|
|
Combine multiple similarity metrics for robust compound identification:
|
|
|
|
```python
|
|
from matchms import calculate_scores
|
|
from matchms.similarity import CosineGreedy, ModifiedCosine, FingerprintSimilarity
|
|
|
|
# Calculate multiple similarity scores
|
|
cosine_scores = calculate_scores(refs, queries, CosineGreedy())
|
|
modified_cosine_scores = calculate_scores(refs, queries, ModifiedCosine())
|
|
fingerprint_scores = calculate_scores(refs, queries, FingerprintSimilarity())
|
|
|
|
# Combine scores with weights
|
|
for i, query in enumerate(queries):
|
|
for j, ref in enumerate(refs):
|
|
combined_score = (0.5 * cosine_scores.scores[j, i] +
|
|
0.3 * modified_cosine_scores.scores[j, i] +
|
|
0.2 * fingerprint_scores.scores[j, i])
|
|
```
|
|
|
|
## Accessing Scores Results
|
|
|
|
The `Scores` object provides multiple methods to access results:
|
|
|
|
```python
|
|
# Get best matches for a query
|
|
best_matches = scores.scores_by_query(query_spectrum, sort=True)[:10]
|
|
|
|
# Get scores as numpy array
|
|
score_array = scores.scores
|
|
|
|
# Get scores as pandas DataFrame
|
|
import pandas as pd
|
|
df = scores.to_dataframe()
|
|
|
|
# Filter by threshold
|
|
high_scores = [(i, j, score) for i, j, score in scores.to_list() if score > 0.7]
|
|
|
|
# Save scores
|
|
scores.to_json("scores.json")
|
|
scores.to_pickle("scores.pkl")
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
**Fast methods** (large datasets):
|
|
- CosineGreedy
|
|
- PrecursorMzMatch
|
|
- ParentMassMatch
|
|
|
|
**Slow methods** (smaller datasets or high accuracy):
|
|
- CosineHungarian
|
|
- ModifiedCosine (slower than CosineGreedy)
|
|
- NeutralLossesCosine
|
|
- FingerprintSimilarity (requires fingerprint computation)
|
|
|
|
**Recommendation**: For large-scale library searches, use PrecursorMzMatch to pre-filter candidates, then apply CosineGreedy or ModifiedCosine to filtered results.
|
|
|
|
## Common Similarity Workflows
|
|
|
|
### Standard Library Matching
|
|
```python
|
|
from matchms.similarity import CosineGreedy
|
|
|
|
scores = calculate_scores(library_spectra, query_spectra,
|
|
CosineGreedy(tolerance=0.1))
|
|
```
|
|
|
|
### Multi-Metric Matching
|
|
```python
|
|
from matchms.similarity import CosineGreedy, ModifiedCosine, FingerprintSimilarity
|
|
|
|
# Spectral similarity
|
|
cosine = calculate_scores(refs, queries, CosineGreedy())
|
|
modified = calculate_scores(refs, queries, ModifiedCosine())
|
|
|
|
# Structural similarity
|
|
fingerprint = calculate_scores(refs, queries, FingerprintSimilarity())
|
|
```
|
|
|
|
### Precursor-Filtered Matching
|
|
```python
|
|
from matchms.similarity import PrecursorMzMatch, CosineGreedy
|
|
|
|
# First filter by precursor mass
|
|
mass_filter = calculate_scores(refs, queries, PrecursorMzMatch(tolerance=0.1))
|
|
|
|
# Then calculate cosine only for matching precursors
|
|
cosine_scores = calculate_scores(refs, queries, CosineGreedy())
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
For detailed API documentation, parameter descriptions, and mathematical formulations, see:
|
|
https://matchms.readthedocs.io/en/latest/api/matchms.similarity.html
|