Matrix Science header
Public Member Functions | Protected Member Functions | Protected Attributes

ms_quantitation Class Reference
[Quantitation analysis for Mascot Server and Distiller]

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

#include <ms_quantitation.hpp>

Inheritance diagram for ms_quantitation:
Inheritance graph
[legend]
Collaboration diagram for ms_quantitation:
Collaboration graph
[legend]

List of all members.

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 std::vector< ms_peptide_quant_key > &activeKeys) const
 Get the number of distinct peptides in the list of active candidates.
virtual int countDistinctPeptides (const ms_peptide_quant_key_vector &activeKeys) const
 Get the number of distinct peptides in the list of active candidates.
const ms_errsgetErrorHandler () 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_infogetProgressInfo ()
 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_methodgetQuantitationMethod () 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_mascotresfile::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:
  2. Access protein ratios and associated peptide quant keys:
  3. Access and modify quantitation method settings related to protein ratio calculation:

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

void appendErrors ( const ms_errors src ) [inherited]

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

Parameters:
srcThe object to copy the errors across from. See Maintaining object references: two rules of thumb.
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:
accessionProtein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdxProtein database index. This is returned verbatim in the returned object and not used otherwise.
ratioNameRatio name. This is returned verbatim in the returned object and not used otherwise.
sampleSample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSampleLog transform of sample.
normalityPvalueThe p-value that logSample looks normally distributed.
activeKeysPeptide quant keys for which sample values are present.
inactiveKeysPeptide 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.
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:
accessionProtein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdxProtein database index. This is returned verbatim in the returned object and not used otherwise.
ratioNameRatio name. This is returned verbatim in the returned object and not used otherwise.
sampleSample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSampleLog transform of sample.
normalityPvalueThe p-value that logSample looks normally distributed.
activeKeysPeptide quant keys for which sample values are present.
inactiveKeysPeptide 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.
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:
accessionProtein accession. This is returned verbatim in the returned object and not used otherwise.
dbIdxProtein database index. This is returned verbatim in the returned object and not used otherwise.
ratioNameRatio name. This is returned verbatim in the returned object and not used otherwise.
sampleSample of peptide ratios in increasing numerical order. Sample size must be at least 1.
logSampleLog transform of sample.
weightsWeighting factors corresponding to the order of sample (and logSample).
normalityPvalueThe p-value that logSample looks normally distributed.
activeKeysPeptide quant keys for which sample values are present.
inactiveKeysPeptide 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.
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.
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
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(const ms_peptide_quant_key_vector &) (which should call the relevant ms_ms1quantitation or ms_ms2quantitation version.

Parameters:
activeKeysPeptide quant keys that are included in the quantitation of a protein.
Returns:
The number of distinct peptides.
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:
activeKeysPeptide quant keys that are included in the quantitation of a protein.
Returns:
The number of distinct peptides.

Reimplemented in ms_ms1quantitation, and ms_ms2quantitation.

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

Reimplemented in ms_mascotresfile.

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

Reimplemented in ms_mascotresfile.

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.
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.
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:
accessionThe protein accession.
dbIdxThe protein database index.
Returns:
A vector of peptide quant keys associated with the protein.
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:
keyThe peptide quant key of the peptide ratio.
ratioNameThe 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.

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:
ratioNamePeptide ratio name.
Returns:
The current peptide ratio normalisation base, or 1 if it hasn't been set.
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.
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:

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:
accessionThe protein accession.
dbIdxThe protein database index.
ratioNameThe 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.

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:
accessionThe protein accession.
dbIdxThe protein database index.
ratioNameThe name of the ratio.
includeKeysPeptide quant keys to always include, even if they are globally excluded or would be marked as outliers.
excludeKeysPeptide 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.

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:
accessionProtein accession.
dbIdxProtein database index.
ratioNameName of the ratio.
includeKeysPrevent these peptide quant keys from being excluded.
excludeKeysPrevent these peptide quant keys from being included.
samplePeptide ratios associated with ratioName and the protein's peptide quant keys, in numerically increasing order.
logSampleLog transform of sample.
weightsWeighting factors corresponding to the order of sample (and logSample).
activeKeysPeptide quant keys corresponding to the order of sample (and logSample).
inactiveKeysPeptide quant keys marked as skipped, excluded or outlier.
normalityPvalueThe p-value that the sample appears to be normally distributed after outlier removal. If less than 0.05, no outliers will have been removed.
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.
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 [protected, pure 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:
ratioNameThe name of the peptide ratio.
keysA list of (sorted or unsorted) peptide quant keys for which to look up the ratios.
includeKeysPrevent these peptide quant keys from being excluded.
excludeKeysPrevent these peptide quant keys from being included.
valuesPeptide ratios associated with ratioName and the given peptide quant keys.
weightsWeighting factors of corresponding to the order of values.
activeKeysPeptide quant keys corresponding to the order of values.
inactiveKeysPeptide quant keys skipped or excluded.

Implemented in ms_customquantitation, and ms_ms2quantitation.

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:
keyThe peptide quant key of the peptide ratio.
ratioNameThe name of the ratio.
Returns:
True if the peptide ratio exists; false otherwise.

Implemented in ms_customquantitation, and ms_ms2quantitation.

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:
qmBaseThe base quantitation method as defined on the Mascot server.
qmConfigThe quantitation method to use to calculate quantitation results using.
Returns:
True.
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:
keyThe peptide quant key of the peptide ratio.
ratioNameThe 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.

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, resfile_summary.cpp, and tools_aahelper.cpp.
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:
ratioNameRatio name whose normalisation base is to be reset.
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.

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:
valueThe 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.
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:
keyThe peptide quant key of the peptide ratio.
ratioNameThe name of the ratio.

Implemented in ms_customquantitation, and ms_ms2quantitation.

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:
keyThe peptide quant key of the peptide ratio.
ratioNameThe name of the ratio.

Implemented in ms_customquantitation, and ms_ms2quantitation.

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:
ratioNamePeptide ratio name to normalise.
bNew 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.
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".

Using the Average protocol in ms_customquantitation: 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:
valueProtein ratio type (e.g. median, average, weighted). Accepted values are defined in the quantitation XML schema.

Implemented in ms_customquantitation, and ms_ms2quantitation.

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

Copyright © 2022 Matrix Science Ltd.  All Rights Reserved. Generated on Thu Mar 31 2022 01:12:37