Fragmentation Pattern Annotation with MAGMa
Summary
MAGMa annotation engine assigns fragment ions in tandem MS/MS spectra to specific neutral losses and bond cleavages within a known molecular structure, enabling structural localization of modifications. This skill is essential when you need to trace MS/MS peaks back to exact atoms or functional groups to localize where a modification has occurred on a known compound.
When to use
Apply this skill when you have a tandem MS/MS spectrum of a structurally modified compound and a known reference structure (SMILES), and you need to annotate which fragment ions correspond to specific bonds or atoms in the molecule. This is particularly valuable prior to or in tandem with spectral alignment when comparing a known compound spectrum to a modified analog spectrum, as it grounds each MS/MS peak in the chemical structure, enabling atom-level modification site probability scoring.
When NOT to use
- Spectrum is purely de novo (no known reference structure available); MAGMa requires a reference SMILES to perform in silico fragmentation.
- Fragment ion masses are outside the specified m/z_tolerance or ppm_tolerance windows; peaks will not be annotated and will not contribute to structural localization.
- Only qualitative peak presence/absence is needed, not structural assignment; simpler cosine similarity or spectral matching may suffice.
Inputs
- Compound object with SMILES string and tandem MS/MS spectrum (peak list with m/z and intensity)
- Precursor m/z and charge state
- MAGMa annotation engine configuration (mz_tolerance, ppm_tolerance)
Outputs
- peak_fragment_dict: dictionary mapping observed m/z values to annotated fragment structures and bond cleavage information
- Fragment annotation metadata: neutral loss masses, cleavage positions, and confidence scores for each peak
How to apply
Instantiate a MAGMaAnnotationEngine and pass it both the known Compound object (with SMILES and spectrum) and the ModiFinder instance. The engine processes the tandem MS/MS spectrum by fragmenting the known structure in silico and matching observed m/z peaks to predicted fragment masses (using mz_tolerance=0.01 and ppm_tolerance=40 by default). Each matched fragment is annotated with the bond(s) cleaved and atom(s) retained, producing a peak-to-fragment dictionary that maps m/z values to specific structural elements. This annotation output is then used by ModiFinder's probability generation to weight per-atom modification scores: peaks with strong MAGMa annotations (high match confidence) contribute more heavily to atom-level probability estimates than ambiguous or unannotated peaks.
Related tools
- ModiFinder (Consumer of MAGMa annotation output; integrates fragment annotations into modification site probability generation) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base
- RDKit (Underlying chemistry engine for in silico fragmentation, structure parsing, and mass calculation) — http://www.rdkit.org/
- Python (Execution language for MAGMa annotation engine and ModiFinder workflow)
Examples
siteLocator = ModiFinder(main_compound, mod_compound, helpers=None); peaksObj, fragmentsObj = siteLocator.get_result(); print(fragmentsObj['frags_map']) # inspect peak-to-fragment annotations
Evaluation signals
- Every observed peak with mass within mz_tolerance (±0.01 m/z) or ppm_tolerance (40 ppm) of a predicted fragment should receive an annotation entry in peak_fragment_dict; check for completeness.
- Annotated fragments should correspond to chemically valid bond cleavages in the reference structure (no impossible fragments); inspect peak_fragment_dict entries for chemical plausibility.
- Per-atom modification site probabilities should show higher values at atoms involved in frequently matched fragments and lower values at unmatched or weakly matched atoms; verify correlation between annotation coverage and probability distribution.
- When comparing known vs. modified compound, peaks that match only in the modified spectrum should map to regions near the modification site, confirming annotation is localizing changes correctly.
- Unannotated peaks (those outside tolerance windows) should be rare (<5% of spectrum intensity) for high-quality spectra; high rates suggest tolerance parameters need adjustment or spectrum quality issues exist.
Limitations
- MAGMa annotation depends critically on accurate SMILES input; incorrect or incomplete SMILES will produce spurious or missing annotations.
- In silico fragmentation complexity grows exponentially with molecular weight; very large molecules may have incomplete fragment coverage or excessive computational cost.
- Isomeric structures cannot be distinguished by MAGMa annotation alone; if the reference structure is ambiguous, annotation ambiguity will propagate into modification site scoring.
- Neutral losses and multi-step fragmentations are not systematically enumerated in the base MAGMa implementation; simple bond cleavages are well-annotated but complex rearrangements may be missed.
- Modification-induced shifts in fragmentation patterns (e.g., post-translational modification changing local chemistry) may cause annotated fragments to no longer match observed peaks, reducing signal for those atoms.
Evidence
- [other] ModiFinder generates per-atom modification site probabilities through tandem mass spectral alignment, enabling structural modification site localization.: "ModiFinder generates per-atom modification site probabilities through tandem mass spectral alignment, enabling structural modification site localization"
- [other] MAGMaAnnotationEngine is instantiated alongside CosineAlignmentEngine when constructing a ModiFinder object for probability generation.: "Instantiate a ModiFinder object with the known compound, modified compound, and default CosineAlignmentEngine and MAGMaAnnotationEngine"
- [other] Peak preprocessing uses specific tolerance and normalization parameters that control fragment matching.: "default preprocessing (mz_tolerance=0.01, ppm_tolerance=40, ratio_to_base_peak=0.01, normalize_peaks=True)"
- [other] ModiFinder integrates fragment annotation into per-atom scoring.: "fragmentation annotation to a known/unknown compound pair"
- [readme] ModiFinder API produces fragment metadata alongside peak data.: "fragmentsObj = { "frags_map": knownCompound.spectrum.peak_fragment_dict, "structure": knownCompound.structure, "peaks": main_compound_peaks"
1---2name: fragmentation-pattern-annotation-magma3description: Use when you have a tandem MS/MS spectrum of a structurally modified compound and a known reference structure (SMILES), and you need to annotate which fragment ions correspond to specific bonds or atoms in the molecule.4license: CC-BY-4.05---67# Fragmentation Pattern Annotation with MAGMa89## Summary1011MAGMa annotation engine assigns fragment ions in tandem MS/MS spectra to specific neutral losses and bond cleavages within a known molecular structure, enabling structural localization of modifications. This skill is essential when you need to trace MS/MS peaks back to exact atoms or functional groups to localize where a modification has occurred on a known compound.1213## When to use1415Apply this skill when you have a tandem MS/MS spectrum of a structurally modified compound and a known reference structure (SMILES), and you need to annotate which fragment ions correspond to specific bonds or atoms in the molecule. This is particularly valuable prior to or in tandem with spectral alignment when comparing a known compound spectrum to a modified analog spectrum, as it grounds each MS/MS peak in the chemical structure, enabling atom-level modification site probability scoring.1617## When NOT to use1819- Spectrum is purely de novo (no known reference structure available); MAGMa requires a reference SMILES to perform in silico fragmentation.20- Fragment ion masses are outside the specified m/z_tolerance or ppm_tolerance windows; peaks will not be annotated and will not contribute to structural localization.21- Only qualitative peak presence/absence is needed, not structural assignment; simpler cosine similarity or spectral matching may suffice.2223## Inputs2425- Compound object with SMILES string and tandem MS/MS spectrum (peak list with m/z and intensity)26- Precursor m/z and charge state27- MAGMa annotation engine configuration (mz_tolerance, ppm_tolerance)2829## Outputs3031- peak_fragment_dict: dictionary mapping observed m/z values to annotated fragment structures and bond cleavage information32- Fragment annotation metadata: neutral loss masses, cleavage positions, and confidence scores for each peak3334## How to apply3536Instantiate a MAGMaAnnotationEngine and pass it both the known Compound object (with SMILES and spectrum) and the ModiFinder instance. The engine processes the tandem MS/MS spectrum by fragmenting the known structure in silico and matching observed m/z peaks to predicted fragment masses (using mz_tolerance=0.01 and ppm_tolerance=40 by default). Each matched fragment is annotated with the bond(s) cleaved and atom(s) retained, producing a peak-to-fragment dictionary that maps m/z values to specific structural elements. This annotation output is then used by ModiFinder's probability generation to weight per-atom modification scores: peaks with strong MAGMa annotations (high match confidence) contribute more heavily to atom-level probability estimates than ambiguous or unannotated peaks.3738## Related tools3940- **ModiFinder** (Consumer of MAGMa annotation output; integrates fragment annotations into modification site probability generation) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base41- **RDKit** (Underlying chemistry engine for in silico fragmentation, structure parsing, and mass calculation) — http://www.rdkit.org/42- **Python** (Execution language for MAGMa annotation engine and ModiFinder workflow)4344## Examples4546```47siteLocator = ModiFinder(main_compound, mod_compound, helpers=None); peaksObj, fragmentsObj = siteLocator.get_result(); print(fragmentsObj['frags_map']) # inspect peak-to-fragment annotations48```4950## Evaluation signals5152- Every observed peak with mass within mz_tolerance (±0.01 m/z) or ppm_tolerance (40 ppm) of a predicted fragment should receive an annotation entry in peak_fragment_dict; check for completeness.53- Annotated fragments should correspond to chemically valid bond cleavages in the reference structure (no impossible fragments); inspect peak_fragment_dict entries for chemical plausibility.54- Per-atom modification site probabilities should show higher values at atoms involved in frequently matched fragments and lower values at unmatched or weakly matched atoms; verify correlation between annotation coverage and probability distribution.55- When comparing known vs. modified compound, peaks that match only in the modified spectrum should map to regions near the modification site, confirming annotation is localizing changes correctly.56- Unannotated peaks (those outside tolerance windows) should be rare (<5% of spectrum intensity) for high-quality spectra; high rates suggest tolerance parameters need adjustment or spectrum quality issues exist.5758## Limitations5960- MAGMa annotation depends critically on accurate SMILES input; incorrect or incomplete SMILES will produce spurious or missing annotations.61- In silico fragmentation complexity grows exponentially with molecular weight; very large molecules may have incomplete fragment coverage or excessive computational cost.62- Isomeric structures cannot be distinguished by MAGMa annotation alone; if the reference structure is ambiguous, annotation ambiguity will propagate into modification site scoring.63- Neutral losses and multi-step fragmentations are not systematically enumerated in the base MAGMa implementation; simple bond cleavages are well-annotated but complex rearrangements may be missed.64- Modification-induced shifts in fragmentation patterns (e.g., post-translational modification changing local chemistry) may cause annotated fragments to no longer match observed peaks, reducing signal for those atoms.6566## Evidence6768- [other] ModiFinder generates per-atom modification site probabilities through tandem mass spectral alignment, enabling structural modification site localization.: "ModiFinder generates per-atom modification site probabilities through tandem mass spectral alignment, enabling structural modification site localization"69- [other] MAGMaAnnotationEngine is instantiated alongside CosineAlignmentEngine when constructing a ModiFinder object for probability generation.: "Instantiate a ModiFinder object with the known compound, modified compound, and default CosineAlignmentEngine and MAGMaAnnotationEngine"70- [other] Peak preprocessing uses specific tolerance and normalization parameters that control fragment matching.: "default preprocessing (mz_tolerance=0.01, ppm_tolerance=40, ratio_to_base_peak=0.01, normalize_peaks=True)"71- [other] ModiFinder integrates fragment annotation into per-atom scoring.: "fragmentation annotation to a known/unknown compound pair"72- [readme] ModiFinder API produces fragment metadata alongside peak data.: "fragmentsObj = { "frags_map": knownCompound.spectrum.peak_fragment_dict, "structure": knownCompound.structure, "peaks": main_compound_peaks"
HolobiomicsLab