proforma-notation-parsing
Summary
Parsing and standardization of modified peptide sequences into HUPO-PSI ProForma v2 notation, which unifies search-engine-specific modification labels (e.g., MaxQuant 'ox', mass shifts) into controlled-vocabulary identifiers (Unimod, PSI-MOD, or chemical formulas) for downstream MS²Rescore rescoring and feature generation.
When to use
When peptide identifications from a search engine (MaxQuant, MSGFPlus, Sage, etc.) contain custom or engine-specific modification notation that must be converted to a standardized format before rescoring, or when different search engines use incompatible modification label schemes that need unification for joint analysis or cross-tool compatibility.
When NOT to use
- PSM files already encoded in standardized ProForma notation (no remapping needed)
- Modifications that are absent from all five controlled vocabularies and cannot be expressed as chemical formulas (unless custom formula mapping is explicitly documented)
- Search engines that do not report any modifications in the PSM file (use fixed_modifications configuration instead)
Inputs
- PSM file from search engine (MaxQuant msms.txt, MSGFPlus .mzid, Sage .sage.tsv, or other format supported by psm_utils)
- Modification mapping configuration (TOML or JSON file with search-engine label → ProForma label mappings)
- Peptide sequences with search-engine-specific modification notation
Outputs
- PSM records with peptide sequences remapped to ProForma v2 notation
- Annotated PSM object or intermediate file with standardized modification labels
- Validation report confirming all labels conform to HUPO-PSI ProForma v2
How to apply
Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+15.9949', or mass-shift notation). Read the modification_mapping configuration from a TOML/JSON file, where each search-engine label is explicitly mapped to a ProForma-compatible label in one of five accepted formats: PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P'). For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label using the mapping dictionary. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation and are recognized by psm_utils. Write or update the PSM record with the remapped peptide sequences, preserving all other PSM fields and metadata.
Related tools
- psm_utils (Parsing and validation of PSM files in multiple formats; acceptance and validation of ProForma-compliant modification labels)
- MS²Rescore (Rescoring engine that consumes ProForma-normalized PSM records; uses standardized modification notation for feature generation and rescoring) — https://github.com/compomics/ms2rescore
- Unimod (Controlled vocabulary for UniMod accessions and names used in ProForma label mapping (e.g., 'U:Oxidation'))
- PSI-MOD (Controlled vocabulary for PSI-MOD accessions and names used in ProForma label mapping)
- HUPO-PSI/ProForma (Standard notation specification defining syntax and validation rules for ProForma v2 modification labels) — https://github.com/HUPO-PSI/ProForma
Evaluation signals
- All search-engine modification labels in the input PSM file are successfully matched against the modification_mapping dictionary with zero unmapped labels reported
- Output PSM records conform to HUPO-PSI ProForma v2 syntax when parsed by psm_utils (no validation errors)
- Each mapped ProForma label is expressed in one of the five accepted formats: PSI-MOD accession (e.g., MOD:00696), PSI-MOD name (e.g., Oxidation), Unimod accession (e.g., U:1), Unimod name (e.g., U:Oxidation), or chemical formula (e.g., Formula:HO3P)
- Spot-check: a sample of 10+ PSMs shows correct 1:1 mapping of input labels to output ProForma labels (e.g., MaxQuant 'ox' → 'U:Oxidation', 'gl' → 'U:Gln->pyro-Glu')
- All non-modification fields in the PSM record (scan number, spectrum ID, peptide sequence backbone, charge, m/z, RT) are preserved unchanged in the output
Limitations
- Modification mapping is search-engine-specific and must be manually curated per search engine; no automatic detection of unmapped labels across engines
- Chemical formula notation is recommended only for modifications absent from Unimod and PSI-MOD controlled vocabularies; mass-shift-only modifications may not be fully portable across tools
- ProForma notation supports a fixed set of syntax rules (e.g., square brackets for position-specific modifications); non-standard or proprietary search-engine notation (e.g., Mascot-specific mass deltas) may require custom pre-processing before mapping
- Fixed modifications not reported in the PSM file must be added via a separate fixed_modifications configuration; this skill only remaps labels already present in the input
Evidence
- [other] MS²Rescore implements modification_mapping as a configuration object that maps search-engine-specific modification labels to ProForma labels in five accepted formats: PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P').: "MS²Rescore implements modification_mapping as a configuration object that maps search-engine-specific modification labels to ProForma labels in five accepted formats: PSI-MOD accession, PSI-MOD name,"
- [intro] MS²Rescore requires mapping of search engine modification labels to ProForma notation; most PSM file types coming from different proteomics search engines use a custom modification notation...Therefore, 'ox' needs to be mapped to 'U:Oxidation': "most PSM file types coming from different proteomics search engines use a custom modification notation...Therefore,
ox needs to be mapped to U:Oxidation"
- [other] 1. Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+57.02146', or mass-shift notation). 2. Read the modification_mapping configuration from the TOML/JSON file, where each search-engine label is mapped to a ProForma-compatible label. 3. For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label using the mapping dictionary. 4. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation and are recognized by psm_utils.: "Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+57.02146', or mass-shift notation). 2. Read the modification_mapping configuration from the"
- [intro] MS²Rescore uses the
HUPO-PSI standardized ProForma v2 notation to represent modified peptides...requires a configuration :py:obj:modification_mapping which maps each specific search engine: "MS²Rescore uses the HUPO-PSI standardized ProForma v2 notation to represent modified peptides...requires a configuration :py:obj:modification_mapping which maps each specific search engine"
- [readme] Protein and peptide sequences are usually represented using a string of amino acids using a well-known one letter code endorsed by the IUPAC. However, there is still no clear consensus about how to represent 'proteoforms' and 'peptidoforms'... A standard notation for proteoforms and peptidoforms is then required for the community: "A standard notation for proteoforms and peptidoforms is then required for the community, so that it can be embedded in many relevant PSI (and potentially other) file formats."
1---2name: proforma-notation-parsing-23description: Use when when peptide identifications from a search engine (MaxQuant, MSGFPlus, Sage, etc.) contain custom or engine-specific modification notation that must be converted to a standardized format before rescoring, or when different search engines use incompatible modification label schemes that.4license: CC-BY-4.05---67# proforma-notation-parsing89## Summary1011Parsing and standardization of modified peptide sequences into HUPO-PSI ProForma v2 notation, which unifies search-engine-specific modification labels (e.g., MaxQuant 'ox', mass shifts) into controlled-vocabulary identifiers (Unimod, PSI-MOD, or chemical formulas) for downstream MS²Rescore rescoring and feature generation.1213## When to use1415When peptide identifications from a search engine (MaxQuant, MSGFPlus, Sage, etc.) contain custom or engine-specific modification notation that must be converted to a standardized format before rescoring, or when different search engines use incompatible modification label schemes that need unification for joint analysis or cross-tool compatibility.1617## When NOT to use1819- PSM files already encoded in standardized ProForma notation (no remapping needed)20- Modifications that are absent from all five controlled vocabularies and cannot be expressed as chemical formulas (unless custom formula mapping is explicitly documented)21- Search engines that do not report any modifications in the PSM file (use fixed_modifications configuration instead)2223## Inputs2425- PSM file from search engine (MaxQuant msms.txt, MSGFPlus .mzid, Sage .sage.tsv, or other format supported by psm_utils)26- Modification mapping configuration (TOML or JSON file with search-engine label → ProForma label mappings)27- Peptide sequences with search-engine-specific modification notation2829## Outputs3031- PSM records with peptide sequences remapped to ProForma v2 notation32- Annotated PSM object or intermediate file with standardized modification labels33- Validation report confirming all labels conform to HUPO-PSI ProForma v23435## How to apply3637Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+15.9949', or mass-shift notation). Read the modification_mapping configuration from a TOML/JSON file, where each search-engine label is explicitly mapped to a ProForma-compatible label in one of five accepted formats: PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P'). For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label using the mapping dictionary. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation and are recognized by psm_utils. Write or update the PSM record with the remapped peptide sequences, preserving all other PSM fields and metadata.3839## Related tools4041- **psm_utils** (Parsing and validation of PSM files in multiple formats; acceptance and validation of ProForma-compliant modification labels)42- **MS²Rescore** (Rescoring engine that consumes ProForma-normalized PSM records; uses standardized modification notation for feature generation and rescoring) — https://github.com/compomics/ms2rescore43- **Unimod** (Controlled vocabulary for UniMod accessions and names used in ProForma label mapping (e.g., 'U:Oxidation'))44- **PSI-MOD** (Controlled vocabulary for PSI-MOD accessions and names used in ProForma label mapping)45- **HUPO-PSI/ProForma** (Standard notation specification defining syntax and validation rules for ProForma v2 modification labels) — https://github.com/HUPO-PSI/ProForma4647## Evaluation signals4849- All search-engine modification labels in the input PSM file are successfully matched against the modification_mapping dictionary with zero unmapped labels reported50- Output PSM records conform to HUPO-PSI ProForma v2 syntax when parsed by psm_utils (no validation errors)51- Each mapped ProForma label is expressed in one of the five accepted formats: PSI-MOD accession (e.g., MOD:00696), PSI-MOD name (e.g., Oxidation), Unimod accession (e.g., U:1), Unimod name (e.g., U:Oxidation), or chemical formula (e.g., Formula:HO3P)52- Spot-check: a sample of 10+ PSMs shows correct 1:1 mapping of input labels to output ProForma labels (e.g., MaxQuant 'ox' → 'U:Oxidation', 'gl' → 'U:Gln->pyro-Glu')53- All non-modification fields in the PSM record (scan number, spectrum ID, peptide sequence backbone, charge, m/z, RT) are preserved unchanged in the output5455## Limitations5657- Modification mapping is search-engine-specific and must be manually curated per search engine; no automatic detection of unmapped labels across engines58- Chemical formula notation is recommended only for modifications absent from Unimod and PSI-MOD controlled vocabularies; mass-shift-only modifications may not be fully portable across tools59- ProForma notation supports a fixed set of syntax rules (e.g., square brackets for position-specific modifications); non-standard or proprietary search-engine notation (e.g., Mascot-specific mass deltas) may require custom pre-processing before mapping60- Fixed modifications not reported in the PSM file must be added via a separate fixed_modifications configuration; this skill only remaps labels already present in the input6162## Evidence6364- [other] MS²Rescore implements modification_mapping as a configuration object that maps search-engine-specific modification labels to ProForma labels in five accepted formats: PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P').: "MS²Rescore implements modification_mapping as a configuration object that maps search-engine-specific modification labels to ProForma labels in five accepted formats: PSI-MOD accession, PSI-MOD name,"65- [intro] MS²Rescore requires mapping of search engine modification labels to ProForma notation; most PSM file types coming from different proteomics search engines use a custom modification notation...Therefore, 'ox' needs to be mapped to 'U:Oxidation': "most PSM file types coming from different proteomics search engines use a custom modification notation...Therefore, ``ox`` needs to be mapped to ``U:Oxidation``"66- [other] 1. Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+57.02146', or mass-shift notation). 2. Read the modification_mapping configuration from the TOML/JSON file, where each search-engine label is mapped to a ProForma-compatible label. 3. For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label using the mapping dictionary. 4. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation and are recognized by psm_utils.: "Load the PSM file and extract modification labels as they appear in the search engine output (e.g., 'ox', '+57.02146', or mass-shift notation). 2. Read the modification_mapping configuration from the"67- [intro] MS²Rescore uses the `HUPO-PSI standardized ProForma v2 notation` to represent modified peptides...requires a configuration :py:obj:`modification_mapping` which maps each specific search engine: "MS²Rescore uses the `HUPO-PSI standardized ProForma v2 notation` to represent modified peptides...requires a configuration :py:obj:`modification_mapping` which maps each specific search engine"68- [readme] Protein and peptide sequences are usually represented using a string of amino acids using a well-known one letter code endorsed by the IUPAC. However, there is still no clear consensus about how to represent 'proteoforms' and 'peptidoforms'... A standard notation for proteoforms and peptidoforms is then required for the community: "A standard notation for proteoforms and peptidoforms is then required for the community, so that it can be embedded in many relevant PSI (and potentially other) file formats."
HolobiomicsLab 