fragment-ion-spectral-matching
Summary
Calculate MS2 spectral similarity scores between fragment ion profiles of candidate ion-species pairs to confirm they originate from the same analyte compound. This is the final confirmation step in DBDIpy's three-stage identification pipeline for direct-injection plasma ionization mass spectrometry.
When to use
Apply this skill after pointwise correlation analysis and exact mass difference refinement have identified candidate ion-species pairs that may share a common analyte origin. Use it when you have preprocessed MS2 fragment spectra (normalized intensity, noise-removed) for each candidate pair and need to computationally verify their putative relationship by comparing fragmentation patterns.
When NOT to use
- MS2 data are not available or are of poor quality (sparse fragmentation, low signal-to-noise ratio)
- Input is a single ion species without a paired candidate — spectral similarity comparison requires at least two spectra
- Candidate pairs have not yet undergone pointwise correlation and mass difference refinement (required upstream steps)
Inputs
- MS2 spectral data (fragment m/z–intensity pairs for each ion species)
- candidate ion-species pair list from mass difference refinement step
- preprocessed fragment spectra (intensity-normalized, noise-reduced)
Outputs
- annotated candidate pair table with spectral similarity scores
- confirmation status for each pair (above/below threshold)
- output table mapping candidate pairs to spectral similarity scores and confirmation status
How to apply
For each candidate ion-species pair output from the mass difference refinement step, extract and preprocess the corresponding MS2 fragment spectra by normalizing intensities and removing noise. Calculate the spectral similarity score using cosine similarity or a related spectral matching algorithm that compares the fragment ion profiles between pair members. Annotate each candidate pair with its computed similarity score and apply an acceptance threshold (typically ≥0.9 for Pearson correlation in the DBDIpy workflow) to flag pairs that exceed the threshold as confirmed shared-analyte relationships. Generate a final output table mapping each candidate pair to its spectral similarity score and confirmation status.
Related tools
- DBDIpy (implements the three-step identification procedure including MS2 spectral similarity scoring as the final confirmation step) — https://github.com/leopold-weidner/DBDIpy
- matchms (provides spectral matching algorithms and is integrated into DBDIpy's workflow for spectral preprocessing and similarity calculation) — https://github.com/matchms/matchms
- Python (execution environment for DBDIpy library and cosine similarity / spectral matching implementations)
Examples
search_res = dbdi.identify_adducts(df=specs_imputed, masses=feature_mz, custom_adducts=adduct_rule, method='pearson', threshold=0.9, mass_error=2)
Evaluation signals
- All candidate pairs receive a numerical spectral similarity score in the valid range [0, 1] or similar bounded metric
- Pairs exceeding the acceptance threshold (e.g., ≥0.9) are consistently flagged as confirmed; pairs below threshold are marked as unconfirmed
- Output table contains no null or missing similarity scores for pairs that have valid MS2 data
- Confirmed pairs show strong visual overlap when their fragment spectra are plotted or aligned (qualitative sanity check)
- Similarity scores for true biological adducts/fragments are significantly higher than scores for random peak pairs from the same dataset
Limitations
- MS2 spectral similarity scoring requires high-quality, complete MS2 data; sparse or noisy fragmentation patterns reduce confidence in similarity scores
- Threshold selection (e.g., 0.9 for Pearson correlation) is user-dependent and may require empirical tuning based on instrument type, ionization method, and dataset characteristics
- Spectral similarity alone cannot distinguish between true analyte fragments and coincidental spectral overlap; it must be applied after correlation and mass accuracy filtering for reliable confirmation
- Performance depends on preprocessing steps (normalization, noise removal); suboptimal upstream preprocessing degrades downstream similarity calculations
Evidence
- [other] DBDIpy implements a three-step identification procedure in which MS2 spectral similarity scoring is the final step, following pointwise correlation analysis of temporal intensity profiles and exact mass difference refinement, to confirm shared analyte origin of candidate ion pairs.: "MS2 spectral similarity scoring is the final step, following pointwise correlation analysis of temporal intensity profiles and exact mass difference refinement, to confirm shared analyte origin"
- [other] For each candidate pair, extract and preprocess the corresponding MS2 fragment spectra (normalize intensity, remove noise). Calculate MS2 spectral similarity score using cosine similarity or related spectral matching algorithm between fragment profiles.: "extract and preprocess the corresponding MS2 fragment spectra (normalize intensity, remove noise). Calculate MS2 spectral similarity score using cosine similarity or related spectral matching"
- [readme] The identification is performed in a three-step procedure (from V > 2.* on, in preparation): calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. (exact) mass differences are used to refine the nature of potential candidates. calculation of MS2 spectral similarity score by ...: "The identification is performed in a three-step procedure: calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. (exact) mass"
- [other] Annotate each pair with its similarity score and flag pairs exceeding the acceptance threshold as confirmed shared-analyte relationships. Generate output table mapping candidate pairs to their spectral similarity scores and confirmation status.: "flag pairs exceeding the acceptance threshold as confirmed shared-analyte relationships. Generate output table mapping candidate pairs to their spectral similarity scores and confirmation status"
- [readme] major implementation for V2: modification of the former two-step search algorithm towards refinement by MS2 spectral similarity scoring.: "major implementation for V2: modification of the former two-step search algorithm towards refinement by MS2 spectral similarity scoring"
1---2name: fragment-ion-spectral-matching3description: Use when after pointwise correlation analysis and exact mass difference refinement have identified candidate ion-species pairs that may share a common analyte origin.4license: CC-BY-4.05---67# fragment-ion-spectral-matching89## Summary1011Calculate MS2 spectral similarity scores between fragment ion profiles of candidate ion-species pairs to confirm they originate from the same analyte compound. This is the final confirmation step in DBDIpy's three-stage identification pipeline for direct-injection plasma ionization mass spectrometry.1213## When to use1415Apply this skill after pointwise correlation analysis and exact mass difference refinement have identified candidate ion-species pairs that may share a common analyte origin. Use it when you have preprocessed MS2 fragment spectra (normalized intensity, noise-removed) for each candidate pair and need to computationally verify their putative relationship by comparing fragmentation patterns.1617## When NOT to use1819- MS2 data are not available or are of poor quality (sparse fragmentation, low signal-to-noise ratio)20- Input is a single ion species without a paired candidate — spectral similarity comparison requires at least two spectra21- Candidate pairs have not yet undergone pointwise correlation and mass difference refinement (required upstream steps)2223## Inputs2425- MS2 spectral data (fragment m/z–intensity pairs for each ion species)26- candidate ion-species pair list from mass difference refinement step27- preprocessed fragment spectra (intensity-normalized, noise-reduced)2829## Outputs3031- annotated candidate pair table with spectral similarity scores32- confirmation status for each pair (above/below threshold)33- output table mapping candidate pairs to spectral similarity scores and confirmation status3435## How to apply3637For each candidate ion-species pair output from the mass difference refinement step, extract and preprocess the corresponding MS2 fragment spectra by normalizing intensities and removing noise. Calculate the spectral similarity score using cosine similarity or a related spectral matching algorithm that compares the fragment ion profiles between pair members. Annotate each candidate pair with its computed similarity score and apply an acceptance threshold (typically ≥0.9 for Pearson correlation in the DBDIpy workflow) to flag pairs that exceed the threshold as confirmed shared-analyte relationships. Generate a final output table mapping each candidate pair to its spectral similarity score and confirmation status.3839## Related tools4041- **DBDIpy** (implements the three-step identification procedure including MS2 spectral similarity scoring as the final confirmation step) — https://github.com/leopold-weidner/DBDIpy42- **matchms** (provides spectral matching algorithms and is integrated into DBDIpy's workflow for spectral preprocessing and similarity calculation) — https://github.com/matchms/matchms43- **Python** (execution environment for DBDIpy library and cosine similarity / spectral matching implementations)4445## Examples4647```48search_res = dbdi.identify_adducts(df=specs_imputed, masses=feature_mz, custom_adducts=adduct_rule, method='pearson', threshold=0.9, mass_error=2)49```5051## Evaluation signals5253- All candidate pairs receive a numerical spectral similarity score in the valid range [0, 1] or similar bounded metric54- Pairs exceeding the acceptance threshold (e.g., ≥0.9) are consistently flagged as confirmed; pairs below threshold are marked as unconfirmed55- Output table contains no null or missing similarity scores for pairs that have valid MS2 data56- Confirmed pairs show strong visual overlap when their fragment spectra are plotted or aligned (qualitative sanity check)57- Similarity scores for true biological adducts/fragments are significantly higher than scores for random peak pairs from the same dataset5859## Limitations6061- MS2 spectral similarity scoring requires high-quality, complete MS2 data; sparse or noisy fragmentation patterns reduce confidence in similarity scores62- Threshold selection (e.g., 0.9 for Pearson correlation) is user-dependent and may require empirical tuning based on instrument type, ionization method, and dataset characteristics63- Spectral similarity alone cannot distinguish between true analyte fragments and coincidental spectral overlap; it must be applied after correlation and mass accuracy filtering for reliable confirmation64- Performance depends on preprocessing steps (normalization, noise removal); suboptimal upstream preprocessing degrades downstream similarity calculations6566## Evidence6768- [other] DBDIpy implements a three-step identification procedure in which MS2 spectral similarity scoring is the final step, following pointwise correlation analysis of temporal intensity profiles and exact mass difference refinement, to confirm shared analyte origin of candidate ion pairs.: "MS2 spectral similarity scoring is the final step, following pointwise correlation analysis of temporal intensity profiles and exact mass difference refinement, to confirm shared analyte origin"69- [other] For each candidate pair, extract and preprocess the corresponding MS2 fragment spectra (normalize intensity, remove noise). Calculate MS2 spectral similarity score using cosine similarity or related spectral matching algorithm between fragment profiles.: "extract and preprocess the corresponding MS2 fragment spectra (normalize intensity, remove noise). Calculate MS2 spectral similarity score using cosine similarity or related spectral matching"70- [readme] The identification is performed in a three-step procedure (from V > 2.* on, in preparation): calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. (exact) mass differences are used to refine the nature of potential candidates. calculation of MS2 spectral similarity score by ...: "The identification is performed in a three-step procedure: calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. (exact) mass"71- [other] Annotate each pair with its similarity score and flag pairs exceeding the acceptance threshold as confirmed shared-analyte relationships. Generate output table mapping candidate pairs to their spectral similarity scores and confirmation status.: "flag pairs exceeding the acceptance threshold as confirmed shared-analyte relationships. Generate output table mapping candidate pairs to their spectral similarity scores and confirmation status"72- [readme] major implementation for V2: modification of the former two-step search algorithm towards refinement by MS2 spectral similarity scoring.: "major implementation for V2: modification of the former two-step search algorithm towards refinement by MS2 spectral similarity scoring"
HolobiomicsLab