Matchms Similarity Functions Reference

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.

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:

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:

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:

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:

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:

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):

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):

# 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:

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:

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:

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:

# 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

from matchms.similarity import CosineGreedy

scores = calculate_scores(library_spectra, query_spectra,
                         CosineGreedy(tolerance=0.1))

Multi-Metric Matching

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

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