Generate components of transformation products

Generates components by linking feature groups of transformation products and their parents.

generateComponentsTPs(fGroups, ...)

# S4 method for class 'featureGroups'
generateComponentsTPs(
  fGroups,
  fGroupsTPs = fGroups,
  ignoreParents = FALSE,
  TPs = NULL,
  MSPeakLists = NULL,
  formulas = NULL,
  compounds = NULL,
  minRTDiff = 20,
  specSimParams = getDefSpecSimParams()
)

# S4 method for class 'featureGroupsSet'
generateComponentsTPs(
  fGroups,
  fGroupsTPs = fGroups,
  ignoreParents = FALSE,
  TPs = NULL,
  MSPeakLists = NULL,
  formulas = NULL,
  compounds = NULL,
  minRTDiff = 20,
  specSimParams = getDefSpecSimParams()
)

Arguments

fGroups: The input featureGroups for componentization. See fGroupsTPs.
...: Further arguments specified to the methods.
fGroupsTPs: A featureGroups object containing the feature groups that are expected to be transformation products. If a distinction between parents and TPs is not yet known, fGroupsTPs should equal the fGroups argument. Otherwise, fGroups should only contain the parent feature groups, and both fGroups and fGroupsTPs must be a subset of the same featureGroups object.
ignoreParents: If TRUE then feature groups present in both fGroups and fGroupsTPs are not considered as TPs.
TPs: A transformationProducts object. Set to NULL to perform linking without this data.
MSPeakLists, formulas, compounds: A MSPeakLists/formulas/compounds object to calculate MS/MS or annotation similarities between parents and TPs. If NULL then this data is not calculated. For more details see the Linking parents and transformation products section below.
minRTDiff: Minimum retention time (in seconds) difference between the parent and a TP to determine whether a TP elutes prior/after the parent (to calculate retDir values, see Details in componentsTPs))
specSimParams: A named list with parameters that influence the calculation of MS spectra similarities. See the spectral similarity parameters documentation for more details.

Value

The components are stored in objects derived from componentsTPs.

Details

This function uses transformation product screening to generate components. This function is called when calling generateComponents with algorithm="tp".

This method typically employs data from generated transformation products to find parents and their TPs. However, this data is not necessary, and components can also be made based on MS/MS similarity and/or other annotation similarities between the parent and its TPs. For more details see the Linking parents and transformation products section below.

Note

The shift parameter of specSimParams is ignored by generateComponentsTPs, since it always calculates similarities with all supported options.

Linking parents and transformation products

Each component consists of feature groups that are considered to be transformation products for one parent (the parent that 'belongs' to the component can be retrieved with the componentInfo method). The parent feature groups are taken from the fGroups parameter, while the feature groups for TPs are taken from fGroupsTPs. If a feature group occurs in both variables, it may therefore be considered as both a parent or TP.

If transformation product data is given, i.e. the TPs argument is set, then a suspect screening of the TPs must be performed in advance (see screenSuspects and convertToSuspects to create the suspect list). Furthermore, if TPs were generated with generateTPsBioTransformer or generateTPsLibrary then the suspect screening must also include the parents (e.g. by setting includeParents=TRUE when calling convertToSuspects or by amending results by setting amend=TRUE to screenSuspects). The suspect screening is necessary for the componentization algorithm to map the feature groups of the parent or TP. If the the suspect screening yields multiple TP hits, all will be reported. Similarly, if the suspect screening contains multiple hits for a parent, a component is made for each of the parent hits.

In case no transformation product data is provided (TPs=NULL), the componentization algorithm simply assumes that each feature group from fGroupsTPs is a potential TP for every parent feature group in fGroups. For this reason, it is highly recommended to specify which feature groups are parents/TPs (see the fGroupsTPs argument description above) and crucial that the data is post-processed, for instance by only retaining TPs that have high annotation similarity with their parents (see the filter method for componentsTPs).

A typical way to distinguish which feature groups are parents or TPs from two different (groups of) samples is by calculating Fold Changes (see the as.data.table method for feature groups and plotVolcano). Of course, other statistical techniques from R are also suitable.

During componentization, several characteristics are calculated which may be useful for post-processing:

specSimilarity: the MS/MS spectral similarity between the feature groups of the TP and its parent (0-1).
specSimilarityPrec,specSimilarityBoth: as specSimilarity, but calculated with binned data using the "precursor" and "both" method, respectively (see MS spectral similarity parameters for more details).
fragmentMatches The number of MS/MS fragment formula annotations that overlap between the TP and parent. If both the formulas and compounds arguments are specified then the annotation data is pooled prior to calculation. Note that only unique matches are counted. Furthermore, note that annotations from all candidates are considered, even if the formula/structure of the parent/TP is known. Hence, fragmentMatches is mainly useful when little or no chemical information is known on the parents/TPs, i.e., when TPs=NULL or originates from generateTPsLogic. Since annotations for all candidates are used, it is highly recommended that the annotation objects are first processed with the filter method, for instance, to select only the top ranked candidates.
neutralLossMatches As fragmentMatches, but counting overlapping neutral loss formulae.
retDir The retention time direction of the TP relative to its parent. See Details in componentsTPs. If TP data was specified, the expected direction is stored in TP_retDir.
retDiff,mzDiff,formulaDiff The retention time, m/z and formula difference between the parent and TP (latter only available if data TP formula is available).

Sets workflows

In a sets workflow the component tables are amended with extra information such as overall/specific set spectrum similarities. As sets data is mixed, transformation products are able to be linked with a parent, even if they were not measured in the same set.