Base class for grouped features.

Source: R/generics.R, R/feature_groups.R, R/feature_groups-set.R, and 8 more

This class holds all the information for grouped features.

groupTable(object, ...)

groupFeatIndex(fGroups)

groupInfo(fGroups)

unique(x, incomparables = FALSE, ...)

overlap(fGroups, which, exclusive = FALSE, ...)

selectIons(fGroups, components, prefAdduct, ...)

groupQualities(fGroups)

groupScores(fGroups)

internalStandards(fGroups)

internalStandardAssignments(fGroups, ...)

normInts(
  fGroups,
  featNorm = "none",
  groupNorm = FALSE,
  normFunc = max,
  standards = NULL,
  ISTDRTWindow = 120,
  ISTDMZWindow = 300,
  minISTDs = 3,
  ...
)

# S4 method for class 'featureGroups'
names(x)

# S4 method for class 'featureGroups'
analyses(obj)

# S4 method for class 'featureGroups'
replicateGroups(obj)

# S4 method for class 'featureGroups'
groupNames(obj)

# S4 method for class 'featureGroups'
length(x)

# S4 method for class 'featureGroups'
show(object)

# S4 method for class 'featureGroups'
groupTable(object, areas = FALSE, normalized = FALSE)

# S4 method for class 'featureGroups'
analysisInfo(obj)

# S4 method for class 'featureGroups'
groupInfo(fGroups)

# S4 method for class 'featureGroups'
featureTable(obj)

# S4 method for class 'featureGroups'
getFeatures(obj)

# S4 method for class 'featureGroups'
groupFeatIndex(fGroups)

# S4 method for class 'featureGroups'
groupQualities(fGroups)

# S4 method for class 'featureGroups'
groupScores(fGroups)

# S4 method for class 'featureGroups'
annotations(obj)

# S4 method for class 'featureGroups'
internalStandards(fGroups)

# S4 method for class 'featureGroups'
internalStandardAssignments(fGroups)

# S4 method for class 'featureGroups'
adducts(obj)

# S4 method for class 'featureGroups'
adducts(obj) <- value

# S4 method for class 'featureGroups'
concentrations(fGroups)

# S4 method for class 'featureGroups'
toxicities(fGroups)

# S4 method for class 'featureGroups,ANY,ANY,missing'
x[i, j, ..., rGroups, results, drop = TRUE]

# S4 method for class 'featureGroups,ANY,ANY'
x[[i, j]]

# S4 method for class 'featureGroups'
x$name

# S4 method for class 'featureGroups'
delete(obj, i = NULL, j = NULL, ...)

# S4 method for class 'featureGroups'
export(obj, type, out)

# S4 method for class 'featureGroups'
as.data.table(
  x,
  average = FALSE,
  areas = FALSE,
  features = FALSE,
  qualities = FALSE,
  regression = FALSE,
  averageFunc = mean,
  normalized = FALSE,
  FCParams = NULL,
  concAggrParams = getDefPredAggrParams(),
  toxAggrParams = getDefPredAggrParams(),
  normConcToTox = FALSE
)

# S4 method for class 'featureGroups'
unique(x, which, relativeTo = NULL, outer = FALSE)

# S4 method for class 'featureGroups'
overlap(fGroups, which, exclusive)

# S4 method for class 'featureGroups'
calculatePeakQualities(
  obj,
  weights,
  flatnessFactor,
  avgFunc = mean,
  parallel = TRUE
)

# S4 method for class 'featureGroups'
selectIons(
  fGroups,
  components,
  prefAdduct,
  onlyMonoIso = TRUE,
  chargeMismatch = "adduct"
)

# S4 method for class 'featureGroups'
normInts(
  fGroups,
  featNorm = "none",
  groupNorm = FALSE,
  normFunc = max,
  standards = NULL,
  ISTDRTWindow = 120,
  ISTDMZWindow = 300,
  minISTDs = 3,
  ...
)

# S4 method for class 'featureGroups'
getTICs(obj, retentionRange = NULL, MSLevel = c(1, 2))

# S4 method for class 'featureGroups'
getBPCs(obj, retentionRange = NULL, MSLevel = c(1, 2))

# S4 method for class 'featureGroupsSet'
sets(obj)

# S4 method for class 'featureGroupsSet'
internalStandardAssignments(fGroups, set = NULL)

# S4 method for class 'featureGroupsSet'
adducts(obj, set, ...)

# S4 method for class 'featureGroupsSet'
adducts(obj, set, reGroup = TRUE) <- value

# S4 method for class 'featureGroupsSet'
delete(obj, i = NULL, j = NULL, ...)

# S4 method for class 'featureGroupsSet'
show(object)

# S4 method for class 'featureGroupsSet'
featureTable(obj)

# S4 method for class 'featureGroupsSet,ANY,ANY,missing'
x[i, j, ..., rGroups, sets = NULL, drop = TRUE]

# S4 method for class 'featureGroupsSet'
export(obj, type, out, set)

# S4 method for class 'featureGroupsSet'
unique(x, which, ..., sets = FALSE)

# S4 method for class 'featureGroupsSet'
overlap(fGroups, which, exclusive, sets = FALSE)

# S4 method for class 'featureGroupsSet'
selectIons(fGroups, components, prefAdduct, ...)

# S4 method for class 'featureGroupsSet'
normInts(
  fGroups,
  featNorm = "none",
  groupNorm = FALSE,
  normFunc = max,
  standards = NULL,
  ISTDRTWindow = 120,
  ISTDMZWindow = 300,
  minISTDs = 3,
  ...
)

# S4 method for class 'featureGroupsSet'
unset(obj, set)

# S4 method for class 'featureGroupsKPIC2'
delete(obj, ...)

# S4 method for class 'featureGroups'
plotTICs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  colourBy = c("none", "analyses", "rGroups"),
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

# S4 method for class 'featureGroups'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  colourBy = c("none", "analyses", "rGroups"),
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

# S4 method for class 'featureGroupsXCMS'
delete(obj, ...)

# S4 method for class 'featureGroupsXCMS3'
delete(obj, ...)

Arguments

...

For the "[" operator: ignored.

For delete: passed to the function specified as j.

For normInts: passed to screenSuspects if featNorm="istd".

For sets workflow methods: further arguments passed to the base featureGroups method.

fGroups, obj, x, object

featureGroups object to be accessed.

incomparables

Ignored.

which

A character vector with replicate groups used for comparison.

For overlap: can also be a list of character vectors with replicate groups to compare. For instance, which=list(c("samp1", "samp2"), c("samp3", "samp4")) returns the overlap between "samp1"+"samp2" and "samp3"+"samp4".

exclusive

If TRUE then all feature groups are removed that are not unique to the given replicate groups.

components

The components object that was generated for the given featureGroups object. Obviously, the components must be created with algorithms that support adduct/isotope annotations, such as those from RAMClustR and cliqueMS.

prefAdduct

The 'preferred adduct' (see method description). This is often "[M+H]+" or "[M-H]-".

featNorm

The method applied for feature normalization: "istd", "tic", "conc" or "none". See the Feature intensity normalization section for details.

groupNorm

If TRUE then group normalization is performed. See the Feature intensity normalization section for details.

normFunc

A function to combine data for normalization. See the Feature intensity normalization section for details.

standards

A data.table (or data.frame) with all internal standards. Should follow the format of a suspect list. Only used if featNorm="istd". See the Feature intensity normalization section for details.

(sets workflow) Can also be a list with internal standard lists.

See the suspects argument to screenSuspects for more details.

ISTDRTWindow, ISTDMZWindow

The retention time and m/z windows for IS selection. Only used if featNorm="istd". See the Feature intensity normalization section for details.

minISTDs

The minimum number of IS that should be assigned to each feature (if possible). Only used if featNorm="istd". See the Feature intensity normalization section for details.

areas

If set to TRUE then areas are considered instead of peak intensities.

For as.data.table: ignored if features=TRUE, as areas of features are always reported.

normalized

If TRUE then normalized intensity data is used (see the Feature intensity normalization section.

For as.data.table: if no normalization data is available (e.g. because normInts was not used) then an automatic group normalization is performed.

value

For adducts<-: A character with adduct annotations assigned to each feature group. The length should equal the number of feature groups. Can be named with feature group names to customize the assignment order.

i, j

For [/[[: A numeric or character value which is used to select analyses/feature groups by their index or name, respectively (for the order/names see analyses()/names()).

For [: Can also be logical to perform logical selection (similar to regular vectors). If missing all analyses/feature groups are selected.

For [[: should be a scalar value. If j is not specified, i selects by feature groups instead.

For delete: The data to remove from. i are the analyses as numeric index, logical or character, j the feature groups as numeric index, logical or character. If either is NULL then data for all is removed. j may also be a function: it will be called for each feature group, with a vector of the group intensities, the group name and any other arguments passed as ... to delete. The return value of this function specifies the analyses of the features in the group to be removed (same format as i).

rGroups

For [: An optional character vector: if specified only keep results for the given replicate groups (equivalent to the rGroups argument to filter).

results

Optional argument. If specified only feature groups with results in the specified object are kept. The class of results should be featureAnnotations or components. Multiple objects can be specified in a list: in this case a feature group is kept if it has a result in any of the objects (equivalent to the results argument to filter).

drop

ignored.

name

The feature group name (partially matched).

type

The export type: "brukerpa" (Bruker ProfileAnalysis), "brukertasq" (Bruker TASQ) or "mzmine" (MZmine).

out

The destination file for the exported data.

average

If TRUE then data within replicate groups are averaged.

For as.data.table: if features=TRUE other feature properties are also averaged.

features

If TRUE then feature specific data will be added. If average=TRUE this data will be averaged for each feature group.

qualities

Adds feature (group) qualities (qualities="quality"), scores (qualities="score") or both (qualities="both"), if this data is available (i.e. from calculatePeakQualities). If qualities=FALSE then nothing is reported.

regression

Set to TRUE to add regression data for each feature group. For this a linear model is created (intensity/area [depending on areas argument] vs concentration). The model concentrations (e.g. of a set of standards) is derived from the conc column of the analysis information. From this model the intercept, slope and R2 is added to the output. In addition, when features=TRUE, concentrations for each feature are added. Note that no regression information is added when no conc column is present in the analysis information or when less than two concentrations are specified (i.e. the minimum amount).

averageFunc

Function used for averaging. Only used when average=TRUE or FCParams != NULL.

FCParams

A parameter list to calculate Fold change data. See getFCParams for more details. Set to NULL to not perform FC calculations.

concAggrParams, toxAggrParams

Parameters to aggregate calculated concentrations/toxicities (obtained with calculateConcs/calculateTox). See prediction aggregation parameters for more information. Set to NULL to omit this data.

normConcToTox

Set to TRUE to normalize concentrations to toxicities. Only relevant if this data is present (see calculateConcs/calculateTox).

relativeTo

A character vector with replicate groups that should be used for unique comparison. If NULL then all replicate groups are used for comparison. Replicate groups specified in which are ignored.

outer

If TRUE then only feature groups are kept which do not overlap between the specified replicate groups for the which parameter.

weights

A named numeric vector that defines the weight for each score to calculate the totalScore. The names of the vector follow the score names. Unspecified weights are defaulted to 1. Example: weights=c(ApexBoundaryRatioScore=0.5, GaussianSimilarityScore=2).

flatnessFactor

Passed to MetaClean as the flatness.factor argument to calculateJaggedness and calculateModality.

avgFunc

The function used to average the peak qualities and scores for each feature group.

parallel

If set to TRUE then code is executed in parallel through the futures package. Please see the parallelization section in the handbook for more details.

onlyMonoIso

Set to TRUE to only keep feature groups that were annotated as monoisotopic. Feature groups are never removed by this setting if no isotope annotations are available.

chargeMismatch

Specifies how to deal with a mismatch in charge between adduct and isotope annotations. Valid values are: "adduct" (ignore isotope annotation), "isotope" (ignore adduct annotation), "none" (ignore both annotations) and "ignore" (don't check for charge mismatches). Important: when OpenMS is used to find features, it already removes any detected non-monoisotopic features by default. Hence, in such case setting chargeMismatch="adduct" is more appropriate.

retentionRange

Range of retention time (in seconds) to collect TIC traces. Should be a numeric vector with length of two containing the min/max values. Set to NULL to ignore.

MSLevel

Integer vector with the ms levels (i.e., 1 for MS1 and 2 for MS2) to obtain TIC traces.

set

(sets workflow) The name of the set.

reGroup

(sets workflow) Set to TRUE to re-group the features after the adduct annotations are changed. See the Sets workflow section for more details.

sets

(sets workflow) For [: a character with name(s) of the sets to keep.

For overlap and unique: If TRUE then the which argument changes its meaning and is used to specify the names of the sets to be compared.

retMin

Plot retention time in minutes (instead of seconds).

title

Character string used for title of the plot. If NULL a title will be automatically generated.

colourBy

Sets the automatic colour selection: "none" for a single colour or "analyses"/"rGroups" for a distinct colour per analysis or analysis replicate group.

showLegend

Plot a legend if TRUE.

xlim, ylim

Sets the plot size limits used by plot. Set to NULL for automatic plot sizing.

Value

delete returns the object for which the specified data was removed.

calculatePeakQualities returns a modified object amended with peak qualities and scores.

selectIons returns a featureGroups object with only the selected feature groups and amended with adduct annotations.

normInts returns a featureGroups object, amended with data in the ISTDs and ISTDAssignments slots if featNorm="istd".

Details

The featureGroup class is the workhorse of patRoon: almost all functionality operate on its instantiated objects. The class holds all information from grouped features (obtained from features). This class itself is virtual, hence, objects are not created directly from it. Instead, 'feature groupers' such as groupFeaturesXCMS return a featureGroups derived object after performing the actual grouping of features across analyses.

Methods (by generic)

  • names(featureGroups): Obtain feature group names.

  • analyses(featureGroups): returns a character vector with the names of the analyses for which data is present in this object.

  • replicateGroups(featureGroups): returns a character vector with the names of the replicate groups for which data is present in this object.

  • groupNames(featureGroups): Same as names. Provided for consistency to other classes.

  • length(featureGroups): Obtain number of feature groups.

  • show(featureGroups): Shows summary information for this object.

  • groupTable(featureGroups): Accessor for groups slot.

  • analysisInfo(featureGroups): Obtain analysisInfo (see analysisInfo slot in features).

  • groupInfo(featureGroups): Accessor for groupInfo slot.

  • featureTable(featureGroups): Obtain feature information (see features).

  • getFeatures(featureGroups): Accessor for features slot.

  • groupFeatIndex(featureGroups): Accessor for ftindex slot.

  • groupQualities(featureGroups): Accessor for groupQualities slot.

  • groupScores(featureGroups): Accessor for groupScores slot.

  • annotations(featureGroups): Accessor for annotations slot.

  • internalStandards(featureGroups): Accessor for ISTDs slot.

  • internalStandardAssignments(featureGroups): Accessor for ISTDAssignments slot.

  • adducts(featureGroups): Returns a named character with adduct annotations assigned to each feature group (if available).

  • adducts(featureGroups) <- value: Sets adduct annotations for feature groups.

  • concentrations(featureGroups): Accessor for concentrations slot.

  • toxicities(featureGroups): Accessor for toxicities slot.

  • x[i: Subset on analyses/feature groups.

  • x[[i: Extract intensity values.

  • $: Extract intensity values for a feature group.

  • delete(featureGroups): Completely deletes specified feature groups.

  • export(featureGroups): Exports feature groups to a .csv file that is readable to Bruker ProfileAnalysis (a 'bucket table'), Bruker TASQ (an analyte database) or that is suitable as input for the Targeted peak detection functionality of MZmine.

  • as.data.table(featureGroups): Obtain a summary table (a data.table) with retention, m/z, intensity and optionally other feature data.

  • unique(featureGroups): Obtain a subset with unique feature groups present in one or more specified replicate group(s).

  • overlap(featureGroups): Obtain a subset with feature groups that overlap between a set of specified replicate group(s).

  • calculatePeakQualities(featureGroups): Calculates peak and group qualities for all features and feature groups. The peak qualities (and scores) are calculated with the features method of this function, and subsequently averaged per feature group. Then, MetaClean is used to calculate the Elution Shift and Retention Time Consistency group quality metrics (see the MetaClean publication cited below for more details). Similarly to the features method, these metrics are scored by normalizing qualities among all groups and scaling them from 0 (worst) to 1 (best). The totalScore for each group is then calculated as the weighted sum from all feature (group) scores. The getMCTrainData and predictCheckFeaturesSession functions can be used to train and apply Pass/Fail ML models from MetaClean.

  • selectIons(featureGroups): uses componentization results to select feature groups with preferred adduct ion and/or isotope annotation. Typically, this means that only feature groups are kept if they are (de-)protonated adducts and are monoisotopic. The adduct annotation assignments for the selected feature groups are copied from the components to the annotations slot. If the adduct for a feature group is unknown, its annotation is defaulted to the 'preferred' adduct, and hence, the feature group will never be removed. Furthermore, if a component does not contain an annotation with the preferred adduct, the most intense feature group is selected instead. Similarly, if no isotope annotation is available, the feature group is assumed to be monoisotopic and thus not removed. An important advantage of selectIons is that it may considerably simplify your dataset. Furthermore, the adduct assignments allow formula/compound annotation steps later in the workflow to improve their annotation accuracy. On the other hand, it is important the componentization results are reliable. Hence, it is highly recommended that, prior to calling selectIons, the settings to generateComponents are optimized and its results are reviewed with checkComponents. Finally, the adducts<- method can be used to manually correct adduct assignments afterwards if necessary.

  • normInts(featureGroups): Provides various methods to normalizes feature intensities for each sample analysis or of all features within a feature group. See the Feature intensity normalization section below.

  • getTICs(featureGroups): Obtain the total ion chromatogram/s (TICs) of the analyses.

  • getBPCs(featureGroups): Obtain the base peak chromatogram/s (BPCs) of the analyses.

  • plotTICs(featureGroups): Plots the total ion chromatogram/s (TICs) of the analyses.

  • plotBPCs(featureGroups): Plots the base peak chromatogram/s (BPCs) of the analyses.

Slots

groups

Matrix (data.table) with intensities for each feature group (columns) per analysis (rows). Access with groups method.

analysisInfo,features

Analysis info and features class associated with this object. Access with analysisInfo and featureTable methods, respectively.

groupInfo

data.frame with retention time (rts column, in seconds) and m/z (mzs column) for each feature group. Access with groupInfo method.

ftindex

Matrix (data.table) with feature indices for each feature group (columns) per analysis (rows). Each index corresponds to the row within the feature table of the analysis (see featureTable).

groupQualities,groupScores

A data.table with qualities/scores for each feature group (see the calculatePeakQualities method).

annotations

A data.table with adduct annotations for each group (see the selectIons method).

ISTDs

A data.table with screening results for internal standards (filled in by the normInts method).

ISTDAssignments

A list, where each item is named by a feature group and consists of a vector with feature group names of the internal standards assigned to it (filled in by the normInts method).

concentrations,toxicities

A data.table with predicted concentrations/toxicities for each feature group. Assigned by the calculateConcs/calculateTox methods. Use the concentratrions/toxicities methods for access.

groupAlgo,groupArgs,groupVerbose

(sets workflow) Grouping parameters that were used when this object was created. Used by adducts<- and selectIons when these methods perform a re-grouping of features.

annotations,ISTDAssignments

(sets workflow) As the featureGroups slots, but contains the data per set.

annotationsChanged

Set internally by adducts()<- and applied as soon as reGroup=TRUE.

S4 class hierarchy

Feature intensity normalization

The normInts method performs normalization of feature intensities (and areas). These values are amended in the features slot, while the original intensities/areas are kept. To use the normalized intensities set normalized=TRUE to methods such as plotInt, generateComponentsIntClust and as.data.table. Please see the normalized argument documentation for these methods for more details.

The normInts method supports several methods to normalize intensities/areas of features within the same analysis. Most methods are influenced by the normalization concentration (norm_conc in the analysis information) set for each sample analysis. For NA or zero values the output will be zero. If the norm_conc is completely absent from the analysis information, the normalization concentration is defaulted to one.

The different normalization methods are:

  1. featNorm="istd" Uses internal standards (IS) for normalization. The IS are screened internally by the screenSuspects function. Hence, the IS specified by the standards argument should follow the format of a suspect list. Note that labelled elements in IS formulae should be specified with the rcdk format, e.g. "[13]C" for 13C, "[2]H" for a deuterium etc. Example IS lists are provided with the patRoonData package.

    The assignment of IS to features is automatically performed, using the following criteria:

    1. Only analyses are considered with a defined normalization concentration.

    2. The IS must be detected in all of the analyses in which the feature was detected.

    3. The retention time and m/z are reasonably close (ISTDRTWindow/ISTDMZWindow arguments). However, additional IS candidates outside these windows will be chosen if the number of candidates is less than the minISTDs argument. In this case the next close(st) candidate(s) will be chosen.

    Normalization of features within the same feature group always occur with the same IS. If multiple IS are assigned to a feature then normalization occurs with the combined intensity (area), which is calculated with the function defined by the normFunc argument. The (combined) IS intensity is then normalized by the normalization concentration, and finally used for feature normalization.

  2. featNorm="tic" Uses the Total Ion Current (TIC) to normalize intensities. The TIC is calculated by combining all intensities with the function defined by the normFunc argument. For this reason, you may need to take care to perform normalization before e.g. suspect screening or other prioritization techniques. The TIC normalized intensities are finally divided by the normalization concentration.

  3. featNorm="conc" Simply divides all intensities (areas) with the normalization concentration defined for the sample.

  4. featNorm="none" Performs no normalization. The raw intensity values are simply copied. This is mainly useful if you only want to do group normalization (described below).

The meaning of the normalization concentration differs for each method: for "istd" it resembles the IS concentration of a sample analysis, whereas for "tic" and "conc" it is used to normalize different sample amounts (e.g. injection volume).

If groupNorm=TRUE then feature intensities (areas) will be normalized by the combined values for its feature group (again, combination occurs with normFunc). This group normalization always occurs after aforementioned normalization methods. Group normalization was the only method with patRoon <2.1, and still occurs automatically if normInts was not called when a method is executed that requests normalized data.

Sets workflows

The featureGroupsSet class is applicable for sets workflows. This class is derived from featureGroups and therefore largely follows the same user interface.

The following methods are specifically defined for sets workflows:

  • sets Returns the set names for this object.

  • unset Converts the object data for a specified set into a 'non-set' object (featureGroupsUnset), which allows it to be used in 'regular' workflows. The adduct annotations for the selected set are used to convert all feature (group) masses to ionic m/z values. The annotations persist in the converted object.

The following methods are changed or with new functionality:

  • adducts, adducts<- require the set argument. The order of the data that is returned/changed follows that of the annotations slot. Furthermore, adducts<- will perform a re-grouping of features when its reGroup parameter is set to TRUE. The implications for this are discussed below. Note that no adducts are changed until reGroup=TRUE.

  • the subset operator ([) has specific arguments to choose (feature presence in) sets. See the argument descriptions.

  • as.data.table: normalization of intensities is performed per set.

  • export Only allows to export data from one set. The unset method is used prior to exporting the data.

  • overlap and unique allow to handle data per set. See the sets argument description.

  • selectIons Will perform a re-grouping of features. The implications of this are discussed below.

  • normInts Performs normalization for each set independently.

A re-grouping of features occurs if selectIons is called or adducts<- is used with reGroup=TRUE. Afterwards, it is very likely that feature group names are changed. Since data generated later in the workflow (e.g. annotation steps) rely on feature group names, these objects are not valid anymore, and must be re-generated.

References

Chetnik K, Petrick L, Pandey G (2020). “MetaClean: a machine learning-based classifier for reduced false positive peak detection in untargeted LC-MS metabolomics data.” Metabolomics, 16(11). doi:10.1007/s11306-020-01738-3 .

See also

groupFeatures for generating feature groups, feature-filtering and feature-plotting for more advanced featureGroups methods.

Author

Rick Helmus <r.helmus@uva.nl> and Ricardo Cunha <cunha@iuta.de> (getTICs and getBPCs functions)