ms_ms2quantitation Class Reference

Peptide and protein quantitation in a Reporter or Multiplex Mascot results file. More...

#include <ms_ms2quantitation.hpp>

Inheritance diagram for ms_ms2quantitation:

Collaboration diagram for ms_ms2quantitation:

Public Member Functions
	ms_ms2quantitation (const ms_peptidesummary &pepsum)
	Default constructor: load the quantitation method from the results file and quantitate all peptides that pass the quality thresholds.
	ms_ms2quantitation (const ms_peptidesummary &pepsum, const ms_quant_method &qm)
	Quantitate all peptides that pass the quality thresholds using the given quantitation method.
virtual	~ms_ms2quantitation ()
	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
	Bring across base class member that we don't overload, otherwise it will be hidden.
virtual int	countDistinctPeptides (const std::vector< ms_peptide_quant_key > &activeKeys) const
	Bring across base class member that we don't overload, otherwise it will be hidden.
virtual int	countDistinctPeptides (const std::vector< ms_peptide_quant_key > &activeKeys) const
	Get the number of distinct peptides in the list of active candidates.
void	excludeProteinPeptideRatioKeys (const std::string &accession, int dbIdx, const std::string &ratioName, const ms_peptide_quant_key_vector &excludeKeys)
	Excludes the passed peptide ratio values from the protein ratio calculation.
const ms_quant_ratio *	getCombinedReportRatio (const std::string &ratioName) const
	Return a combined quantitation ratio matching the given name.
std::vector< std::string >	getCombinedReportRatioNames () const
	Return a list of current combined report ratio names.
std::vector< double >	getComponentIntensities (const ms_peptide_quant_key &key, bool raw=false) const
	Return the component intensities for the given peptide-spectrum match, if available.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
double	getIntensityNormalisationBase (const std::string &componentName) const
	Get the intensity normalisation base of the given component name.
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
	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_peptidesummary &	getPeptideSummary () const
	The summary is needed to recover the proteins and peptides.
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
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
	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.
const ms_quant_ratio *	getReportRatioFromFile (unsigned int fileNum, const std::string &ratioName) const
	Return a quantitation ratio matching the given name in the given file.
std::vector< std::string >	getReportRatioNamesInFile (unsigned int fileNum) const
	Return a list of current report ratio names in the given file.
bool	hasIntensityNormalisation () const
	Return true if intensity normalisation is enabled and configured.
virtual bool	hasPeptideRatio (const ms_peptide_quant_key &key, const std::string &ratioName) const
	Existence check: return true if a peptide ratio with the associated peptide quant key and ratio name exists.
bool	hasPeptideRatioNormalisation () const
	Return true if peptide ratio normalisation is enabled and configured.
void	includeProteinPeptideRatioKeys (const std::string &accession, int dbIdx, const std::string &ratioName, const ms_peptide_quant_key_vector &includeKeys)
	Includes the passed peptide ratio values in the protein ratio calculation.
virtual bool	isPeptideRatioExcluded (const ms_peptide_quant_key &key, const std::string &ratioName) const
	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.
bool	loadCdbFile (const char *path)
	Load user adjusted protein-peptide quantitation ratio settings from a cdb file.
bool	loadCdbFiles (const std::vector< std::string > &cdbFiles)
	Merges the settings from multiple protein-peptide user selection cdbfiles.
void	normaliseIntensities ()
	Normalise component intensities, or do nothing if intensity normalisation is disabled.
void	normalisePeptideRatios ()
	Normalise peptide ratios, or do nothing if normalisation is disabled.
void	removeCombinedReportRatio (const std::string &ratioName)
	Remove the combined quantitation ratio matching the given name from all files.
void	removeIntensityNormalisationBase (const std::string &componentName)
	Reset the intensity normalisation base of the given ratio name.
void	removeIntensityNormalisationBases ()
	Reset all Intensity normalisation bases.
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	removeReportRatioInFile (unsigned int fileNum, const std::string &ratioName)
	Remove the quantitation ratio matching the given name from the given file.
bool	saveCdbFile (const std::string &cdbFilename)
	Save the user edited protein-peptide quantitation settings to a cdb file.
bool	saveXmlFile (const std::string &xmlFilename, bool completeReport)
	Save the quantitation results to an XML file.
void	setCombinedReportRatio (const std::string &ratioName, const ms_quant_ratio &ratioDef)
	Add or modify the combined quantitation ratio matching the given name in all files.
void	setIntensityNormalisationBase (const std::string &componentName, double b)
	Set the intensity normalisation base of the given component name.
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)
	Globally exclude a particular peptide ratio from protein ratio calculation.
virtual void	setPeptideRatioIncluded (const ms_peptide_quant_key &key, const std::string &ratioName)
	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)
	Set the protein ratio type.
void	setQuantNormalisation (const ms_quant_normalisation *norm)
	Set new peptide and protein ratio normalisation settings.
virtual void	setQuantOutliers (const ms_quant_outliers *)
	Set new peptide ratio outlier settings.
void	setReportRatioInFile (unsigned int fileNum, const std::string &ratioName, const ms_quant_ratio &ratioDef)
	Add or modify the quantitation ratio matching the given name in the given file.

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

Peptide and protein quantitation in a Reporter or Multiplex Mascot results file.

ms_ms2quantitation implements a single use case: given a Mascot results file of a search whose quantitation protocol is Reporter (e.g. iTRAQ) or Multiplex (e.g. ¹⁸O), it will calculate, on demand, peptide and proteins ratios from component intensities extracted from the MS/MS spectra.

Peptide ratios are identified by q,p peptide quant keys (ms_peptide_quant_key(int q, int p)). Not all peptide matches in the results file have an associated peptide ratio; for example, the Reporter ions could be missing from the input query.

Protein ratios are identified by protein accession and database index. There are three types of ratio: 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.

All values are read-only. If you need to edit anything, apart from protein ratio calculation settings, or if you need to use some other protocol, use ms_customquantitation instead.

The class supports all types of normalisation configurable in the quantitation method. However, you need to explicitly ask for the normalisation constants to be calculated (see normalisePeptideRatios()). This is because normalisation may require calculating peptide ratios for all quantifiable peptide matches in the results file, which can be a time-consuming operation. Thus, if you change parameters or ratio definitions, and normalisation is enabled, you will need to call normalisePeptideRatios() to recalculate the normalisation constants. (If normalisation is not enabled, there is no penalty in calling normalisePeptideRatios().)

You can skip the remainder of this section if you are not combining results files (see Combining multiple results files for background reading).

If the results file is a merged file, peptide ratios will be merged across the files in the following way. Imagine peptide ratios are arranged in a table, so that a row contains the report ratios for a particular peptide (q,p), and the columns are indexed by report ratio names. Each report ratio with a unique name becomes its own column. If a report ratio with the same name appears in more than one file, these are treated as the same column (regardless of whether the formulas are exactly the same).

There are three complications which you must address:

1. Two report ratios with the same formula may not actually have the same name in different files (e.g. the iTRAQ 115/114 ratio is called "115/114" in one file but "Control" in another).
2. Two report ratios with the same name may not actually have the same formulas in different files (e.g. the report ratio named "Control" in one file is not calculated the same way "Control" is in another).
3. Two report ratios with the same name and same formula may mean different things in different files (e.g. "115/114" is control in one file, patient in another).

The solution is to modify report ratios in different files using setCombinedReportRatio(), so that the names, formulas and meanings match between files. Of course, if you want to keep ratios from different files separate, you need to rename ratios in each file (using setReportRatioInFile()) so that they are all different across all files.

Note the naming convention: methods with "InFile" (e.g. setReportRatioInFile()) modify report ratios in a single file (in the combined results file), while methods with "Combined" (e.g. setCombinedReportRatio()) modify report ratios across all files (in the combined results file).

Constructor & Destructor Documentation

ms_ms2quantitation() [1/2]

ms_ms2quantitation ( const ms_peptidesummary &  pepsum )

explicit

Default constructor: load the quantitation method from the results file and quantitate all peptides that pass the quality thresholds.

The constructor performs the following steps. If any of them fail, the corresponding error will be set and the object left in invalid state. Use isValid() to check for this and getLastErrorString() to fetch the error description:

• Load the quantitation method from the results file. If the results file has no quantitation method, or it doesn't validate against the schema, the process ends here.
• If protocol isn't Reporter or Multiplex, the process ends here. (Use ms_customquantitation instead, as outlined in Peptide and protein quantitation.)
• Prepare combined report ratios, if the input file is a combined results file.

Note that the constructor will not normalise peptide ratios or component intensities automatically, even if normalisation is enabled and configured. You need to call normalisePeptideRatios() and normaliseIntensities().

Parameters

pepsum

Mascot results file to quantitate. Note that you must first validate the embedded XML sections of the results file. Either pass the schema directory to the ms_mascotresfilebase constructor or use ms_mascotresfilebase::setXMLschemaFilePath().

ms_ms2quantitation() [2/2]

ms_ms2quantitation	(	const ms_peptidesummary &	pepsum,
		const ms_quant_method &	qm
	)

Quantitate all peptides that pass the quality thresholds using the given quantitation method.

The constructor performs the following steps. If any of them fail, the corresponding error will be set and the object left in invalid state. Use isValid() to check for this and getLastErrorString() to fetch the error description:

• Load the quantitation method from the results file. If the results file has no quantitation method, or it doesn't validate against the default quantitation schema, the process ends here.
• If protocol isn't Reporter or Multiplex, the process ends here. (Use ms_customquantitation instead, as outlined in Peptide and protein quantitation.)
• If the protocol or component definitions between the embedded quantitation method and qm do not match, as tested with ms_quant_method::isMethodCompatible(), the process ends here with an error.
• Prepare combined report ratios, if the input file is a combined results file.

Note that the constructor will not normalise peptide ratios or component intensities automatically, even if normalisation is enabled and configured. You need to call normalisePeptideRatios() and normaliseIntensities().

Parameters

pepsum	Mascot results file to quantitate. Note that you must first validate the embedded XML sections of the results file. Either pass the schema directory to the ms_mascotresfilebase constructor or use ms_mascotresfilebase::setXMLschemaFilePath().
qm	Quantitation method to use. The protocol and component definitions must match exactly those defined in the results file. It is best to use the return value from ms_mascotresfilebase::getQuantitationMethod() as the base and then alter peptide quality settings as needed.

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

protectedinherited

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

protectedinherited

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

protectedinherited

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

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

excludeProteinPeptideRatioKeys()

void excludeProteinPeptideRatioKeys	(	const std::string &	accession,
		int	dbIdx,
		const std::string &	ratioName,
		const ms_peptide_quant_key_vector &	excludeKeys
	)

Excludes the passed peptide ratio values from the protein ratio calculation.

Sets the user excluded list of peptide ratio keys for the specified protein hit and ratio.

Parameters

accession	The accession of the protein.
dbIdx	The database the protein is from.
ratioName	The name of the ratio to calculate.
excludeKeys	The vector of peptide ratio keys to exclude

getCombinedReportRatio()

const ms_quant_ratio * getCombinedReportRatio

(

const std::string &

ratioName

)

const

Return a combined quantitation ratio matching the given name.

Even if the report ratio formulas of ratio ratioName differ between the files, they are considered the same (merged in the same "column"), since they have the same name. This method returns the ratio definition from the first file (in numerical order) that has a definition with the name ratioName. You should always verify, using getReportRatioFromFile() and related methods, that the definitions with the same names are actually the same before relying on the return value of this method.

Parameters

ratioName

The name of the report ratio. This must match exactly (case sensitively) the desired report ratio name.

Returns

If no such report ratio exists, this method returns NULL. Otherwise the corresponding object is returned.

getCombinedReportRatioNames()

std::vector< std::string > getCombinedReportRatioNames

(

)

const

Return a list of current combined report ratio names.

This method returns the unique report ratio names across all files (i.e. the "columns" in the peptide ratio table).

Returns

The list of combined report ratio names in the order they appear in each file. Duplicate ratio names are removed.

getComponentIntensities()

std::vector< double > getComponentIntensities	(	const ms_peptide_quant_key &	key,
		bool	raw = false
	)		const

Return the component intensities for the given peptide-spectrum match, if available.

In the Reporter protocol, component intensities are extracted from a given input spectrum q based on the presence of reporter ion peaks, regardless of which peptide was matched to the spectrum. In this case all peptide matches in the same query that pass the quality threshold will have the same component intensities.

In the Multiplex protocol, component intensity extraction requires both the input spectrum q and the peptide that was matched to it, identified by (q,p). In this case, if component intensity extraction succeeded, then you may get different component intensities (or none at all) for different values of p.

Parameters

key	Peptide quant key created with ms_peptide_quant_key(int q, int p).
raw	(optional) If true, return raw intensities. Corrected intensities are returned by default. Note that if Reporter "sum" normalisation is in use, the corrected intensities will be normalised, whereas the raw intensities will not be.

Returns

A vector of component intensities, in the same order as components are defined in the quantitation method. This can be empty if there is no component intensity data for the peptide-spectrum match or if it did not pass the quality thresholds.

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.

getIntensityNormalisationBase()

double getIntensityNormalisationBase

(

const std::string &

componentName

)

const

Get the intensity normalisation base of the given component name.

Parameters

componentName

Name of one of the components defined in the quantitation method.

Returns

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

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

protectedinherited

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

inherited

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

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.

Implements ms_quantitation.

getPeptideRatioNormalisationBase()

double getPeptideRatioNormalisationBase ( const std::string &  ratioName ) const

inherited

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.

getPeptideSummary()

const matrix_science::ms_peptidesummary & getPeptideSummary

(

)

const

The summary is needed to recover the proteins and peptides.

Returns

The summary that was passed to the constructor.

getProgressInfo()

const matrix_science::ms_progress_info & getProgressInfo ( )

inherited

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

virtual

See ms_quantitation::getProteinRatio for further details of how the ratio is calculated

The list of any user included and excluded keys are retrieved from the result before being passed to the base class for processing. These will override the lists of keys set by setPeptideRatioExcluded() and setPeptideRatioIncluded() so that the same result can be obtained as was set when the results were calculated.

See also

includeProteinPeptideRatioKeys()

excludeProteinPeptideRatioKeys()

Parameters

accession	The accession of the protein.
dbIdx	The database the protein is from.
ratioName	The name of the ratio to calculate.

Returns

The match from the list of matches associated with the protein hit, or null if the index or match identifiers are invalid.

Implements ms_quantitation.

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

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.

Implements ms_quantitation.

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

protectedinherited

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

inherited

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.

getReportRatioFromFile()

const ms_quant_ratio * getReportRatioFromFile	(	unsigned int	fileNum,
		const std::string &	ratioName
	)		const

Return a quantitation ratio matching the given name in the given file.

Parameters

fileNum	Integer between 1 and ms_mascotresfilebase::getNumberOfResfiles().
ratioName	The name of the report ratio. This must match exactly (case sensitively) the desired report ratio name.

Returns

If no such report ratio exists, this method returns NULL. Otherwise the corresponding object is returned.

getReportRatioNamesInFile()

std::vector< std::string > getReportRatioNamesInFile

(

unsigned int

fileNum

)

const

Return a list of current report ratio names in the given file.

This method simply returns the names of the report ratios as defined in that file. This is the same order they are defined in the file's embedded quantitation method, unless the report ratios have been later changed with setReportRatioInFile() or setCombinedReportRatio().

Parameters

fileNum

Integer between 1 and ms_mascotresfilebase::getNumberOfResfiles().

Returns

The list of report ratio names in file fileNum.

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

protectedvirtual

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.

Implements ms_quantitation.

hasIntensityNormalisation()

bool hasIntensityNormalisation

(

)

const

Return true if intensity normalisation is enabled and configured.

You can enable and disable component intensity normalisation with setQuantNormalisation(). Note that only the "sum" normalisation is supported and only with the Reporter protocol.

If intensity normalisation is enabled, peptide ratio normalisation will be disabled, and vice versa.

Returns

True if normalisation is enabled and configured, false otherwise.

hasPeptideRatio()

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

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.

Implements ms_quantitation.

hasPeptideRatioNormalisation()

bool hasPeptideRatioNormalisation

(

)

const

Return true if peptide ratio normalisation is enabled and configured.

You can enable and disable peptide ratio normalisation with setQuantNormalisation().

If intensity normalisation is enabled, peptide ratio normalisation will be disabled, and vice versa.

Returns

True if normalisation is enabled and configured, false otherwise.

includeProteinPeptideRatioKeys()

void includeProteinPeptideRatioKeys	(	const std::string &	accession,
		int	dbIdx,
		const std::string &	ratioName,
		const ms_peptide_quant_key_vector &	includeKeys
	)

Includes the passed peptide ratio values in the protein ratio calculation.

Sets the user included list of peptide ratio keys for the specified protein hit and ratio.

Parameters

accession	The accession of the protein.
dbIdx	The database the protein is from.
ratioName	The name of the ratio to calculate.
includeKeys	The vector of peptide ratio keys to include

initialiseBaseSettings()

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

protectedinherited

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

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.

Implements ms_quantitation.

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.

loadCdbFile()

bool loadCdbFile

(

const char *

path

)

Load user adjusted protein-peptide quantitation ratio settings from a cdb file.

Updates the user protein-peptide ratio inclusions and exclusions from the cdbfile, overwriting any selections already made. If there is a problem loading the file and the method returns false, check getLastError() for further details.

Parameters

path	The path to the cdbfile to load

Returns

True if the cdbfile was valid and has been loaded, false if there was an error.

loadCdbFiles()

bool loadCdbFiles

(

const std::vector< std::string > &

cdbFiles

)

Merges the settings from multiple protein-peptide user selection cdbfiles.

For multfile merged datasets, thie method will update the user protein-peptide ratio inclusions and exclusions from the cdbfiles, overwriting any selections already made. If there is a problem loading any of the cdb files, this method will return false. Check getLastError() for further details.

Parameters

cdbFiles

The paths of the cdb files to load

Returns

True if all the cdb files were valid and have been loaded, false if there was an error.

normaliseIntensities()

void normaliseIntensities

(

)

Normalise component intensities, or do nothing if intensity normalisation is disabled.

Component intensity normalisation will require loading query data for most or all queries in the file, which can be a time-consuming process. This is why normalisation is not performed automatically once the constructor finishes.

Note that if hasIntensityNormalisation() returns false, then this method does nothing.

normalisePeptideRatios()

void normalisePeptideRatios

(

)

Normalise peptide ratios, or do nothing if normalisation is disabled.

Normalisation may require calculating all peptide ratios for all quantifiable peptide matches in the file, which can be a time-consuming process. This is why normalisation is not performed automatically once the constructor finishes. Automatic normalisation is also skipped when you change quantitation method parameters or report ratios, for the same reason.

Note that if hasPeptideRatioNormalisation() returns false, then this method does nothing.

removeCombinedReportRatio()

void removeCombinedReportRatio

(

const std::string &

ratioName

)

Remove the combined quantitation ratio matching the given name from all files.

The report ratio with name ratioName will be removed from all files where it is found. Other files remain unchanged.

Removing a combined report ratio does not alter normalisation constants, because the report ratio is removed from all files simultaneously (and because report ratios are independent of each other with respect to normalisation).

Parameters

ratioName

The name of the ratio to remove. If this is the empty string, nothing will be removed.

removeIntensityNormalisationBase()

void removeIntensityNormalisationBase

(

const std::string &

componentName

)

Reset the intensity normalisation base of the given ratio name.

Resetting means the component intensity normalisation constant is set to 1.0. This has the same effect as calling setIntensityNormalisationBase() with b = 1.

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

Parameters

componentName

Component name whose normalisation base is to be reset.

removeIntensityNormalisationBases()

void removeIntensityNormalisationBases

(

)

Reset all Intensity normalisation bases.

Resetting all intensity normalisation bases means all component intensities become unnormalised.

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

removePeptideRatioNormalisationBase()

void removePeptideRatioNormalisationBase ( const std::string &  ratioName )

inherited

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

inherited

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.

removeReportRatioInFile()

void removeReportRatioInFile	(	unsigned int	fileNum,
		const std::string &	ratioName
	)

Remove the quantitation ratio matching the given name from the given file.

The report ratio with name ratioName will be removed from file fileNum, if it exists. Otherwise nothing is removed.

Removing a report ratio from one file resets its normalisation constant across the whole combined file. You will need to use normalisePeptideRatios() to (re)calculate it. If you are changing multiple report ratios at the same time, it is best to wait until all changes are done before calling normalisePeptideRatios(), as that way you only need to normalise once.

Parameters

fileNum	Integer between 1 and ms_mascotresfilebase::getNumberOfResfiles().
ratioName	The name of the ratio to remove. If this is the empty string, nothing will be removed.

saveCdbFile()

bool saveCdbFile

(

const std::string &

cdbFilename

)

Save the user edited protein-peptide quantitation settings to a cdb file.

Distiller stores this in an MDRO project file (*.rov) in stream 0xC350+n where n is the value in the projectStream attribute of the QuantResult from the Quantitation folder.

The generated cdb file does not contain the complete quantitation report. It records only the details of any user selected or deselected protein-peptide quantitation ratios. If you wish to export the complete report, use the saveXmlFile() method instead.

Parameters

cdbFilename

The path and filename of the cdbfile to save

Returns

True if the file was saved successfully.

saveXmlFile()

bool saveXmlFile	(	const std::string &	xmlFilename,
		bool	completeReport
	)

Save the quantitation results to an XML file.

Parameters

xmlFilename	The path and filename of the file to save.
completeReport	True if a complete report of all data is to be generated, or false to generate concise report data.

Returns

True if the file was saved successfully.

setCombinedReportRatio()

void setCombinedReportRatio	(	const std::string &	ratioName,
		const ms_quant_ratio &	ratioDef
	)

Add or modify the combined quantitation ratio matching the given name in all files.

This method has does two things, in order:

1. The report ratio with name ratioName is modified to match ratioDef in all files where it is found.
2. A new report ratio will be added to files which don't have a report ratio with name ratioName.

Afterwards, all files will have a report ratio definition matching ratioDef, which will be merged in one "column" (since its name is the same in all files).

Note that the name defined in ratioDef can differ from ratioName. There are two use cases:

1. Adding a new definition: set ratioName to the name of a report ratio that does not yet exist and ratioDef to the definition itself.
   • The name set in ratioDef is ignored.
2. Updating, replacing and renaming a definition: set ratioName to the name of an existing report ratio and pass in ratioDef.
   • If ratioDef name is empty or equals ratioName, then the existing definition will be updated.
   • If ratioDef name differs from ratioName, then the existing definition will be replaced with ratioDef. (If the body of ratioDef is the same as before, this is a rename and otherwise a replace operation.)

Note that if ratioName is the empty string, this method does nothing and returns immediately.

Changing a combined report ratio resets all normalisation constants – that is, peptide ratios become unnormalised. Use normalisePeptideRatios() to recalculate the normalisation constants.

Parameters

ratioName	The name of the ratio to replace, or the name of the new ratio to add. If this is the empty string, a new report ratio will be added.
ratioDef	The ratio definition.

setIntensityNormalisationBase()

void setIntensityNormalisationBase	(	const std::string &	componentName,
		double	b
	)

Set the intensity normalisation base of the given component name.

Setting component intensity normalisation to a particular value means all peptide ratios calculated from componentName will be affected. However, the underlying compnent intensities remain unaffected, which means this method will always return immediately without computing anything.

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.

You can always set b to 1 to disable component intensity componentName normalisation.

Parameters

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

setMinNumPeptides()

void setMinNumPeptides ( int  value )

inherited

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  )

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.

Implements ms_quantitation.

setPeptideRatioIncluded()

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

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.

Implements ms_quantitation.

setPeptideRatioNormalisationBase()

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

inherited

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 )

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.

Implements ms_quantitation.

setQuantNormalisation()

void setQuantNormalisation

(

const ms_quant_normalisation *

norm

)

Set new peptide and protein ratio normalisation settings.

Peptide and protein ratios can be normalised in several ways. Please consult the quantitation configuration help page for details. Changing ratio normalisation settings may involve a delay as the normalisation base is computed from ratio data.

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

Changing the settings resets all normalisation constants – that is, peptide ratios become unnormalised. Use normalisePeptideRatios() to recalculate the normalisation constants.

Parameters

norm	A normalisation configuration object. If this is NULL, normalisation will be disabled (equivalent to "none").

setQuantOutliers()

void setQuantOutliers ( const ms_quant_outliers *  qo )

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

Implements ms_quantitation.

setReportRatioInFile()

void setReportRatioInFile	(	unsigned int	fileNum,
		const std::string &	ratioName,
		const ms_quant_ratio &	ratioDef
	)

Add or modify the quantitation ratio matching the given name in the given file.

This method does two things, in order:

1. The report ratio with name ratioName in file fileNum is modified to match ratioDef, if it exists.
2. Otherwise a new report ratio will be added to file fileNum.

The new report ratio will be merged with report ratios from other files if its name matches any other report ratio's name.

Note that the name defined in ratioDef can differ from ratioName. There are two use cases:

1. Adding a new definition: set ratioName to the name of a report ratio that does not yet exist in this file and ratioDef to the definition itself.
   • The name set in ratioDef is ignored.
2. Updating, replacing and renaming a definition: set ratioName to the name of an existing report ratio and pass in ratioDef.
   • If ratioDef name is empty or equals ratioName, then the existing definition will be updated.
   • If ratioDef name differs from ratioName, then the existing definition will be replaced with ratioDef. (If the body of ratioDef is the same as before, this is a rename and otherwise a replace operation.)

Note that if ratioName is the empty string, this method does nothing and returns immediately.

Changing a report ratio resets its normalisation constant across the whole combined file, while a fresh report ratio starts out with a constant of 1.0. You will need to use normalisePeptideRatios() to (re)calculate it. If you are changing multiple report ratios at the same time, it is best to wait until all changes are done before calling normalisePeptideRatios(), as that way you only need to normalise once.

Parameters

fileNum	Integer between 1 and ms_mascotresfilebase::getNumberOfResfiles().
ratioName	The name of the ratio to replace, or the name of the new ratio to add. If this is the empty string, a new report ratio will be added.
ratioDef	The ratio definition.

---

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

• ms_ms2quantitation.hpp
• ms_ms2quantitation.cpp