Calculates false discovery rates (FDR) from identifications. More...

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

Inheritance diagram for FalseDiscoveryRate:

Collaboration diagram for FalseDiscoveryRate:

Classes
class	DecoyStringHelper
	Finds decoy strings in ProteinIdentification runs. More...

Public Member Functions
	FalseDiscoveryRate ()
	Default constructor.

void	apply (PeptideIdentificationList &fwd_ids, PeptideIdentificationList &rev_ids) const
	Calculates the FDR of two runs, a forward run and a decoy run on peptide level.

void	apply (PeptideIdentificationList &id, bool annotate_peptide_fdr=false) const
	Calculates the FDR of one run from a concatenated sequence DB search.

void	apply (std::vector< ProteinIdentification > &fwd_ids, std::vector< ProteinIdentification > &rev_ids) const
	Calculates the FDR of two runs, a forward run and decoy run on protein level.

void	apply (std::vector< ProteinIdentification > &ids) const
	Calculate the FDR of one run from a concatenated sequence db search.

void	applyEstimated (std::vector< ProteinIdentification > &ids) const
	Calculate the FDR based on PEPs or PPs (if present) and modifies the IDs inplace.

double	applyEvaluateProteinIDs (const std::vector< ProteinIdentification > &ids, double pepCutoff=1.0, UInt fpCutoff=50, double diffWeight=0.2) const
	Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

double	applyEvaluateProteinIDs (const ProteinIdentification &ids, double pepCutoff=1.0, UInt fpCutoff=50, double diffWeight=0.2) const
	Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

double	applyEvaluateProteinIDs (ScoreToTgtDecLabelPairs &score_to_tgt_dec_fraction_pairs, double pepCutoff=1.0, UInt fpCutoff=50, double diffWeight=0.2) const
	Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

void	applyBasic (const std::vector< ProteinIdentification > &run_info, PeptideIdentificationList &ids)
	simpler reimplementation of the apply function above for PSMs. With charge and identifier info from `run_info`

void	applyBasic (PeptideIdentificationList &ids, bool higher_score_better, int charge=0, std::string identifier="", bool only_best_per_pep=false)
	simpler reimplementation of the apply function above for PSMs or peptides.

void	applyBasicPeptideLevel (PeptideIdentificationList &ids)

void	applyBasicPeptideLevel (ConsensusMap &ids, bool use_unassigned_peptides=true)

void	applyBasic (ConsensusMap &cmap, bool use_unassigned_peptides=true)
	simpler reimplementation of the apply function above for peptides in ConsensusMaps.

void	applyBasic (ProteinIdentification &id, bool groups_too=true)
	simpler reimplementation of the apply function above for proteins.

void	applyPickedProteinFDR (ProteinIdentification &id, std::string decoy_string="", bool prefix=true, bool groups_too=true)
	Applies a picked protein FDR. Behaves like a normal target-decoy FDR where only the score of the best protein per target-decoy pair is used. A pair is calculated by checking accession equality after removing the decoy string. If `decoy_string` is empty, we try to guess it. If you set `decoy_string` you should also set `prefix` and say if the string is a prefix (true) or suffix (false). `groups_too` decides if also a (indistinguishable) group-level FDR will be calculated. Here a group score will be taken if not ALL proteins in the group were picked already. Targets preferred.

double	rocN (const PeptideIdentificationList &ids, Size fp_cutoff) const

double	rocN (const PeptideIdentificationList &ids, Size fp_cutoff, const std::string &identifier) const

double	rocN (const ConsensusMap &ids, Size fp_cutoff, bool include_unassigned_peptides=false) const

double	rocN (const ConsensusMap &ids, Size fp_cutoff, const std::string &identifier, bool include_unassigned_peptides=false) const

double	diffEstimatedEmpirical (const ScoreToTgtDecLabelPairs &scores_labels, double pepCutoff=1.0) const
	calculates the area of the difference between estimated and empirical FDR on the fly. Does not store results.

double	rocN (const ScoreToTgtDecLabelPairs &scores_labels, Size fpCutoff=50) const

IdentificationData::ScoreTypeRef	applyToObservationMatches (IdentificationData &id_data, IdentificationData::ScoreTypeRef score_ref) const
	Calculate FDR on the level of observation matches (e.g. peptide-spectrum matches) for "general" identification data.

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.

Private Member Functions
	FalseDiscoveryRate (const FalseDiscoveryRate &)
	Not implemented.

FalseDiscoveryRate &	operator= (const FalseDiscoveryRate &)
	Not implemented.

void	calculateFDRs_ (std::map< double, double > &score_to_fdr, std::vector< double > &target_scores, std::vector< double > &decoy_scores, bool q_value, bool higher_score_better) const
	calculates the FDR, given two vectors of scores

void	handleObservationMatch_ (IdentificationData::ObservationMatchRef match_ref, IdentificationData::ScoreTypeRef score_ref, std::vector< double > &target_scores, std::vector< double > &decoy_scores, std::map< IdentificationData::IdentifiedMolecule, bool > &molecule_to_decoy, std::map< IdentificationData::ObservationMatchRef, double > &match_to_score) const
	Helper function for applyToObservationMatches()

void	calculateEstimatedQVal_ (std::map< double, double > &scores_to_FDR, ScoreToTgtDecLabelPairs &scores_labels, bool higher_score_better) const

void	calculateFDRBasic_ (std::map< double, double > &scores_to_FDR, ScoreToTgtDecLabelPairs &scores_labels, bool qvalue, bool higher_score_better) const

double	trapezoidal_area_xEqy (double exp1, double exp2, double act1, double act2) const

double	trapezoidal_area (double x1, double x2, double y1, double y2) const
	calculates the trapezoidal area for a trapezoid with a flat horizontal base e.g. for an AUC

Additional Inherited Members
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.

Protected Member Functions inherited from DefaultParamHandler
virtual void	updateMembers_ ()
	This method is used to update extra member variables at the end of the setParameters() method.

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

Calculates false discovery rates (FDR) from identifications.

Either two runs of forward and decoy database identification or one run containing both (with annotations) can be used to annotate each of the peptide hits with an FDR or q-value.

q-values are basically only adjusted p-values, also ranging from 0 to 1, with lower values being preferable. When looking at the list of hits ordered by q-values, then a specific q-value of x means that x*100 percent of hits with a q-value <= x are expected to be false positives.

Only simple target-decoy FDRs are supported with a formula depending on the "conservative" parameter:

false: (D+1)/T.
true: (D+1)/(T+D) [for comparison with protein level FDR used by other tools like e.g., Fido] For protein groups, a group is considered as a target when it contains at least one target protein. Group level FDRs assume the same score type as on protein level.

For peptide hits, a hit is considered target also if it maps to both a target and a decoy protein (i.e. "target+decoy") as value in the "target_decoy" metavalue e.g. annotated by PeptideIndexer

Note: The parameter add_decoy_proteins currently does not affect groups

Parameters of this class are:

Name	Type	Default	Restrictions	Description
no_qvalues	string	false	true, false	If 'true' strict FDRs will be calculated instead of q-values (the default)
use_all_hits	string	false	true, false	If 'true' not only the first hit, but all are used (peptides only)
split_charge_variants	string	false	true, false	If 'true' charge variants are treated separately (for peptides of combined target/decoy searches only).
treat_runs_separately	string	false	true, false	If 'true' different search runs are treated separately (for peptides of combined target/decoy searches only).
add_decoy_peptides	string	false	true, false	If 'true' decoy peptides will be written to output file, too. The q-value is set to the closest target score.
add_decoy_proteins	string	false	true, false	If 'true' decoy proteins will be written to output file, too. The q-value is set to the closest target score.
conservative	string	true	true, false	If 'true' (D+1)/T instead of (D+1)/(T+D) is used as a formula.

Note:

If a section name is documented, the documentation is displayed as tooltip.
Advanced parameter names are italic.

Constructor & Destructor Documentation

◆ FalseDiscoveryRate() [1/2]

FalseDiscoveryRate ( )

Default constructor.

◆ FalseDiscoveryRate() [2/2]

FalseDiscoveryRate ( const FalseDiscoveryRate & )

private

Not implemented.

Member Function Documentation

◆ apply() [1/4]

void apply	(	PeptideIdentificationList &	fwd_ids,
		PeptideIdentificationList &	rev_ids
	)		const

Calculates the FDR of two runs, a forward run and a decoy run on peptide level.

Parameters

[in,out]	fwd_ids	forward peptide identifications
[in,out]	rev_ids	reverse peptide identifications

◆ apply() [2/4]

void apply	(	PeptideIdentificationList &	id,
		bool	annotate_peptide_fdr = `false`
	)		const

Calculates the FDR of one run from a concatenated sequence DB search.

Parameters

[in,out]	id	peptide identifications, containing target and decoy hits
[in]	annotate_peptide_fdr	adds the peptide q-value or peptide fdr meta value to each PSM. Calculation uses best PSM per peptide.

◆ apply() [3/4]

void apply	(	std::vector< ProteinIdentification > &	fwd_ids,
		std::vector< ProteinIdentification > &	rev_ids
	)		const

Calculates the FDR of two runs, a forward run and decoy run on protein level.

Parameters

[in,out]	fwd_ids	forward protein identifications
[in,out]	rev_ids	reverse protein identifications

◆ apply() [4/4]

void apply ( std::vector< ProteinIdentification > & ids ) const

Calculate the FDR of one run from a concatenated sequence db search.

Parameters

[in,out] ids protein identifications, containing target and decoy hits

◆ applyBasic() [1/4]

void applyBasic	(	ConsensusMap &	cmap,
		bool	use_unassigned_peptides = `true`
	)

simpler reimplementation of the apply function above for peptides in ConsensusMaps.

◆ applyBasic() [2/4]

void applyBasic	(	const std::vector< ProteinIdentification > &	run_info,
		PeptideIdentificationList &	ids
	)

simpler reimplementation of the apply function above for PSMs. With charge and identifier info from run_info

◆ applyBasic() [3/4]

void applyBasic	(	PeptideIdentificationList &	ids,
		bool	higher_score_better,
		int	charge = `0`,
		std::string	identifier = `""`,
		bool	only_best_per_pep = `false`
	)

simpler reimplementation of the apply function above for PSMs or peptides.

◆ applyBasic() [4/4]

void applyBasic	(	ProteinIdentification &	id,
		bool	groups_too = `true`
	)

simpler reimplementation of the apply function above for proteins.

◆ applyBasicPeptideLevel() [1/2]

void applyBasicPeptideLevel	(	ConsensusMap &	ids,
		bool	use_unassigned_peptides = `true`
	)

like applyBasic with "only_best_per_peptide" but it assigns a score to EVERY PSM sharing the peptide sequence with the best representative. Useful if all hits need to have a peptide score (e.g., for mzTab report). No support for specific charges, runs etc. yet

◆ applyBasicPeptideLevel() [2/2]

void applyBasicPeptideLevel ( PeptideIdentificationList & ids )

like applyBasic with "only_best_per_peptide" but it assigns a score to EVERY PSM sharing the peptide sequence with the best representative. Useful if all hits need to have a peptide score (e.g., for mzTab report). No support for specific charges, runs etc. yet

◆ applyEstimated()

void applyEstimated ( std::vector< ProteinIdentification > & ids ) const

Calculate the FDR based on PEPs or PPs (if present) and modifies the IDs inplace.

Parameters

[in,out] ids protein identifications, containing PEP scores (not necessarily) annotated with target decoy.

◆ applyEvaluateProteinIDs() [1/3]

double applyEvaluateProteinIDs	(	const ProteinIdentification &	ids,
		double	pepCutoff = `1.0`,
		UInt	fpCutoff = `50`,
		double	diffWeight = `0.2`
	)		const

Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

Parameters

[in]	ids	protein identifications, containing PEP scores annotated with target decoy.
[in]	pepCutoff	up to which PEP should the differences between the two FDRs be calculated
[in]	fpCutoff	up to which nr. of false positives should the target-decoy AUC be evaluated
[in]	diffWeight	which weight should the difference get. The ROC-N value gets 1 - this weight.

◆ applyEvaluateProteinIDs() [2/3]

double applyEvaluateProteinIDs	(	const std::vector< ProteinIdentification > &	ids,
		double	pepCutoff = `1.0`,
		UInt	fpCutoff = `50`,
		double	diffWeight = `0.2`
	)		const

Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

Parameters

[in]	ids	protein identifications, containing PEP scores annotated with target decoy. Only first run will be evaluated.
[in]	pepCutoff	up to which PEP should the differences between the two FDRs be calculated
[in]	fpCutoff	up to which nr. of false positives should the target-decoy AUC be evaluated
[in]	diffWeight	which weight should the difference get. The ROC-N value gets 1 - this weight.

◆ applyEvaluateProteinIDs() [3/3]

double applyEvaluateProteinIDs	(	ScoreToTgtDecLabelPairs &	score_to_tgt_dec_fraction_pairs,
		double	pepCutoff = `1.0`,
		UInt	fpCutoff = `50`,
		double	diffWeight = `0.2`
	)		const

Calculate a linear combination of the area of the difference in estimated vs. empirical (TD) FDR and the ROC-N value (AUC up to first N false positives).

Parameters

[in,out]	score_to_tgt_dec_fraction_pairs	extracted scores of protein(group) identifications, containing PEP scores annotated with target decoy fractions. Simple case target=1, decoy=0.
[in]	pepCutoff	up to which PEP should the differences between the two FDRs be calculated
[in]	fpCutoff	up to which nr. of false positives should the target-decoy AUC be evaluated
[in]	diffWeight	which weight should the difference get. The ROC-N value gets 1 - this weight.

◆ applyPickedProteinFDR()

void applyPickedProteinFDR	(	ProteinIdentification &	id,
		std::string	decoy_string = `""`,
		bool	prefix = `true`,
		bool	groups_too = `true`
	)

Applies a picked protein FDR. Behaves like a normal target-decoy FDR where only the score of the best protein per target-decoy pair is used. A pair is calculated by checking accession equality after removing the decoy string. If decoy_string is empty, we try to guess it. If you set decoy_string you should also set prefix and say if the string is a prefix (true) or suffix (false). groups_too decides if also a (indistinguishable) group-level FDR will be calculated. Here a group score will be taken if not ALL proteins in the group were picked already. Targets preferred.

◆ applyToObservationMatches()

IdentificationData::ScoreTypeRef applyToObservationMatches	(	IdentificationData &	id_data,
		IdentificationData::ScoreTypeRef	score_ref
	)		const

Calculate FDR on the level of observation matches (e.g. peptide-spectrum matches) for "general" identification data.

Parameters

[in,out]	id_data	Identification data
[in]	score_ref	Key of the score to use for FDR calculation

Returns: Key of the FDR score

Referenced by NucleicAcidSearchEngine::calculateAndFilterFDR_().

◆ calculateEstimatedQVal_()

void calculateEstimatedQVal_	(	std::map< double, double > &	scores_to_FDR,
		ScoreToTgtDecLabelPairs &	scores_labels,
		bool	higher_score_better
	)		const

private

calculates an estimated FDR (based on P(E)Ps) given a vector of score value pairs and fills a map for lookup in scores_to_FDR

◆ calculateFDRBasic_()

void calculateFDRBasic_	(	std::map< double, double > &	scores_to_FDR,
		ScoreToTgtDecLabelPairs &	scores_labels,
		bool	qvalue,
		bool	higher_score_better
	)		const

private

calculates the FDR with a basic and faster algorithm Just goes through the sorted scores and counts the number of decoys and targets and annotates the FDR for this score as it goes. Q-values are optionally annotated by calculating the cumulative minimum in reversed order afterwards. Since I never understood our other algorithm, I can not explain the difference.

Note: Formula used depends on Param "conservative": false -> (D+1)/T, true (e.g. used in Fido) -> (D+1)/(T+D)

◆ calculateFDRs_()

void calculateFDRs_	(	std::map< double, double > &	score_to_fdr,
		std::vector< double > &	target_scores,
		std::vector< double > &	decoy_scores,
		bool	q_value,
		bool	higher_score_better
	)		const

private

calculates the FDR, given two vectors of scores

◆ diffEstimatedEmpirical()

double diffEstimatedEmpirical	(	const ScoreToTgtDecLabelPairs &	scores_labels,
		double	pepCutoff = `1.0`
	)		const

calculates the area of the difference between estimated and empirical FDR on the fly. Does not store results.

◆ handleObservationMatch_()

void handleObservationMatch_	(	IdentificationData::ObservationMatchRef	match_ref,
		IdentificationData::ScoreTypeRef	score_ref,
		std::vector< double > &	target_scores,
		std::vector< double > &	decoy_scores,
		std::map< IdentificationData::IdentifiedMolecule, bool > &	molecule_to_decoy,
		std::map< IdentificationData::ObservationMatchRef, double > &	match_to_score
	)		const

private

Helper function for applyToObservationMatches()

◆ operator=()

FalseDiscoveryRate & operator= ( const FalseDiscoveryRate & )

private

Not implemented.

◆ rocN() [1/5]

double rocN	(	const ConsensusMap &	ids,
		Size	fp_cutoff,
		bool	include_unassigned_peptides = `false`
	)		const

calculates the AUC until the first fp_cutoff False positive pep IDs (takes all runs together) if fp_cutoff = 0, it will calculate the full AUC

◆ rocN() [2/5]

double rocN	(	const ConsensusMap &	ids,
		Size	fp_cutoff,
		const std::string &	identifier,
		bool	include_unassigned_peptides = `false`
	)		const

calculates the AUC until the first fp_cutoff False positive pep IDs. if fp_cutoff = 0, it will calculate the full AUC. Restricted to IDs from a specific ID run with identifier.

◆ rocN() [3/5]

double rocN	(	const PeptideIdentificationList &	ids,
		Size	fp_cutoff
	)		const

calculates the AUC until the first fp_cutoff False positive pep IDs (currently only takes all runs together) if fp_cutoff = 0, it will calculate the full AUC

◆ rocN() [4/5]

double rocN	(	const PeptideIdentificationList &	ids,
		Size	fp_cutoff,
		const std::string &	identifier
	)		const

calculates the AUC until the first fp_cutoff False positive pep IDs (currently only takes all runs together) if fp_cutoff = 0, it will calculate the full AUC. Restricted to IDs from a specific ID run.

◆ rocN() [5/5]

double rocN	(	const ScoreToTgtDecLabelPairs &	scores_labels,
		Size	fpCutoff = `50`
	)		const

calculates AUC of empirical FDR up to the first fpCutoff false positives on the fly. Does not store results. use e.g. fpCutoff = scores_labels.size() for complete AUC

◆ trapezoidal_area()

double trapezoidal_area	(	double	x1,
		double	x2,
		double	y1,
		double	y2
	)		const

private

calculates the trapezoidal area for a trapezoid with a flat horizontal base e.g. for an AUC

◆ trapezoidal_area_xEqy()

double trapezoidal_area_xEqy	(	double	exp1,
		double	exp2,
		double	act1,
		double	act2
	)		const

private

calculates the error area around the x=x line between two consecutive values of expected and actual i.e. it assumes exp2 > exp1

Classes

Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FalseDiscoveryRate() [1/2]

◆ FalseDiscoveryRate() [2/2]

Member Function Documentation

◆ apply() [1/4]

◆ apply() [2/4]

◆ apply() [3/4]

◆ apply() [4/4]

◆ applyBasic() [1/4]

◆ applyBasic() [2/4]

◆ applyBasic() [3/4]

◆ applyBasic() [4/4]

◆ applyBasicPeptideLevel() [1/2]

◆ applyBasicPeptideLevel() [2/2]

◆ applyEstimated()

◆ applyEvaluateProteinIDs() [1/3]

◆ applyEvaluateProteinIDs() [2/3]

◆ applyEvaluateProteinIDs() [3/3]

◆ applyPickedProteinFDR()

◆ applyToObservationMatches()

◆ calculateEstimatedQVal_()

◆ calculateFDRBasic_()

◆ calculateFDRs_()

◆ diffEstimatedEmpirical()

◆ handleObservationMatch_()

◆ operator=()

◆ rocN() [1/5]

◆ rocN() [2/5]

◆ rocN() [3/5]

◆ rocN() [4/5]

◆ rocN() [5/5]

◆ trapezoidal_area()

◆ trapezoidal_area_xEqy()