 |
OpenMS
|
Measures the false discovery proportion of identifications with an entrapment database.
Search a database that contains entrapment sequences (for example made by DecoyDatabase with -entrapment_ratio 1), estimate the FDR as usual (FalseDiscoveryRate, PercolatorAdapter or a search engine's own rescoring), then run this tool on the result. At each q-value threshold it reports how many discoveries were accepted, how many of them match only entrapment proteins, and estimates of the true false discovery proportion (FDP), following Wen et al., "Assessment of false discovery rate control in tandem mass spectrometry analysis using
entrapment", Nat. Methods (2025). With N accepted discoveries, N_E of them entrapment:
-database). Every entrapment peptide is paired with the target peptide it was shuffled from; N_{E>=s>T} counts accepted entrapment peptides whose paired target is not accepted, N_{E>T>=s} those whose paired target is accepted but does not rank above them (q-value, then -score_meta_value; a tie counts against the FDP).Two levels are reported: "psm" (the top hit of each spectrum) and "peptide" (distinct unmodified sequences, I = L). The paper evaluates peptides, not PSMs. A peptide is accepted at its peptide-level q-value when the PSMs carry one (FalseDiscoveryRate -peptide true writes it as "peptide q-value"), otherwise at the best q-value of its PSMs, which is not a peptide-level FDR (the tool warns).
T/E is the ratio of searchable target to entrapment peptides. It is computed from -database when given (by in-silico digestion, I and L taken as one residue), otherwise taken from -te_ratio. A discovery counts as entrapment only when all its proteins are entrapment proteins and, with -database, its sequence is not also a target peptide of the database with I and L taken as one residue (I and L have the same mass, so such a PSM cannot be told apart from the target peptide; search engines usually map peptides to proteins without this equivalence).
Use it to validate changes to search and rescoring: a change that yields more identifications at the same nominal FDR is only an improvement if the FDP stays controlled.
With -class_meta_value the result is also broken down by the value of a peptide hit meta value, for example to check the FDR within a modification class.
The command line parameters of this tool are:
EntrapmentEvaluator -- Measures the false discovery proportion of identifications with an entrapment database
.
Full documentation: http://www.openms.de/doxygen/nightly/html/TOPP_EntrapmentEvaluator.html
Version: 3.7.0-pre-nightly-2026-11-13 Nov 14 2026, 01:17:51, Revision: 339429f
To cite OpenMS:
+ Pfeuffer, J., Bielow, C., Wein, S. et al.. OpenMS 3 enables reproducible analysis of large-scale mass spec
trometry data. Nat Methods (2024). doi:10.1038/s41592-024-02197-7.
Usage:
EntrapmentEvaluator <options>
Options (mandatory options marked with '*'):
-in <files>* Identifications with q-values (as main score or 'q-value' meta value).
Each file is evaluated on its own and all files together. (valid formats:
'idXML', 'idparquet')
-out <file> Optional tab-separated output (one row per file name, class and threshold)
. (valid formats: 'tsv')
-database <file> Searched database (target + entrapment, decoys are skipped). Used to compu
te T/E (if not given, 'te_ratio' is used), to count an entrapment PSM whos
e sequence is also a target peptide with I = L as target, and to pair entr
apment with target peptides for 'paired_fdp'. (valid formats: 'fasta',
'fa', 'faa')
-te_ratio <ratio> Ratio of searchable target to entrapment peptides (used if no 'database'
is given). (default: '1.0') (min: '0.0')
-entrapment_string <string> Accession prefix of entrapment proteins. (default: 'ENTRAP_')
-decoy_string <string> Decoy string of the database. Decoy proteins are skipped when computing
T/E, and a hit counts as entrapment if all its non-decoy proteins are entr
apment. (default: 'DECOY_')
-decoy_string_position <choice> Is 'decoy_string' a prefix or a suffix? (default: 'prefix') (valid: 'prefi
x', 'suffix')
-q_value <thresholds> Q-value thresholds at which to report. (default: '[0.01]')
-class_meta_value <name> Also report per value of this peptide hit meta value.
Common TOPP options:
-ini <file> Use the given TOPP INI file
-threads <n> Sets the number of threads allowed to be used by the TOPP tool (0 = all
available cores) (default: '1')
-write_ini <file> Writes the default configuration file
--help Shows options
--helphelp Shows all options (including advanced)
INI file documentation of this tool:
This section lists all parameters supported by the tool. Parameters are organized into hierarchical subsections that group related settings together. Subsections may contain further subsections or individual parameters.
Each parameter entry contains the following information:
Parameter tags provide additional information about how a parameter is used. Some tags indicate whether a parameter is required or intended for advanced configuration, while others may be used internally by OpenMS or workflow tools.
Parameters highlighted as required must be specified for the tool to run successfully. Parameters marked as advanced allow fine-tuning of algorithm behavior and are typically not needed for standard workflows.
1.9.8