decoy-psm-identification-and-tagging
Summary
Identify and tag decoy peptide-spectrum matches (PSMs) in search engine output using regex patterns or protein name prefixes to enable correct false discovery rate (FDR) control during rescoring. This skill is essential for distinguishing target identifications from decoys before rank filtering and statistical validation.
When to use
Apply this skill when ingesting PSM files from proteomics search engines (MS Amanda, MSGFPlus, MaxQuant, etc.) that contain a mixture of target and decoy PSMs, and you need to ensure accurate FDR calculation during or after rescoring. Decoy identification is a prerequisite for rank-based filtering (max_psm_rank_output) and FDR-based significance testing in MS²Rescore workflows.
When NOT to use
- Input PSM file has already been FDR-filtered; MS²Rescore requires all target and decoy PSMs without FDR-filtering applied beforehand.
- Search engine output uses a non-standard or undocumented decoy naming scheme that cannot be reliably parsed by regex or prefix matching.
- PSM file contains only target PSMs or only decoy PSMs (no mix); decoy identification is meaningless without both populations.
Inputs
- PSM file in psm_utils-supported format (TSV, mzID, CSV, msf, xml)
- Search engine output (MS Amanda, MSGFPlus, MaxQuant, Sage, Mascot, etc.)
- Regex pattern for decoy identification (id_decoy_pattern parameter)
- Protein name prefix convention (e.g., 'DECOY_')
Outputs
- Annotated PSM table with decoy/target classification
- Parsed PSM objects (via psm_utils) with is_decoy flag set
- Stratified PSM sets ready for rank filtering and FDR calculation
How to apply
Extract decoy PSM identifiers using one of two strategies: (1) apply a regex pattern (id_decoy_pattern) to match decoy annotations in PSM file fields, or (2) detect a protein name prefix convention (e.g., 'DECOY_') to flag decoy entries. This classification must occur during PSM file parsing before any rank-based filtering, so that downstream FDR calculations can correctly separate target from decoy PSMs. The choice of pattern depends on the search engine output format; for example, Percolator-compatible workflows often use a dedicated decoy label field, while concatenated target-decoy searches may embed 'DECOY_' in protein IDs. Correctly tagged decoys enable MS²Rescore to filter lower-ranking PSMs (controlled by max_psm_rank_output) while preserving FDR validity, since FDR is computed as (number of decoys passing threshold) / (number of targets passing threshold).
Related tools
- psm_utils (Parses PSM files from heterogeneous search engines and provides standardized data structures for decoy tagging and classification)
- MS²Rescore (Consumes classified decoy/target PSMs and enforces FDR control during rescoring and output filtering using the decoy population) — https://github.com/compomics/ms2rescore
- Percolator (Downstream rescoring engine that relies on correctly identified decoy PSMs to compute q-values and FDR thresholds) — https://github.com/percolator/percolator
Evaluation signals
- Decoy PSMs are correctly classified: verify by inspecting the parsed PSM objects or output TSV for is_decoy flag agreement with regex pattern or prefix rule.
- No false negatives in decoy detection: spot-check protein names in the input file against the regex pattern to confirm all decoys matching the convention are tagged.
- FDR values in downstream output are consistent with the decoy count: confirm that FDR = (# decoys above threshold) / (# targets above threshold) matches reported q-values.
- Stratification is preserved after rank filtering: verify that both decoy and target PSMs are retained and ranked independently per spectrum before max_psm_rank_output filtering.
- Output PSM table includes decoy/target annotation column: inspect the output TSV for a 'is_decoy' or equivalent column with boolean or binary values.
Limitations
- Regex pattern must be carefully designed to avoid cross-matching target protein names that coincidentally contain the decoy substring; testing against real search engine output is critical.
- Some search engines (e.g., MaxQuant) may not report decoy annotations in all fields; manual configuration of the decoy pattern is often necessary.
- Concatenated target-decoy searches require the search engine to be run with appropriate flags (e.g., MSGFPlus with -addFeatures 1) to ensure decoys are present in the output file.
- Decoy identification relies on consistent naming conventions; if the search engine output or protein database changes the naming scheme between runs, the regex pattern may fail silently.
Evidence
- [intro] Identify decoy PSMs using id_decoy_pattern or protein name prefix: "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] Decoy identification is a prerequisite for FDR control: "To ensure a correct FDR control after rescoring, MS²Rescore filters out lower-ranking PSMs before final FDR calculation"
- [intro] MS²Rescore requires both target and decoy PSMs: "MS²Rescore always needs access to all target and decoy PSMs, without any FDR-filtering"
- [methods] Decoy identification uses regex pattern parameter: "Regex pattern used to identify the decoy PSMs in identification file"
- [readme] Multiple search engine formats are supported: "MS²Rescore can read peptide identifications in any format supported by [psm_utils][psm_utils] (see [Supported file formats][file-formats]) and has been tested with various search engines output files"
1---2name: decoy-psm-identification-and-tagging3description: Use when ingesting PSM files from proteomics search engines (MS Amanda, MSGFPlus, MaxQuant, etc.) that contain a mixture of target and decoy PSMs, and you need to ensure accurate FDR calculation during or after rescoring.4license: CC-BY-4.05---67# decoy-psm-identification-and-tagging89## Summary1011Identify and tag decoy peptide-spectrum matches (PSMs) in search engine output using regex patterns or protein name prefixes to enable correct false discovery rate (FDR) control during rescoring. This skill is essential for distinguishing target identifications from decoys before rank filtering and statistical validation.1213## When to use1415Apply this skill when ingesting PSM files from proteomics search engines (MS Amanda, MSGFPlus, MaxQuant, etc.) that contain a mixture of target and decoy PSMs, and you need to ensure accurate FDR calculation during or after rescoring. Decoy identification is a prerequisite for rank-based filtering (max_psm_rank_output) and FDR-based significance testing in MS²Rescore workflows.1617## When NOT to use1819- Input PSM file has already been FDR-filtered; MS²Rescore requires all target and decoy PSMs without FDR-filtering applied beforehand.20- Search engine output uses a non-standard or undocumented decoy naming scheme that cannot be reliably parsed by regex or prefix matching.21- PSM file contains only target PSMs or only decoy PSMs (no mix); decoy identification is meaningless without both populations.2223## Inputs2425- PSM file in psm_utils-supported format (TSV, mzID, CSV, msf, xml)26- Search engine output (MS Amanda, MSGFPlus, MaxQuant, Sage, Mascot, etc.)27- Regex pattern for decoy identification (id_decoy_pattern parameter)28- Protein name prefix convention (e.g., 'DECOY_')2930## Outputs3132- Annotated PSM table with decoy/target classification33- Parsed PSM objects (via psm_utils) with is_decoy flag set34- Stratified PSM sets ready for rank filtering and FDR calculation3536## How to apply3738Extract decoy PSM identifiers using one of two strategies: (1) apply a regex pattern (id_decoy_pattern) to match decoy annotations in PSM file fields, or (2) detect a protein name prefix convention (e.g., 'DECOY_') to flag decoy entries. This classification must occur during PSM file parsing before any rank-based filtering, so that downstream FDR calculations can correctly separate target from decoy PSMs. The choice of pattern depends on the search engine output format; for example, Percolator-compatible workflows often use a dedicated decoy label field, while concatenated target-decoy searches may embed 'DECOY_' in protein IDs. Correctly tagged decoys enable MS²Rescore to filter lower-ranking PSMs (controlled by max_psm_rank_output) while preserving FDR validity, since FDR is computed as (number of decoys passing threshold) / (number of targets passing threshold).3940## Related tools4142- **psm_utils** (Parses PSM files from heterogeneous search engines and provides standardized data structures for decoy tagging and classification)43- **MS²Rescore** (Consumes classified decoy/target PSMs and enforces FDR control during rescoring and output filtering using the decoy population) — https://github.com/compomics/ms2rescore44- **Percolator** (Downstream rescoring engine that relies on correctly identified decoy PSMs to compute q-values and FDR thresholds) — https://github.com/percolator/percolator4546## Evaluation signals4748- Decoy PSMs are correctly classified: verify by inspecting the parsed PSM objects or output TSV for is_decoy flag agreement with regex pattern or prefix rule.49- No false negatives in decoy detection: spot-check protein names in the input file against the regex pattern to confirm all decoys matching the convention are tagged.50- FDR values in downstream output are consistent with the decoy count: confirm that FDR = (# decoys above threshold) / (# targets above threshold) matches reported q-values.51- Stratification is preserved after rank filtering: verify that both decoy and target PSMs are retained and ranked independently per spectrum before max_psm_rank_output filtering.52- Output PSM table includes decoy/target annotation column: inspect the output TSV for a 'is_decoy' or equivalent column with boolean or binary values.5354## Limitations5556- Regex pattern must be carefully designed to avoid cross-matching target protein names that coincidentally contain the decoy substring; testing against real search engine output is critical.57- Some search engines (e.g., MaxQuant) may not report decoy annotations in all fields; manual configuration of the decoy pattern is often necessary.58- Concatenated target-decoy searches require the search engine to be run with appropriate flags (e.g., MSGFPlus with -addFeatures 1) to ensure decoys are present in the output file.59- Decoy identification relies on consistent naming conventions; if the search engine output or protein database changes the naming scheme between runs, the regex pattern may fail silently.6061## Evidence6263- [intro] Identify decoy PSMs using id_decoy_pattern or protein name prefix: "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"64- [intro] Decoy identification is a prerequisite for FDR control: "To ensure a correct FDR control after rescoring, MS²Rescore filters out lower-ranking PSMs before final FDR calculation"65- [intro] MS²Rescore requires both target and decoy PSMs: "MS²Rescore always needs access to **all target and decoy PSMs, without any FDR-filtering**"66- [methods] Decoy identification uses regex pattern parameter: "Regex pattern used to identify the decoy PSMs in identification file"67- [readme] Multiple search engine formats are supported: "MS²Rescore can read peptide identifications in any format supported by [psm_utils][psm_utils] (see [Supported file formats][file-formats]) and has been tested with various search engines output files"
HolobiomicsLab