ion-type-assignment-verification
Summary
Validate that observed mass spectrum peaks are correctly annotated with their ion types (b, y, or other fragment series), charge states, and theoretical mass deviations when matched against a ProForma 2.0 peptidoform string. This skill ensures the integrity of fragment ion assignments before downstream analysis.
When to use
After calling MsmsSpectrum.annotate_proforma() to assign fragment ions to a mass spectrum, verify that each annotated peak has the correct ion_type ('b' or 'y'), charge state, and m/z deviation from the theoretical mass computed for that peptidoform. Use this skill to catch annotation errors before proceeding to spectral matching or peptide identification workflows.
When NOT to use
- Input spectrum has already been manually validated and ion assignments confirmed by expert review in a previous step.
- Peptidoform contains non-standard modifications not defined in Unimod or PSI-MOD controlled vocabularies, preventing accurate theoretical m/z computation.
- Fragment mass tolerance is set so wide (e.g., >500 ppm) that multiple ion types could plausibly match the same peak, making verification ambiguous.
Inputs
- MsmsSpectrum object with observed peak list (m/z, intensity pairs)
- ProForma 2.0 peptidoform string (e.g., DLTDYLM[Oxidation]K)
- Fragment mass tolerance (Da or ppm)
- Tolerance mode (absolute or relative)
Outputs
- Validated annotation table with peak m/z, ion_type, charge, theoretical m/z, and mass error
- List of correctly annotated peaks per ion series
- List of unmatched or mis-annotated peaks (if any)
- Summary statistics (number of b ions, y ions, total annotated peaks)
How to apply
Iterate through the annotated peaks returned by spectrum_utils.MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by'). For each peak, extract its assigned ion_type, charge state, and observed m/z. Compare the observed m/z against the theoretical m/z computed from the ProForma 2.0 peptidoform and verify that the deviation falls within the specified fragment_tol_mass (in Da) or fragment_tol_mode (ppm). Confirm that ion_type assignments follow chemical logic—b ions increase in mass sequentially from the N terminus, y ions from the C terminus—and that no peak is misassigned to a physically impossible ion series for the given peptide length and charge state. Document any peaks that fail these checks as unmatched or incorrectly annotated.
Related tools
- spectrum_utils (Provides MsmsSpectrum.annotate_proforma() method to compute theoretical b and y ion m/z values and match them to observed peaks; provides ProForma parser to extract sequence and modification positions.) — https://github.com/bittremieux/spectrum_utils
- ProForma 2.0 (Standard notation for specifying peptidoforms with modifications; enables unambiguous definition of theoretical fragment ions.) — https://www.psidev.info/proforma
- Unimod (Controlled vocabulary of protein modifications used to resolve modification names in ProForma strings and compute accurate mass shifts.) — https://www.unimod.org/
- PSI-MOD (Controlled vocabulary providing alternative standardized identifiers for protein modifications.) — https://github.com/HUPO-PSI/psi-mod-CV/
Examples
from spectrum_utils.spectrum import MsmsSpectrum; usi = 'mzspec:MSV000079960:DY_HS_Exp7-Ad1:scan:30372'; spectrum = MsmsSpectrum.from_usi(usi); peptide = 'DLTDYLM[Oxidation]K'; annotated = spectrum.annotate_proforma(peptide, fragment_tol_mass=0.05, fragment_tol_mode='Da', ion_types='by'); [print(f"{peak.mz:.4f} {peak.ion_type} +{peak.charge} error={peak.mz_error:.6f} Da") for peak in annotated if peak.ion_type in ['b', 'y']]
Evaluation signals
- All annotated peaks have an assigned ion_type ('b' or 'y'), charge state (≥1), and m/z value.
- Observed m/z of each annotated peak deviates from its theoretical m/z by ≤ fragment_tol_mass (Da) or fragment_tol_mode (ppm), as specified.
- Ion type assignments respect chemical constraints: b-ion m/z values increase monotonically along the peptide sequence; y-ion m/z values follow expected mass ladder.
- No peak is assigned to a charge state inconsistent with its observed m/z (e.g., charge +3 assigned to a singly-charged ion m/z that would be physically impossible).
- Annotation coverage (number of annotated peaks / total peaks in spectrum) is consistent with prior observations for the given peptide mass and fragmentation method.
Limitations
- Verification assumes the ProForma 2.0 string and modification definitions in Unimod are correct; errors in the input peptidoform will propagate to theoretical m/z calculations and cause false failures.
- Internal fragment ions, neutral loss products, and non-protease cleavage patterns are not verified by this skill; only canonical b and y ions are annotated by the default ion_types='by' setting.
- High mass accuracy requirements (<5 ppm) may result in false negatives if the mass spectrometer calibration drifts during acquisition.
- Ambiguous assignments (two or more valid ion types within tolerance of the same observed peak) are not flagged as a concern by this skill; a secondary scoring or consensus step may be needed.
Evidence
- [other] Call MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by') to compute theoretical b and y ion m/z values and match them to observed spectrum peaks within the specified tolerance.: "Call MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by') to compute theoretical b and y ion m/z values and match them to observed spectrum peaks"
- [other] Iterate through annotated peaks and validate that each peak's assigned ion_type ('b' or 'y'), charge state, and m/z deviation from theoretical mass are correct and consistent with the input parameters.: "Iterate through annotated peaks and validate that each peak's assigned ion_type ('b' or 'y'), charge state, and m/z deviation from theoretical mass are correct and consistent"
- [other] spectrum_utils provides functionality to annotate observed spectrum fragments using the ProForma 2.0 specification for modified peptidoforms, enabling ion type annotation.: "spectrum_utils provides functionality to annotate observed spectrum fragments using the ProForma 2.0 specification for modified peptidoforms, enabling ion type annotation"
- [other] Parse the ProForma 2.0 peptidoform string (e.g. DLTDYLM[Oxidation]K) using spectrum_utils.proforma to extract the peptide sequence and modification positions.: "Parse the ProForma 2.0 peptidoform string (e.g. DLTDYLM[Oxidation]K) using spectrum_utils.proforma to extract the peptide sequence and modification positions"
- [other] Modifications are defined by controlled vocabularies (CVs), including Unimod, PSI-MOD, and support for modifications from cross-linking (using XL-MOD) and glycans (using the Glycan Naming Ontology).: "Modifications are defined by controlled vocabularies (CVs), including Unimod, PSI-MOD"
1---2name: ion-type-assignment-verification-33description: Use when after calling MsmsSpectrum.annotate_proforma() to assign fragment ions to a mass spectrum, verify that each annotated peak has the correct ion_type ('b' or 'y'), charge state, and m/z deviation from the theoretical mass computed for that peptidoform.4license: CC-BY-4.05---67# ion-type-assignment-verification89## Summary1011Validate that observed mass spectrum peaks are correctly annotated with their ion types (b, y, or other fragment series), charge states, and theoretical mass deviations when matched against a ProForma 2.0 peptidoform string. This skill ensures the integrity of fragment ion assignments before downstream analysis.1213## When to use1415After calling MsmsSpectrum.annotate_proforma() to assign fragment ions to a mass spectrum, verify that each annotated peak has the correct ion_type ('b' or 'y'), charge state, and m/z deviation from the theoretical mass computed for that peptidoform. Use this skill to catch annotation errors before proceeding to spectral matching or peptide identification workflows.1617## When NOT to use1819- Input spectrum has already been manually validated and ion assignments confirmed by expert review in a previous step.20- Peptidoform contains non-standard modifications not defined in Unimod or PSI-MOD controlled vocabularies, preventing accurate theoretical m/z computation.21- Fragment mass tolerance is set so wide (e.g., >500 ppm) that multiple ion types could plausibly match the same peak, making verification ambiguous.2223## Inputs2425- MsmsSpectrum object with observed peak list (m/z, intensity pairs)26- ProForma 2.0 peptidoform string (e.g., DLTDYLM[Oxidation]K)27- Fragment mass tolerance (Da or ppm)28- Tolerance mode (absolute or relative)2930## Outputs3132- Validated annotation table with peak m/z, ion_type, charge, theoretical m/z, and mass error33- List of correctly annotated peaks per ion series34- List of unmatched or mis-annotated peaks (if any)35- Summary statistics (number of b ions, y ions, total annotated peaks)3637## How to apply3839Iterate through the annotated peaks returned by spectrum_utils.MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by'). For each peak, extract its assigned ion_type, charge state, and observed m/z. Compare the observed m/z against the theoretical m/z computed from the ProForma 2.0 peptidoform and verify that the deviation falls within the specified fragment_tol_mass (in Da) or fragment_tol_mode (ppm). Confirm that ion_type assignments follow chemical logic—b ions increase in mass sequentially from the N terminus, y ions from the C terminus—and that no peak is misassigned to a physically impossible ion series for the given peptide length and charge state. Document any peaks that fail these checks as unmatched or incorrectly annotated.4041## Related tools4243- **spectrum_utils** (Provides MsmsSpectrum.annotate_proforma() method to compute theoretical b and y ion m/z values and match them to observed peaks; provides ProForma parser to extract sequence and modification positions.) — https://github.com/bittremieux/spectrum_utils44- **ProForma 2.0** (Standard notation for specifying peptidoforms with modifications; enables unambiguous definition of theoretical fragment ions.) — https://www.psidev.info/proforma45- **Unimod** (Controlled vocabulary of protein modifications used to resolve modification names in ProForma strings and compute accurate mass shifts.) — https://www.unimod.org/46- **PSI-MOD** (Controlled vocabulary providing alternative standardized identifiers for protein modifications.) — https://github.com/HUPO-PSI/psi-mod-CV/4748## Examples4950```51from spectrum_utils.spectrum import MsmsSpectrum; usi = 'mzspec:MSV000079960:DY_HS_Exp7-Ad1:scan:30372'; spectrum = MsmsSpectrum.from_usi(usi); peptide = 'DLTDYLM[Oxidation]K'; annotated = spectrum.annotate_proforma(peptide, fragment_tol_mass=0.05, fragment_tol_mode='Da', ion_types='by'); [print(f"{peak.mz:.4f} {peak.ion_type} +{peak.charge} error={peak.mz_error:.6f} Da") for peak in annotated if peak.ion_type in ['b', 'y']]52```5354## Evaluation signals5556- All annotated peaks have an assigned ion_type ('b' or 'y'), charge state (≥1), and m/z value.57- Observed m/z of each annotated peak deviates from its theoretical m/z by ≤ fragment_tol_mass (Da) or fragment_tol_mode (ppm), as specified.58- Ion type assignments respect chemical constraints: b-ion m/z values increase monotonically along the peptide sequence; y-ion m/z values follow expected mass ladder.59- No peak is assigned to a charge state inconsistent with its observed m/z (e.g., charge +3 assigned to a singly-charged ion m/z that would be physically impossible).60- Annotation coverage (number of annotated peaks / total peaks in spectrum) is consistent with prior observations for the given peptide mass and fragmentation method.6162## Limitations6364- Verification assumes the ProForma 2.0 string and modification definitions in Unimod are correct; errors in the input peptidoform will propagate to theoretical m/z calculations and cause false failures.65- Internal fragment ions, neutral loss products, and non-protease cleavage patterns are not verified by this skill; only canonical b and y ions are annotated by the default ion_types='by' setting.66- High mass accuracy requirements (<5 ppm) may result in false negatives if the mass spectrometer calibration drifts during acquisition.67- Ambiguous assignments (two or more valid ion types within tolerance of the same observed peak) are not flagged as a concern by this skill; a secondary scoring or consensus step may be needed.6869## Evidence7071- [other] Call MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by') to compute theoretical b and y ion m/z values and match them to observed spectrum peaks within the specified tolerance.: "Call MsmsSpectrum.annotate_proforma(peptide, fragment_tol_mass, fragment_tol_mode, ion_types='by') to compute theoretical b and y ion m/z values and match them to observed spectrum peaks"72- [other] Iterate through annotated peaks and validate that each peak's assigned ion_type ('b' or 'y'), charge state, and m/z deviation from theoretical mass are correct and consistent with the input parameters.: "Iterate through annotated peaks and validate that each peak's assigned ion_type ('b' or 'y'), charge state, and m/z deviation from theoretical mass are correct and consistent"73- [other] spectrum_utils provides functionality to annotate observed spectrum fragments using the ProForma 2.0 specification for modified peptidoforms, enabling ion type annotation.: "spectrum_utils provides functionality to annotate observed spectrum fragments using the ProForma 2.0 specification for modified peptidoforms, enabling ion type annotation"74- [other] Parse the ProForma 2.0 peptidoform string (e.g. DLTDYLM[Oxidation]K) using spectrum_utils.proforma to extract the peptide sequence and modification positions.: "Parse the ProForma 2.0 peptidoform string (e.g. DLTDYLM[Oxidation]K) using spectrum_utils.proforma to extract the peptide sequence and modification positions"75- [other] Modifications are defined by controlled vocabularies (CVs), including Unimod, PSI-MOD, and support for modifications from cross-linking (using XL-MOD) and glycans (using the Glycan Naming Ontology).: "Modifications are defined by controlled vocabularies (CVs), including Unimod, PSI-MOD"
HolobiomicsLab