Candidate psm cardinality control

Candidate PSM Cardinality Control

Summary

Apply rank-based filtering to limit the number of candidate peptide-spectrum matches (PSMs) per spectrum at two distinct stages: input (for rescoring feature generation) and output (before FDR calculation). This dual-stage filtering ensures efficient rescoring while maintaining correct false discovery rate control.

When to use

When rescoring PSMs from a search engine with MS²Rescore and you need to (1) constrain computational cost by reducing the number of candidates fed to feature generators and rescoring engines, (2) control false discovery rate correctly by removing lower-ranking PSMs before final statistical calculations, or (3) handle chimeric spectra where multiple valid peptide identifications exist per spectrum but only top-ranked results should be reported.

When NOT to use

• Input PSM file is already FDR-filtered; MS²Rescore requires access to all target and decoy PSMs without any FDR-filtering applied beforehand.
• You have no need to rescore PSMs; cardinality control is specific to the rescoring workflow and adds complexity without benefit in search-only pipelines.
• Spectrum files are unavailable or unlinked to PSM entries; feature generation for rescoring requires valid spectrum ID mapping.

Inputs

• PSM file from proteomics search engine (e.g., MaxQuant msms.txt, MSGFPlus .mzid, Mascot .mzid, MS Amanda .csv)
• Spectrum file (mzML or mgf format) — required for feature generation
• Configuration parameters: max_psm_rank_input, max_psm_rank_output, lower_score_is_better flag, decoy identification pattern (id_decoy_pattern or protein name prefix)

Outputs

• Filtered PSM table (TSV format) with all retained PSMs and their ranks, grouped by spectrum
• Rank assignments per PSM (1, 2, 3, ...) within each spectrum
• Subset of PSMs meeting cardinality constraints for FDR calculation

How to apply

Load all target and decoy PSM entries from the search engine output (without prior FDR filtering) using psm_utils, grouping by spectrum identifier. For each spectrum, sort PSMs by the search engine score (applying the lower_score_is_better flag if necessary). Filter to retain up to max_psm_rank_input PSMs per spectrum (default 10) as candidates for downstream feature generation and model rescoring. After rescoring completes, re-sort PSMs by the rescored metric for each spectrum, then filter to retain up to max_psm_rank_output PSMs per spectrum (default 1) before applying FDR calculation. The rationale is that input filtering reduces computational burden without affecting FDR control, while output filtering ensures that lower-ranking PSMs (which may have been boosted by rescoring in chimeric spectra) do not violate FDR assumptions during statistical tests.

Related tools

• MS²Rescore (Primary rescoring platform that implements rank-based filtering at input and output stages) — https://github.com/compomics/ms2rescore
• psm_utils (PSM file parser and grouper; used to load, parse, and organize target and decoy PSM entries by spectrum identifier) — https://github.com/compomics/psm_utils
• Mokapot (Rescoring engine supported by MS²Rescore; receives rank-filtered input PSMs and produces rescored metrics)
• Percolator (Rescoring engine supported by MS²Rescore; receives rank-filtered input PSMs and produces rescored metrics) — https://github.com/percolator/percolator/releases/latest

Examples

ms2rescore config.json --max_psm_rank_input 10 --max_psm_rank_output 1

Evaluation signals

• Each spectrum in the output PSM table contains ≤ max_psm_rank_output PSMs, verified by counting rows per spectrum identifier.
• PSMs are sorted by rescored metric within each spectrum and assigned consecutive ranks (1, 2, 3, ...) in rank column.
• Input feature generation received ≤ max_psm_rank_input PSMs per spectrum; downstream rescoring engines processed this constrained set.
• FDR calculation results remain statistically valid; lower-ranking PSMs removed before statistical tests do not inflate false positive rates.
• Chimeric spectra with multiple valid peptides retain their top-1 ranked PSM (if max_psm_rank_output=1) while lower-ranking candidates are excluded from final output.

Limitations

• Setting max_psm_rank_input too low (e.g., 1–2) may exclude valid alternative PSMs and reduce rescoring benefit, especially for chimeric or ambiguous spectra.
• Setting max_psm_rank_output to 1 enforces single-PSM reporting per spectrum, which may discard valid co-identifications for spectra with genuinely ambiguous peptide assignments.
• The lower_score_is_better flag must be set correctly for each search engine; incorrect orientation can lead to inverted ranking and removal of top-scoring candidates.
• Decoy identification pattern (id_decoy_pattern or protein name prefix) must match the search engine's decoy labeling scheme; mismatched patterns cause decoy PSMs to be treated as targets or vice versa, violating FDR control.

Evidence

• [other] max_psm_rank_input controls how many candidate PSMs per spectrum are included for rescoring: "max_psm_rank_input controls how many candidate PSMs per spectrum are included for rescoring (e.g., top 5 PSMs)"
• [other] max_psm_rank_output filters lower-ranking PSMs before final FDR calculation: "max_psm_rank_output filters lower-ranking PSMs before final FDR calculation and output writing to ensure correct FDR control"
• [intro] MS²Rescore requires access to all target and decoy PSMs without FDR-filtering: "MS²Rescore always needs access to all target and decoy PSMs, without any FDR-filtering"
• [intro] MS²Rescore supports rescoring of multiple candidate PSMs per spectrum, allowing lower-ranking candidates to become top-ranked after rescoring: "MS²Rescore can rescore multiple candidate PSMs per spectrum. This allows for lower-ranking candidate PSMs to become the top-ranked PSM after rescoring"
• [other] Two-stage rank filtering: input candidates sorted by search engine score, output candidates sorted by rescored metric: "For each spectrum, sort PSMs by search engine score (lower is better if lower_score_is_better flag is true, otherwise higher is better). Select up to max_psm_rank_input PSMs per spectrum (default 10)"
• [other] PSM grouping by spectrum identifier using psm_utils: "Load PSM file and parse all target and decoy PSM entries using psm_utils, grouping by spectrum identifier"
• [intro] FDR control rationale for output filtering: "To ensure a correct FDR control after rescoring, MS²Rescore filters out lower-ranking PSMs before final FDR calculation"