ms_quantitation Class Reference

Base class for peptide and protein quantitation. More...

#include <ms_quantitation.hpp>

Inheritance diagram for ms_quantitation:

Collaboration diagram for ms_quantitation:

Public Member Functions
virtual	~ms_quantitation ()=0
	Destructor.
void	addHeaderField (const std::string &name, const std::string &value)
	Adds an item of project or search header information.
void	addRawFileField (const unsigned int id, const std::string &name, const std::string &value)
	Adds an item of raw file header information.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
void	clearHeaderFields ()
	Clears any header information from the result.
void	clearRawFileFields ()
	Clears any raw file header information from the result.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
virtual int	countDistinctPeptides (const ms_peptide_quant_key_vector &activeKeys) const
	Get the number of distinct peptides in the list of active candidates.
virtual int	countDistinctPeptides (const std::vector< ms_peptide_quant_key > &activeKeys) const
	Get the number of distinct peptides in the list of active candidates.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
ms_peptide_quant_key_vector	getPeptideQuantKeys (const std::string &accession, int dbIdx) const
	Look up peptide quant keys associated with a given protein, if any.
virtual ms_peptide_quant_ratio	getPeptideRatio (const ms_peptide_quant_key &key, const std::string &ratioName) const =0
	Given peptide quant key and ratio name, return the corresponding peptide ratio data.
double	getPeptideRatioNormalisationBase (const std::string &ratioName) const
	Get the peptide ratio normalisation base of the given ratio name.
const ms_progress_info &	getProgressInfo ()
	Get information about the progress of a currently running long operation (e.g. loading from a file).
virtual ms_protein_quant_ratio	getProteinRatio (const std::string &accession, int dbIdx, const std::string &ratioName) const =0
	Given the protein accession, database ID and ratio name, return the protein ratio data.
virtual ms_protein_quant_ratio	getProteinRatio (const std::string &accession, int dbIdx, const std::string &ratioName, const ms_peptide_quant_key_vector &includeKeys, const ms_peptide_quant_key_vector &excludeKeys) const =0
	Given the protein accession, database ID and ratio name, return the protein ratio data, overriding the default inclusion and exclusion of the specified peptide quant keys.
const ms_quant_method &	getQuantitationMethod () const
	Return the current quantitation method.
virtual bool	hasPeptideRatio (const ms_peptide_quant_key &key, const std::string &ratioName) const =0
	Existence check: return true if a peptide ratio with the associated peptide quant key and ratio name exists.
virtual bool	isPeptideRatioExcluded (const ms_peptide_quant_key &key, const std::string &ratioName) const =0
	Boolean flag: is the given peptide ratio globally excluded from protein ratio calculation?
bool	isValid () const
	Call this function to determine if there have been any errors.
void	removePeptideRatioNormalisationBase (const std::string &ratioName)
	Reset the peptide ratio normalisation base of the given ratio name.
void	removePeptideRatioNormalisationBases ()
	Reset all peptide ratio normalisation bases.
void	setMinNumPeptides (int value)
	Set the minimum number of peptides needed for protein ratio calculation.
virtual void	setPeptideRatioExcluded (const ms_peptide_quant_key &key, const std::string &ratioName)=0
	Globally exclude a particular peptide ratio from protein ratio calculation.
virtual void	setPeptideRatioIncluded (const ms_peptide_quant_key &key, const std::string &ratioName)=0
	Globally include a particular peptide ratio in protein ratio calculation.
void	setPeptideRatioNormalisationBase (const std::string &ratioName, double b)
	Set the peptide ratio normalisation base of the given ratio name.
virtual void	setProteinRatioType (const char *value)=0
	Set the protein ratio type.
virtual void	setQuantOutliers (const ms_quant_outliers *)=0
	Set new peptide ratio outlier settings.

Protected Member Functions
ms_protein_quant_ratio	calculateGeometricMeanRatio (const std::string &accession, int dbIdx, const std::string &ratioName, const std::vector< double > &sample, const std::vector< double > &logSample, const std::vector< ms_peptide_quant_key > &activeKeys, const std::map< ms_peptide_quant_key, int > &inactiveKeys, double normalityPvalue) const
	Given a sample of peptide ratios, calculate the geometric mean and standard deviation.
ms_protein_quant_ratio	calculateMedianRatio (const std::string &accession, int dbIdx, const std::string &ratioName, const std::vector< double > &sample, const std::vector< double > &logSample, const std::vector< ms_peptide_quant_key > &activeKeys, const std::map< ms_peptide_quant_key, int > &inactiveKeys, double normalityPvalue) const
	Given a sample of peptide ratios, calculate the median and standard deviation from the median.
ms_protein_quant_ratio	calculateWeightedGeometricMeanRatio (const std::string &accession, int dbIdx, const std::string &ratioName, const std::vector< double > &sample, const std::vector< double > &logSample, const std::vector< double > &weights, const std::vector< ms_peptide_quant_key > &activeKeys, const std::map< ms_peptide_quant_key, int > &inactiveKeys, double normalityPvalue) const
	Given a sample of peptide ratios, calculate the weighted geometric mean and standard deviation.
int	getMinNumPeptides () const
	Get the minimum number of peptides needed for protein ratio calculation.
void	getProteinRatioSample (const std::string &accession, int dbIdx, const std::string &ratioName, const std::vector< ms_peptide_quant_key > &includeKeys, const std::vector< ms_peptide_quant_key > &excludeKeys, std::vector< double > &sample, std::vector< double > &logSample, std::vector< double > &weights, std::vector< ms_peptide_quant_key > &activeKeys, std::map< ms_peptide_quant_key, int > &inactiveKeys, double &normalityPvalue) const
	Find the peptide quant keys associated with the protein, collect their unique peptide ratios, remove outliers (if desired) and return the values as the sample of peptide ratios.
virtual void	getSortedFinitePeptideRatioValues (const std::string &ratioName, const std::set< ms_peptide_quant_key > &keys, const std::set< ms_peptide_quant_key > &includeKeys, const std::set< ms_peptide_quant_key > &excludeKeys, std::vector< double > &values, std::vector< double > &weights, std::vector< ms_peptide_quant_key > &activeKeys, std::map< ms_peptide_quant_key, int > &inactiveKeys) const =0
	Given a list of q,p values and ratio name, find the non-infinite peptide ratio values and return them in numerically increasing order.
bool	initialiseBaseSettings (const ms_quant_method &qmBase, const ms_quant_method &qmConfig)
	Initialise quantitation method settings from the two method objects.

Protected Attributes
protein_to_peptide_quant_key_t	proteinKeys_
	Protein-to-peptide mapping.

Detailed Description

Base class for peptide and protein quantitation.

ms_quantitation is an abstract class and cannot be instantiated. It provides shared read access methods for two child classes: ms_ms2quantitation and ms_customquantitation. See Peptide and protein quantitation and child class documentation for details and use cases.

You always need to define a quantitation method when creating an object of either kind. For ms_ms2quantitation, a full quantitation method definition is needed, including protocol settings, component definitions, peptide quality settings and protein ratio settings. Usually it is easiest to use the quantitation method from the Mascot results file and customise it as needed; see ms_mascotresfilebase::getQuantitationMethod() and the ms_ms2quantitation constructor for details.

For ms_customquantitation, the minimum the quantitation method needs to define is protein ratio settings. If you have a Mascot results file, it won't hurt to use the quantitation method from the results file as base configuration. However, the class will not use any component or peptide quality settings.

The input quantitation method needs to be distinguished from the current (or effective) quantitation method. The class will always create a copy of the quantitation method used as input, and allows changing some of its parameters later to alter how protein ratios are calculated or to change normalisation settings. You have read-only access to the current quantitation method with getQuantitationMethod().

The base class provides three kinds of functionality:

1. Access peptide ratios:
   • hasPeptideRatio(const ms_peptide_quant_key&, const std::string &) const
   • getPeptideRatio(const ms_peptide_quant_key&, const std::string &) const
2. Access protein ratios and associated peptide quant keys:
   • getProteinRatio(const std::string &, int, const std::string &) const
   • getProteinRatio(const std::string &, int, const std::string &, const ms_peptide_quant_key_vector &includeKeys, const ms_peptide_quant_key_vector &excludeKeys) const
   • getPeptideQuantKeys(const std::string &, int) const
3. Access and modify quantitation method settings related to protein ratio calculation:
   • getQuantitationMethod() const
   • setPeptideRatioExcluded(const ms_peptide_quant_key &, const std::string &)
   • setQuantOutliers(const ms_quant_outliers *)
   • setMinNumPeptides(int value)
   • setProteinRatioType(const char *value)

Protein ratios are calculated from peptide ratios on demand, which means changing any of the protein ratio related quantitation method settings will take effect immediately. Depending on child class, peptide ratios are either extracted from a Mascot results file (ms_ms2quantitation) or constructed manually (ms_customquantitation).

Two kinds of indexing are used: peptide ratios are identified by the tuple (peptide quant key, ratio name) and protein ratios are identified by the triplet (accession, database index, ratio name). Ratio name refers to the name of report ratios defined in the quantitation method. For example, for iTRAQ 4-plex this could be "115/114", "116/114" and "117/114". You can find the ratio names from the quantitation method object using ms_quant_method::getReportRatioByNumber().

In ms_ms2quantitation, the mapping between peptide ratios and the peptide ID triplet is one-to-one; that is, each peptide ratio has a single associated query and rank (q,p value), from which its peptide quant key is constructed.

In ms_customquantitation, peptide quant keys are free-form.

In both cases, the protein database index is usually the return value of ms_protein::getDB() for Mascot search results, but need not be in ms_customquantitation. See the latter's documentation for details.

Member Function Documentation

appendErrors()

void appendErrors ( const ms_errors &  src )

inherited

Copies all errors from another instance and appends them at the end of own list.

Parameters

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

calculateGeometricMeanRatio()

ms_protein_quant_ratio calculateGeometricMeanRatio ( const std::string &  accession, int  dbIdx, const std::string &  ratioName, const std::vector< double > &  sample, const std::vector< double > &  logSample, const std::vector< ms_peptide_quant_key > &  activeKeys, const std::map< ms_peptide_quant_key, int > &  inactiveKeys, double  normalityPvalue  ) const

protected

Given a sample of peptide ratios, calculate the geometric mean and standard deviation.

Parameters

accession	Protein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdx	Protein database index. This is returned verbatim in the returned object and not used otherwise.
ratioName	Ratio name. This is returned verbatim in the returned object and not used otherwise.
sample	Sample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSample	Log transform of sample.
normalityPvalue	The p-value that logSample looks normally distributed.
activeKeys	Peptide quant keys for which sample values are present.
inactiveKeys	Peptide quant keys ignored due to being skipped, excluded or detected as outliers.

Returns

A protein ratio object encapsulating the calculated ratio, standard deviation and p-value, if relevant.

calculateMedianRatio()

ms_protein_quant_ratio calculateMedianRatio ( const std::string &  accession, int  dbIdx, const std::string &  ratioName, const std::vector< double > &  sample, const std::vector< double > &  logSample, const std::vector< ms_peptide_quant_key > &  activeKeys, const std::map< ms_peptide_quant_key, int > &  inactiveKeys, double  normalityPvalue  ) const

protected

Given a sample of peptide ratios, calculate the median and standard deviation from the median.

See ms_quant_stats::sortedMedian for details of how this is calculated.

Parameters

accession	Protein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdx	Protein database index. This is returned verbatim in the returned object and not used otherwise.
ratioName	Ratio name. This is returned verbatim in the returned object and not used otherwise.
sample	Sample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSample	Log transform of sample.
normalityPvalue	The p-value that logSample looks normally distributed.
activeKeys	Peptide quant keys for which sample values are present.
inactiveKeys	Peptide quant keys ignored due to being skipped, excluded or detected as outliers.

Returns

A protein ratio object encapsulating the calculated ratio, standard deviation and p-values, if relevant.

calculateWeightedGeometricMeanRatio()

ms_protein_quant_ratio calculateWeightedGeometricMeanRatio ( const std::string &  accession, int  dbIdx, const std::string &  ratioName, const std::vector< double > &  sample, const std::vector< double > &  logSample, const std::vector< double > &  weights, const std::vector< ms_peptide_quant_key > &  activeKeys, const std::map< ms_peptide_quant_key, int > &  inactiveKeys, double  normalityPvalue  ) const

protected

Given a sample of peptide ratios, calculate the weighted geometric mean and standard deviation.

Parameters

accession	Protein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdx	Protein database index. This is returned verbatim in the returned object and not used otherwise.
ratioName	Ratio name. This is returned verbatim in the returned object and not used otherwise.
sample	Sample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSample	Log transform of sample.
weights	Weighting factors corresponding to the order of sample (and logSample).
normalityPvalue	The p-value that logSample looks normally distributed.
activeKeys	Peptide quant keys for which sample values are present.
inactiveKeys	Peptide quant keys ignored due to being skipped, excluded or detected as outliers.

Returns

A protein ratio object encapsulating the calculated ratio, standard deviation and p-value, if relevant.

clearAllErrors()

void clearAllErrors ( )

inherited

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also

isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples

common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

copyFrom()

void copyFrom ( const ms_errors *  right )

inherited

Use this member to make a copy of another instance.

Parameters

right

is the source to initialise from

countDistinctPeptides() [1/2]

int countDistinctPeptides ( const ms_peptide_quant_key_vector &  activeKeys ) const

virtual

Get the number of distinct peptides in the list of active candidates.

The base class ms_quantitation does not have enough infomation about the peptides associated with each ms_peptide_quant_key to determine if they are truly distinct. By default, the number of distinct peptides is the number of elements in activeKeys.

In ms_ms1quantitation and ms_ms2quantitation, peptides are treated as distinctly different only if they have a difference in their peptide string.

This function just calls countDistinctPeptides() relevant to the implementing class (ms_ms1quantitation or ms_ms2quantitation).

Parameters

activeKeys

Peptide quant keys that are included in the quantitation of a protein.

Returns

The number of distinct peptides.

Reimplemented in ms_ms1quantitation, and ms_ms2quantitation.

countDistinctPeptides() [2/2]

int countDistinctPeptides ( const std::vector< ms_peptide_quant_key > &  activeKeys ) const

virtual

Get the number of distinct peptides in the list of active candidates.

The base class ms_quantitation does not have enough infomation about the peptides associated with each ms_peptide_quant_key to determine if they are truly distinct. By default, the number of distinct peptides is the number of elements in activeKeys.

In ms_ms1quantitation and ms_ms2quantitation, peptides are treated as distinctly different only if they have a difference in their peptide string.

Parameters

activeKeys

Peptide quant keys that are included in the quantitation of a protein.

Returns

The number of distinct peptides.

Reimplemented in ms_ms1quantitation, ms_ms1quantitation, ms_ms2quantitation, and ms_ms2quantitation.

getErrorHandler()

const ms_errs * getErrorHandler ( ) const

inherited

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns

Constant pointer to the error handler

See also

isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, and http_helper_getstring.cpp.

getLastError()

int getLastError ( ) const

inherited

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also

isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns

the error number of the last error, or 0 if there have been no errors.

getLastErrorString()

std::string getLastErrorString ( ) const

inherited

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns

Most recent error, warning, information or debug message

See Error Handling.

See also

isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

getMinNumPeptides()

int getMinNumPeptides ( ) const

protected

Get the minimum number of peptides needed for protein ratio calculation.

Returns

The minimum number of peptides needed for protein ratio calculation.

getPeptideQuantKeys()

ms_peptide_quant_key_vector getPeptideQuantKeys	(	const std::string &	accession,
		int	dbIdx
	)		const

Look up peptide quant keys associated with a given protein, if any.

In ms_ms2quantitation, the list of peptide quant keys associated with the given protein is immutable, as the keys are derived from q,p values in the Mascot results file. The list does not contain all q,p values, but only those that 1) have component intensities and 2) pass the quality thresholds. Unless the data quality is extremely good, this list will always have fewer elements than the actual peptide matches assigned to the protein hit.

In ms_customquantitation, the peptide-to-protein mapping can be altered with ms_customquantitation::addPeptideQuantKey() and ms_customquantitation::removePeptideQuantKey().

Parameters

accession	The protein accession.
dbIdx	The protein database index.

Returns

A vector of peptide quant keys associated with the protein.

getPeptideRatio()

ms_peptide_quant_ratio getPeptideRatio ( const ms_peptide_quant_key &  key, const std::string &  ratioName  ) const

pure virtual

Given peptide quant key and ratio name, return the corresponding peptide ratio data.

Often, most peptide matches in a Mascot results file have no ratio data. For example, the peptide match could be non-significant or not quantitable (quality check fails); or with Reporter or Multiplex protocol, the MS/MS spectrum may not contain all component intensities required for ratio calculation.

If hasPeptideRatio(const ms_peptide_quant_key&, std::string) const returns false for the given peptide quant key and ratio name, then the peptide ratio object returned by this method represents an undefined ("missing") value.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, peptide ratios are interpreted as raw intensity values. It is usually meaningless to define more than one ratio name in this case.

Parameters

key	The peptide quant key of the peptide ratio.
ratioName	The name of the ratio.

Returns

The peptide ratio. If hasPeptideRatio() returns false, the field values of the object returned by this method are undefined.

Implemented in ms_customquantitation, and ms_ms2quantitation.

getPeptideRatioNormalisationBase()

double getPeptideRatioNormalisationBase

(

const std::string &

ratioName

)

const

Get the peptide ratio normalisation base of the given ratio name.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, peptide ratio normalisation has no meaning. It is strongly recommended to not set normalisation constants.

Parameters

ratioName

Peptide ratio name.

Returns

The current peptide ratio normalisation base, or 1 if it hasn't been set.

getProgressInfo()

const matrix_science::ms_progress_info & getProgressInfo

(

)

Get information about the progress of a currently running long operation (e.g. loading from a file).

Returns

Progress information about the most recent long operation.

getProteinRatio() [1/2]

ms_protein_quant_ratio getProteinRatio ( const std::string &  accession, int  dbIdx, const std::string &  ratioName  ) const

pure virtual

Given the protein accession, database ID and ratio name, return the protein ratio data.

Protein ratios are calculated on demand from the current protein-peptide mapping using the current quantitation method and taking peptide exclusion into account. You can exclude peptides from protein ratio calculation by using setPeptideRatioExcluded(). The current outlier detection method may also change which peptide ratios are used for any given protein.

For ms_ms2quantitation, the protein-peptide mapping is immutable. There are three types of protein ratio, which can be changed with setProteinRatioType(): median, average and weighted. Median is the median of all peptide ratios associated with the protein hit, and average is the geometric mean (equivalently, the arithmetic mean of log-transformed peptide ratios). Weighted is a weighted mean of peptide ratios, where the weights are channel intensities. The weighted ratio type is only available for Reporter data.

For ms_customquantitation, you can change the protein-peptide mapping by associating different peptide quant keys with the protein accession; see ms_customquantitation::addPeptideQuantKey() for details. There are three types of protein ratio: median, average and weighted. Median and average are the same as in ms_ms2quantitation, except in the Average protocol (see below). Weighted is the weighted geometric mean, where the weighting factor of each peptide ratio must be specified when the peptide ratio is added to the class. This is not the same weighting as in ms_ms2quantitation.

ms1, ms2 and custom protein ratios are calculated using:

• median - See ms_quant_stats::sortedMedian
• average - See ms_quant_stats::geometricMean
• weighted - See ms_quant_stats::weightedArithmeticMean

It is possible for the protein ratio to be undefined ("missing") even when it has associated peptide ratios, if there are not enough peptide ratios (setMinNumPeptides()), if all of them are marked excluded, or if too many of them are infinite.

If quantitation protocol is Reporter, Multiplex, Replicate or Precursor, the returned protein ratio object contains two p-values: the normality test value and the null hypothesis value.

The log-transformed peptide ratios are assumed normally distributed, and this hypothesis is tested using the Shapiro-Wilk W test. The normality p-value is -1 when the test could not be run (e.g. too few peptide ratios) and otherwise a positive number between 0 and 1. In the latter case, a value of less than 0.05 (or similar threshold) is usually taken as evidence that the log-transformed peptide ratios are not normally distributed, or equivalently that the peptide ratios are not log-normally distributed.

If outlier removal is configured, then outliers will be removed before normality testing. If this makes the normality p-value fall below 0.05, then the outliers will be restored. In this case the original sample was likely not normal to start with, and the normality p-value is calculated based on the original sample. If outlier removal is successful, then the normality p-value is based on the sample from which outliers have been removed, and it always exceeds 0.05.

The second p-value is for the null hypothesis. The null hypothesis is that the protein ratio equals 1.0 (component intensities have equal values). The p-value is -1 if there is only one peptide ratio, and otherwise a positive number between 0 and 1. The test is conducted after outlier removal, if any.

Note that the hypothesis test is done regardless of the p-value of the normality test. This means that you need to decide first if you accept peptide ratio normality before deciding whether to reject or not reject the null hypothesis. If normality is violated, then the hypothesis p-value is meaningless.

You can inspect which peptide quant keys were used in protein ratio calculation and which were ignored, due to being excluded or being outliers, with ms_protein_quant_ratio::getActiveKeys(), ms_protein_quant_ratio::getExcludedKeys() and ms_protein_quant_ratio::getOutlierKeys(). You can "move" peptide quant keys between the last two categories and the first by using the method getProteinRatio(const std::string &, int, const std::string &, const ms_peptide_quant_key_vector &, const ms_peptide_quant_key_vector &) const.

Note about weighted protein ratios: Parser 2.5 and 2.6 do not calculate the standard deviation, standard error or p-values when protein ratio type is weighted in Reporter data. The values are set to -1 ("unavailable"); see ms_protein_quant_ratio::getStandardDeviation(). The values are available in ms_customquantitation, which uses a different weighting formula.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, the only supported protein ratio type is "average", which does not mean a geometric average. Rather, the protein ratio is the sum of the "top N" peptide intensities, divided by the sum of the top N peptide intensities of the reference protein (see ms_customquantitation::setAverageReferenceProtein()). Neither outlier removal nor normalisation have any meaning in this protocol, which means no significance tests are done and the returned protein ratio object will not contain any p-values.

For more details on configuring other aspects of protein ratio calculation, please consult the quantitation help pages.

Parameters

accession	The protein accession.
dbIdx	The protein database index.
ratioName	The name of the ratio.

Returns

The protein ratio as calculated from peptide ratios associated with this protein accession. If the ratio could not be calculated (e.g. there are no associated peptide ratios), then the returned object will represent an undefined ("missing") value.

Implemented in ms_customquantitation, ms_ms1quantitation, and ms_ms2quantitation.

getProteinRatio() [2/2]

ms_protein_quant_ratio getProteinRatio ( const std::string &  accession, int  dbIdx, const std::string &  ratioName, const ms_peptide_quant_key_vector &  includeKeys, const ms_peptide_quant_key_vector &  excludeKeys  ) const

pure virtual

Given the protein accession, database ID and ratio name, return the protein ratio data, overriding the default inclusion and exclusion of the specified peptide quant keys.

The protein ratio is calculated as described in getProteinRatio(const std::string &, int, const std::string &) const, but the two peptide quant key vectors includeKeys and excludeKeys can be used to override default decisions about globally excluded and outlier peptide ratios. The rules are as follows:

1. If a peptide quant key is globally excluded with setPeptideRatioExcluded(), then giving the peptide quant key in includeKeys causes the peptide quant key to be included regardless ("undo global exclusion").
2. If a peptide quant key is given in excludeKeys, then the peptide quant key will be always excluded ("exclude locally").

If the peptide quant key is in both includeKeys and excludeKeys, the latter takes precedence and the peptide quant key is excluded.

Note that if outlier detection is enabled, then a peptide quant key determined to be an outlier cannot be included back using includeKeys, i.e. the inclusion mechanism does not undo outlier removal. You can disable outlier removal entirely before calling getProteinRatio() if you do not want peptide quant keys to be removed.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, then the effect of excludeKeys depends on whether the peptide quant key describes a "top N" peptide intensity. If the peptide intensity is one of the top N intensities assigned to this protein, then excluding it means the next highest outside the top N intensities will take its place. No peptide quant keys will ever be excluded automatically as outliers, since outlier removal has no meaning in this protocol.

Parameters

accession	The protein accession.
dbIdx	The protein database index.
ratioName	The name of the ratio.
includeKeys	Peptide quant keys to always include, even if they are globally excluded or would be marked as outliers.
excludeKeys	Peptide quant keys to always exclude, even if they are not outliers.

Returns

The protein ratio as calculated from peptide ratios associated with this protein accession. If the ratio could not be calculated (e.g. there are no associated peptide ratios), then the returned object will represent an undefined ("missing") value.

Implemented in ms_customquantitation, ms_ms1quantitation, and ms_ms2quantitation.

getProteinRatioSample()

void getProteinRatioSample ( const std::string &  accession, int  dbIdx, const std::string &  ratioName, const std::vector< ms_peptide_quant_key > &  includeKeys, const std::vector< ms_peptide_quant_key > &  excludeKeys, std::vector< double > &  sample, std::vector< double > &  logSample, std::vector< double > &  weights, std::vector< ms_peptide_quant_key > &  activeKeys, std::map< ms_peptide_quant_key, int > &  inactiveKeys, double &  normalityPvalue  ) const

protected

Find the peptide quant keys associated with the protein, collect their unique peptide ratios, remove outliers (if desired) and return the values as the sample of peptide ratios.

This method uses getSortedFinitePeptideRatioValues() internally to collect the vector of peptide ratios. If there are no peptide quant keys associated with the protein, or if no peptide ratios are associated with with those peptide quant keys, then sample, logSample, activeKeys and inactiveKeys will be empty and normalityPvalue will have an undefined value.

Parameters

accession	Protein accession.
dbIdx	Protein database index.
ratioName	Name of the ratio.
includeKeys	Prevent these peptide quant keys from being excluded.
excludeKeys	Prevent these peptide quant keys from being included.
sample	Peptide ratios associated with ratioName and the protein's peptide quant keys, in numerically increasing order.
logSample	Log transform of sample.
weights	Weighting factors corresponding to the order of sample (and logSample).
activeKeys	Peptide quant keys corresponding to the order of sample (and logSample).
inactiveKeys	Peptide quant keys marked as skipped, excluded or outlier.
normalityPvalue	The p-value that the sample appears to be normally distributed after outlier removal. If less than 0.05, no outliers will have been removed.

getQuantitationMethod()

const ms_quant_method & getQuantitationMethod

(

)

const

Return the current quantitation method.

The current (or effective) quantitation method is the original quantitation method given as argument to the constructor (or loaded from the Mascot results file), with possible later modifications, such as changing normalisation or outlier settings.

For ms_ms2quantitation, you cannot change the protocol settings, component definitions or peptide quality settings. You must create a new object with the new settings instead. You are free to change how protein ratios are calculated and set new normalisation parameters. These changes will be reflected in this method's output value.

For ms_customquantitation, same restrictions apply, although it makes little difference, as the class does not use any protocol settings, component definitions or peptide quality settings.

Returns

The current quantitation method.

getSortedFinitePeptideRatioValues()

void getSortedFinitePeptideRatioValues ( const std::string &  ratioName, const std::set< ms_peptide_quant_key > &  keys, const std::set< ms_peptide_quant_key > &  includeKeys, const std::set< ms_peptide_quant_key > &  excludeKeys, std::vector< double > &  values, std::vector< double > &  weights, std::vector< ms_peptide_quant_key > &  activeKeys, std::map< ms_peptide_quant_key, int > &  inactiveKeys  ) const

protectedpure virtual

Given a list of q,p values and ratio name, find the non-infinite peptide ratio values and return them in numerically increasing order.

The method looks up all peptide ratios associated with keys (ignoring duplicates) and returns them in numerically increasing order in values. Infinite and missing ratios are ignored. The vector activeKeys contains active peptide quant keys in the same order as values, and the map inactiveKeys contains peptide quant keys associated with the protein ratio but for indicated reasons not included in ratio calculation.

Parameters

ratioName	The name of the peptide ratio.
keys	A list of (sorted or unsorted) peptide quant keys for which to look up the ratios.
includeKeys	Prevent these peptide quant keys from being excluded.
excludeKeys	Prevent these peptide quant keys from being included.
values	Peptide ratios associated with ratioName and the given peptide quant keys.
weights	Weighting factors of corresponding to the order of values.
activeKeys	Peptide quant keys corresponding to the order of values.
inactiveKeys	Peptide quant keys skipped or excluded.

Implemented in ms_customquantitation, and ms_ms2quantitation.

hasPeptideRatio()

bool hasPeptideRatio ( const ms_peptide_quant_key &  key, const std::string &  ratioName  ) const

pure virtual

Existence check: return true if a peptide ratio with the associated peptide quant key and ratio name exists.

Often, most peptide matches in a Mascot results file have no ratio data. For example, the peptide match could be non-significant or not quantitable (quality check fails); or with Reporter or Multiplex protocol, the MS/MS spectrum may not contain all component intensities required for ratio calculation.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, peptide ratios are interpreted as raw intensity values. It is usually meaningless to define more than one ratio name in this case.

Parameters

key	The peptide quant key of the peptide ratio.
ratioName	The name of the ratio.

Returns

True if the peptide ratio exists; false otherwise.

Implemented in ms_customquantitation, and ms_ms2quantitation.

initialiseBaseSettings()

bool initialiseBaseSettings ( const ms_quant_method &  qmBase, const ms_quant_method &  qmConfig  )

protected

Initialise quantitation method settings from the two method objects.

For any method settings which are not consistent between the passed qmBase and qmConfig, the values from qmConfig will be used.

Parameters

qmBase	The base quantitation method as defined on the Mascot server.
qmConfig	The quantitation method to use to calculate quantitation results using.

Returns

True.

isPeptideRatioExcluded()

bool isPeptideRatioExcluded ( const ms_peptide_quant_key &  key, const std::string &  ratioName  ) const

pure virtual

Boolean flag: is the given peptide ratio globally excluded from protein ratio calculation?

(This method is redundant; you could also look up the peptide ratio and use ms_peptide_quant_ratio::isExcluded().)

Parameters

key	The peptide quant key of the peptide ratio.
ratioName	The name of the ratio.

Returns

True if the peptide ratio should be excluded from protein ratio calculation; false otherwise.

Implemented in ms_customquantitation, and ms_ms2quantitation.

isValid()

bool isValid ( ) const

inherited

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns

True if no fatal error occured

See also

getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, repeat_search.cpp, resfile_error.cpp, resfile_info.cpp, resfile_input.cpp, resfile_params.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

removePeptideRatioNormalisationBase()

void removePeptideRatioNormalisationBase

(

const std::string &

ratioName

)

Reset the peptide ratio normalisation base of the given ratio name.

Resetting means the report ratio normalisation constant is set to 1.0. This has the same effect as calling setPeptideRatioNormalisationBase() with b = 1.

In ms_ms2quantitation, resetting a normalisation constant is possible even if normalisation settings have been configured with setQuantNormalisation() and normalisePeptideRatios() has been called. It is generally not a good idea to reset normalisation bases, because it will lead to inconsistent peptide ratios.

Parameters

ratioName

Ratio name whose normalisation base is to be reset.

removePeptideRatioNormalisationBases()

void removePeptideRatioNormalisationBases

(

)

Reset all peptide ratio normalisation bases.

Resetting all report ratio normalisation bases means all peptide and protein ratios become unnormalised.

In ms_ms2quantitation, resetting a normalisation constant is possible even if normalisation settings have been configured with setQuantNormalisation() and normalisePeptideRatios() has been called. It is generally not a good idea to reset normalisation bases, because it will lead to inconsistent peptide ratios.

setMinNumPeptides()

void setMinNumPeptides

(

int

value

)

Set the minimum number of peptides needed for protein ratio calculation.

Changing the minimum number of peptides changes the current quantitation method. It does not alter the original quantitation method object.

Using the Average protocol in ms_customquantitation: The Average protocol has two settings for minimum number of peptides. This setting defines how many peptide intensities are needed for a protein before its ratio can be calculated. It is usually meaningless to choose a value other than 1. Use ms_customquantitation::setAverageNumPeptides() to define how many intensities should be used in protein ratio calculation.

Parameters

value

The minimum number of peptide ratios (the sample size) a protein must have for protein ratio calculation purposes. Values less than 1 are interpreted as 1.

setPeptideRatioExcluded()

void setPeptideRatioExcluded ( const ms_peptide_quant_key &  key, const std::string &  ratioName  )

pure virtual

Globally exclude a particular peptide ratio from protein ratio calculation.

All peptide matches associated with a protein ratio are used in calculating that protein's ratio, assuming the peptide ratio passes outlier testing (if used). This may not be desirable in some cases; for example, visual inspection could indicate the peptide match is incorrect. You can use setPeptideRatioExcluded() and setPeptideRatioIncluded() to globally exclude or include individual peptide ratios.

Parameters

key	The peptide quant key of the peptide ratio.
ratioName	The name of the ratio.

Implemented in ms_customquantitation, and ms_ms2quantitation.

setPeptideRatioIncluded()

void setPeptideRatioIncluded ( const ms_peptide_quant_key &  key, const std::string &  ratioName  )

pure virtual

Globally include a particular peptide ratio in protein ratio calculation.

All peptide matches associated with a protein ratio are used in calculating that protein's ratio, assuming the peptide ratio passes outlier testing (if used). This may not be desirable in some cases; for example, visual inspection could indicate the peptide match is incorrect. You can use setPeptideRatioExcluded() and setPeptideRatioIncluded() to globally exclude or include individual peptide ratios.

Parameters

key	The peptide quant key of the peptide ratio.
ratioName	The name of the ratio.

Implemented in ms_customquantitation, and ms_ms2quantitation.

setPeptideRatioNormalisationBase()

void setPeptideRatioNormalisationBase	(	const std::string &	ratioName,
		double	b
	)

Set the peptide ratio normalisation base of the given ratio name.

Setting peptide ratio normalisation to a particular value means all peptide ratios with ratioName will be divided by b before they are returned by getPeptideRatio(). That is, the underlying peptide ratios remain unaffected, which means this method will always return immediately without computing anything.

In ms_ms2quantitation, normalisation constants can most easily be calculated with ms_ms2quantitation::normalisePeptideRatios(), if normalisation is enabled and configured in the quantitation method. You are free to override this, but keeping track of who calculated which constant is up to you.

It is not a good idea to define both peptide ratio normalisation and component intensity normalisation at the same time. In fact, you can only configure one or the other using setQuantNormalisation(), and neither normalisePeptideRatios() nor normaliseIntensities() will step on each other's toes.

It is possible, but not recommended, to manually set normalisation bases for both peptide ratios and component intensities. The resulting peptide ratios are most likely meaningless.

In ms_customquantitation, you can use ms_customquantitation::getUnnormalisedAveragePeptideRatio() to calculate the mean or median of peptide ratios currently stored in the class, for normalisation purposes.

You can always set b to 1 to disable peptide ratio ratioName normalisation.

Using the Average protocol in ms_customquantitation: If quantitation protocol is Average, peptide ratio normalisation has no meaning. It is strongly recommended to not set normalisation constants.

Parameters

ratioName	Peptide ratio name to normalise.
b	New normalisation base. If it is zero, the old base will be kept. If this is the first time the base is set, a value of 0 means it is set to 1.0.

setProteinRatioType()

void setProteinRatioType ( const char *  value )

pure virtual

Set the protein ratio type.

Changing the protein ratio type changes the current quantitation method. It does not alter the original quantitation method object.

ms_ms2quantitation supports "median", "average" and "weighted", and ms_customquantitation supports "median" and "average. If the ratio type is not implemented, it is set to "median". <strong>Using the Average protocol in ms_customquantitation</strong>: If quantitation protocol is Average, the only supported protein ratio type is "average". Setting it to anything else will result in an error. You should inspect isValid() and use clearAllErrors() should you accidentally do so.

Parameters

value

Protein ratio type (e.g. median, average, weighted). Accepted values are defined in the quantitation XML schema.

Implemented in ms_customquantitation, and ms_ms2quantitation.

setQuantOutliers()

void setQuantOutliers ( const ms_quant_outliers *  qo )

pure virtual

Set new peptide ratio outlier settings.

Peptide ratio outlier detection can be configured in several ways. Please consult the quantitation configuration help page for details.

Changing outlier settings changes the current quantitation method. It does not alter the original quantitation method object.

Using the Average protocol in ms_customquantitation: It is an error to define outlier removal if quantitation protocol is Average. You will need to inspect isValid() and clear the error with clearAllErrors() should you accidentally do so.

Parameters

qo	An outlier configuration object. If this is NULL, outlier detection will be disabled (equivalent to "none").

Implemented in ms_customquantitation, and ms_ms2quantitation.

---

The documentation for this class was generated from the following files:

• ms_quantitation.hpp
• ms_quantitation.cpp