Skip to contents

Assign Ion Mobility and CCS values to features

Source: R/feature_groups.R, R/feature_groups-set.R, R/feature_groups-screening.R, and 1 more
assignMobilities_feat.Rd

Various approaches to assign mobilities to features and perform CCS conversions.

Usage

# S4 method for class 'featureGroups'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe"
)

# S4 method for class 'featureGroupsSet'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe"
)

# S4 method for class 'featureGroupsScreening'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe",
  fromSuspects = FALSE,
  IMSMatchParams = NULL
)

# S4 method for class 'featureGroupsScreeningSet'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe",
  fromSuspects = FALSE,
  IMSMatchParams = NULL
)

Arguments

obj

A featureGroups (derived) object to which IMS data should be assigned.

mobPeakParams

A list with peak detection parameters for mobility peaks, generated with getDefPeakParams. Set to NULL to skip detection of mobility peaks.

chromPeakParams

A list with peak detection parameters for the re-integration of IMS features, generated with getDefPeakParams. Set to NULL to skip re-integration by peak detection.

EIMParams, EICParams

Parameters to be used for the generation of EIMs (for mobility peak detection) and EICs (for IMS feature re-integration), generated by getDefEIMParams and getDefEICParams.

peakRTWindow

The retention time tolerance (in seconds) for detected peaks to be used for re-integration (Step 3, see Mobility assignment). This should be kept low to ensure no closely eluting features from other compounds are used. Note that peaks with retention times outside the RT window of the IMS precursor are always ignored.

fallbackEIC

Set to TRUE to allow updating intensities and areas from raw EICs in Step 3 (see Mobility assignment).

calcArea

controls how the area is calculated when updating from raw EIC data (see fallbackEIC): "integrate" (performs area integration) or "sum" (sums up all intensity data points). Note: these methods may be different than what is used by the feature detection of the IMS precursor or the peak detection algorithm used for re-integration, hence, comparing areas should be done with care.

mobWindow

The mobility tolerance window.

scoreWeights

A numeric with the weights used by greedy grouping. NOTE: only the mobility and intensity weights are used. See the documentation of groupFeaturesGreedy for more details on the scoring and grouping.

CCSParams

A list with parameters for mobility <–> CCS conversion. See getCCSParams for details and to make such parameter lists. Set to NULL to skip conversions.

parallel

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

Alternatively, set parallel="maybe" to disable parallelization if this normally will not

fromSuspects

If TRUE then mobilities values are directly copied from suspect list data (if available). See the Post mobility assignment section.

IMSMatchParams

(IMS workflow) A list with parameters to be used for matching IMS data. See getIMSMatchParams for details and how to make such a parameter list.

Details

The assignMobilities method function for features is used (1) to assign Ion Mobility values and (2) calculate CCS values from these mobilities.

In patRoon, two approaches are supported to assign mobilities to features: direct and post assignment (DMA and PMA). With the DMA the mobility values are directly assigned during feature detection. This is currently only supported by the piek and greedy algorithms or by importing feature data. With PMA, the mobility values are assigned after feature detection and grouping (and possibly other steps such as filtering). Thus, the PMA approach is supported by all available feature detection algorithms in patRoon. The PMA approach is further described below. Only the CCS conversion functionality of assignMobilities should be used in PMA mobility assignment workflows.

The assignment of CCS values is controlled by the CCSParams argument (see above).

In suspect screening workflows assignMobilities also assigns reference mobility and CCS values to suspect hits, and can filter hits if IMSMatchParams is set. This is similarly performed as screenSuspects, please see its documentation for more details.

Post mobility assignment

The post assignment of mobilities occurs in the following steps:

  1. Extracted ion mobilograms (EIMs) are generated for all features and subjected to automatic peak detection to obtain mobility peaks.

  2. The detected mobility peaks in an EIM are then used to form IMS features. These features inherit their LC-MS properties (RT, m/z, etc) from the corresponding IMS precursor, i.e. the feature for which the EIM was created. The mobility peak centroids and ranges are used to assign IMS data to the IMS features. Multiple mobility peaks within the same EIM result in multiple IMS features, and each are linked to the same IMS precursor. The linkage is especially useful to keep a relation between e.g. protomers.

  3. LC-MS properties such as the area, intensity and RTs are (optionally) updated by re-integration of detected peaks from mobility filtered extracted ion chromatograms. If peak detection is disabled or fails, then the intensity and areas can be estimated directly from raw EIC data (fallbackEIC argument).

  4. Any IMS features that could not be re-integrated (either by peak detection or EIC fallback) are removed.

  5. The feature grouping is updated: the IMS features with close mobilities (defined by mobWindow) within a feature group are split-off into new feature groups and linked to the original IMS precursor feature group. This is performed by the greedy grouping algorithm. LC-MS properties and most other data such as feature group qualities and scores (calculatePeakQualities), adduct annotations (e.g. selectIons), predicted concentrations and toxicities (calculateConcs and calculateTox) and internal standards for intensity normalization (normInts) are copied from the IMS precursors to the IMS feature groups.

Note that re-running assignMobilities will first remove any existing IMS features.

Suspect screening workflows

In suspect screening workflows the fromSuspects arguments can be set to alternatively perform mobility assignment directly from the suspect list data (replacing Steps 1-2). The feature mobility is simply assigned from the suspect data and the mobility range is derived from the mobWindow argument. Relationships with IMS precursors (Step 2) are similarly formed. An advantage of this approach is that no mobility peak detection is needed, which may useful for low intensity features where this could be difficult. Setting fromSuspects=TRUE is primarily intended for workflows where (1) the mobility of a suspect is accurately known upfront or (2) IMS data should only be used as a rough filtering step for feature data. In the latter case accurate feature mobility assignment is not of interest and the suspect IMS data is typically not accurately known (e.g. predicted), hence, for these workflows the tolerance specified by mobWindow should be increased.

With fromSuspects=TRUE no mobility peak detection is performed, hence, the actual presence of the feature is only verified in Step 3. For this reason, falling back to EIC data (fallbackEIC argument) is never performed for IMS features from suspects, and chromPeakParams must always be defined to allow chromatographic peak detection.

If both fromSuspects and mobPeakParams are set, regular mobility assignment (Steps 1-2) is performed for features without suspect hit. If multiple suspects were assigned to a feature group then suspect data is never used to form IMS features.

IMS features

The features (and feature groups) with IMS properties are referred to IMS features (and IMS feature groups). These are referred to orphans if their link to the original IMS precursor is removed (in post workflows, see previous section) or non-existent (direct workflows). The formation of orphans in post workflows typically occurs by removal of IMS precursors by subsetting or filtering operations.

Most data-processing functionality, such as subsetting, plotting, filtering, etc., allows to selectively operate either on the IMS features, their IMS precursors, both or either the precursor or orphans (controlled by the IMS argument to the corresponding functions).

Use of raw HRMS data

The raw data interface of patRoon is used by assignMobilities to process HRMS (or IMS-HRMS) data. Please see its documentation for more information on the supported formats and available configuration options.

Sets workflows

Mobility assignment in a sets workflow is equivalent to non-sets workflows. However, currently there is no (known) way to relate mobilities across MS polarities (+/- mode). Thus, IMS features will always be formed for each set separately. However, IMS precursors will still be grouped across polarities (like a non-IMS workflow) and their links to IMS features can therefore be used to relate IMS features across MS polarities.