 |
OpenMS
|
Tool to estimate the probability of peptide hits to be incorrectly assigned.
| potential predecessor tools | → IDPosteriorErrorProbability → | potential successor tools |
|---|---|---|
| CometAdapter (or other ID engines), PeptideIndexer | FalseDiscoveryRate, Epifany |
Posterior error probabilities (PEPs) are estimated separately for each search engine (and charge state, if split_charge is set, and MS run, if split_run is set). The search engine scores are transformed such that higher scores are better (e.g. -log10 of e-values). X! Tandem, Mascot, MyriMatch, OMSSA, MS-GF+, Comet, MSFragger, SpectraST, Sage, SimpleSearchEngine and ProSE have a dedicated score selection. For other search engines, the main score of the identifications is used, unless it is already a probability (e.g. a q-value or PEP).
Target-decoy based estimation (recommended)
If the peptide hits are annotated as target or decoy (e.g. by PeptideIndexer after a search against a concatenated target+decoy database), the decoys are used (parameter fit_algorithm:decoy_handling, default 'auto'): the PEP is estimated non-parametrically from the local ratio of decoy and target top hits (target-decoy competition: each decoy top hit stands in for one incorrect target top hit). The decoy probability as a function of the score is estimated by isotonic regression, so the PEP decreases with the score. The estimate does not assume any shape of the score distributions and only depends on the ordering of the scores (up to the interpolation within and between blocks), so it works for any score type. This also works with very few decoys (or targets): even a single decoy carries information about the number of incorrect targets.
Only top hits (one per spectrum) are used for fitting. Lower-ranked target hits receive the PEP of a target top hit with the same score. Decoys receive the PEP that they would get as targets (label swap), which makes decoys and incorrect targets exchangeable, as target-decoy FDR estimates on the PEPs (e.g. FalseDiscoveryRate, or the protein FDR after protein inference) require. Decoys therefore need to be kept in the data, i.e. run this tool before FalseDiscoveryRate (or use its option to keep decoys). If a spectrum has several identifications (e.g. results of separate target and decoy searches of the same run), only its best top hit is used for fitting. With split_charge, charge states with fewer than fit_algorithm:min_decoys decoys (or without targets, or whose model cannot be fitted, or whose targets do not score better than their decoys) use the target-decoy data of all charge states.
Several runs
By default, all search runs of the input file that stem from the same search engine are modeled together (one PEP curve per search engine), with target-decoy competition per spectrum. Score types must be comparable across the runs (same search engine and settings; e-values are preferable to raw scores). One model for several runs is more accurate than a model per run if the runs are small (e.g. fractions, or runs with few identifications): with few decoys, the PEPs of a run depend strongly on the chance positions of its decoys, and the few incorrect targets that score above the best decoy of their run get low PEPs. With split_run, the PEPs of each MS run are estimated separately, e.g. if the score distributions of the runs differ strongly. An MS run is identified by its spectra file, so separate target and decoy searches of the same spectra file still compete per spectrum (identifications whose spectra file is unknown are grouped by their identification run). With out_plot, the plot files of the MS runs are numbered in the order of the runs in the input ('_run_1', '_run_2', ...).
PSM or peptide level
By default (fit_level 'psm'), the model is fitted to the PSMs. With fit_level 'peptide', it is fitted to the best PSM of each peptide (modified sequence; with split_charge: of each peptide and charge state): for the target-decoy estimate, the best top hit of each peptide after the competition per spectrum, as Percolator and mokapot do at the peptide level. Every PSM gets the PEP of this model at its score, so the best PSM of each peptide carries the PEP of the peptide. Use the peptide level for protein inference that takes the best PSM of each peptide (e.g. Epifany): the best of several PSMs is selected by its score, which PSM-level PEPs do not account for, while the decoys go through the same selection at the peptide level. For PSM-level uses of the PEPs (e.g. filtering PSMs by PEP, or the PEPs of all PSMs of a peptide), use the PSM level. The parameter fit_algorithm:min_decoys counts decoy peptides at the peptide level, and fit_algorithm:min_mixture_scores the peptides (their best scores) for the mixture model.
Mixture models
Without target/decoy information (or with fit_algorithm:decoy_handling 'ignore'), a mixture model is fitted to all scores (or only the top hits, if top_hits_only is set): By default an estimation is performed using the (inverse) Gumbel distribution for incorrectly assigned sequences and a Gaussian distribution for correctly assigned sequences. The probabilities are calculated by using Bayes' law, similar to PeptideProphet. Alternatively, a second Gaussian distribution can be used for incorrectly assigned sequences. Without decoys, the mixture model assumes that the data contain correct assignments: for data with few or no correct assignments, it might assign low PEPs to a few PSMs in the extreme upper tail of the scores. On real data (Comet e-values of a yeast/UPS1 dataset, validated with an entrapment database), the PEPs of the mixture model were about 1.5 times too high in total, and much too high for confident PSMs, while the target-decoy estimate was within a few percent. Use target/decoy information whenever possible. The mixture model needs at least fit_algorithm:min_mixture_scores scores (default 35, as PeptideProphet), also after outlier handling. With split_charge, a charge state with fewer scores, or whose mixture model cannot be fitted, uses the mixture model of all charge states. If there are still too few scores, the tool fails (with ignore_bad_data: the hits get a PEP of 1, the original score is kept as meta value).
Plots
In order to validate the computed probabilities an optional plot output can be generated. There are two parameters for the plot: The scores are plotted in the form of bins. Each bin represents a set of scores in a range of '(highest_score - smallest_score) / number_of_bins' (if all scores have positive values). The midpoint of the bin is the mean of the scores it represents. The parameter 'out_plot' should be used to give the plot a unique name. Two files are created. One with the binned scores and one with all steps of the estimation. If target/decoy information is available, an additional plot will be generated with the score distributions of the target and decoy top hits and the estimated PEPs ('out_plot' must not be empty). The plots are saved as a Gnuplot file. An attempt is made to call Gnuplot, which will create a PDF file containing all steps of the estimation. If this fails, the user has to run Gnuplot manually - or adjust the PATH environment such that Gnuplot can be found and retry.
The command line parameters of this tool are:
IDPosteriorErrorProbability -- Estimates probabilities for incorrectly assigned peptide sequences and a set
of search engine scores using target-decoy information or a mixture model.
Full documentation: http://www.openms.de/doxygen/nightly/html/TOPP_IDPosteriorErrorProbability.html
Version: 3.7.0-pre-nightly-2026-11-04 Nov 5 2026, 01:20:03, Revision: f358100
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:
IDPosteriorErrorProbability <options>
This tool has algorithm parameters that are not shown here! Please check the ini file for a detailed descript
ion or use the --helphelp option
Options (mandatory options marked with '*'):
-in <file>* Input file (valid formats: 'idXML')
-out <file>* Output file (valid formats: 'idXML')
-out_plot <file> Txt file (if gnuplot is available, a corresponding PDF will be created as well.) (valid
formats: 'txt')
-split_charge The search engine scores are split by charge if this flag is set. Thus, for each charge
state a new model will be computed.
-split_run If set, the PEPs of each MS run (spectra file) are estimated separately. By default,
one model is fitted to all runs of the input file (per search engine).
-fit_level <level> Fit the model to the PSMs ('psm'), or to the best PSM of each peptide ('peptide'; for
protein inference that uses the best PSM per peptide, e.g. Epifany). Every PSM gets
the PEP of the model at its score. (default: 'psm') (valid: 'psm', 'peptide')
-top_hits_only If set only the top hits of every PeptideIdentification will be used for fitting the
mixture model without target/decoy information. (Target-decoy based estimates always
use the top hits only.)
-ignore_bad_data If set errors will be written but ignored. Useful for pipelines with many datasets wher
e only a few are bad, but the pipeline should run through.
-prob_correct If set scores will be calculated as '1 - ErrorProbabilities' and can be interpreted as
probabilities for correct identifications.
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)
The following configuration subsections are valid:
- fit_algorithm Algorithm parameter subsection
You can write an example INI file using the '-write_ini' option.
Documentation of subsection parameters can be found in the doxygen documentation or the INIFileEditor.
For more information, please consult the online documentation for this tool:
- http://www.openms.de/doxygen/nightly/html/TOPP_IDPosteriorErrorProbability.html
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.
For the parameters of the algorithm section see the algorithms documentation:
fit_algorithm
1.9.8