PeptDeepRescoring Class Reference

Annotates PSMs with rescoring features derived from PeptDeep predictions. More...

#include <OpenMS/ANALYSIS/ID/PeptDeepRescoring.h>

Inheritance diagram for PeptDeepRescoring:

Classes
struct	PSMRows
struct	Row
	Row of the flat PSM work list built by annotate(). More...

Public Member Functions
	PeptDeepRescoring ()
	Constructor. Sets the default parameters; the model paths start empty and must be set.
	~PeptDeepRescoring () override
	Destructor.
void	annotate (const PeakMap &spectra, std::vector< ProteinIdentification > &protein_ids, PeptideIdentificationList &peptide_ids)
	Annotates peptide_ids in place and registers the features for rescoring.
void	selectNCE (const PeakMap &spectra, std::vector< ProteinIdentification > &protein_ids, const PeptideIdentificationList &peptide_ids)
	Selects the normalised collision energy of each run of peptide_ids as annotate() does, without predicting the spectra of all PSMs or adding features.
void	selectNCE (const PeakMap &spectra, std::vector< ProteinIdentification > &protein_ids, const PeptideIdentificationList &peptide_ids, PeptDeepMS2Inference &ms2_inference)
double	getUsedNCE () const
double	getRTCalibrationError () const
Size	getNumPSMs () const
	Number of PSMs (peptide hits) seen by the last annotate() call.
Size	getNumPredictedPSMs () const
Public Member Functions inherited from DefaultParamHandler
	DefaultParamHandler (const std::string &name)
	Constructor with name that is displayed in error messages.
	DefaultParamHandler (const DefaultParamHandler &rhs)
	Copy constructor.
virtual	~DefaultParamHandler ()
	Destructor.
DefaultParamHandler &	operator= (const DefaultParamHandler &rhs)
	Assignment operator.
virtual bool	operator== (const DefaultParamHandler &rhs) const
	Equality operator.
void	setParameters (const Param &param)
	Sets the parameters.
const Param &	getParameters () const
	Non-mutable access to the parameters.
const Param &	getDefaults () const
	Non-mutable access to the default parameters.
const std::string &	getName () const
	Non-mutable access to the name.
void	setName (const std::string &name)
	Mutable access to the name.
const std::vector< std::string > &	getSubsections () const
	Non-mutable access to the registered subsections.
Public Member Functions inherited from ProgressLogger
	ProgressLogger ()
	Constructor.
virtual	~ProgressLogger ()
	Destructor.
	ProgressLogger (const ProgressLogger &other)
	Copy constructor.
ProgressLogger &	operator= (const ProgressLogger &other)
	Assignment Operator.
void	setLogType (LogType type) const
	Sets the progress log that should be used. The default type is NONE!
LogType	getLogType () const
	Returns the type of progress log being used.
void	setLogger (ProgressLoggerImpl *logger)
	Sets the logger to be used for progress logging.
void	startProgress (SignedSize begin, SignedSize end, const std::string &label) const
	Initializes the progress display.
void	setProgress (SignedSize value) const
	Sets the current progress.
void	endProgress (UInt64 bytes_processed=0) const
void	nextProgress () const
	increment progress by 1 (according to range begin-end)

Static Public Member Functions
static StringList	featureNames ()
	Names of the features this class adds to each PSM, in a stable order.
Static Public Member Functions inherited from DefaultParamHandler
static void	writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const std::string &key_prefix="")
	Writes all parameters to meta values.

Static Public Attributes
static constexpr const char *	NCE_META_VALUE = "peptdeep_nce"

Protected Member Functions
void	updateMembers_ () override
	This method is used to update extra member variables at the end of the setParameters() method.
bool	startCall_ (const PeptideIdentificationList &peptide_ids, const StringList &models, const std::string &what)
void	selectNCE_ (const PeakMap &spectra, std::vector< ProteinIdentification > &protein_ids, const PeptideIdentificationList &peptide_ids, PeptDeepMS2Inference &ms2_inference)
	selectNCE() with the session ms2_inference
std::vector< Size >	confidentRows_ (const std::vector< Row > &rows, const std::vector< Size > &run_rows, bool higher_better) const
double	selectRunNCE_ (const std::map< std::string, double > &collision_energies, const PeptideIdentificationList &peptide_ids, const PSMRows &psms, const std::vector< Size > &run_rows, const std::vector< Size > &confident, PeptDeepMS2Inference &ms2_inference, double &centre, double &median_cosine)
void	annotateRun_ (const std::string &run_id, const std::map< std::string, double > &collision_energies, PeptideIdentificationList &peptide_ids, const PSMRows &psms, const std::vector< Size > &run_rows, bool higher_better, PeptDeepMS2Inference &ms2_inference, PeptDeepRTInference &rt_inference)
Protected Member Functions inherited from DefaultParamHandler
void	defaultsToParam_ ()
	Updates the parameters after the defaults have been set in the constructor.

Static Protected Member Functions
static PSMRows	gatherPSMs_ (const PeptideIdentificationList &peptide_ids)
static std::map< std::string, double >	collisionEnergies_ (const PeakMap &spectra)
static void	storeNCE_ (std::vector< ProteinIdentification > &protein_ids, const std::map< std::string, double > &nce_by_run)

Protected Attributes
std::string	ms2_model_
std::string	rt_model_
double	nce_ {-1.0}
double	nce_grid_halfwidth_ {6.0}
double	nce_grid_step_ {2.0}
double	nce_fallback_ {30.0}
Size	nce_sample_size_ {2000}
std::string	instrument_
double	calibration_quantile_ {0.5}
std::string	rt_model_type_ {"b_spline"}
Size	rt_num_nodes_ {5}
int	ms2_min_ordinal_ {1}
double	ms2_strong_fraction_ {0.05}
Size	batch_size_ {64}
Int	threads_ {4}
double	used_nce_ {-1.0}
double	rt_calibration_error_ {-1.0}
Size	num_psms_ {0}
Size	num_predicted_psms_ {0}
Protected Attributes inherited from DefaultParamHandler
Param	param_
	Container for current parameters.
Param	defaults_
	Container for default parameters. This member should be filled in the constructor of derived classes!
std::vector< std::string >	subsections_
	Container for registered subsections. This member should be filled in the constructor of derived classes!
std::string	error_name_
	Name that is displayed in error messages during the parameter checking.
bool	check_defaults_
	If this member is set to false no checking if parameters in done;.
bool	warn_empty_defaults_
	If this member is set to false no warning is emitted when defaults are empty;.
Protected Attributes inherited from ProgressLogger
LogType	type_
time_t	last_invoke_
ProgressLoggerImpl *	current_logger_

Additional Inherited Members
Public Types inherited from ProgressLogger
enum	LogType { CMD , GUI , NONE }
	Possible log types. More...
Static Protected Attributes inherited from ProgressLogger
static std::atomic< int >	recursion_depth_

Detailed Description

Annotates PSMs with rescoring features derived from PeptDeep predictions.

Compares every PSM against an AlphaPeptDeep prediction of the same peptide and stores the agreement as per-hit features, which are then registered in the search parameters' extra_features list so that PercolatorAdapter picks them up:

• ms2_cosine, ms2_spectral_angle, ms2_pearson, ms2_frac_pred_found – predicted versus observed fragment intensities
• rt_abs_error – observed retention time versus a per-run calibration of the predicted retention time

Observed intensities are taken from the PSM's own peak annotations, so no second pass over the spectra is needed; the search engine must have been run with fragment annotation enabled (ProSE's annotate:PSM default of ALL does this). Predicted ions that were not matched contribute zero on the observed side, which is what makes a wrong peptide score badly rather than simply score on fewer ions.

Two per-run quantities are calibrated from the data rather than being asked of the user, because both are properties of the run and neither has a safe global default:

• Normalised collision energy. The model's NCE scale does not coincide with the number the instrument reports, so the mzML value is used only as the centre of a small search grid. Each candidate is scored on a sample of confident PSMs and the one with the highest median cosine wins. With nce set to a positive value the scan is skipped and that value is used directly.
• Retention time. Predicted RT is in the model's own iRT-like units, so it is mapped onto the run's observed gradient by fitting a TransformationModel on confident PSMs before the residual is taken.

Confident PSMs are selected by search score rather than by spectral similarity: using similarity here would tie the RT feature to the MS2 features and let one feature's errors propagate into the other. Only the best-scoring hit of each spectrum, and only if it is not a decoy, is a candidate, so the calibration does not depend on how many hits per spectrum the search reports: with ten, lower-ranked candidates and decoys would otherwise make up most of the better-scoring half.

Parameters are not pulled into the generated documentation with @htmlinclude: that requires the class to be registered in DefaultParamHandlerDocumenter, which cannot instantiate a type that only exists in ONNX-enabled builds. ProSEAlgorithm omits it for the same reason.

---

Class Documentation

OpenMS::PeptDeepRescoring::PSMRows

struct OpenMS::PeptDeepRescoring::PSMRows

The PSMs of annotate() and selectNCE(): a row per hit with a sequence, the distinct (sequence, charge) pairs to predict, and the rows of each run (by run identifier, in a stable order)

Class Members
vector< Row >	rows
map< string, vector< Size > >	rows_by_run
vector< float >	uniq_charge
vector< string >	uniq_seq

OpenMS::PeptDeepRescoring::Row

struct OpenMS::PeptDeepRescoring::Row

Row of the flat PSM work list built by annotate().

Class Members
bool	calibration_candidate	best hit of its spectrum and not a decoy
Size	hit	index into that identification's hits
Size	key	index into the de-duplicated (sequence, charge) list
Size	len	peptide length
Size	pi	index into the PeptideIdentificationList
double	score	search score, used to pick the calibration set

Constructor & Destructor Documentation

PeptDeepRescoring()

PeptDeepRescoring

(

)

Constructor. Sets the default parameters; the model paths start empty and must be set.

~PeptDeepRescoring()

~PeptDeepRescoring ( )

override

Destructor.

Member Function Documentation

annotate()

void annotate	(	const PeakMap &	spectra,
		std::vector< ProteinIdentification > &	protein_ids,
		PeptideIdentificationList &	peptide_ids
	)

Annotates peptide_ids in place and registers the features for rescoring.

Parameters

[in]	spectra	Spectra the identifications were made on; supplies retention time and, for the NCE scan, the instrument's reported collision energy.
[in,out]	protein_ids	Search metadata; the feature names are appended to the extra_features of each run that has PSMs, and the NCE its predictions used is stored on the run as the double meta value NCE_META_VALUE (see below).
[in,out]	peptide_ids	PSMs to annotate. Every hit receives every feature, so that no run ends up with a feature present on only some of its PSMs.

Multiple runs in one call are fine: PSMs are partitioned by PeptideIdentification::getIdentifier() and each run gets its own NCE scan and its own RT calibration.

Each annotated ProteinIdentification gets the meta value NCE_META_VALUE ("peptdeep_nce", a double): the NCE its run's predictions used – the one selected by the scan, or nce when that is set. It lets a consumer of the result predict spectra at the same energy the annotation used. A ProteinIdentification without PSMs is not annotated and gets none. If no run identifier matches any ProteinIdentification, the features go on the first one as before, and so does the value, but only when all runs used the same NCE.

Note

That partition is only as good as the run identifiers, so call this before any step that collapses several runs into one – ProSE's out_merged and IDMergerAlgorithm, which remap every identifier onto a single merged run, or IDMerger with merge_proteins_add_PSMs (its default appends runs and is therefore safe). Both calibrated quantities genuinely differ between runs: six files of one HLA ligand atlas dataset (PXD019643) calibrated to median RT residuals between 98 s and 625 s. On already-collapsed input this silently fits one NCE and one RT curve across all of them, and nothing here can detect it after the fact – the merged input is indistinguishable from a genuine single run.

Exceptions

Exception::FileNotFound	if a configured model file does not exist.
Exception::MissingInformation	if no PSM carries peak annotations, since every MS2 feature would otherwise be silently zero.

annotateRun_()

void annotateRun_ ( const std::string &  run_id, const std::map< std::string, double > &  collision_energies, PeptideIdentificationList &  peptide_ids, const PSMRows &  psms, const std::vector< Size > &  run_rows, bool  higher_better, PeptDeepMS2Inference &  ms2_inference, PeptDeepRTInference &  rt_inference  )

protected

Annotates the PSMs of a single identification run. Each run gets its own collision energy and its own retention-time calibration, since neither transfers across runs with different gradients or acquisition settings.

collisionEnergies_()

static std::map< std::string, double > collisionEnergies_ ( const PeakMap &  spectra )

staticprotected

The collision energy of each MS2 spectrum of spectra by native ID (native IDs recorded with differing energies are left out, with a warning)

confidentRows_()

std::vector< Size > confidentRows_ ( const std::vector< Row > &  rows, const std::vector< Size > &  run_rows, bool  higher_better  ) const

protected

The confident rows of a run (run_rows of rows): its calibration candidates (all rows if it has none), best search score first, without the calibration_quantile held out

featureNames()

static StringList featureNames ( )

static

Names of the features this class adds to each PSM, in a stable order.

gatherPSMs_()

static PSMRows gatherPSMs_ ( const PeptideIdentificationList &  peptide_ids )

staticprotected

The PSMs of peptide_ids. Throws Exception::MissingInformation if no PSM carries peak annotations, and warns if only some runs do.

getNumPredictedPSMs()

Size getNumPredictedPSMs

(

)

const

Number of PSMs of the last annotate() call that received a model prediction and carry peak annotations, i.e. whose MS2 features are computed rather than zero-filled. 0 if annotate() returned early or predicted nothing.

getNumPSMs()

Size getNumPSMs

(

)

const

Number of PSMs (peptide hits) seen by the last annotate() call.

getRTCalibrationError()

double getRTCalibrationError

(

)

const

Median absolute RT residual over the calibration set of the run annotated last. -1 if annotate() has not run, or could not calibrate.

getUsedNCE()

double getUsedNCE

(

)

const

Normalised collision energy used for the run annotated last (after any scan). -1 if annotate() has not run, or returned before selecting one.

selectNCE() [1/2]

void selectNCE	(	const PeakMap &	spectra,
		std::vector< ProteinIdentification > &	protein_ids,
		const PeptideIdentificationList &	peptide_ids
	)

Selects the normalised collision energy of each run of peptide_ids as annotate() does, without predicting the spectra of all PSMs or adding features.

For a caller that predicts spectra itself at the energy annotate() would use (e.g. ProSE's -qpx_extended for runs that were not rescored with PeptDeep): the same selection on the same sample of confident PSMs (the scan of the grid, or nce if that is set), and the NCE stored on the runs as NCE_META_VALUE, exactly as annotate() stores it. Needs only ms2_model. Logs no "[PeptDeepRescoring]" lines of its own besides warnings about the input (shared with annotate()); its progress is that of the scan ("Selecting collision energy...").

Parameters

[in]	spectra	As for annotate()
[in,out]	protein_ids	The runs; each run with PSMs gets NCE_META_VALUE
[in]	peptide_ids	The PSMs, as for annotate(); not changed

Exceptions

Exception::FileNotFound	if ms2_model does not exist.
Exception::MissingInformation	if ms2_model is not set, or no PSM carries peak annotations.

selectNCE() [2/2]

void selectNCE	(	const PeakMap &	spectra,
		std::vector< ProteinIdentification > &	protein_ids,
		const PeptideIdentificationList &	peptide_ids,
		PeptDeepMS2Inference &	ms2_inference
	)

selectNCE() with the session of the MS2 model ms2_inference (e.g. one for all inputs of a run) instead of one of ms2_model; its threads and batch size apply

selectNCE_()

void selectNCE_ ( const PeakMap &  spectra, std::vector< ProteinIdentification > &  protein_ids, const PeptideIdentificationList &  peptide_ids, PeptDeepMS2Inference &  ms2_inference  )

protected

selectNCE() with the session ms2_inference

selectRunNCE_()

double selectRunNCE_ ( const std::map< std::string, double > &  collision_energies, const PeptideIdentificationList &  peptide_ids, const PSMRows &  psms, const std::vector< Size > &  run_rows, const std::vector< Size > &  confident, PeptDeepMS2Inference &  ms2_inference, double &  centre, double &  median_cosine  )

protected

The NCE of a run (run_rows of psms): 'nce' if set, else the grid scan on a sample of its confident rows. With the scan, centre is the centre of its grid and median_cosine the median cosine of the selected NCE (else both unchanged).

startCall_()

bool startCall_ ( const PeptideIdentificationList &  peptide_ids, const StringList &  models, const std::string &  what  )

protected

The start of annotate() and selectNCE(): resets the diagnostics; throws Exception::MissingInformation (what) if one of models is not set, Exception::FileNotFound if one does not exist; false if there are no PSMs

storeNCE_()

static void storeNCE_ ( std::vector< ProteinIdentification > &  protein_ids, const std::map< std::string, double > &  nce_by_run  )

staticprotected

Stores the NCE of each run of nce_by_run on the run of protein_ids with its identifier (NCE_META_VALUE); if none has one of these identifiers, on the first run, provided that all NCEs agree

updateMembers_()

void updateMembers_ ( )

overrideprotectedvirtual

This method is used to update extra member variables at the end of the setParameters() method.

Also call it at the end of the derived classes' copy constructor and assignment operator.

The default implementation is empty.

Reimplemented from DefaultParamHandler.

Member Data Documentation

batch_size_

Size batch_size_ {64}

protected

calibration_quantile_

double calibration_quantile_ {0.5}

protected

instrument_

std::string instrument_

protected

ms2_min_ordinal_

int ms2_min_ordinal_ {1}

protected

ms2_model_

std::string ms2_model_

protected

ms2_strong_fraction_

double ms2_strong_fraction_ {0.05}

protected

nce_

double nce_ {-1.0}

protected

nce_fallback_

double nce_fallback_ {30.0}

protected

nce_grid_halfwidth_

double nce_grid_halfwidth_ {6.0}

protected

nce_grid_step_

double nce_grid_step_ {2.0}

protected

NCE_META_VALUE

constexpr const char* NCE_META_VALUE = "peptdeep_nce"

staticconstexpr

Name of the run meta value ("peptdeep_nce", a double) in which annotate() stores, on each annotated ProteinIdentification, the normalised collision energy its predictions used. It is written to idXML with the run, so consumers of stored results can rely on the name.

nce_sample_size_

Size nce_sample_size_ {2000}

protected

num_predicted_psms_

Size num_predicted_psms_ {0}

protected

num_psms_

Size num_psms_ {0}

protected

rt_calibration_error_

double rt_calibration_error_ {-1.0}

protected

rt_model_

std::string rt_model_

protected

rt_model_type_

std::string rt_model_type_ {"b_spline"}

protected

rt_num_nodes_

Size rt_num_nodes_ {5}

protected

threads_

Int threads_ {4}

protected

used_nce_

double used_nce_ {-1.0}

protected