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

Public Types
enum class	ScoreType { RAW , RAW_EVAL , PP , PEP , FDR , QVAL }
	This is a rough hierarchy of possible score types in MS. More...

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

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

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

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

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

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

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

void	determineScoreNameOrientationAndType (const std::vector< PeptideIdentification > &pep_ids, String &name, bool &higher_better, ScoreType &score_type)
	Determines the score type and orientation of the main score for a set of peptide identifications. More...

void	determineScoreNameOrientationAndType (const ConsensusMap &cmap, 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. More...

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

void	switchScores (std::vector< PeptideIdentification > &pep_ids, Size &counter)
	Switches the scores of peptide identifications. More...

template<typename IDType >
String	findScoreType (IDType &id, IDScoreSwitcherAlgorithm::ScoreType type)
	Searches for a specified score type within an identification object and its meta values. More...

Public Member Functions inherited from DefaultParamHandler
	DefaultParamHandler (const String &name)
	Constructor with name that is displayed in error messages. More...

	DefaultParamHandler (const DefaultParamHandler &rhs)
	Copy constructor. More...

virtual	~DefaultParamHandler ()
	Destructor. More...

DefaultParamHandler &	operator= (const DefaultParamHandler &rhs)
	Assignment operator. More...

virtual bool	operator== (const DefaultParamHandler &rhs) const
	Equality operator. More...

void	setParameters (const Param &param)
	Sets the parameters. More...

const Param &	getParameters () const
	Non-mutable access to the parameters. More...

const Param &	getDefaults () const
	Non-mutable access to the default parameters. More...

const String &	getName () const
	Non-mutable access to the name. More...

void	setName (const String &name)
	Mutable access to the name. More...

const std::vector< String > &	getSubsections () const
	Non-mutable access to the registered subsections. More...

Static Public Member Functions
static ScoreType	toScoreTypeEnum (String score_type)
	Converts a string representation of a score type to a ScoreType enum. More...

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

static IDSwitchResult	switchToScoreType (std::vector< PeptideIdentification > &pep_ids, String requested_score_type_as_string)
	Switches the score type of peptide identifications to the requested type. More...

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

static void	switchBackScoreType (std::vector< PeptideIdentification > &pep_ids, IDSwitchResult isr)
	Reverts the scoring type of peptide identifications to their original scores. More...

Static Public Member Functions inherited from DefaultParamHandler
static void	writeParametersToMetaValues (const Param &write_this, MetaInfoInterface &write_here, const String &key_prefix="")
	Writes all parameters to meta values. More...

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

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

String	new_score_
	will be set according to the algorithm parameters More...

String	new_score_type_

String	old_score_

bool	higher_better_
	will be set according to the algorithm parameters More...

std::map< ScoreType, std::set< String > >	type_to_str_
	a map from ScoreType to their names as used around OpenMS More...

std::map< ScoreType, bool >	type_to_better_
	a map from ScoreType to their ordering More...

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

Protected Attributes inherited from DefaultParamHandler
Param	param_
	Container for current parameters. More...

Param	defaults_
	Container for default parameters. This member should be filled in the constructor of derived classes! More...

std::vector< String >	subsections_
	Container for registered subsections. This member should be filled in the constructor of derived classes! More...

String	error_name_
	Name that is displayed in error messages during the parameter checking. More...

bool	check_defaults_
	If this member is set to false no checking if parameters in done;. More...

bool	warn_empty_defaults_
	If this member is set to false no warning is emitted when defaults are empty;. More...

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	The name of the original score used before the switch.
String	original_score_name
ScoreType	original_score_type	whether a higher original score is better
bool	requested_score_higher_better	the type of the original score
String	requested_score_name	the type of the requested score
ScoreType	requested_score_type	whether a higher requested score is better
bool	score_switched

Member Enumeration Documentation

◆ ScoreType

enum ScoreType

strong

This is a rough hierarchy of possible score types in MS.

In an ideal case, this should be reimplemented to follow ontology hierarchies as soon as e.g. MS-OBO is complete and we switched the Metavalues to CV terms.

Enumerator
RAW	Raw score, e.g., search engine specific scores like hyperscore.
RAW_EVAL	Raw score with E-value, e.g., search engine specific scores like expect score.
PP	Posterior probability.
PEP	Posterior error probability.
FDR	False discovery rate.
QVAL	Q-value.

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,
		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

cmap	The ConsensusMap to inspect.
name	Output parameter to store the determined overall score type.
higher_better	Output parameter to store whether a higher score is considered better.
score_type	Output parameter to store the determined score type.
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 std::vector< PeptideIdentification > &	pep_ids,
		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

pep_ids	The vector of PeptideIdentification objects to inspect.
name	Output parameter to store the determined overall score type.
higher_better	Output parameter to store whether a higher score is considered better.
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 OPENMS_LOG_INFO.

Referenced by IDScoreSwitcherAlgorithm::switchToScoreType().

◆ findScoreType()

String findScoreType	(	IDType &	id,
		IDScoreSwitcherAlgorithm::ScoreType	type
	)

inline

Searches for a specified score type within an identification object and its meta values.

This method attempts to find a given score type in the main score type of an identification object (id) or within its hits' meta values. It first checks if the current main score type of id matches any of the possible score types for the specified type. If not found, it iterates through the meta values of the first hit in id looking for a match. If the score type or a related meta value is found, it is returned as a String. Otherwise, an empty String is returned, indicating the score type is not present.

Template Parameters

IDType The type of the identification object, which must support getScoreType(), getHits(), and meta value operations.

Parameters

[in]	id	The identification object to search for the score type. It is expected to have a main score type and possibly additional scores stored as meta values in its hits.
[in]	type	The `ScoreType` to search for, defined in `IDScoreSwitcherAlgorithm`. This type specifies the score of interest.

Returns: A String representing the found score type. If the score type is not found, an empty String is returned.

Note: This method logs an informational message if the requested score type is already set as the main score, a warning if the identification entry is empty, and another warning if the score type is not found in the UserParams of the checked ID object. It only checks the first hit of the id for meta values.

References OPENMS_LOG_INFO, and OPENMS_LOG_WARN.

Referenced by IDFilter::filterHitsByScore().

◆ getScoreNames()

std::vector<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 String &	score_name,
		const ScoreType &	type
	)

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

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

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

References String::chop(), and String::hasSuffix().

Referenced by IDFilter::filterHitsByScore().

◆ isScoreTypeHigherBetter()

bool isScoreTypeHigherBetter ( ScoreType score_type )

inline

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

Parameters

score_type The score type to check.

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

Referenced by IDFilter::filterHitsByScore(), 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

cmap	The ConsensusMap object whose scores will be modified.
isr	The IDSwitchResult containing information about the score switch.
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	(	std::vector< PeptideIdentification > &	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

pep_ids	A vector of PeptideIdentification objects to be updated.
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

cmap	The ConsensusMap containing peptide identifications whose scores need to be switched.
counter	A reference to a counter that will be incremented for each peptide identification processed.
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]

void switchScores	(	IDType &	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

IDType 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().

◆ switchScores() [3/3]

void switchScores	(	std::vector< PeptideIdentification > &	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

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

◆ switchToGeneralScoreType() [1/2]

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

cmap	The ConsensusMap containing peptide identifications whose scores need to be switched.
type	The desired general score type to switch to.
counter	A reference to a counter that will be incremented for each peptide identification processed.
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(), String::chop(), String::hasSuffix(), and OPENMS_LOG_WARN.

◆ switchToGeneralScoreType() [2/2]

void switchToGeneralScoreType	(	std::vector< IDType > &	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

IDType 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 String::chop(), String::hasSuffix(), and OPENMS_LOG_WARN.

Referenced by IDScoreSwitcherAlgorithm::switchToScoreType().

◆ switchToScoreType() [1/2]

static IDSwitchResult switchToScoreType	(	ConsensusMap &	cmap,
		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

cmap	The ConsensusMap object whose score types are to be switched.
requested_score_type_as_string	The desired score type as a string (e.g., "RAW", "PEP", "q-value").
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	(	std::vector< PeptideIdentification > &	pep_ids,
		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

pep_ids	A vector of PeptideIdentification objects to be processed.
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 ( 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

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.

References OpenMS::Constants::c, String::chop(), String::hasSuffix(), and String::toLower().

Referenced by IDScoreSwitcherAlgorithm::switchToScoreType().

◆ 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_

String new_score_

private

will be set according to the algorithm parameters

◆ new_score_type_

String new_score_type_

private

◆ old_score_

String old_score_

private

◆ tolerance_

const double tolerance_ = 1e-6

private

relative tolerance for score comparisons:

◆ type_to_better_

std::map<ScoreType, bool> type_to_better_

private

Initial value:

=
        {
            {ScoreType::RAW, true}, 
            {ScoreType::RAW_EVAL, false},
            {ScoreType::PP, true},
            {ScoreType::PEP, false},
            {ScoreType::FDR, false},
            {ScoreType::QVAL, false}
        }

a map from ScoreType to their ordering

◆ type_to_str_

std::map<ScoreType, std::set<String> > type_to_str_

private

Initial value:

=
        {
            
            {ScoreType::RAW, {"svm", "MS:1001492", "XTandem", "OMSSA", "SEQUEST:xcorr", "Mascot", "mvh", "hyperscore", "ln(hyperscore)"}},
            
            
            
            
            
            {ScoreType::RAW_EVAL, {"expect", "SpecEValue", "E-Value", "evalue", "MS:1002053", "MS:1002257"}},
            {ScoreType::PP, {"Posterior Probability"}},
            {ScoreType::PEP, {"Posterior Error Probability", "pep", "MS:1001493"}}, 
            {ScoreType::FDR, {"FDR", "fdr", "false discovery rate"}},
            {ScoreType::QVAL, {"q-value", "qvalue", "MS:1001491", "q-Value", "qval"}}
        }

a map from ScoreType to their names as used around OpenMS

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

Member Enumeration 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/2]

◆ switchToGeneralScoreType() [2/2]

◆ switchToScoreType() [1/2]

◆ switchToScoreType() [2/2]

◆ toScoreTypeEnum()

◆ updateMembers_()

Member Data Documentation

◆ higher_better_

◆ new_score_

◆ new_score_type_

◆ old_score_

◆ tolerance_

◆ type_to_better_

◆ type_to_str_