configuration-file-interpretation
Summary
Parse and apply JSON/TOML configuration files to map search-engine-specific modification labels to standardized ProForma notation, enabling MS²Rescore to correctly link PSMs to spectra and configure rescoring parameters. This skill is essential for translating heterogeneous search engine outputs into a unified proteomics rescoring workflow.
When to use
When you have PSM files from proteomics search engines (MaxQuant, MSGFPlus, Sage, etc.) that use non-standard modification notation (e.g., 'ox', '+57.02146', or mass-shift labels) and need to resccore peptide identifications with MS²Rescore. The configuration file bridges the gap between search engine output and the ProForma v2 standard required by rescoring engines and feature generators like DeepLC.
When NOT to use
- PSM files already contain ProForma-compliant modification notation (e.g., from a previous MS²Rescore run) — no remapping is needed.
- You have pre-filtered PSM files (FDR-filtered results) — MS²Rescore requires access to ALL target and decoy PSMs without FDR filtering.
- Spectrum files are unavailable or unlinked — some feature generators (e.g., DeepLC) require spectrum data and cannot proceed with configuration alone.
Inputs
- JSON or TOML configuration file with modification_mapping, fixed_modifications, spectrum_id_pattern, id_decoy_pattern, and rescoring engine settings
- PSM files from search engines (MaxQuant msms.txt, MSGFPlus .mzid, Sage .sage.tsv, etc.) in formats supported by psm_utils
- Spectrum files in mzML or mgf format linked via spectrum_id_pattern
Outputs
- Parsed configuration object with validated modification mappings conforming to ProForma v2
- PSM objects with remapped peptide sequences using ProForma notation
- Intermediate or final PSM file with standardized modification labels ready for feature generation and rescoring
- Decoy/target PSM sets correctly partitioned using id_decoy_pattern
How to apply
Load the JSON or TOML configuration file that contains three key mappings: (1) modification_mapping, which translates each search-engine-specific modification label to ProForma notation using PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P'); (2) fixed_modifications, mapping amino acids to modification names for modifications not reported in the PSM file; and (3) spectrum_id_pattern and id_decoy_pattern regex patterns to extract scan numbers and identify decoy PSMs. For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label from the mapping dictionary. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation using psm_utils validation. The configuration also specifies decoy identification strategy (e.g., 'DECOY_' protein name prefix) and rescoring engine parameters (Mokapot or Percolator). Apply the configuration via CLI (ms2rescore --config config.toml), GUI, or Python API before feature generation and rescoring.
Related tools
- MS²Rescore (Primary rescoring platform that reads and applies the configuration file to map modifications, link PSMs to spectra, and orchestrate rescoring) — https://github.com/compomics/ms2rescore
- psm_utils (Validates that mapped modification labels conform to HUPO-PSI ProForma v2 notation and parses PSM files from multiple search engines)
- Percolator (Rescoring engine configured and invoked by MS²Rescore after modification mapping is applied) — https://github.com/percolator/percolator/releases/latest
- Mokapot (Alternative rescoring engine that can be selected and configured via the configuration file)
- DeepLC (Feature generator that requires modification formula notation; configuration determines which modification format is preferred)
Examples
ms2rescore --config config.toml input_psms.mzid --spectrum_files spectra.mzML
Evaluation signals
- All search-engine-specific modification labels (e.g., 'ox', 'gl', '+57.02146') are successfully mapped to ProForma labels (e.g., 'U:Oxidation', 'U:Gln->pyro-Glu') and validate against psm_utils ProForma v2 schema without errors.
- PSM-to-spectrum linkage succeeds for ≥95% of PSMs using the spectrum_id_pattern regex; failed linkages are logged and investigated.
- Decoy PSMs are correctly identified using id_decoy_pattern (e.g., protein name prefix 'DECOY_' or custom regex); decoy rate in output matches input before rescoring.
- Fixed modifications not reported in the PSM file are correctly added to the peptide sequences for all affected amino acids (e.g., carbamidomethyl on all C residues).
- Feature generators (DeepLC, MS²PIP) and rescoring engines (Percolator, Mokapot) execute without modification-related errors after configuration is applied; rescoring improves PSM confidence scores and increases identifications at constant FDR threshold.
Limitations
- Some search engines (e.g., MaxQuant) do not report fixed modifications in the PSM file; these must be configured separately in fixed_modifications or rescoring will not account for them.
- Mass-shift notation (e.g., '+57.02146') is ambiguous and may map to multiple modifications; formula notation (e.g., 'Formula:HO3P') is preferred for modifications not in PSI-MOD or Unimod controlled vocabularies.
- Regex patterns for spectrum_id_pattern, id_decoy_pattern, and PSM_id extraction (psm_id_pattern) are search-engine-specific and error-prone; incorrect patterns cause silent PSM-spectrum mismatches or incorrect decoy identification.
- Configuration file format (JSON vs. TOML) and parameter naming differ across MS²Rescore versions; version compatibility must be verified.
Evidence
- [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"
- [intro] Configuration via JSON/TOML file is a primary usage mode: "MS²Rescore can be configured through the command line interface (CLI), the graphical user interface (GUI), or a JSON/TOML configuration file"
- [methods] Modification mapping accepts five standardized formats from controlled vocabularies: "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,"
- [intro] Fixed modifications must be configured separately for search engines that do not report them: "fixed modifications that are not reported in the PSM file must be configured separately"
- [intro] Decoy identification is configured via regex pattern: "it can usually be derived from the protein name. For example, if the protein name contains the prefix
DECOY_, the PSM is a decoy PSM"
- [intro] Spectrum linkage requires configurable ID extraction patterns: "Essential for MS²Rescore to function correctly is linking the search engine PSMs to the original spectra...two options are available to map PSMs to spectra:
spectrum_id_pattern and"
- [intro] Input requires all target and decoy PSMs unfiltered: "MS²Rescore always needs access to all target and decoy PSMs, without any FDR-filtering"
- [intro] ProForma v2 is the standardized notation required: "MS²Rescore uses the
HUPO-PSI standardized ProForma v2 notation to represent modified peptides"
1---2name: configuration-file-interpretation-23description: Use when when you have PSM files from proteomics search engines (MaxQuant, MSGFPlus, Sage, etc.) that use non-standard modification notation (e.g., 'ox', '+57.02146', or mass-shift labels) and need to resccore peptide identifications with MS²Rescore.4license: CC-BY-4.05metadata:6 source: https://skillmd.com/skills/holobiomicslab/configuration-file-interpretation-27 edam_operation: http://edamontology.org/operation_30968 edam_topics:9 - http://edamontology.org/topic_012110 - http://edamontology.org/topic_352011 tools:12 - psm_utils13 - MS²Rescore14 - Percolator15 - Mokapot16 - DeepLC17 techniques:18 - mass-spectrometry19derived_from:20- doi: 10.1002/pmic.20230033621 title: MS2Rescore (immunopeptidome rescoring)22evidence_spans:23- Accepted ProForma modification labels in :py:mod:`psm_utils`24- MS²Rescore is a tool for rescoring peptide-spectrum matches25claims: []26provenance:27 collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v228 assembled_by: scripts/collect_metabolomics_collection.py29 sources:30 - build: coll_ms2rescore_immunopeptidome_rescoring_cq31 doi: 10.1002/pmic.20230033632 title: MS2Rescore (immunopeptidome rescoring)33 dedup_kept_from: coll_ms2rescore_immunopeptidome_rescoring_cq34schema_version: 0.2.035attribution:36 generator: AgenticScienceBuilder37 original_doi: 10.1002/pmic.20230033638 all_source_dois:39 - 10.1002/pmic.20230033640 zenodo_doi: 10.5281/zenodo.2079402741 curators: []42 promoter: Louis-Félix Nothias43 sponsor: CNRS & Université Côte d'Azur44---4546# configuration-file-interpretation4748## Summary4950Parse and apply JSON/TOML configuration files to map search-engine-specific modification labels to standardized ProForma notation, enabling MS²Rescore to correctly link PSMs to spectra and configure rescoring parameters. This skill is essential for translating heterogeneous search engine outputs into a unified proteomics rescoring workflow.5152## When to use5354When you have PSM files from proteomics search engines (MaxQuant, MSGFPlus, Sage, etc.) that use non-standard modification notation (e.g., 'ox', '+57.02146', or mass-shift labels) and need to resccore peptide identifications with MS²Rescore. The configuration file bridges the gap between search engine output and the ProForma v2 standard required by rescoring engines and feature generators like DeepLC.5556## When NOT to use5758- PSM files already contain ProForma-compliant modification notation (e.g., from a previous MS²Rescore run) — no remapping is needed.59- You have pre-filtered PSM files (FDR-filtered results) — MS²Rescore requires access to ALL target and decoy PSMs without FDR filtering.60- Spectrum files are unavailable or unlinked — some feature generators (e.g., DeepLC) require spectrum data and cannot proceed with configuration alone.6162## Inputs6364- JSON or TOML configuration file with modification_mapping, fixed_modifications, spectrum_id_pattern, id_decoy_pattern, and rescoring engine settings65- PSM files from search engines (MaxQuant msms.txt, MSGFPlus .mzid, Sage .sage.tsv, etc.) in formats supported by psm_utils66- Spectrum files in mzML or mgf format linked via spectrum_id_pattern6768## Outputs6970- Parsed configuration object with validated modification mappings conforming to ProForma v271- PSM objects with remapped peptide sequences using ProForma notation72- Intermediate or final PSM file with standardized modification labels ready for feature generation and rescoring73- Decoy/target PSM sets correctly partitioned using id_decoy_pattern7475## How to apply7677Load the JSON or TOML configuration file that contains three key mappings: (1) modification_mapping, which translates each search-engine-specific modification label to ProForma notation using PSI-MOD accession, PSI-MOD name, Unimod accession, Unimod name, or chemical formula (e.g., 'Formula:HO3P'); (2) fixed_modifications, mapping amino acids to modification names for modifications not reported in the PSM file; and (3) spectrum_id_pattern and id_decoy_pattern regex patterns to extract scan numbers and identify decoy PSMs. For each PSM, iterate through its peptide sequence and replace each search-engine modification label with its corresponding ProForma label from the mapping dictionary. Validate that all mapped labels conform to HUPO-PSI ProForma v2 notation using psm_utils validation. The configuration also specifies decoy identification strategy (e.g., 'DECOY_' protein name prefix) and rescoring engine parameters (Mokapot or Percolator). Apply the configuration via CLI (ms2rescore --config config.toml), GUI, or Python API before feature generation and rescoring.7879## Related tools8081- **MS²Rescore** (Primary rescoring platform that reads and applies the configuration file to map modifications, link PSMs to spectra, and orchestrate rescoring) — https://github.com/compomics/ms2rescore82- **psm_utils** (Validates that mapped modification labels conform to HUPO-PSI ProForma v2 notation and parses PSM files from multiple search engines)83- **Percolator** (Rescoring engine configured and invoked by MS²Rescore after modification mapping is applied) — https://github.com/percolator/percolator/releases/latest84- **Mokapot** (Alternative rescoring engine that can be selected and configured via the configuration file)85- **DeepLC** (Feature generator that requires modification formula notation; configuration determines which modification format is preferred)8687## Examples8889```90ms2rescore --config config.toml input_psms.mzid --spectrum_files spectra.mzML91```9293## Evaluation signals9495- All search-engine-specific modification labels (e.g., 'ox', 'gl', '+57.02146') are successfully mapped to ProForma labels (e.g., 'U:Oxidation', 'U:Gln->pyro-Glu') and validate against psm_utils ProForma v2 schema without errors.96- PSM-to-spectrum linkage succeeds for ≥95% of PSMs using the spectrum_id_pattern regex; failed linkages are logged and investigated.97- Decoy PSMs are correctly identified using id_decoy_pattern (e.g., protein name prefix 'DECOY_' or custom regex); decoy rate in output matches input before rescoring.98- Fixed modifications not reported in the PSM file are correctly added to the peptide sequences for all affected amino acids (e.g., carbamidomethyl on all C residues).99- Feature generators (DeepLC, MS²PIP) and rescoring engines (Percolator, Mokapot) execute without modification-related errors after configuration is applied; rescoring improves PSM confidence scores and increases identifications at constant FDR threshold.100101## Limitations102103- Some search engines (e.g., MaxQuant) do not report fixed modifications in the PSM file; these must be configured separately in fixed_modifications or rescoring will not account for them.104- Mass-shift notation (e.g., '+57.02146') is ambiguous and may map to multiple modifications; formula notation (e.g., 'Formula:HO3P') is preferred for modifications not in PSI-MOD or Unimod controlled vocabularies.105- Regex patterns for spectrum_id_pattern, id_decoy_pattern, and PSM_id extraction (psm_id_pattern) are search-engine-specific and error-prone; incorrect patterns cause silent PSM-spectrum mismatches or incorrect decoy identification.106- Configuration file format (JSON vs. TOML) and parameter naming differ across MS²Rescore versions; version compatibility must be verified.107108## Evidence109110- [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``"111- [intro] Configuration via JSON/TOML file is a primary usage mode: "MS²Rescore can be configured through the command line interface (CLI), the graphical user interface (GUI), or a JSON/TOML configuration file"112- [methods] Modification mapping accepts five standardized formats from controlled vocabularies: "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,"113- [intro] Fixed modifications must be configured separately for search engines that do not report them: "fixed modifications that are not reported in the PSM file must be configured separately"114- [intro] Decoy identification is configured via regex pattern: "it can usually be derived from the protein name. For example, if the protein name contains the prefix ``DECOY_``, the PSM is a decoy PSM"115- [intro] Spectrum linkage requires configurable ID extraction patterns: "Essential for MS²Rescore to function correctly is linking the search engine PSMs to the original spectra...two options are available to map PSMs to spectra: ``spectrum_id_pattern`` and"116- [intro] Input requires all target and decoy PSMs unfiltered: "MS²Rescore always needs access to **all target and decoy PSMs, without any FDR-filtering**"117- [intro] ProForma v2 is the standardized notation required: "MS²Rescore uses the `HUPO-PSI standardized ProForma v2 notation` to represent modified peptides"