R/feature_groups.R, R/feature_groups-set.R, R/feature_groups-screening.R, and 1 more
assignMobilities_feat.RdVarious approaches to assign mobilities to features and perform CCS conversions.
# 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
)A featureGroups (derived) object to which IMS data should be assigned.
A list with peak detection parameters for mobility peaks, generated with
getDefPeakParams. Set to NULL to skip detection of mobility peaks.
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.
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.
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.
Set to TRUE to allow updating intensities and areas from raw EICs in Step 3 (see
Mobility assignment).
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.
The mobility tolerance window.
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.
A list with parameters for mobility <–> CCS conversion. See
getCCSParams for details and to make such parameter lists. Set to NULL to skip conversions.
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
If TRUE then mobilities values are directly copied from suspect list data (if available).
See the Post mobility assignment section.
(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.
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.
The post assignment of mobilities occurs in the following steps:
Extracted ion mobilograms (EIMs) are generated for all features and subjected to automatic peak detection to obtain mobility peaks.
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.
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).
Any IMS features that could not be re-integrated (either by peak detection or EIC fallback) are removed.
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.
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.
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).
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.
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.