This class is used to switch identification scores within identification or consensus feature maps. More...

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

Inheritance diagram for IDScoreSwitcherAlgorithm:

Collaboration diagram for IDScoreSwitcherAlgorithm:

Classes
struct	IDSwitchResult
	Structure holding score switching information for IDScoreSwitcherAlgorithm. More...

struct	ScoreSearchResult
	Structure to hold score detection results for any ScoreType. More...

Public Types
using	ScoreType = Scores::IDType
	Backward compatible typedef for Scores::IDType.

Public Member Functions
	IDScoreSwitcherAlgorithm ()
	Default constructor. Initializes the parameter handler with default values.

bool	isScoreType (const std::string &score_name, const ScoreType &type) const
	Checks if the given score name corresponds to a specific score type.

bool	isScoreTypeHigherBetter (ScoreType score_type)
	Determines whether a higher score type is better given a ScoreType enum.

std::vector< std::string >	getScoreNames ()
	Gets a vector of all score names that are used in OpenMS.

template<typename IdentificationType >
ScoreSearchResult	findScoreType (const IdentificationType &id, ScoreType score_type) const
	Searches for a general score type (e.g. PEP, QVAL) in an identification data structure.

template<typename IdentificationType >
void	switchScores (IdentificationType &id, Size &counter)
	Switches the main scores of all hits in an identification object based on the new scoring settings.

template<class IdentificationType >
void	switchToGeneralScoreType (std::vector< IdentificationType > &id, ScoreType type, Size &counter)
	Switches the scoring type of identification objects to a general score type.

void	switchToGeneralScoreType (PeptideIdentificationList &pep_ids, ScoreType type, Size &counter)
	Switches the score type of a PeptideIdentificationList to a general score type.

void	switchToGeneralScoreType (ConsensusMap &cmap, ScoreType type, Size &counter, bool unassigned_peptides_too=true)
	Switches the score type of a ConsensusMap to a general score type.

void	determineScoreNameOrientationAndType (const PeptideIdentificationList &pep_ids, std::string &name, bool &higher_better, ScoreType &score_type)
	Determines the score type and orientation of the main score for a set of peptide identifications.

void	determineScoreNameOrientationAndType (const ConsensusMap &cmap, std::string &name, bool &higher_better, ScoreType &score_type, bool include_unassigned=true)
	Determines the score type and orientation of the main score in a ConsensusMap.

void	switchScores (ConsensusMap &cmap, Size &counter, bool unassigned_peptides_too=true)
	Switches the scores of peptide identifications in a ConsensusMap.

void	switchScores (PeptideIdentificationList &pep_ids, Size &counter)
	Switches the scores of peptide identifications.

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.

Static Public Member Functions
static ScoreType	toScoreTypeEnum (const std::string &score_type)
	Converts a string representation of a score type to a ScoreType enum.

static IDSwitchResult	switchToScoreType (ConsensusMap &cmap, std::string requested_score_type_as_string, bool include_unassigned=true)
	Switches the score type of a ConsensusMap to the requested score type.

static IDSwitchResult	switchToScoreType (PeptideIdentificationList &pep_ids, std::string requested_score_type_as_string)
	Switches the score type of peptide identifications to the requested type.

static void	switchBackScoreType (ConsensusMap &cmap, IDSwitchResult isr, bool include_unassigned=true)
	Reverts the score type of a ConsensusMap to its original type based on the provided IDSwitchResult.

static void	switchBackScoreType (PeptideIdentificationList &pep_ids, IDSwitchResult isr)
	Reverts the scoring type of peptide identifications to their original scores.

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.

Private Member Functions
void	updateMembers_ () override
	documented in base class

Private Attributes
const double	tolerance_ = 1e-6
	relative tolerance for score comparisons:

std::string	new_score_
	will be set according to the algorithm parameters

std::string	new_score_type_

std::string	old_score_

bool	higher_better_
	will be set according to the algorithm parameters

Additional Inherited Members
Protected Member Functions inherited from DefaultParamHandler
void	defaultsToParam_ ()
	Updates the parameters after the defaults have been set in the constructor.

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;.

Detailed Description

This class is used to switch identification scores within identification or consensus feature maps.

This class provides functionality to switch the main scoring type used in peptide or protein identification data. It supports switching between different score types, such as raw scores, E-values, posterior probabilities, posterior error probabilities, FDR, and q-values. The class also handles the direction of the score (whether a higher score is better) and can store the original scores as meta values to prevent data loss.

The score switching process is configurable through parameters that specify the score types, as well as the desired score direction and how old scores are annotated in the meta information.

The class can operate on individual identification objects or ConsensusMaps, updating the main scores of all hits based on the specified criteria.

Class Documentation

◆ OpenMS::IDScoreSwitcherAlgorithm::IDSwitchResult

struct OpenMS::IDScoreSwitcherAlgorithm::IDSwitchResult

Structure holding score switching information for IDScoreSwitcherAlgorithm.

This structure contains both the original and requested score details, including score names, their orientation (whether higher scores are better), and score types before and after the switch. It also includes a flag to indicate if the main score has been switched. Used to switch back to the original score if needed.

Collaboration diagram for IDScoreSwitcherAlgorithm::IDSwitchResult:

[legend]

Class Members
bool	original_score_higher_better = true	The name of the original score used before the switch.
string	original_score_name
ScoreType	original_score_type = IDScoreSwitcherAlgorithm::ScoreType::RAW	whether a higher original score is better
bool	requested_score_higher_better = original_score_higher_better	the type of the original score
string	requested_score_name	the type of the requested score
ScoreType	requested_score_type = original_score_type	whether a higher requested score is better
bool	score_switched = false

◆ OpenMS::IDScoreSwitcherAlgorithm::ScoreSearchResult

struct OpenMS::IDScoreSwitcherAlgorithm::ScoreSearchResult

Structure to hold score detection results for any ScoreType.

Collaboration diagram for IDScoreSwitcherAlgorithm::ScoreSearchResult:

[legend]

Class Members
bool	is_main_score_type = false	True if the main score is already of the requested score type.
string	score_name	Name of score to use (main score name if is_main_score_type=true, meta value name if found in meta values, empty if not found anywhere)

Member Typedef Documentation

◆ ScoreType

using ScoreType = Scores::IDType

Backward compatible typedef for Scores::IDType.

Deprecated:: Use Scores::IDType directly instead.

Constructor & Destructor Documentation

◆ IDScoreSwitcherAlgorithm()

IDScoreSwitcherAlgorithm ( )

Default constructor. Initializes the parameter handler with default values.

Member Function Documentation

◆ determineScoreNameOrientationAndType() [1/2]

void determineScoreNameOrientationAndType	(	const ConsensusMap &	cmap,
		std::string &	name,
		bool &	higher_better,
		ScoreType &	score_type,
		bool	include_unassigned = `true`
	)

inline

Determines the score type and orientation of the main score in a ConsensusMap.

This static method inspects a ConsensusMap to determine the overall score type and whether a higher score is considered better. It iterates through the ConsensusMap's features and uses the first PeptideIdentification found to determine the score type and orientation. If no assigned peptide identifications are found, it optionally considers unassigned peptide identifications.

Parameters

[in]	cmap	The ConsensusMap to inspect.
[out]	name	Output parameter to store the determined overall score type.
[out]	higher_better	Output parameter to store whether a higher score is considered better.
[in]	score_type	Output parameter to store the determined score type.
[in]	include_unassigned	If true, unassigned peptide identifications are considered if no assigned ones are found. Default is true.

References ConsensusMap::getUnassignedPeptideIdentifications().

◆ determineScoreNameOrientationAndType() [2/2]

void determineScoreNameOrientationAndType	(	const PeptideIdentificationList &	pep_ids,
		std::string &	name,
		bool &	higher_better,
		ScoreType &	score_type
	)

inline

Determines the score type and orientation of the main score for a set of peptide identifications.

This static method inspects a vector of PeptideIdentification objects to determine the overall score type and whether a higher score is considered better. It uses the first PeptideIdentification in the vector to make this determination, assuming that all identifications in the vector have the same score type and orientation.

Parameters

[in]	pep_ids	The vector of PeptideIdentification objects to inspect.
[out]	name	Output parameter to store the determined overall score type.
[out]	higher_better	Output parameter to store whether a higher score is considered better.
[in]	score_type	Output parameter to store the determined score type.

Note: This method assumes that all PeptideIdentification objects in the input vector have the same score type and orientation.

References ExposedVector< VectorElement >::empty(), and OPENMS_LOG_INFO.

Referenced by IDScoreSwitcherAlgorithm::switchToScoreType(), and IDScoreSwitcherAlgorithm::switchToScoreType().

◆ findScoreType()

template<typename IdentificationType >

ScoreSearchResult findScoreType	(	const IdentificationType &	id,
		ScoreType	score_type
	)		const

inline

Searches for a general score type (e.g. PEP, QVAL) in an identification data structure.

Returns a ScoreSearchResult for any identification type, checking if the main score of an identification object is already of the requested score type, and if not, searches for scores of that type in the meta values of the first hit.

Template Parameters

IdentificationType The type of the identification object (e.g., PeptideIdentification, ProteinIdentification)

Parameters

[in]	id	The identification object to analyze for scores
[in]	score_type	The ScoreType to search for (e.g., ScoreType::PEP, ScoreType::QVAL, etc.)

Returns: ScoreSearchResult containing whether main score is of the requested type and its name.

Note: This method only checks the first hit for meta values, similar to other methods in this class.; Returns empty score_name if no score of the requested type is found.

References IDScoreSwitcherAlgorithm::ScoreSearchResult::is_main_score_type, and IDScoreSwitcherAlgorithm::ScoreSearchResult::score_name.

Referenced by IDFilter::filterHitsByScore().

◆ getScoreNames()

std::vector< std::string > getScoreNames ( )

Gets a vector of all score names that are used in OpenMS.

Returns: A vector of all score names that are used in OpenMS (e.g., "q-value", "ln(hyperscore)").

◆ isScoreType()

bool isScoreType	(	const std::string &	score_name,
		const ScoreType &	type
	)		const

inline

Checks if the given score name corresponds to a specific score type.

This method determines if a given score name, typically derived from an identification object or meta value, matches a specified ScoreType. It performs a case-insensitive comparison and optionally removes the "_score" suffix if present.

Parameters

[in]	score_name	The name of the score to check.
[in]	type	The ScoreType to compare against.

Returns: True if the score name matches the given ScoreType, false otherwise.

Referenced by IDFilter::filterHitsByScore().

◆ isScoreTypeHigherBetter()

bool isScoreTypeHigherBetter ( ScoreType score_type )

inline

Determines whether a higher score type is better given a ScoreType enum.

Parameters

[in] score_type The score type to check.

Returns: True if a higher score type is better, false otherwise.

Referenced by IDFilter::filterHitsByScore(), IDScoreSwitcherAlgorithm::switchToScoreType(), and IDScoreSwitcherAlgorithm::switchToScoreType().

◆ switchBackScoreType() [1/2]

static void switchBackScoreType	(	ConsensusMap &	cmap,
		IDSwitchResult	isr,
		bool	include_unassigned = `true`
	)

inlinestatic

Reverts the score type of a ConsensusMap to its original type based on the provided IDSwitchResult.

This function checks if the scores have been switched and, if so, it switches them back to the original score type. It updates the ConsensusMap by switching the scores, optionally including unassigned PSMs.

Parameters

[in]	cmap	The ConsensusMap object whose scores will be modified.
[out]	isr	The IDSwitchResult containing information about the score switch.
[in]	include_unassigned	A boolean flag indicating whether to include unassigned PSMs in the score switching process. Defaults to true.

References DefaultParamHandler::getDefaults(), OPENMS_LOG_DEBUG, IDScoreSwitcherAlgorithm::IDSwitchResult::original_score_higher_better, IDScoreSwitcherAlgorithm::IDSwitchResult::original_score_name, IDScoreSwitcherAlgorithm::IDSwitchResult::score_switched, DefaultParamHandler::setParameters(), Param::setValue(), and IDScoreSwitcherAlgorithm::switchScores().

◆ switchBackScoreType() [2/2]

static void switchBackScoreType	(	PeptideIdentificationList &	pep_ids,
		IDSwitchResult	isr
	)

inlinestatic

Reverts the scoring type of peptide identifications to their original scores.

This function checks if the scores have been switched. If so, it restores the original scoring parameters using the provided IDSwitchResult. It updates the peptide identifications accordingly and logs the number of PSMs (Peptide-Spectrum Matches) that were reverted.

Parameters

[in]	pep_ids	A vector of PeptideIdentification objects to be updated.
[out]	isr	An IDSwitchResult object containing information about the score switch state and original score details.

References DefaultParamHandler::getDefaults(), OPENMS_LOG_DEBUG, IDScoreSwitcherAlgorithm::IDSwitchResult::original_score_higher_better, IDScoreSwitcherAlgorithm::IDSwitchResult::original_score_name, IDScoreSwitcherAlgorithm::IDSwitchResult::score_switched, DefaultParamHandler::setParameters(), Param::setValue(), and IDScoreSwitcherAlgorithm::switchScores().

◆ switchScores() [1/3]

void switchScores	(	ConsensusMap &	cmap,
		Size &	counter,
		bool	unassigned_peptides_too = `true`
	)

inline

Switches the scores of peptide identifications in a ConsensusMap.

This function iterates over all peptide identifications in the given ConsensusMap and switches their scores using the switchScores function. It also increments the provided counter for each peptide identification processed. Score names are taken from the algorithm's parameters. If the requested score is already set as the main score, the function returns without making any changes.

Parameters

[in]	cmap	The ConsensusMap containing peptide identifications whose scores need to be switched.
[in]	counter	A reference to a counter that will be incremented for each peptide identification processed.
[in]	unassigned_peptides_too	A boolean flag indicating whether to include unassigned peptides in the score switching process. Default is true.

References MapUtilities< MapType >::applyFunctionOnPeptideIDs().

◆ switchScores() [2/3]

template<typename IdentificationType >

void switchScores	(	IdentificationType &	id,
		Size &	counter
	)

inline

Switches the main scores of all hits in an identification object based on the new scoring settings.

This method iterates through all hits in the provided identification object and updates their main scores according to the new scoring settings defined in the switcher class's parameter object. If the old and new score types share the same name (e.g., "q-value"), the method safeguards the original scores by storing them as meta values with a "~" appended to the old score type. This prevents overwriting the meta value of the new score.

Template Parameters

IdentificationType The type of the identification object, which must support getHits(), getScoreType(), setScoreType(), and setHigherScoreBetter() methods, along with the ability to handle meta values.

Parameters

[in,out]	id	An identification object containing hits whose scores are to be switched. The object will be modified in place, with updated scores and score type.
[in,out]	counter	A reference to a Size variable that counts the number of hits processed.

Exceptions

Exception::MissingInformation If a required meta value (specified as the new score) is not found in any of the hits, indicating incomplete or incorrect score setup.

Note: The method assumes that the identification object's hits are properly initialized with all necessary meta values. It also relies on the tolerance_ value to determine significant differences between scores.

References DataValue::isEmpty().

Referenced by IDScoreSwitcherAlgorithm::switchBackScoreType(), and IDScoreSwitcherAlgorithm::switchBackScoreType().

◆ switchScores() [3/3]

void switchScores	(	PeptideIdentificationList &	pep_ids,
		Size &	counter
	)

inline

Switches the scores of peptide identifications.

This function iterates over all peptide identifications and switches their scores using the switchScores function. It also increments the provided counter for each peptide identification processed. Score names are taken from the algorithm's parameters. If the requested score is already set as the main score, the function returns without making any changes.

Parameters

[in]	pep_ids	The peptide identifications whose scores need to be switched.
[in]	counter	A reference to a counter that will be incremented for each peptide identification processed.

References ExposedVector< VectorElement >::empty().

◆ switchToGeneralScoreType() [1/3]

void switchToGeneralScoreType	(	ConsensusMap &	cmap,
		ScoreType	type,
		Size &	counter,
		bool	unassigned_peptides_too = `true`
	)

inline

Switches the score type of a ConsensusMap to a general score type.

Looks at the first Hit of the given ConsensusMap and according to the given score type, deduces a fitting score and score direction to be switched to. Then tries to switch all hits.

Parameters

[in,out]	cmap	The ConsensusMap containing peptide identifications whose scores need to be switched.
[in]	type	The desired general score type to switch to.
[in]	counter	A reference to a counter that will be incremented for each peptide identification processed.
[in]	unassigned_peptides_too	A boolean flag indicating whether to include unassigned peptides in the score switching process. Default is true.

Exceptions

Exception::MissingInformation If the first encountered ID does not have the requested score type.

References MapUtilities< MapType >::applyFunctionOnPeptideIDs(), and OPENMS_LOG_WARN.

◆ switchToGeneralScoreType() [2/3]

void switchToGeneralScoreType	(	PeptideIdentificationList &	pep_ids,
		ScoreType	type,
		Size &	counter
	)

inline

Switches the score type of a PeptideIdentificationList to a general score type.

Overload for PeptideIdentificationList to avoid template deduction issues.

Parameters

[in,out]	pep_ids	The PeptideIdentificationList whose scores need to be switched.
[in]	type	The desired general score type to switch to.
[in]	counter	A reference to a counter that will be incremented for each peptide identification processed.

References ExposedVector< VectorElement >::getData().

◆ switchToGeneralScoreType() [3/3]

template<class IdentificationType >

void switchToGeneralScoreType	(	std::vector< IdentificationType > &	id,
		ScoreType	type,
		Size &	counter
	)

inline

Switches the scoring type of identification objects to a general score type.

This method iterates over a vector of identification objects and changes their scoring type to a specified general score type. It first checks the score type of the first identification object in the vector to determine the necessary conversion. If the first ID does not have the requested score type, an exception is thrown. The method also adjusts the score direction (higher_better_) based on the specified score type if it's different from the raw score.

Template Parameters

IdentificationType The type of the identification objects contained in the vector. Must have getScoreType() and other relevant methods for score manipulation.

Parameters

[in,out]	id	A vector of identification objects whose score types are to be switched.
[in]	type	The desired general score type to switch to. This could be an enum or similar representing different scoring systems (e.g., RAW, LOG, etc.).
[in,out]	counter	A reference to a Size variable that may be used to count certain operations or changes made by this method. The exact usage depends on the implementation details and needs.

Exceptions

Exception::MissingInformation If the first identification object in the vector does not have the requested score type, indicating that the operation cannot proceed.

Note: The method assumes that if the first identification object has the correct score type, all subsequent objects in the vector also have the correct score type. This assumption might need validation depending on the use case.

References OPENMS_LOG_WARN.

Referenced by IDScoreSwitcherAlgorithm::switchToScoreType(), and IDScoreSwitcherAlgorithm::switchToScoreType().

◆ switchToScoreType() [1/2]

static IDSwitchResult switchToScoreType	(	ConsensusMap &	cmap,
		std::string	requested_score_type_as_string,
		bool	include_unassigned = `true`
	)

inlinestatic

Switches the score type of a ConsensusMap to the requested score type.

This static method updates the scores within the provided ConsensusMap to the specified score type. It determines the original score properties, checks if a switch is necessary based on the requested score type, and performs the switch if required.

Parameters

[in]	cmap	The ConsensusMap object whose score types are to be switched.
[in]	requested_score_type_as_string	The desired score type as a string (e.g., "RAW", "PEP", "q-value").
[in]	include_unassigned	Optional flag indicating whether to include unassigned IDs in the score switch. Defaults to true.

Returns: An IDSwitchResult structure containing information about the score switch operation, including the original and requested score names, types, and whether a switch was performed.

◆ switchToScoreType() [2/2]

static IDSwitchResult switchToScoreType	(	PeptideIdentificationList &	pep_ids,
		std::string	requested_score_type_as_string
	)

inlinestatic

Switches the score type of peptide identifications to the requested type.

This static function modifies the provided vector of PeptideIdentification objects by switching their main score to the specified type. If no score type is requested, the original main score is retained. The function determines the original score's name, orientation, and type, and updates these attributes based on the requested score type. If a different score type is requested, it performs the switch and updates the relevant score information.

Parameters

[in]	pep_ids	A vector of PeptideIdentification objects to be processed.
[in]	requested_score_type_as_string	The desired score type as a string (e.g., "RAW", "PEP", "q-value").

Returns: IDSwitchResult A struct containing details about the original and requested score types, whether a switch was performed, and the number of IDs updated.

◆ toScoreTypeEnum()

static ScoreType toScoreTypeEnum ( const std::string & score_type )

inlinestatic

Converts a string representation of a score type to a ScoreType enum.

This static method attempts to map a given string, representing a score type, to the corresponding ScoreType enum value. It handles various common representations of score types, including those with or without the "_score" suffix, and ignores case and special characters like '-', '_', and ' '.

Parameters

[in] score_type The string representation of the score type.

Returns: The corresponding ScoreType enum value.

Exceptions

Exception::MissingInformation If the provided score_type string does not match any known score type.

◆ updateMembers_()

void updateMembers_ ( )

overrideprivatevirtual

documented in base class

Reimplemented from DefaultParamHandler.

Member Data Documentation

◆ higher_better_

bool higher_better_

private

will be set according to the algorithm parameters

◆ new_score_

std::string new_score_

private

will be set according to the algorithm parameters

◆ new_score_type_

std::string new_score_type_

private

◆ old_score_

std::string old_score_

private

◆ tolerance_

const double tolerance_ = 1e-6

private

relative tolerance for score comparisons:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Class Documentation

◆ OpenMS::IDScoreSwitcherAlgorithm::IDSwitchResult

◆ OpenMS::IDScoreSwitcherAlgorithm::ScoreSearchResult

Member Typedef Documentation

◆ ScoreType

Constructor & Destructor Documentation

◆ IDScoreSwitcherAlgorithm()

Member Function Documentation

◆ determineScoreNameOrientationAndType() [1/2]

◆ determineScoreNameOrientationAndType() [2/2]

◆ findScoreType()

◆ getScoreNames()

◆ isScoreType()

◆ isScoreTypeHigherBetter()

◆ switchBackScoreType() [1/2]

◆ switchBackScoreType() [2/2]

◆ switchScores() [1/3]

◆ switchScores() [2/3]

◆ switchScores() [3/3]

◆ switchToGeneralScoreType() [1/3]

◆ switchToGeneralScoreType() [2/3]

◆ switchToGeneralScoreType() [3/3]

◆ switchToScoreType() [1/2]

◆ switchToScoreType() [2/2]

◆ toScoreTypeEnum()

◆ updateMembers_()

Member Data Documentation

◆ higher_better_

◆ new_score_

◆ new_score_type_

◆ old_score_

◆ tolerance_