[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CVF478NGGY36S16PQJQBH1":3,"skill-same:01M7CVF478NGGY36S16PQJQBH1":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M7CVF478NGGY36S16PQJQBH1","bio-proteomics-peptide-identification",null,"Peptide-spectrum matching from MS\u002FMS with target-decoy FDR control, framing identification confidence as a property of a ranked list (q-value\u002FPEP) rather than a raw engine score (XCorr, hyperscore, Andromeda, SpecEValue). Covers sequence-database search engines (Comet, MS-GF+, MSFragger, Sage, MaxQuant, MetaMorpheus), concatenated vs separate target-decoy competition, PEP vs q-value, the multi-level FDR cascade, open\u002Fmass-tolerant search, rescoring (Percolator, mokapot, MS2Rescore), and pyOpenMS SimpleSearchEngineAlgorithm + FalseDiscoveryRate. Use when identifying peptides from tandem mass spectra and deciding what FDR threshold to act on. Protein grouping and protein-level FDR are protein-inference; PTM site localization is ptm-analysis; DIA peptide-centric scoring is dia-analysis; intensity quant is quantification.","mrsonord2240\u002Fopenscience-specialists","mrsonord2240","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76487430?v=4","01M7CTEM40S43GSJZ9A3YCCXZK","Samuel Nord","01M7CTEM4K69JD1GBYNHVJ9ZP4",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-proteomics-peptide-identification\ndescription: Peptide-spectrum matching from MS\u002FMS with target-decoy FDR control, framing identification confidence as a property of a ranked list (q-value\u002FPEP) rather than a raw engine score (XCorr, hyperscore, Andromeda, SpecEValue). Covers sequence-database search engines (Comet, MS-GF+, MSFragger, Sage, MaxQuant, MetaMorpheus), concatenated vs separate target-decoy competition, PEP vs q-value, the multi-level FDR cascade, open\u002Fmass-tolerant search, rescoring (Percolator, mokapot, MS2Rescore), and pyOpenMS SimpleSearchEngineAlgorithm + FalseDiscoveryRate. Use when identifying peptides from tandem mass spectra and deciding what FDR threshold to act on. Protein grouping and protein-level FDR are protein-inference; PTM site localization is ptm-analysis; DIA peptide-centric scoring is dia-analysis; intensity quant is quantification.\ntool_type: mixed\nprimary_tool: pyOpenMS\n---\n\n## Version Compatibility\n\nReference examples tested with: pyOpenMS 3.5.0, pandas 2.2+, numpy 1.26+ (pyOpenMS 3.5 takes a `PeptideIdentificationList`, not a plain Python list, for peptide IDs). Command-line route checked on Sage 0.14.6, Comet 2026.02 rev.2, MS-GF+ v2024.03.26, Percolator 3.09.0, OpenMS 3.5.0 `DecoyDatabase`, Java 17.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n- R: `packageVersion('\u003Cpkg>')` then `?function_name` to verify parameters\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed\npackage and adapt the example to match the actual API rather than retrying.\n\n# Peptide Identification -- Confidence Is a Property of a Ranked List, Not a Single PSM\n\n**\"Identify peptides from my MS\u002FMS spectra\"** -> Match tandem mass spectra against a protein database, then control false discovery rate by target-decoy competition and act on a q-value -- because a raw match score is meaningless in isolation; only the list-level error rate is interpretable.\n- Python: `pyopenms.SimpleSearchEngineAlgorithm().search(...)` for in-process database search, `FalseDiscoveryRate` for q-values\n- CLI: `comet`, `msfragger`, `sage`, `MSGFPlus` for high-throughput database searching, `percolator`\u002F`mokapot` for rescoring\n- R: `mzID::mzID()` + `flatten()` or `mzR::openIDfile()` + `psms()` to read mzIdentML search results\n\nScope: this skill owns spectrum-to-peptide matching and PSM\u002Fpeptide-level FDR. Protein grouping and protein-level (picked) FDR -> protein-inference. PTM site localization and open-search mod discovery follow-up -> ptm-analysis. DIA peptide-centric extraction and scoring -> dia-analysis. FDR-filtered IDs feeding intensities -> quantification. mzML\u002Fraw loading -> data-import. OUT OF SCOPE: protein inference, PTM localization scoring, DIA peptide-centric pipelines, label-free\u002FTMT quantification.\n\n## The Single Most Important Modern Insight -- A q-value Is a Verdict on the List, a Raw Score Is Not Even Comparable\n\n1. **Identification confidence is a property of a ranked LIST controlled by target-decoy competition, never a property of one PSM.** The number to act on is a q-value (list-level) or PEP (per-PSM), NOT the engine's raw score. XCorr (Comet), hyperscore (MSFragger\u002FX!Tandem), Andromeda score (MaxQuant), and SpecEValue (MS-GF+) live on different scales, are charge- and length-dependent, and are frequently not even monotone in true probability within a single engine -- which is exactly why rescoring (Percolator\u002Fmokapot) exists. \"1% FDR\" answers \"what fraction of the list I keep is wrong,\" NOT \"I am 99% sure of this one ID.\" The catastrophic error is thresholding on a raw score, or comparing scores across engines.\n\n2. **A q-value is valid only if (a) the decoy DB is a faithful null, (b) targets and decoys competed in ONE concatenated search, and (c) there are enough PSMs for the decoy count to be stable.** Generate decoys at the PROTEIN level then digest (so decoy peptides obey the same enzyme rules), matching the target in size and composition. Concatenated competition (one best hit per spectrum) gives FDR = (#decoys above threshold + 1) \u002F (#targets above threshold) -- one decoy above threshold estimates one false target, and the +1 keeps small lists honest. Elias & Gygi's 2 * #decoy \u002F (#target + #decoy) is the older, conservative form of the same concatenated-search estimate, counted over the whole target+decoy list. Separate target\u002Fdecoy searches (no per-spectrum competition) instead need pi0 * #decoy \u002F #target (Kall, Storey, MacCoss & Noble 2008) or the refined mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). Applying 2d\u002F(t+d) to separate searches over-estimates FDR and throws away identifications (synthetic test: 2.06% estimated vs 0.62% true).\n\n3. **PEP and q-value answer different questions; filtering at \"PEP \u003C= 0.01\" is far stricter than \"q \u003C= 0.01.\"** PEP (posterior error probability, local FDR) is the probability that THIS PSM is wrong; q-value is the FDR of the list cut at this PSM. FDR is the average of PEP over the accepted set (Kall 2008). The worst PSM in a 1%-FDR list typically has a PEP of 10-50%. Use q-value for list cutoffs; use PEP only for per-ID decisions (e.g. picking one PTM site). And PSM-FDR at 1% does NOT give 1% peptide-FDR or 1% protein-FDR -- each level needs its own estimation; hand protein-level control to protein-inference.\n\n## The FDR Vocabulary, Precisely\n\n- **FDR**: the expected proportion of false positives among ALL accepted items at a threshold -- a property of the whole list.\n- **q-value**: the minimum FDR at which a given PSM is still accepted; monotone after taking the running minimum from the bottom of the ranked list. Filter on q \u003C= 0.01.\n- **PEP (local FDR)**: the probability that THIS PSM is wrong given its score. Local, per-PSM; FDR is the integral of PEP over the accepted set (Kall 2008, \"two sides of the same coin\").\n- **The estimator must match the search mode.** Concatenated target-decoy competition (TDC): FDR = (#decoy + 1) \u002F #target (one best hit per spectrum already resolves the competition; Elias-Gygi's 2 * #decoy \u002F (#target + #decoy) is the older, conservative whole-list form for this same composite search). Separate target and decoy searches: pi0 * #decoy \u002F #target (Kall et al. 2008; pi0 = 1 is valid but conservative), or the refined mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). Mix-max is a distinct, calibrated-score procedure for the separate-search setting.\n\n## Tool Taxonomy\n\n| Tool \u002F method | Citation | Mechanism \u002F role | When |\n|---|---|---|---|\n| Comet | Eng 2013 | XCorr + E-value; SEQUEST lineage, open-source | Robust default, TPP pipelines; pairs with Percolator |\n| X!Tandem | -- | hyperscore + refinement passes | Legacy\u002Ffree; semi-tryptic refinement niche |\n| MS-GF+ | Kim & Pevzner 2014 | SpecEValue via generating-function DP | Calibrated cross-instrument E-value; ETD\u002FCID, low-res, non-standard enzymes |\n| MaxQuant \u002F Andromeda | Cox 2011 | binomial probability score; integrated MBR\u002FLFQ\u002FTMT | All-in-one quant pipeline (LFQ, TMT, SILAC); GUI |\n| MSFragger | Kong 2017 | hyperscore via fragment-ion indexing (~100x faster) | Open\u002Fmass-tolerant search, PTM discovery, huge datasets; core of FragPipe |\n| Sage | Lazear 2023 | hyperscore-style, Rust, rescoring-native | Modern scalable open-source pipelines; emits Percolator-ready features |\n| MetaMorpheus | Solntsev 2018 | calibration + G-PTM-D multinotch | PTM discovery with built-in calibration; proteoform-aware |\n| pFind 3 | Chi 2018 | open-search engine | Maximal unrestricted-PTM\u002Fmutation discovery |\n| Percolator | Kall 2007 | semi-supervised SVM re-rank on decoy negatives | Boost IDs at fixed FDR; non-tryptic\u002FPTM\u002Flarge search spaces |\n| mokapot | Fondrie & Noble 2021 | Percolator in Python; swappable XGBoost classifier | Python pipelines, Sage output, custom features |\n| MS2Rescore + DeepLC + MS2PIP | Declercq 2022; Bouwmeester 2021; Gabriels 2019 | predicted-RT + predicted-intensity rescoring features | Sharpen target\u002Fdecoy separation; immunopeptidomics |\n| Spectral-library search | -- | match empirical reference spectra (intensity + RT) | Faster\u002Fmore specific for known peptides -> spectral-libraries |\n| Protein grouping \u002F protein FDR | Savitski 2015; The 2022 | picked \u002F picked-group FDR | route OUT -> protein-inference |\n| PTM site localization | -- | per-site PEP, localization scoring | route OUT -> ptm-analysis |\n\n## Decision Tree by Scenario\n\n| Scenario | Recommended | Why |\n|---|---|---|\n| Standard DDA, clean FDR, scriptable | Comet or Sage + Percolator\u002Fmokapot at q \u003C= 0.01 | well-validated; rescoring boosts IDs at fixed FDR |\n| Cross-instrument \u002F varied fragmentation \u002F odd enzyme | MS-GF+ | SpecEValue is calibrated so a threshold means the same everywhere |\n| Discover unknown PTMs \u002F mass shifts | MSFragger open search (-150..+500 Da) | fragment indexing makes wide-window search feasible; then closed search on discovered mods -> ptm-analysis |\n| Huge dataset, reproducible, cloud-scale | Sage (rescoring-native) | Rust speed; emits Percolator features directly |\n| All-in-one with quant in the same tool | MaxQuant\u002FAndromeda | integrated LFQ\u002FTMT\u002FSILAC and MBR |\n| Non-tryptic (immunopeptidomics, degradomics) | any engine + Percolator\u002FMS2Rescore | rescoring gains are largest where search space explodes |\n| Few PSMs (single-protein pulldown) | do NOT trust decoy FDR; inspect spectra manually | decoy counts too noisy below ~hundreds of PSMs |\n| Need per-site \u002F per-ID confidence | act on PEP, not q-value | q-value is list-level; PEP is local |\n\nDefault when uncertain: concatenated target-decoy search with Comet or Sage, rescore with Percolator\u002Fmokapot, filter at q \u003C= 0.01, and hand protein-level FDR to protein-inference.\n\n### Build the Concatenated Target-Decoy Database\n\n**Goal:** Turn a target-only FASTA into the concatenated target+decoy database that every FDR number below depends on.\n\n**Approach:** Reverse at the PROTEIN level with the peptide N\u002FC termini held fixed, so decoy peptides obey the same enzyme rules and match the targets in length and amino-acid composition, at 1:1. Sage generates decoys internally and takes the TARGET-ONLY FASTA (so do MSFragger and MetaMorpheus, per their documentation); Comet, MS-GF+ and X!Tandem need this file. Include contaminants in the input before reversing, so contaminant decoys exist too. **The decoy tag is where this Skill silently fails:** every tool defaults to a different string, and a mismatch means zero decoys are found and every PSM is reported \"at 1% FDR\" with no error.\n\n```bash\n# OpenMS 3.5.0; -method shuffle is the alternative when reversal makes\n# decoy peptides that are palindromes of real ones\nDecoyDatabase -in human_plus_contaminants.fasta -out human_target_decoy.fasta \\\n  -decoy_string DECOY_ -decoy_string_position prefix \\\n  -method reverse -enzyme Trypsin -threads 8\n\ngrep -c '^>' human_target_decoy.fasta        # must be 2x the target count\ngrep -c '^>DECOY_' human_target_decoy.fasta  # must equal the target count\n```\n\n| Tool | Default decoy tag | Set it with |\n|---|---|---|\n| OpenMS `DecoyDatabase` \u002F `PeptideIndexing` | `DECOY_` | `-decoy_string`, `decoy_string` |\n| Sage | `rev_` (lower case) | `decoy_tag` in the JSON, with `generate_decoys: true` |\n| Comet | `DECOY_` | `decoy_prefix`; `decoy_search = 0` when the DB already holds them |\n| MS-GF+ | `XXX_` | `-decoy`; `-tda 0` when the DB already holds them |\n| MSFragger \u002F FragPipe \u002F Philosopher | `rev_` (lower case) | `decoy_prefix`, `--decoy` |\n| MaxQuant | `REV__` | fixed |\n| Percolator | reads the pin `Label` column | `-P` only for `--picked-protein` |\n\nChecked on OpenMS 3.5.0: 31,437 UniProt entries (human + yeast + E. coli + contaminants) became 62,874 with 31,437 `DECOY_` entries in 5 s.\n\n### Run a DDA Search from the Command Line\n\n**Goal:** Search a centroided mzML against the database and emit PSMs plus Percolator features.\n\n**Approach:** All three engines below run one concatenated search and write a Percolator `.pin`, so the rescoring step is the same for each. Convert vendor raw first (`msconvert --mzML --zlib --filter \"peakPicking vendor msLevel=1-\"` -> data-import). Set tolerances to the instrument, not to the default: 10 ppm precursor and high-res fragment settings for an Orbitrap, 0.6 Da \u002F ion-trap binning for CID. `examples\u002Fdda_search.sh` runs the whole route (database -> search -> Percolator -> 1% list) for `ENGINE=sage` or `ENGINE=comet`.\n\n```bash\n# Sage 0.14.6 -- generates its own 'rev_' decoys, so it takes the TARGET-ONLY FASTA.\n# search.json: {\"database\": {\"enzyme\": {\"missed_cleavages\": 2, \"min_len\": 7, \"max_len\": 30,\n#   \"cleave_at\": \"KR\", \"restrict\": \"P\"}, \"static_mods\": {\"C\": 57.0215},\n#   \"variable_mods\": {\"M\": [15.9949]}, \"max_variable_mods\": 2,\n#   \"decoy_tag\": \"rev_\", \"generate_decoys\": true, \"fasta\": \"human.fasta\"},\n#  \"precursor_tol\": {\"ppm\": [-10, 10]}, \"fragment_tol\": {\"ppm\": [-20, 20]},\n#  \"isotope_errors\": [0, 1], \"deisotope\": true, \"predict_rt\": true, \"report_psms\": 1}\nsage search.json sample.mzML --write-pin     # -> results.sage.tsv + results.sage.pin\n\n# Comet 2026.02 -- searches the concatenated DB built above.\ncomet -p                                     # writes comet.params.new to edit\n#   database_name = human_target_decoy.fasta   decoy_search = 0   decoy_prefix = DECOY_\n#   peptide_mass_tolerance_upper = 10.0   peptide_mass_tolerance_lower = -10.0\n#   peptide_mass_units = 2                 # 2 = ppm\n#   fragment_bin_tol = 0.02  fragment_bin_offset = 0.0   # high-res HCD; 1.0005\u002F0.4 for ion trap\n#   search_enzyme_number = 1  allowed_missed_cleavage = 2  peptide_length_range = 7 30\n#   variable_mod01 = 15.9949 M 0 2 -1 0 0 0.0   max_variable_mods_in_peptide = 2\n#   output_percolatorfile = 1  output_txtfile = 1  num_output_lines = 1\ncomet -Pcomet.params -Nsample sample.mzML    # -> sample.pin, sample.txt, sample.pep.xml\n\n# MS-GF+ v2024.03.26 -- calibrated SpecEValue; -tda 0 because the DB already has decoys.\njava -Xmx8g -jar MSGFPlus.jar -s sample.mzML -d human_target_decoy.fasta \\\n  -decoy DECOY_ -o sample.mzid -t 10ppm -ti 0,1 -tda 0 \\\n  -m 3 -inst 3 -e 1 -ntt 2 -mod mods.txt \\\n  -minLength 7 -maxLength 30 -maxMissedCleavages 2 -n 1 -addFeatures 1 -thread 8\n# mods.txt: \"NumMods=2\" \u002F \"C2H3N1O1,C,fix,any,Carbamidomethyl\" \u002F \"O1,M,opt,any,Oxidation\"\njava -cp MSGFPlus.jar edu.ucsd.msjava.ui.MzIDToTsv -i sample.mzid -o sample.tsv -showDecoy 1\n```\n\n### Rescore to FDR-Controlled PSMs with Percolator\n\n**Goal:** Turn engine features into a single learned score and a q-value, and read off the 1% list.\n\n**Approach:** Percolator trains a semi-supervised SVM on the decoy PSMs with three-fold cross-validation, so it must be told which post-processing matches the search. `-Y`\u002F`--post-processing-tdc` is target-decoy competition, correct for a concatenated search with one hit per spectrum; `-y`\u002F`--post-processing-mix-max` is the mix-max method and **only has an effect on separate target and decoy searches**, where it is the default (flag text from `percolator --help`, 3.09.0). `--results-psms` holds targets only, so no decoy filtering afterwards -- but read the `q-value` column BY NAME, because Percolator emits a `filename` column only when the pin carries one (Sage does, Comet does not), which shifts every later column by one.\n\n```bash\npercolator --post-processing-tdc \\\n  --results-psms psms.target.tsv       --decoy-results-psms psms.decoy.tsv \\\n  --results-peptides peptides.target.tsv --decoy-results-peptides peptides.decoy.tsv \\\n  results.sage.pin\n\n# 1% list, with the q-value column located by name rather than by index\nawk -F'\\t' 'NR == 1 { for (i = 1; i \u003C= NF; i++) if ($i == \"q-value\") q = i; next }\n            q && $q \u003C= 0.01' psms.target.tsv > psms_1pct.tsv\n```\n\nRescoring pays where the engine's own score is weakest. On one Orbitrap Astral 5-min DDA run (250 pg HYE load, 6,135 MS2 spectra, 31,437-protein database, PXD070049), Comet's raw `-log10(e-value)` gave **916** PSMs at 1% FDR and Percolator lifted the same search to **1,144** (+25%); Sage's `sage_discriminant_score` is already a learned score, so Percolator moved it from **1,406** to **1,398** (-0.6%) -- no gain to be had. Sage 0.14.6 wins this input outright; Comet 2026.02 with Percolator lands 19% behind it, and MS-GF+ v2024.03.26 read straight off `-log10(SpecEValue)` with no rescoring gives **656**, because a calibrated E-value buys cross-instrument comparability, not raw yield. **Do not generalise these counts**: one run, one low-load short-gradient method, each engine at its own idiomatic high-res settings. Rescoring also needs training data -- pooling the three DDA runs (6,864 PSMs) gave Percolator 5,006 PSMs against Sage's own 4,961, while on a single run of 1,939 PSMs it had too few positives to improve anything.\n\n### Database Search with pyOpenMS\n\n**Goal:** Match tandem mass spectra in an mzML file against a protein FASTA and produce scored PSMs as idXML.\n\n**Approach:** `SimpleSearchEngineAlgorithm` actually scores spectra (the hand-rolled `ProteaseDigestion` loop only digests, it never matches a spectrum). The FASTA must already contain target + decoy sequences concatenated for downstream FDR; decoys carry a recognizable prefix (or set `decoys` to `'true'` to let the engine generate them). Defaults are 10 ppm fragment tolerance and 1 missed cleavage, so set parameters explicitly. The search already annotates `target_decoy` on each hit.\n\n```python\nfrom pyopenms import SimpleSearchEngineAlgorithm, IdXMLFile, PeptideIdentificationList\n\nprotein_ids = []\npeptide_ids = PeptideIdentificationList()   # pyOpenMS 3.5+: a plain [] raises TypeError\nsearch = SimpleSearchEngineAlgorithm()\np = search.getParameters()\np.setValue('precursor:mass_tolerance', 10.0)\np.setValue('precursor:mass_tolerance_unit', 'ppm')\np.setValue('fragment:mass_tolerance', 0.02)         # HCD Orbitrap; default is 10 ppm\np.setValue('fragment:mass_tolerance_unit', 'Da')\np.setValue('peptide:missed_cleavages', 2)           # default is 1\np.setValue('modifications:fixed', [b'Carbamidomethyl (C)'])\np.setValue('modifications:variable', [b'Oxidation (M)'])\nsearch.setParameters(p)\n# spectra are scored against in-silico fragment ions of every candidate peptide\nsearch.search('sample.mzML', 'human_target_decoy.fasta', protein_ids, peptide_ids)\n\n# protein_ids FIRST in load\u002Fstore -- the OpenMS argument order is fixed\nIdXMLFile().store('search_results.idXML', protein_ids, peptide_ids)\n```\n\n### Annotate Target\u002FDecoy and Estimate FDR with pyOpenMS\n\n**Goal:** Convert raw PSM scores into q-values and keep only PSMs at 1% FDR.\n\n**Approach:** `PeptideIndexing` maps each PSM back to proteins and flags target vs decoy from the decoy prefix -- needed for idXML from other engines or after changing the FASTA; `SimpleSearchEngineAlgorithm` output above is already annotated and can go straight to `FalseDiscoveryRate`. `FalseDiscoveryRate.apply` runs the concatenated competition; `IDFilter` keeps q \u003C= 0.01. This is the real pyOpenMS path -- not a hand-rolled decoy\u002Ftarget ratio of unknown provenance.\n\n```python\nfrom pyopenms import PeptideIndexing, FalseDiscoveryRate, IDFilter, FASTAFile\n\nfasta = []\nFASTAFile().load('human_target_decoy.fasta', fasta)\nindexer = PeptideIndexing()\nparams = indexer.getParameters()\nparams.setValue('decoy_string', 'DECOY_')      # must match the decoy prefix in the FASTA\nparams.setValue('decoy_string_position', 'prefix')\nindexer.setParameters(params)\nindexer.run(fasta, protein_ids, peptide_ids)   # sets target\u002Fdecoy flags on every hit\n\nFalseDiscoveryRate().apply(peptide_ids)         # concatenated competition -> per-PSM q-value as the new score\nIDFilter().filterHitsByScore(peptide_ids, 0.01) # 0.01 = 1% FDR, the community list-level standard\nIDFilter().removeDecoyHits(peptide_ids)\n```\n\n### FDR from a Results Table (concatenated competition, made explicit)\n\n**Goal:** Compute q-values from any engine's PSM table when the search was a single concatenated target-decoy search.\n\n**Approach:** Keep the best hit per spectrum, rank by score, walk down accumulating target and decoy counts, FDR = (decoys + 1)\u002Ftargets, then take the running minimum from the bottom to get monotone q-values. `score` must be higher-is-better, and the decoy prefix must match the engine's (Sage and FragPipe write lowercase `rev_`); a table with no recognised decoys must stop, not pass every PSM. This form is correct ONLY for concatenated competition; separate searches need pi0 * decoys\u002Ftargets (Kall et al. 2008; pi0 = 1 is the conservative default) or the mix-max estimator (Keich, Kertesz-Farkas & Noble 2015; Percolator's default for separate-search input).\n\n```python\nimport pandas as pd\n\nDECOY_PREFIXES = ('decoy_', 'rev_', 'xxx_')   # compared lower-cased: DECOY_, REV_ \u002F REV__ (MaxQuant), rev_ (Sage, FragPipe), XXX_\n\npsms = pd.read_csv('search_results.tsv', sep='\\t')   # map engine columns to 'scan', 'score', 'protein'\n# score must be HIGHER-is-better: Sage sage_discriminant_score or Comet xcorr as is;\n# E-values (Comet e-value, MS-GF+ SpecEValue) as -log10(E-value)\npsms['is_decoy'] = psms['protein'].str.lower().str.startswith(DECOY_PREFIXES)\nif not psms['is_decoy'].any():\n    raise ValueError('no decoy PSMs recognised: check the decoy prefix, or the table was already decoy-filtered')\n# one best hit per spectrum (Comet .txt writes 5 rows per scan by default)\npsms = psms.sort_values('score', ascending=False).drop_duplicates('scan').reset_index(drop=True)\n\n# concatenated target-decoy competition: each decoy above threshold estimates one false target\ntargets = (~psms['is_decoy']).cumsum()\ndecoys = psms['is_decoy'].cumsum()\npsms['fdr'] = (decoys + 1) \u002F targets.clip(lower=1)   # +1: zero decoys is not zero FDR (OpenMS conservative default)\npsms['qvalue'] = psms['fdr'][::-1].cummin()[::-1]   # running min from the bottom -> monotone q-values\n\nkept = psms[(psms['qvalue'] \u003C= 0.01) & (~psms['is_decoy'])]   # 1% list-level FDR\n```\n\n### FDR from SEPARATE Target and Decoy Searches (pi0 * D \u002F T)\n\n**Goal:** Get a valid 1% list out of two result tables produced by searching the same spectra against a target DB and a decoy DB independently.\n\n**Approach:** No competition resolved which hit wins, so the decoy count estimates the number of incorrect TARGETS directly, scaled by pi0, the proportion of target PSMs that are incorrect (Kall et al. 2008). pi0 = 1 is always valid and conservative; the median-decoy estimate (twice the fraction of target scores below the median decoy score) recovers the identifications that pi0 = 1 throws away, at the cost of estimating a nuisance parameter. Do NOT run the concatenated snippet above on the two tables merged. `examples\u002Fseparate_search_fdr.py` ships this as a script.\n\n```python\nimport numpy as np\n\ndef estimate_pi0(target_scores, decoy_scores):        # Kall et al. 2008\n    median_decoy = np.median(decoy_scores)\n    return min(1.0, 2.0 * np.mean(np.asarray(target_scores) \u003C median_decoy))\n\ndef separate_search_qvalues(targets, decoys, pi0=None):\n    # targets, decoys: DataFrames with 'scan' and 'score', ONE row per spectrum each\n    if pi0 is None:\n        pi0 = estimate_pi0(targets['score'].to_numpy(), decoys['score'].to_numpy())\n    t = targets.sort_values('score', ascending=False).reset_index(drop=True)\n    decoy_sorted = np.sort(decoys['score'].to_numpy())\n    n_decoy_above = len(decoy_sorted) - np.searchsorted(decoy_sorted, t['score'].to_numpy(), side='left')\n    t['fdr'] = np.minimum(1.0, pi0 * n_decoy_above \u002F np.arange(1, len(t) + 1))\n    t['qvalue'] = t['fdr'][::-1].cummin()[::-1]\n    return t, pi0\n```\n\nOn the synthetic separate-search pair with ground truth (12,000 spectra each): pi0-hat = 0.611 keeps 2,888 PSMs at a true FDP of 1.04%, pi0 = 1 keeps 2,588 at 0.62%, and Elias-Gygi's 2d\u002F(t+d) misapplied here keeps only 2,139 at 0.33%. The alternative is to hand both tables to Percolator and let mix-max do it: that is Percolator's default for separate-search input, and it is a calibrated-score procedure, not the same arithmetic.\n\n## Per-Method Failure Modes\n\n### Concatenated vs separate FDR formula mismatch\n**Trigger:** running the concatenated snippet on a merged table from separate searches without per-spectrum competition, or applying Elias-Gygi's 2*decoy\u002F(target+decoy) to separate searches.\n**Mechanism:** Elias-Gygi's factor 2 counts decoys in the combined target+decoy list of a concatenated search; in separate searches every spectrum gets both a target and a decoy hit, so the decoy count estimates false targets directly, scaled by pi0 (the fraction of target PSMs that are incorrect).\n**Symptom:** mis-estimated FDR; 2d\u002F(t+d) on separate searches over-estimates it (synthetic test: 2.06% vs 0.62% true, about a quarter of IDs lost).\n**Fix:** confirm the search mode; concatenated -> (#decoy + 1)\u002F#target; separate -> pi0 * #decoy\u002F#target (Kall et al. 2008; code in \"FDR from SEPARATE Target and Decoy Searches\" above and in `examples\u002Fseparate_search_fdr.py`) or the mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). In Percolator, mix-max is the default for separate-search input and `-Y`\u002F`--post-processing-tdc` selects target-decoy competition instead; concatenated input forces TDC automatically.\n\n### Thresholding on raw engine score\n**Trigger:** filtering on XCorr\u002Fhyperscore\u002FAndromeda score, or comparing scores from two engines.\n**Mechanism:** scores are uncalibrated, charge\u002Flength-dependent, and not monotone in true probability.\n**Symptom:** different cutoffs admit different real FDRs; cross-engine merges nonsensical.\n**Fix:** always convert to q-value (or SpecEValue\u002FPEP) first; rescore with Percolator\u002Fmokapot.\n\n### Decoy FDR on too few PSMs\n**Trigger:** reporting \"0% FDR\" from a single-protein pulldown or tiny PSM list.\n**Mechanism:** the decoy count is a noisy Poisson-like estimate; zero observed decoys does not mean zero false targets.\n**Symptom:** spuriously confident IDs from small experiments.\n**Fix:** below ~hundreds of PSMs, inspect spectra manually; do not act on the decoy q-value.\n\n### Open-search results used for clean FDR or quant\n**Trigger:** taking IDs from a wide-window (-150..+500 Da) search as final, FDR-controlled results.\n**Mechanism:** wide windows admit \"free\" mass shifts that inflate random matches; the target-decoy null differs per mass-shift bin.\n**Symptom:** inflated, unreliable FDR on open-search output.\n**Fix:** treat open search as discovery; follow with a closed search restricted to the discovered mods -> ptm-analysis.\n\n### Rescoring overfitting\n**Trigger:** custom features that leak label information, or training without proper cross-validation.\n**Mechanism:** the model learns the decoys, making rescored FDR optimistic.\n**Symptom:** ID counts jump but downstream validation fails.\n**Fix:** use Percolator\u002Fmokapot default cross-validation; predicted-feature rescoring (DeepLC\u002FMS2PIP) is safer; validate with entrapment for high-stakes claims (Wen 2025).\n\n### DIA tool FDR taken at face value\n**Trigger:** trusting a DIA tool's reported 1% peptide\u002Fprotein FDR.\n**Mechanism:** entrapment shows several DIA tools do not reliably control FDR (Wen 2025).\n**Symptom:** real error rate exceeds the reported FDR.\n**Fix:** validate with entrapment for high-stakes DIA claims -> dia-analysis.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|---|---|---|\n| Precursor tolerance 10-20 ppm (high-res Orbitrap) | -- | matches FT mass accuracy; tighter = fewer random candidates at fixed FDR |\n| Precursor tolerance -150..+500 Da (open search) | Kong 2017 | captures arbitrary PTM\u002Fmutation shifts; feasible only with fragment indexing |\n| Fragment tolerance 0.02 Da (HCD Orbitrap) \u002F 0.6 Da (ion-trap CID) | -- | instrument-dependent; 0.6 Da on Orbitrap discards resolving power |\n| Missed cleavages 2 | -- | covers incomplete trypsin digestion without exploding search space |\n| PSM\u002Fpeptide FDR 1% (q \u003C= 0.01) | Elias & Gygi 2007 | community standard; list-level error, not per-PSM |\n| Decoy:target ratio 1:1 | Elias & Gygi 2007 | standard; unequal ratios need formula correction |\n| Min PSMs for trustworthy decoy FDR: hundreds+ | -- | below this the decoy count is too noisy |\n| Variable mods per peptide \u003C= 2-3 | -- | each variable mod multiplies search space and random-match rate |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| pyOpenMS \"search\" returns peptides but never scores spectra | used `ProteaseDigestion`, which only digests a FASTA | use `SimpleSearchEngineAlgorithm().search(mzML, fasta, protein_ids, peptide_ids)` |\n| `TypeError: Argument 'pep_ids' has incorrect type (expected ...PeptideIdentificationList, got list)` or `can not handle type` | pyOpenMS 3.5+ needs a `PeptideIdentificationList` | `peptide_ids = PeptideIdentificationList()`; protein_ids FIRST: `IdXMLFile().load(path, protein_ids, peptide_ids)` |\n| `RuntimeError: Meta value 'target_decoy' does not exist` from `FalseDiscoveryRate` | decoys not annotated (e.g. idXML from another engine) | run `PeptideIndexing` with matching `decoy_string` first |\n| Every PSM passes 1% FDR, or `ValueError: no decoy PSMs recognised` | decoy prefix not matched (Sage and FragPipe write lowercase `rev_`) | compare prefixes lower-cased; check `psms['protein'].str[:6].value_counts()` |\n| Empty 1% list from a table snippet | lower-is-better score (E-value, SpecEValue) used as `score` | use `-log10(E-value)` |\n| All q-values 0 from a hand-rolled table | no +1 correction on a list with zero decoys | use (decoys + 1)\u002Ftargets; a tiny list cannot reach 1% |\n| Percolator q-method mismatched to search mode | mix-max is the default for separate-search input | for separate searches, mix-max (default) or `-Y`\u002F`--post-processing-tdc` for target-decoy competition; concatenated input forces TDC automatically; use `--picked-protein` for protein FDR |\n| Percolator's 1% list is far too big or too small when cut by column index | Percolator writes a `filename` column only when the pin has one (Sage yes, Comet no), shifting `q-value` between columns 3 and 4 | locate `q-value` by header name, never by a fixed index |\n| Decoy count is twice the target count after a search | `-tda 1` (MS-GF+) or `generate_decoys: true` (Sage) run against a database that already contains decoys | use `-tda 0` \u002F `generate_decoys: false` with a concatenated DB, or feed the target-only FASTA and let the engine make them |\n| `philosopher peptideprophet` exits 0 but the output has no `peptideprophet_result` and the log says `read in 0 1+, 0 2+ ... spectra` \u002F `read in no data` | its embedded PeptideProphet does not model this pepXML (seen with Comet 2026.02 rev.2 pepXML under Philosopher v5.1.0 on Windows, with and without `--nonparam --decoy`) | rescore with Percolator on the engine's `.pin` instead; check the interact file for `peptideprophet_result` before trusting a PeptideProphet run |\n| 1% PSM FDR assumed to give 1% protein FDR | each level needs its own estimation | estimate protein-level (picked) FDR -> protein-inference |\n| \"PEP \u003C= 0.01\" returns far fewer IDs than expected | PEP is per-PSM and far stricter than q-value | filter list cutoffs on q-value; reserve PEP for per-ID decisions |\n\n## References\n\n- Elias, J.E. & Gygi, S.P. 2007. Target-decoy search strategy for increased confidence in large-scale protein identifications by mass spectrometry. *Nature Methods* 4(3):207-214.\n- Keich, U., Kertesz-Farkas, A. & Noble, W.S. 2015. Improved false discovery rate estimation procedure for shotgun proteomics. *Journal of Proteome Research* 14(8):3148-3161.\n- Kall, L., Canterbury, J.D., Weston, J., Noble, W.S. & MacCoss, M.J. 2007. Semi-supervised learning for peptide identification from shotgun proteomics datasets. *Nature Methods* 4(11):923-925.\n- Kall, L., Storey, J.D., MacCoss, M.J. & Noble, W.S. 2008. Assigning significance to peptides identified by tandem mass spectrometry using decoy databases. *Journal of Proteome Research* 7(1):29-34.\n- Kall, L., Storey, J.D., MacCoss, M.J. & Noble, W.S. 2008. Posterior error probabilities and false discovery rates: two sides of the same coin. *Journal of Proteome Research* 7(1):40-44.\n- Eng, J.K., Jahan, T.A. & Hoopmann, M.R. 2013. Comet: an open-source MS\u002FMS sequence database search tool. *Proteomics* 13(1):22-24.\n- Kim, S. & Pevzner, P.A. 2014. MS-GF+ makes progress towards a universal database search tool for proteomics. *Nature Communications* 5:5277.\n- Cox, J., Neuhauser, N., Michalski, A., Scheltema, R.A., Olsen, J.V. & Mann, M. 2011. Andromeda: a peptide search engine integrated into the MaxQuant environment. *Journal of Proteome Research* 10(4):1794-1805.\n- Kong, A.T., Leprevost, F.V., Avtonomov, D.M., Mellacheruvu, D. & Nesvizhskii, A.I. 2017. MSFragger: ultrafast and comprehensive peptide identification in mass spectrometry-based proteomics. *Nature Methods* 14(5):513-520.\n- Lazear, M.R. 2023. Sage: an open-source tool for fast proteomics searching and quantification at scale. *Journal of Proteome Research* 22(11):3652-3659.\n- Solntsev, S.K., Shortreed, M.R., Frey, B.L. & Smith, L.M. 2018. Enhanced global post-translational modification discovery with MetaMorpheus. *Journal of Proteome Research* 17(5):1844-1851.\n- Chi, H., Liu, C., Yang, H. et al. 2018. Comprehensive identification of peptides in tandem mass spectra using an efficient open search engine. *Nature Biotechnology* 36:1059-1061.\n- Fondrie, W.E. & Noble, W.S. 2021. mokapot: fast and flexible semisupervised learning for peptide detection. *Journal of Proteome Research* 20(4):1966-1971.\n- Bouwmeester, R., Gabriels, R., Hulstaert, N., Martens, L. & Degroeve, S. 2021. DeepLC can predict retention times for peptides that carry as-yet unseen modifications. *Nature Methods* 18:1363-1369.\n- Gabriels, R., Martens, L. & Degroeve, S. 2019. Updated MS2PIP web server delivers fast and accurate MS2 peak intensity prediction for multiple fragmentation methods, instruments and labeling techniques. *Nucleic Acids Research* 47(W1):W295-W299.\n- Declercq, A., Bouwmeester, R., Hirschler, A., Carapito, C., Degroeve, S., Martens, L. & Gabriels, R. 2022. MS2Rescore: data-driven rescoring dramatically boosts immunopeptide identification rates. *Molecular & Cellular Proteomics* 21(8):100266.\n- Savitski, M.M., Wilhelm, M., Hahne, H., Kuster, B. & Bantscheff, M. 2015. A scalable approach for protein false discovery rate estimation in large proteomic data sets. *Molecular & Cellular Proteomics* 14(9):2394-2404.\n- The, M., Samaras, P., Kuster, B. & Wilhelm, M. 2022. Reanalysis of ProteomicsDB using an accurate, sensitive, and scalable false discovery rate estimation approach for protein groups. *Molecular & Cellular Proteomics* 21(12):100437.\n- Wen, B., Freestone, J., Riffle, M., MacCoss, M.J., Noble, W.S. & Keich, U. 2025. Assessment of false discovery rate control in tandem mass spectrometry analysis using entrapment. *Nature Methods* 22:1454-1463.\n\n## Related Skills\n\n- protein-inference - Group peptides to protein groups and control protein-level (picked) FDR\n- ptm-analysis - Open\u002Fvariable-mod search follow-up and per-site PTM localization\n- dia-analysis - DIA peptide-centric extraction and scoring; entrapment FDR validation\n- quantification - FDR-filtered IDs feed label-free\u002FTMT intensity quantification\n- spectral-libraries - Empirical and predicted spectral-library search as an ID alternative\n- data-import - Load mzML\u002Fraw MS data before identification\n- database-access\u002Funiprot-access - Build the target FASTA (canonical vs isoform, contaminants)\n","## Version Compatibility\n\nReference examples tested with: pyOpenMS 3.5.0, pandas 2.2+, numpy 1.26+ (pyOpenMS 3.5 takes a `PeptideIdentificationList`, not a plain Python list, for peptide IDs). Command-line route checked on Sage 0.14.6, Comet 2026.02 rev.2, MS-GF+ v2024.03.26, Percolator 3.09.0, OpenMS 3.5.0 `DecoyDatabase`, Java 17.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n- R: `packageVersion('\u003Cpkg>')` then `?function_name` to verify parameters\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed\npackage and adapt the example to match the actual API rather than retrying.\n\n# Peptide Identification -- Confidence Is a Property of a Ranked List, Not a Single PSM\n\n**\"Identify peptides from my MS\u002FMS spectra\"** -> Match tandem mass spectra against a protein database, then control false discovery rate by target-decoy competition and act on a q-value -- because a raw match score is meaningless in isolation; only the list-level error rate is interpretable.\n- Python: `pyopenms.SimpleSearchEngineAlgorithm().search(...)` for in-process database search, `FalseDiscoveryRate` for q-values\n- CLI: `comet`, `msfragger`, `sage`, `MSGFPlus` for high-throughput database searching, `percolator`\u002F`mokapot` for rescoring\n- R: `mzID::mzID()` + `flatten()` or `mzR::openIDfile()` + `psms()` to read mzIdentML search results\n\nScope: this skill owns spectrum-to-peptide matching and PSM\u002Fpeptide-level FDR. Protein grouping and protein-level (picked) FDR -> protein-inference. PTM site localization and open-search mod discovery follow-up -> ptm-analysis. DIA peptide-centric extraction and scoring -> dia-analysis. FDR-filtered IDs feeding intensities -> quantification. mzML\u002Fraw loading -> data-import. OUT OF SCOPE: protein inference, PTM localization scoring, DIA peptide-centric pipelines, label-free\u002FTMT quantification.\n\n## The Single Most Important Modern Insight -- A q-value Is a Verdict on the List, a Raw Score Is Not Even Comparable\n\n1. **Identification confidence is a property of a ranked LIST controlled by target-decoy competition, never a property of one PSM.** The number to act on is a q-value (list-level) or PEP (per-PSM), NOT the engine's raw score. XCorr (Comet), hyperscore (MSFragger\u002FX!Tandem), Andromeda score (MaxQuant), and SpecEValue (MS-GF+) live on different scales, are charge- and length-dependent, and are frequently not even monotone in true probability within a single engine -- which is exactly why rescoring (Percolator\u002Fmokapot) exists. \"1% FDR\" answers \"what fraction of the list I keep is wrong,\" NOT \"I am 99% sure of this one ID.\" The catastrophic error is thresholding on a raw score, or comparing scores across engines.\n\n2. **A q-value is valid only if (a) the decoy DB is a faithful null, (b) targets and decoys competed in ONE concatenated search, and (c) there are enough PSMs for the decoy count to be stable.** Generate decoys at the PROTEIN level then digest (so decoy peptides obey the same enzyme rules), matching the target in size and composition. Concatenated competition (one best hit per spectrum) gives FDR = (#decoys above threshold + 1) \u002F (#targets above threshold) -- one decoy above threshold estimates one false target, and the +1 keeps small lists honest. Elias & Gygi's 2 * #decoy \u002F (#target + #decoy) is the older, conservative form of the same concatenated-search estimate, counted over the whole target+decoy list. Separate target\u002Fdecoy searches (no per-spectrum competition) instead need pi0 * #decoy \u002F #target (Kall, Storey, MacCoss & Noble 2008) or the refined mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). Applying 2d\u002F(t+d) to separate searches over-estimates FDR and throws away identifications (synthetic test: 2.06% estimated vs 0.62% true).\n\n3. **PEP and q-value answer different questions; filtering at \"PEP \u003C= 0.01\" is far stricter than \"q \u003C= 0.01.\"** PEP (posterior error probability, local FDR) is the probability that THIS PSM is wrong; q-value is the FDR of the list cut at this PSM. FDR is the average of PEP over the accepted set (Kall 2008). The worst PSM in a 1%-FDR list typically has a PEP of 10-50%. Use q-value for list cutoffs; use PEP only for per-ID decisions (e.g. picking one PTM site). And PSM-FDR at 1% does NOT give 1% peptide-FDR or 1% protein-FDR -- each level needs its own estimation; hand protein-level control to protein-inference.\n\n## The FDR Vocabulary, Precisely\n\n- **FDR**: the expected proportion of false positives among ALL accepted items at a threshold -- a property of the whole list.\n- **q-value**: the minimum FDR at which a given PSM is still accepted; monotone after taking the running minimum from the bottom of the ranked list. Filter on q \u003C= 0.01.\n- **PEP (local FDR)**: the probability that THIS PSM is wrong given its score. Local, per-PSM; FDR is the integral of PEP over the accepted set (Kall 2008, \"two sides of the same coin\").\n- **The estimator must match the search mode.** Concatenated target-decoy competition (TDC): FDR = (#decoy + 1) \u002F #target (one best hit per spectrum already resolves the competition; Elias-Gygi's 2 * #decoy \u002F (#target + #decoy) is the older, conservative whole-list form for this same composite search). Separate target and decoy searches: pi0 * #decoy \u002F #target (Kall et al. 2008; pi0 = 1 is valid but conservative), or the refined mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). Mix-max is a distinct, calibrated-score procedure for the separate-search setting.\n\n## Tool Taxonomy\n\n| Tool \u002F method | Citation | Mechanism \u002F role | When |\n|---|---|---|---|\n| Comet | Eng 2013 | XCorr + E-value; SEQUEST lineage, open-source | Robust default, TPP pipelines; pairs with Percolator |\n| X!Tandem | -- | hyperscore + refinement passes | Legacy\u002Ffree; semi-tryptic refinement niche |\n| MS-GF+ | Kim & Pevzner 2014 | SpecEValue via generating-function DP | Calibrated cross-instrument E-value; ETD\u002FCID, low-res, non-standard enzymes |\n| MaxQuant \u002F Andromeda | Cox 2011 | binomial probability score; integrated MBR\u002FLFQ\u002FTMT | All-in-one quant pipeline (LFQ, TMT, SILAC); GUI |\n| MSFragger | Kong 2017 | hyperscore via fragment-ion indexing (~100x faster) | Open\u002Fmass-tolerant search, PTM discovery, huge datasets; core of FragPipe |\n| Sage | Lazear 2023 | hyperscore-style, Rust, rescoring-native | Modern scalable open-source pipelines; emits Percolator-ready features |\n| MetaMorpheus | Solntsev 2018 | calibration + G-PTM-D multinotch | PTM discovery with built-in calibration; proteoform-aware |\n| pFind 3 | Chi 2018 | open-search engine | Maximal unrestricted-PTM\u002Fmutation discovery |\n| Percolator | Kall 2007 | semi-supervised SVM re-rank on decoy negatives | Boost IDs at fixed FDR; non-tryptic\u002FPTM\u002Flarge search spaces |\n| mokapot | Fondrie & Noble 2021 | Percolator in Python; swappable XGBoost classifier | Python pipelines, Sage output, custom features |\n| MS2Rescore + DeepLC + MS2PIP | Declercq 2022; Bouwmeester 2021; Gabriels 2019 | predicted-RT + predicted-intensity rescoring features | Sharpen target\u002Fdecoy separation; immunopeptidomics |\n| Spectral-library search | -- | match empirical reference spectra (intensity + RT) | Faster\u002Fmore specific for known peptides -> spectral-libraries |\n| Protein grouping \u002F protein FDR | Savitski 2015; The 2022 | picked \u002F picked-group FDR | route OUT -> protein-inference |\n| PTM site localization | -- | per-site PEP, localization scoring | route OUT -> ptm-analysis |\n\n## Decision Tree by Scenario\n\n| Scenario | Recommended | Why |\n|---|---|---|\n| Standard DDA, clean FDR, scriptable | Comet or Sage + Percolator\u002Fmokapot at q \u003C= 0.01 | well-validated; rescoring boosts IDs at fixed FDR |\n| Cross-instrument \u002F varied fragmentation \u002F odd enzyme | MS-GF+ | SpecEValue is calibrated so a threshold means the same everywhere |\n| Discover unknown PTMs \u002F mass shifts | MSFragger open search (-150..+500 Da) | fragment indexing makes wide-window search feasible; then closed search on discovered mods -> ptm-analysis |\n| Huge dataset, reproducible, cloud-scale | Sage (rescoring-native) | Rust speed; emits Percolator features directly |\n| All-in-one with quant in the same tool | MaxQuant\u002FAndromeda | integrated LFQ\u002FTMT\u002FSILAC and MBR |\n| Non-tryptic (immunopeptidomics, degradomics) | any engine + Percolator\u002FMS2Rescore | rescoring gains are largest where search space explodes |\n| Few PSMs (single-protein pulldown) | do NOT trust decoy FDR; inspect spectra manually | decoy counts too noisy below ~hundreds of PSMs |\n| Need per-site \u002F per-ID confidence | act on PEP, not q-value | q-value is list-level; PEP is local |\n\nDefault when uncertain: concatenated target-decoy search with Comet or Sage, rescore with Percolator\u002Fmokapot, filter at q \u003C= 0.01, and hand protein-level FDR to protein-inference.\n\n### Build the Concatenated Target-Decoy Database\n\n**Goal:** Turn a target-only FASTA into the concatenated target+decoy database that every FDR number below depends on.\n\n**Approach:** Reverse at the PROTEIN level with the peptide N\u002FC termini held fixed, so decoy peptides obey the same enzyme rules and match the targets in length and amino-acid composition, at 1:1. Sage generates decoys internally and takes the TARGET-ONLY FASTA (so do MSFragger and MetaMorpheus, per their documentation); Comet, MS-GF+ and X!Tandem need this file. Include contaminants in the input before reversing, so contaminant decoys exist too. **The decoy tag is where this Skill silently fails:** every tool defaults to a different string, and a mismatch means zero decoys are found and every PSM is reported \"at 1% FDR\" with no error.\n\n```bash\n# OpenMS 3.5.0; -method shuffle is the alternative when reversal makes\n# decoy peptides that are palindromes of real ones\nDecoyDatabase -in human_plus_contaminants.fasta -out human_target_decoy.fasta \\\n  -decoy_string DECOY_ -decoy_string_position prefix \\\n  -method reverse -enzyme Trypsin -threads 8\n\ngrep -c '^>' human_target_decoy.fasta        # must be 2x the target count\ngrep -c '^>DECOY_' human_target_decoy.fasta  # must equal the target count\n```\n\n| Tool | Default decoy tag | Set it with |\n|---|---|---|\n| OpenMS `DecoyDatabase` \u002F `PeptideIndexing` | `DECOY_` | `-decoy_string`, `decoy_string` |\n| Sage | `rev_` (lower case) | `decoy_tag` in the JSON, with `generate_decoys: true` |\n| Comet | `DECOY_` | `decoy_prefix`; `decoy_search = 0` when the DB already holds them |\n| MS-GF+ | `XXX_` | `-decoy`; `-tda 0` when the DB already holds them |\n| MSFragger \u002F FragPipe \u002F Philosopher | `rev_` (lower case) | `decoy_prefix`, `--decoy` |\n| MaxQuant | `REV__` | fixed |\n| Percolator | reads the pin `Label` column | `-P` only for `--picked-protein` |\n\nChecked on OpenMS 3.5.0: 31,437 UniProt entries (human + yeast + E. coli + contaminants) became 62,874 with 31,437 `DECOY_` entries in 5 s.\n\n### Run a DDA Search from the Command Line\n\n**Goal:** Search a centroided mzML against the database and emit PSMs plus Percolator features.\n\n**Approach:** All three engines below run one concatenated search and write a Percolator `.pin`, so the rescoring step is the same for each. Convert vendor raw first (`msconvert --mzML --zlib --filter \"peakPicking vendor msLevel=1-\"` -> data-import). Set tolerances to the instrument, not to the default: 10 ppm precursor and high-res fragment settings for an Orbitrap, 0.6 Da \u002F ion-trap binning for CID. `examples\u002Fdda_search.sh` runs the whole route (database -> search -> Percolator -> 1% list) for `ENGINE=sage` or `ENGINE=comet`.\n\n```bash\n# Sage 0.14.6 -- generates its own 'rev_' decoys, so it takes the TARGET-ONLY FASTA.\n# search.json: {\"database\": {\"enzyme\": {\"missed_cleavages\": 2, \"min_len\": 7, \"max_len\": 30,\n#   \"cleave_at\": \"KR\", \"restrict\": \"P\"}, \"static_mods\": {\"C\": 57.0215},\n#   \"variable_mods\": {\"M\": [15.9949]}, \"max_variable_mods\": 2,\n#   \"decoy_tag\": \"rev_\", \"generate_decoys\": true, \"fasta\": \"human.fasta\"},\n#  \"precursor_tol\": {\"ppm\": [-10, 10]}, \"fragment_tol\": {\"ppm\": [-20, 20]},\n#  \"isotope_errors\": [0, 1], \"deisotope\": true, \"predict_rt\": true, \"report_psms\": 1}\nsage search.json sample.mzML --write-pin     # -> results.sage.tsv + results.sage.pin\n\n# Comet 2026.02 -- searches the concatenated DB built above.\ncomet -p                                     # writes comet.params.new to edit\n#   database_name = human_target_decoy.fasta   decoy_search = 0   decoy_prefix = DECOY_\n#   peptide_mass_tolerance_upper = 10.0   peptide_mass_tolerance_lower = -10.0\n#   peptide_mass_units = 2                 # 2 = ppm\n#   fragment_bin_tol = 0.02  fragment_bin_offset = 0.0   # high-res HCD; 1.0005\u002F0.4 for ion trap\n#   search_enzyme_number = 1  allowed_missed_cleavage = 2  peptide_length_range = 7 30\n#   variable_mod01 = 15.9949 M 0 2 -1 0 0 0.0   max_variable_mods_in_peptide = 2\n#   output_percolatorfile = 1  output_txtfile = 1  num_output_lines = 1\ncomet -Pcomet.params -Nsample sample.mzML    # -> sample.pin, sample.txt, sample.pep.xml\n\n# MS-GF+ v2024.03.26 -- calibrated SpecEValue; -tda 0 because the DB already has decoys.\njava -Xmx8g -jar MSGFPlus.jar -s sample.mzML -d human_target_decoy.fasta \\\n  -decoy DECOY_ -o sample.mzid -t 10ppm -ti 0,1 -tda 0 \\\n  -m 3 -inst 3 -e 1 -ntt 2 -mod mods.txt \\\n  -minLength 7 -maxLength 30 -maxMissedCleavages 2 -n 1 -addFeatures 1 -thread 8\n# mods.txt: \"NumMods=2\" \u002F \"C2H3N1O1,C,fix,any,Carbamidomethyl\" \u002F \"O1,M,opt,any,Oxidation\"\njava -cp MSGFPlus.jar edu.ucsd.msjava.ui.MzIDToTsv -i sample.mzid -o sample.tsv -showDecoy 1\n```\n\n### Rescore to FDR-Controlled PSMs with Percolator\n\n**Goal:** Turn engine features into a single learned score and a q-value, and read off the 1% list.\n\n**Approach:** Percolator trains a semi-supervised SVM on the decoy PSMs with three-fold cross-validation, so it must be told which post-processing matches the search. `-Y`\u002F`--post-processing-tdc` is target-decoy competition, correct for a concatenated search with one hit per spectrum; `-y`\u002F`--post-processing-mix-max` is the mix-max method and **only has an effect on separate target and decoy searches**, where it is the default (flag text from `percolator --help`, 3.09.0). `--results-psms` holds targets only, so no decoy filtering afterwards -- but read the `q-value` column BY NAME, because Percolator emits a `filename` column only when the pin carries one (Sage does, Comet does not), which shifts every later column by one.\n\n```bash\npercolator --post-processing-tdc \\\n  --results-psms psms.target.tsv       --decoy-results-psms psms.decoy.tsv \\\n  --results-peptides peptides.target.tsv --decoy-results-peptides peptides.decoy.tsv \\\n  results.sage.pin\n\n# 1% list, with the q-value column located by name rather than by index\nawk -F'\\t' 'NR == 1 { for (i = 1; i \u003C= NF; i++) if ($i == \"q-value\") q = i; next }\n            q && $q \u003C= 0.01' psms.target.tsv > psms_1pct.tsv\n```\n\nRescoring pays where the engine's own score is weakest. On one Orbitrap Astral 5-min DDA run (250 pg HYE load, 6,135 MS2 spectra, 31,437-protein database, PXD070049), Comet's raw `-log10(e-value)` gave **916** PSMs at 1% FDR and Percolator lifted the same search to **1,144** (+25%); Sage's `sage_discriminant_score` is already a learned score, so Percolator moved it from **1,406** to **1,398** (-0.6%) -- no gain to be had. Sage 0.14.6 wins this input outright; Comet 2026.02 with Percolator lands 19% behind it, and MS-GF+ v2024.03.26 read straight off `-log10(SpecEValue)` with no rescoring gives **656**, because a calibrated E-value buys cross-instrument comparability, not raw yield. **Do not generalise these counts**: one run, one low-load short-gradient method, each engine at its own idiomatic high-res settings. Rescoring also needs training data -- pooling the three DDA runs (6,864 PSMs) gave Percolator 5,006 PSMs against Sage's own 4,961, while on a single run of 1,939 PSMs it had too few positives to improve anything.\n\n### Database Search with pyOpenMS\n\n**Goal:** Match tandem mass spectra in an mzML file against a protein FASTA and produce scored PSMs as idXML.\n\n**Approach:** `SimpleSearchEngineAlgorithm` actually scores spectra (the hand-rolled `ProteaseDigestion` loop only digests, it never matches a spectrum). The FASTA must already contain target + decoy sequences concatenated for downstream FDR; decoys carry a recognizable prefix (or set `decoys` to `'true'` to let the engine generate them). Defaults are 10 ppm fragment tolerance and 1 missed cleavage, so set parameters explicitly. The search already annotates `target_decoy` on each hit.\n\n```python\nfrom pyopenms import SimpleSearchEngineAlgorithm, IdXMLFile, PeptideIdentificationList\n\nprotein_ids = []\npeptide_ids = PeptideIdentificationList()   # pyOpenMS 3.5+: a plain [] raises TypeError\nsearch = SimpleSearchEngineAlgorithm()\np = search.getParameters()\np.setValue('precursor:mass_tolerance', 10.0)\np.setValue('precursor:mass_tolerance_unit', 'ppm')\np.setValue('fragment:mass_tolerance', 0.02)         # HCD Orbitrap; default is 10 ppm\np.setValue('fragment:mass_tolerance_unit', 'Da')\np.setValue('peptide:missed_cleavages', 2)           # default is 1\np.setValue('modifications:fixed', [b'Carbamidomethyl (C)'])\np.setValue('modifications:variable', [b'Oxidation (M)'])\nsearch.setParameters(p)\n# spectra are scored against in-silico fragment ions of every candidate peptide\nsearch.search('sample.mzML', 'human_target_decoy.fasta', protein_ids, peptide_ids)\n\n# protein_ids FIRST in load\u002Fstore -- the OpenMS argument order is fixed\nIdXMLFile().store('search_results.idXML', protein_ids, peptide_ids)\n```\n\n### Annotate Target\u002FDecoy and Estimate FDR with pyOpenMS\n\n**Goal:** Convert raw PSM scores into q-values and keep only PSMs at 1% FDR.\n\n**Approach:** `PeptideIndexing` maps each PSM back to proteins and flags target vs decoy from the decoy prefix -- needed for idXML from other engines or after changing the FASTA; `SimpleSearchEngineAlgorithm` output above is already annotated and can go straight to `FalseDiscoveryRate`. `FalseDiscoveryRate.apply` runs the concatenated competition; `IDFilter` keeps q \u003C= 0.01. This is the real pyOpenMS path -- not a hand-rolled decoy\u002Ftarget ratio of unknown provenance.\n\n```python\nfrom pyopenms import PeptideIndexing, FalseDiscoveryRate, IDFilter, FASTAFile\n\nfasta = []\nFASTAFile().load('human_target_decoy.fasta', fasta)\nindexer = PeptideIndexing()\nparams = indexer.getParameters()\nparams.setValue('decoy_string', 'DECOY_')      # must match the decoy prefix in the FASTA\nparams.setValue('decoy_string_position', 'prefix')\nindexer.setParameters(params)\nindexer.run(fasta, protein_ids, peptide_ids)   # sets target\u002Fdecoy flags on every hit\n\nFalseDiscoveryRate().apply(peptide_ids)         # concatenated competition -> per-PSM q-value as the new score\nIDFilter().filterHitsByScore(peptide_ids, 0.01) # 0.01 = 1% FDR, the community list-level standard\nIDFilter().removeDecoyHits(peptide_ids)\n```\n\n### FDR from a Results Table (concatenated competition, made explicit)\n\n**Goal:** Compute q-values from any engine's PSM table when the search was a single concatenated target-decoy search.\n\n**Approach:** Keep the best hit per spectrum, rank by score, walk down accumulating target and decoy counts, FDR = (decoys + 1)\u002Ftargets, then take the running minimum from the bottom to get monotone q-values. `score` must be higher-is-better, and the decoy prefix must match the engine's (Sage and FragPipe write lowercase `rev_`); a table with no recognised decoys must stop, not pass every PSM. This form is correct ONLY for concatenated competition; separate searches need pi0 * decoys\u002Ftargets (Kall et al. 2008; pi0 = 1 is the conservative default) or the mix-max estimator (Keich, Kertesz-Farkas & Noble 2015; Percolator's default for separate-search input).\n\n```python\nimport pandas as pd\n\nDECOY_PREFIXES = ('decoy_', 'rev_', 'xxx_')   # compared lower-cased: DECOY_, REV_ \u002F REV__ (MaxQuant), rev_ (Sage, FragPipe), XXX_\n\npsms = pd.read_csv('search_results.tsv', sep='\\t')   # map engine columns to 'scan', 'score', 'protein'\n# score must be HIGHER-is-better: Sage sage_discriminant_score or Comet xcorr as is;\n# E-values (Comet e-value, MS-GF+ SpecEValue) as -log10(E-value)\npsms['is_decoy'] = psms['protein'].str.lower().str.startswith(DECOY_PREFIXES)\nif not psms['is_decoy'].any():\n    raise ValueError('no decoy PSMs recognised: check the decoy prefix, or the table was already decoy-filtered')\n# one best hit per spectrum (Comet .txt writes 5 rows per scan by default)\npsms = psms.sort_values('score', ascending=False).drop_duplicates('scan').reset_index(drop=True)\n\n# concatenated target-decoy competition: each decoy above threshold estimates one false target\ntargets = (~psms['is_decoy']).cumsum()\ndecoys = psms['is_decoy'].cumsum()\npsms['fdr'] = (decoys + 1) \u002F targets.clip(lower=1)   # +1: zero decoys is not zero FDR (OpenMS conservative default)\npsms['qvalue'] = psms['fdr'][::-1].cummin()[::-1]   # running min from the bottom -> monotone q-values\n\nkept = psms[(psms['qvalue'] \u003C= 0.01) & (~psms['is_decoy'])]   # 1% list-level FDR\n```\n\n### FDR from SEPARATE Target and Decoy Searches (pi0 * D \u002F T)\n\n**Goal:** Get a valid 1% list out of two result tables produced by searching the same spectra against a target DB and a decoy DB independently.\n\n**Approach:** No competition resolved which hit wins, so the decoy count estimates the number of incorrect TARGETS directly, scaled by pi0, the proportion of target PSMs that are incorrect (Kall et al. 2008). pi0 = 1 is always valid and conservative; the median-decoy estimate (twice the fraction of target scores below the median decoy score) recovers the identifications that pi0 = 1 throws away, at the cost of estimating a nuisance parameter. Do NOT run the concatenated snippet above on the two tables merged. `examples\u002Fseparate_search_fdr.py` ships this as a script.\n\n```python\nimport numpy as np\n\ndef estimate_pi0(target_scores, decoy_scores):        # Kall et al. 2008\n    median_decoy = np.median(decoy_scores)\n    return min(1.0, 2.0 * np.mean(np.asarray(target_scores) \u003C median_decoy))\n\ndef separate_search_qvalues(targets, decoys, pi0=None):\n    # targets, decoys: DataFrames with 'scan' and 'score', ONE row per spectrum each\n    if pi0 is None:\n        pi0 = estimate_pi0(targets['score'].to_numpy(), decoys['score'].to_numpy())\n    t = targets.sort_values('score', ascending=False).reset_index(drop=True)\n    decoy_sorted = np.sort(decoys['score'].to_numpy())\n    n_decoy_above = len(decoy_sorted) - np.searchsorted(decoy_sorted, t['score'].to_numpy(), side='left')\n    t['fdr'] = np.minimum(1.0, pi0 * n_decoy_above \u002F np.arange(1, len(t) + 1))\n    t['qvalue'] = t['fdr'][::-1].cummin()[::-1]\n    return t, pi0\n```\n\nOn the synthetic separate-search pair with ground truth (12,000 spectra each): pi0-hat = 0.611 keeps 2,888 PSMs at a true FDP of 1.04%, pi0 = 1 keeps 2,588 at 0.62%, and Elias-Gygi's 2d\u002F(t+d) misapplied here keeps only 2,139 at 0.33%. The alternative is to hand both tables to Percolator and let mix-max do it: that is Percolator's default for separate-search input, and it is a calibrated-score procedure, not the same arithmetic.\n\n## Per-Method Failure Modes\n\n### Concatenated vs separate FDR formula mismatch\n**Trigger:** running the concatenated snippet on a merged table from separate searches without per-spectrum competition, or applying Elias-Gygi's 2*decoy\u002F(target+decoy) to separate searches.\n**Mechanism:** Elias-Gygi's factor 2 counts decoys in the combined target+decoy list of a concatenated search; in separate searches every spectrum gets both a target and a decoy hit, so the decoy count estimates false targets directly, scaled by pi0 (the fraction of target PSMs that are incorrect).\n**Symptom:** mis-estimated FDR; 2d\u002F(t+d) on separate searches over-estimates it (synthetic test: 2.06% vs 0.62% true, about a quarter of IDs lost).\n**Fix:** confirm the search mode; concatenated -> (#decoy + 1)\u002F#target; separate -> pi0 * #decoy\u002F#target (Kall et al. 2008; code in \"FDR from SEPARATE Target and Decoy Searches\" above and in `examples\u002Fseparate_search_fdr.py`) or the mix-max estimator (Keich, Kertesz-Farkas & Noble 2015). In Percolator, mix-max is the default for separate-search input and `-Y`\u002F`--post-processing-tdc` selects target-decoy competition instead; concatenated input forces TDC automatically.\n\n### Thresholding on raw engine score\n**Trigger:** filtering on XCorr\u002Fhyperscore\u002FAndromeda score, or comparing scores from two engines.\n**Mechanism:** scores are uncalibrated, charge\u002Flength-dependent, and not monotone in true probability.\n**Symptom:** different cutoffs admit different real FDRs; cross-engine merges nonsensical.\n**Fix:** always convert to q-value (or SpecEValue\u002FPEP) first; rescore with Percolator\u002Fmokapot.\n\n### Decoy FDR on too few PSMs\n**Trigger:** reporting \"0% FDR\" from a single-protein pulldown or tiny PSM list.\n**Mechanism:** the decoy count is a noisy Poisson-like estimate; zero observed decoys does not mean zero false targets.\n**Symptom:** spuriously confident IDs from small experiments.\n**Fix:** below ~hundreds of PSMs, inspect spectra manually; do not act on the decoy q-value.\n\n### Open-search results used for clean FDR or quant\n**Trigger:** taking IDs from a wide-window (-150..+500 Da) search as final, FDR-controlled results.\n**Mechanism:** wide windows admit \"free\" mass shifts that inflate random matches; the target-decoy null differs per mass-shift bin.\n**Symptom:** inflated, unreliable FDR on open-search output.\n**Fix:** treat open search as discovery; follow with a closed search restricted to the discovered mods -> ptm-analysis.\n\n### Rescoring overfitting\n**Trigger:** custom features that leak label information, or training without proper cross-validation.\n**Mechanism:** the model learns the decoys, making rescored FDR optimistic.\n**Symptom:** ID counts jump but downstream validation fails.\n**Fix:** use Percolator\u002Fmokapot default cross-validation; predicted-feature rescoring (DeepLC\u002FMS2PIP) is safer; validate with entrapment for high-stakes claims (Wen 2025).\n\n### DIA tool FDR taken at face value\n**Trigger:** trusting a DIA tool's reported 1% peptide\u002Fprotein FDR.\n**Mechanism:** entrapment shows several DIA tools do not reliably control FDR (Wen 2025).\n**Symptom:** real error rate exceeds the reported FDR.\n**Fix:** validate with entrapment for high-stakes DIA claims -> dia-analysis.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|---|---|---|\n| Precursor tolerance 10-20 ppm (high-res Orbitrap) | -- | matches FT mass accuracy; tighter = fewer random candidates at fixed FDR |\n| Precursor tolerance -150..+500 Da (open search) | Kong 2017 | captures arbitrary PTM\u002Fmutation shifts; feasible only with fragment indexing |\n| Fragment tolerance 0.02 Da (HCD Orbitrap) \u002F 0.6 Da (ion-trap CID) | -- | instrument-dependent; 0.6 Da on Orbitrap discards resolving power |\n| Missed cleavages 2 | -- | covers incomplete trypsin digestion without exploding search space |\n| PSM\u002Fpeptide FDR 1% (q \u003C= 0.01) | Elias & Gygi 2007 | community standard; list-level error, not per-PSM |\n| Decoy:target ratio 1:1 | Elias & Gygi 2007 | standard; unequal ratios need formula correction |\n| Min PSMs for trustworthy decoy FDR: hundreds+ | -- | below this the decoy count is too noisy |\n| Variable mods per peptide \u003C= 2-3 | -- | each variable mod multiplies search space and random-match rate |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|---|---|---|\n| pyOpenMS \"search\" returns peptides but never scores spectra | used `ProteaseDigestion`, which only digests a FASTA | use `SimpleSearchEngineAlgorithm().search(mzML, fasta, protein_ids, peptide_ids)` |\n| `TypeError: Argument 'pep_ids' has incorrect type (expected ...PeptideIdentificationList, got list)` or `can not handle type` | pyOpenMS 3.5+ needs a `PeptideIdentificationList` | `peptide_ids = PeptideIdentificationList()`; protein_ids FIRST: `IdXMLFile().load(path, protein_ids, peptide_ids)` |\n| `RuntimeError: Meta value 'target_decoy' does not exist` from `FalseDiscoveryRate` | decoys not annotated (e.g. idXML from another engine) | run `PeptideIndexing` with matching `decoy_string` first |\n| Every PSM passes 1% FDR, or `ValueError: no decoy PSMs recognised` | decoy prefix not matched (Sage and FragPipe write lowercase `rev_`) | compare prefixes lower-cased; check `psms['protein'].str[:6].value_counts()` |\n| Empty 1% list from a table snippet | lower-is-better score (E-value, SpecEValue) used as `score` | use `-log10(E-value)` |\n| All q-values 0 from a hand-rolled table | no +1 correction on a list with zero decoys | use (decoys + 1)\u002Ftargets; a tiny list cannot reach 1% |\n| Percolator q-method mismatched to search mode | mix-max is the default for separate-search input | for separate searches, mix-max (default) or `-Y`\u002F`--post-processing-tdc` for target-decoy competition; concatenated input forces TDC automatically; use `--picked-protein` for protein FDR |\n| Percolator's 1% list is far too big or too small when cut by column index | Percolator writes a `filename` column only when the pin has one (Sage yes, Comet no), shifting `q-value` between columns 3 and 4 | locate `q-value` by header name, never by a fixed index |\n| Decoy count is twice the target count after a search | `-tda 1` (MS-GF+) or `generate_decoys: true` (Sage) run against a database that already contains decoys | use `-tda 0` \u002F `generate_decoys: false` with a concatenated DB, or feed the target-only FASTA and let the engine make them |\n| `philosopher peptideprophet` exits 0 but the output has no `peptideprophet_result` and the log says `read in 0 1+, 0 2+ ... spectra` \u002F `read in no data` | its embedded PeptideProphet does not model this pepXML (seen with Comet 2026.02 rev.2 pepXML under Philosopher v5.1.0 on Windows, with and without `--nonparam --decoy`) | rescore with Percolator on the engine's `.pin` instead; check the interact file for `peptideprophet_result` before trusting a PeptideProphet run |\n| 1% PSM FDR assumed to give 1% protein FDR | each level needs its own estimation | estimate protein-level (picked) FDR -> protein-inference |\n| \"PEP \u003C= 0.01\" returns far fewer IDs than expected | PEP is per-PSM and far stricter than q-value | filter list cutoffs on q-value; reserve PEP for per-ID decisions |\n\n## References\n\n- Elias, J.E. & Gygi, S.P. 2007. Target-decoy search strategy for increased confidence in large-scale protein identifications by mass spectrometry. *Nature Methods* 4(3):207-214.\n- Keich, U., Kertesz-Farkas, A. & Noble, W.S. 2015. Improved false discovery rate estimation procedure for shotgun proteomics. *Journal of Proteome Research* 14(8):3148-3161.\n- Kall, L., Canterbury, J.D., Weston, J., Noble, W.S. & MacCoss, M.J. 2007. Semi-supervised learning for peptide identification from shotgun proteomics datasets. *Nature Methods* 4(11):923-925.\n- Kall, L., Storey, J.D., MacCoss, M.J. & Noble, W.S. 2008. Assigning significance to peptides identified by tandem mass spectrometry using decoy databases. *Journal of Proteome Research* 7(1):29-34.\n- Kall, L., Storey, J.D., MacCoss, M.J. & Noble, W.S. 2008. Posterior error probabilities and false discovery rates: two sides of the same coin. *Journal of Proteome Research* 7(1):40-44.\n- Eng, J.K., Jahan, T.A. & Hoopmann, M.R. 2013. Comet: an open-source MS\u002FMS sequence database search tool. *Proteomics* 13(1):22-24.\n- Kim, S. & Pevzner, P.A. 2014. MS-GF+ makes progress towards a universal database search tool for proteomics. *Nature Communications* 5:5277.\n- Cox, J., Neuhauser, N., Michalski, A., Scheltema, R.A., Olsen, J.V. & Mann, M. 2011. Andromeda: a peptide search engine integrated into the MaxQuant environment. *Journal of Proteome Research* 10(4):1794-1805.\n- Kong, A.T., Leprevost, F.V., Avtonomov, D.M., Mellacheruvu, D. & Nesvizhskii, A.I. 2017. MSFragger: ultrafast and comprehensive peptide identification in mass spectrometry-based proteomics. *Nature Methods* 14(5):513-520.\n- Lazear, M.R. 2023. Sage: an open-source tool for fast proteomics searching and quantification at scale. *Journal of Proteome Research* 22(11):3652-3659.\n- Solntsev, S.K., Shortreed, M.R., Frey, B.L. & Smith, L.M. 2018. Enhanced global post-translational modification discovery with MetaMorpheus. *Journal of Proteome Research* 17(5):1844-1851.\n- Chi, H., Liu, C., Yang, H. et al. 2018. Comprehensive identification of peptides in tandem mass spectra using an efficient open search engine. *Nature Biotechnology* 36:1059-1061.\n- Fondrie, W.E. & Noble, W.S. 2021. mokapot: fast and flexible semisupervised learning for peptide detection. *Journal of Proteome Research* 20(4):1966-1971.\n- Bouwmeester, R., Gabriels, R., Hulstaert, N., Martens, L. & Degroeve, S. 2021. DeepLC can predict retention times for peptides that carry as-yet unseen modifications. *Nature Methods* 18:1363-1369.\n- Gabriels, R., Martens, L. & Degroeve, S. 2019. Updated MS2PIP web server delivers fast and accurate MS2 peak intensity prediction for multiple fragmentation methods, instruments and labeling techniques. *Nucleic Acids Research* 47(W1):W295-W299.\n- Declercq, A., Bouwmeester, R., Hirschler, A., Carapito, C., Degroeve, S., Martens, L. & Gabriels, R. 2022. MS2Rescore: data-driven rescoring dramatically boosts immunopeptide identification rates. *Molecular & Cellular Proteomics* 21(8):100266.\n- Savitski, M.M., Wilhelm, M., Hahne, H., Kuster, B. & Bantscheff, M. 2015. A scalable approach for protein false discovery rate estimation in large proteomic data sets. *Molecular & Cellular Proteomics* 14(9):2394-2404.\n- The, M., Samaras, P., Kuster, B. & Wilhelm, M. 2022. Reanalysis of ProteomicsDB using an accurate, sensitive, and scalable false discovery rate estimation approach for protein groups. *Molecular & Cellular Proteomics* 21(12):100437.\n- Wen, B., Freestone, J., Riffle, M., MacCoss, M.J., Noble, W.S. & Keich, U. 2025. Assessment of false discovery rate control in tandem mass spectrometry analysis using entrapment. *Nature Methods* 22:1454-1463.\n\n## Related Skills\n\n- protein-inference - Group peptides to protein groups and control protein-level (picked) FDR\n- ptm-analysis - Open\u002Fvariable-mod search follow-up and per-site PTM localization\n- dia-analysis - DIA peptide-centric extraction and scoring; entrapment FDR validation\n- quantification - FDR-filtered IDs feed label-free\u002FTMT intensity quantification\n- spectral-libraries - Empirical and predicted spectral-library search as an ID alternative\n- data-import - Load mzML\u002Fraw MS data before identification\n- database-access\u002Funiprot-access - Build the target FASTA (canonical vs isoform, contaminants)\n",{"name":5,"tool_type":24,"description":7,"primary_tool":25},"mixed","pyOpenMS","main","e0956dc9606356ab78468936b502e55a365282e2","specialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification",0,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists","https:\u002F\u002Fgithub.com\u002Fmrsonord2240","2026-10-12 03:19:04",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-proteomics-peptide-identification",{"tool":39,"command":40},"bunx","bunx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-proteomics-peptide-identification",{"tool":42,"command":43},"pnpm","pnpm dlx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-proteomics-peptide-identification","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002FSKILL.md",true,[47,53,57,61],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"examples\u002Fdda_search.sh","SCRIPT","脚本",5289,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002Fexamples\u002Fdda_search.sh",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"examples\u002Ffdr_filtering.py",3768,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002Fexamples\u002Ffdr_filtering.py",{"path":58,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":59,"sourceHtmlUrl":60},"examples\u002Fseparate_search_fdr.py",3688,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002Fexamples\u002Fseparate_search_fdr.py",{"path":62,"resourceType":63,"resourceTypeDesc":64,"sizeBytes":65,"sourceHtmlUrl":66},"usage-guide.md","REFERENCE","参考文档",5348,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fmass-spec-proteomics-analyst\u002Fversions\u002F1.0.1\u002Fpackage\u002Fskills\u002Fbio-proteomics-peptide-identification\u002Fusage-guide.md",[68,75,82,89,96,103],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7CW36A6QAGWFE2C008M1XPG","bio-workflows-metabolomics-pipeline","Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC\u002Fdrift\u002Fnormalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics\u002Fisotope-tracing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-workflows-metabolomics-pipeline\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7CW2Y18623NA2S1Y30FRQW1","bio-metabolomics-xcms-preprocessing","Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment\u002FXcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave\u002Fgrouping\u002Falignment parameters. For drift correction and QC\u002FCV filtering execution see metabolomics\u002Fnormalization-qc; for metabolite identification see metabolomics\u002Fmetabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics\u002Fmsdial-preprocessing; for downstream statistics see metabolomics\u002Fstatistical-analysis.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-xcms-preprocessing\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7CW2M364HVWPNQEKE2WP4PP","bio-metabolomics-statistical-analysis","Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA\u002FHCA for QC), permutation-validated PLS-DA\u002FOPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch\u002FMann-Whitney\u002FANOVA\u002FLMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization\u002Fdrift correction see metabolomics\u002Fnormalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning\u002Fbiomarker-discovery and machine-learning\u002Fmodel-validation; for pathway interpretation see metabolomics\u002Fpathway-mapping; for design\u002Fpower\u002Fmultiplicity regime see experimental-design\u002Fmultiple-testing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-statistical-analysis\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7CW2BCBF851WYE03Z8XPEDQ","bio-metabolomics-pathway-mapping","Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA\u002FQEA), mummichog\u002FPSEA on raw m\u002Fz peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference\u002Fbackground set. For annotation confidence levels feeding ORA see metabolomics\u002Fmetabolite-annotation; for gene-set concepts see pathway-analysis\u002Fgo-enrichment and pathway-analysis\u002Fgsea; for joint gene+metabolite pathways see multi-omics-integration\u002Fmofa-integration.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-pathway-mapping\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7CW21NSZMCPMF7D9CHJM718","bio-metabolomics-normalization-qc","Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS\u002FGC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak\u002Ffeature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics\u002Fxcms-preprocessing or metabolomics\u002Fmsdial-preprocessing; transformation\u002Fscaling for modeling defers to metabolomics\u002Fstatistical-analysis; cross-study design issues link to experimental-design\u002Fbatch-design.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-normalization-qc\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M7CW1SWVM0NYHVE6Q7MA3G7R","bio-metabolomics-msdial-preprocessing","Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA\u002FDIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",[],[]]