8.2 Performing IMS workflows

8.2.1 Parameter defaults

To effectively process IMS-HRMS data, it may be required to adjust the default numerical limits (e.g. mobility tolerances) and other settings. This is especially important since (1) different IMS instruments typically use different mobility units and (2) the data is often more ‘raw’, i.e. more noisy and without centroiding, which therefore require more instrument sensitive optimization. To simplify this, patRoon brings defaults for Bruker timsTOF and Agilent IMS instruments. The default instrument type and general numeric limits, are specified in the limits file. The instrument type that is defined there, also affects the default settings used for piek, mobilogram extraction and peak list generation (discussed later). To generate a limits file with the default settings for Agilent IMS data, the following code can be used:

genLimitsFile(IMS = "agilent")

A limits file is normally generated when using the newProject() function to create a new project. If no limits file is present, the defaults are used from Bruker instruments. See the limits advanced section for more details on the limits file and how to adjust it.

8.2.2 Raw data

The data conversion and pre-treatment section already discussed how raw data can be converted to make it suitable for processing. For the workflows that require raw data that has IMS data (see the Table of the previous section) there are two options:

Use the raw instrument directly. This is currently only supported for Bruker TIMS data, see details here.
Convert the data to the ims type in the mzML file format, e.g. by using convertMSFiles() (explained here).

If IMS collapsed data is needed (see the Table of the previous section) then raw data of the type raw or ims should be converted to the type centroid.

The data conversion and pre-treatment section includes some examples on how to do these conversion steps.

8.2.3 Direct mobility assignment (DMA) workflows

8.2.3.1 Feature detection

In direct mobility assignment (DMA) workflows the feature detection needs to be aware of the IMS dimension. In patRoon this is currently only supported by the piek algorithm. Alternatively, feature data from another IMS aware feature detection can also be imported.

The piek algorithm was already discussed before. By default, piek does not use IMS data for feature detection, even if processing IMS-HRMS data. To enable the use of IMS data, the IMS function argument be set to TRUE. For instance:

# comprehensive feature detection from 2 dimensional EIC bins
genEICParams <- getPiekEICParams(mzRange = c(100, 800), mobRange = c(0.5, 1.5), mzStep = 0.02, mobStep = 0.2)
peakParams <- getDefPeakParams("chrom", "piek")
fList <- findFeatures(anaInfo, "piek", IMS = TRUE, genEICParams = genEICParams, peakParams = peakParams)

8.2.3.1.1 Optimizing computational demands

When piek is used to detect IMS resolved features, it will generate features from EIC bins that are created from the m/z and mobility dimension. This can result in a very large number of EIC bins, which can make feature detection computationally intensive. For this reason, it is recommended to have sufficient amount of RAM (e.g. >= 32GB).

In addition, there are several advanced EIC parameters that can be tweaked to reduce computational demands (see ?getPiekEICParams for a complete overview). For instance:

EIC parameter	Description
`mzRange`, `mobRange`	Limits the dimensions of the EIC bins. Reducing this can significantly speed up feature detection.
`retRange`	Limits the retention time range of the EIC bins. Useful to e.g. discard features from the dead volume.
`filter`, `filterIMS`	Applies filters which can considerably reduce the number of EIC bins. The `filter` parameter was discussed before. The `filterIMS` parameter is analogous to `filter`, but applies the given filter in the mobility dimension. `filterIMS` should be either `"none"` for no mobility filtering or equalling `"filter"` (i.e. `"suspects"` or `"ms2"`).
`minEICIntensity`	Discard EICs with a maximum intensity below the given intensity threshold.
`minEICAdjTime`, `minEICAdjPoints`, `minEICAdjIntensity`	Discard EICs without a clear continious signal.
`topMostEICMob`	Only keep these top most intense EICs (based on maximum signal intensity).

Furthermore, the EICBatchSize function argument can be set to split the work in multiple batches, which is especially useful to reduce RAM usage. The following examples show how these parameters can be used to reduce computational needs:

# filter EIC bins by m/z and mobility data from detected PASEF MS2 precursors
genEICParams <- getPiekEICParams(filter = "ms2", filterIMS = "ms2", minTIC = 1000)
fList <- findFeatures(anaInfo, "piek", IMS = TRUE, genEICParams = genEICParams)

# filter by suspect m/z data, but don't filter mobility bins (e.g. if suspect list doesn't contain IMS data)
genEICParams <- getPiekEICParams(filter = "suspects", filterIMS = "none", mobRange = c(0.5, 1.5))
fList <- findFeatures(anaInfo, "piek", IMS = TRUE, genEICParams = genEICParams,
                      suspects = suspList, adduct = "[M+H]+")

# focus on low m/z and mobility features with high intensity
# don't load and process more than 10,000 EICs at a time
genEICParams <- getPiekEICParams(mzRange = c(100, 300), mobRange = c(0.5, 0.8), minEICIntensity = 1E5)
fList <- findFeatures(anaInfo, "piek", IMS = TRUE, genEICParams = genEICParams, EICBatchSize = 1E4)

8.2.3.1.2 m/z and mobility determination

The raw m/z and mobility data is typically not or partially centroided. For this reason, piek automatically generates m/z and mobility versus intensity peak profiles for each feature, and determines the m/z and mobility data from these profiles. This process is largely similar to centroiding in HRMS workflows. For accurate m/z and mobility determination, it may be needed to tweak the default parameters that are used for profile generation:

EIC profile parameter	Description
`sumWindowMZ`, `sumWindowMob`	The retention window (+/- seconds) for summing up raw data to generate the profiles. Summing up multiple data points is especially needed for noisy data, e.g. generated with fast timsTOF methods. It’s best to keep this smaller than the expected minimum LC peak width to avoid summing up data from different chromatographic peaks. Setting this to zero will dsiable summing.
`smoothWindowMZ`, `smoothWindowMob`, `smoothExtMZ`, `smoothExtMob`	Smoothing parameters. This is again primarily useful for noisy data. Setting these to zero will disable smoothing.

8.2.3.1.3 Instrument defaults

To simplify the configuration of the previously discussed parameters, piek brings defaults for two different instrument types. The instrument is set by the IMS argument for getPiekEICParams() and should be set to "bruker" or "agilent", for Bruker timsTOF and Agilent IMS data, respectively. The default value for IMS is determined from the value determined from the previously discussed limits file.

8.2.3.2 Feature grouping

The grouping of features in DMA workflows is currently only possible with the greedy algorithm or by importing data. The greedy algorithm was already briefly introduced before. This algorithm was introduced in patRoon 3.0 and is a simple and fast grouping algorithm, which also supports IMS data. Its mobWindow argument can be set to configure the mobility grouping tolerance. Some examples:

fGroups <- groupFeatures(fList, "greedy", mobWindow = 1)

# customize all tolerances and weights
fGroups <- groupFeatures(fList, "greedy",
                         rtWindow = 5,
                         mzWindow = 0.003,
                         mobWindow = 0.5,
                         scoreWeights = c(retention = 1, mz = 3, mobility = 3, intensity = 1))

8.2.4 Post mobility assignment (PMA) workflows

8.2.4.1 Feature detection and sample grouping

In post mobility assignment (PMA) workflows, the feature detection and grouping is performed as in regular LC-MS workflows, i.e. without using the IMS data. Hence, the findFeatures() and groupFeatures() functions are used exactly like what was discussed before for HRMS workflows.

8.2.4.2 Assigning mobility values to features

The assignMobilities() method function is used to assign mobilities to features. The most important function arguments are:

Argument	Description
`mobPeaksParams`, `chromPeaksParams`	Parameters for the peak detection in mobilograms and chromatograms, respectively. See `?getDefPeakParams()` for more details.
`EIMParams`, `EICParams`	Parameters for the extraction of ion mobilograms (EIMs) and chromatograms (EICs), respectively. See `?getDefEIMParams()` and `?getDefEICParams()` for more details.
`fallbackEIC`	Set to `TRUE` to use the raw EIC data to update properties of IMS features, in case peak detection fails in mobility filtered EICs (steps 3-4).
`fromSuspects`	Suspect screening workflows: Use suspect data for mobility assignment, this is discussed later.
`IMSMatchParams`	Suspect screening workflows: parameters to match IMS data between features and suspects, this is discussed later.

Note that mobility assignment is only performed if either mobPeaksParams or fromSuspects is set. The latter is discussed later. The assignMobilities() method function is executed after executing groupFeatures(), with often some intermediate steps in-between (e.g. filtering, componentization, discussed later in this chapter). A single call to assignMobilities() will perform all the mobility assignment steps that were introduced before.

The EIMParams parameter influences the construction of extracted ion mobilograms (EIMs), which are used to determine the feature mobilities. Importantly, for noisy data (e.g. obtained with fast timsTOF methods), the enabling if smoothing may be needed. The IMS argument to getDefEIMParams() can be set to "bruker" or "agilent" to use defaults for Bruker timsTOF and Agilent IMS data, respectively. The default value for IMS is determined from the value determined from the previously discussed limits file.

Some examples of how to use assignMobilities() for mobility assignment are given below:

fGroups <- assignMobilities(fGroups, mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                            chromPeaksParams = getDefPeakParams("chrom", "piek"))

# customized peak detection parameters
fGroups <- assignMobilities(fGroups, mobPeaksParams = getDefPeakParams("agilent_ims", "xcms3", peakwidth = c(0.2, 3)),
                            chromPeaksParams = getDefPeakParams("chrom", "openms", gaussWidth = 20))

# use (aggressive) smoothing for noisy EIM data to improve mobility determination
fGroups <- assignMobilities(fGroups, mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                            chromPeaksParams = getDefPeakParams("chrom", "piek"),
                            EIMParams = getDefEIMParams(smooth = "sg", smLength = 25))

# like above, setting changing instrument defaults for Agilent data
fGroups <- assignMobilities(fGroups, ..., EIMParams = getDefEIMParams(IMS = "agilent"))

Further details are found in the reference manual (?assignMobilities_feat).

8.2.5 Mobility and CCS conversion

Conversion of mobility and CCS values in DMA and PMA workflows is performed with the assignMobilities() function introduced in the previous section, and is activated if its CCSParams function argument is set. This argument should be assigned with a list that contains the parameters to configure the conversions process. The parameters are instrument specific and the parameter list can be obtained with the getCCSParams() function. The most important arguments for getCCSParams() are:

Function argument	Description
`method`	Specifies the conversion method. Valid values are: `"bruker"`, `"mason-schamp_k"` `"mason-schamp_1/k"` or `"agilent"`.
`calibrant`	Specifies the calibrant file or parameters if `method="agilent"`.

The function currently only supports Bruker TIMS and Agilent IMS data (contributions to Waters data and information are very welcome!). For Bruker TIMS instruments, the method should be set to "bruker" or "mason-schamp_1/k". The former relies on the Bruker TDF-SDK (see the Installation chapter to install it). The latter doesn’t, but may give very minor differences in the results compared to how Bruker software performs its calculations. For Agilent IMS data, the method should be set to "agilent" and the calibrant argument should be set to configure the calibration settings. The value for calibrant is either a file path to the .d or OverrideImsCal.xml file that should be used for re-calibration, or a list with the elements massGas, TFix and beta. It is recommended to read the reference manual for the getCCSParams() function for more details (?getCCSParams).

Some examples of how to use assignMobilities() for mobility and CCS conversion are given below:

# conversion of Bruker TIMS data using the TDF-SDK
fGroups <- assignMobilities(fGroups, CCSParams = getCCSParams("bruker"))

# conversion of Agilent IMS data
fGroups <- assignMobilities(fGroups, CCSParams = getCCSParams("agilent", calibrant = "path/to/Calibrant.d"))

# combine mobility assignment and CCS conversion into one step
fGroups <- assignMobilities(fGroups, mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                            chromPeaksParams = getDefPeakParams("chrom", "piek"),
                            CCSParams = getCCSParams("bruker"))

8.2.6 Suspect screening

Suspect screening in IMS workflows is mostly the same as in non-IMS workflows. However, the suspect list can be extended with IMS properties to improve suspect matching, and performing the screening step may be slightly different for PMA workflows.

8.2.6.1 Suspect list

The suspect list can contain the following additional columns (all optional):

mobility: The mobility of the suspect.
CCS: The collision cross section (CCS) of the suspect.
mobility_<adduct>, CCS_<adduct>: The mobility and CCS of the suspect for a specific adduct. The <adduct> should be replaced with the adduct name, e.g. mobility_[H+Na]+ or CCS_[M-H]-.

Multiple suspect reference values can specified in each of the columns by separating them with a semicolon (;). If data for both the adduct and non-adduct specific columns is available (and not NA), then the latter gets precedence. It is recommended to include the adduct specific data whenever possible. During the suspect screening step to correct data is automatically chosen based on the adduct assigned to the feature (or assigned to the adduct function argument).

8.2.6.2 Prediction of mobility and CCS data

The assignMobilities() function that was discussed before also has a method specifically for suspect lists. It can be used for the prediction (or library matching) of IMS data for suspects and convert CCS values to mobilities (or vice versa). The common function arguments include:

Function argument	Description
`from`	Specifies from where IMS data is added. See below for more details.
`adducts`	Specifies for which adducts IMS data is added or converted. A `character` vector with multiple values is allowed. Include `NA` to also consider the usage of non-adduct specific data. Any adducts specified in the suspect list (`adduct` column) are always considered.
`CCSParams`	Parameters for the mobility and CCS conversions. See its previous introduction.
`overwrite`	Set to `TRUE` to overwrite any existing IMS data in the suspect list.

The following options exist for the from function argument:

from=NULL (default): No IMS data is added (but mobility and CCS conversion may still occur).
from="pubchemlite": IMS data is matched from the PubChemLite database with CCS data. See the Installation chapter for details on how to install the database.
from="c3sdb": Uses C3SDB to predict CCS values for suspects. See the Installation chapter for installation details.
a data.table or data.frame: A custom library with IMS data.

Some examples:

suspList <- patRoonData::suspectsPos[1:4, ]

# adds CCS values from PubChemLite and converts them to mobilities
suspList <- assignMobilities(suspList, from = "pubchemlite", adducts = c("[M+H]+", "[M+Na]+", "[M+H]-"),
                             CCSParams = getCCSParams("mason-schamp_1/k"))

#> Calculating/Validating chemical data... Done!
#> Loading PubChemLite... Done!
#> Calculating missing mobility/CCS values... Done!

suspList[, grepl("name|InChIKey|mobility|CCS", colnames(suspList))]

#>            name                    InChIKey      InChIKey1 CCS_[M+H]+ CCS_[M+Na]+ mobility_[M+H]+ mobility_[M+Na]+
#> 1          DEET MMOXZBCLCQITDF-UHFFFAOYSA-N MMOXZBCLCQITDF      143.7       150.2       0.6707548        0.7057198
#> 2       Diglyme SBZXBUIDTXKZTM-UHFFFAOYSA-N SBZXBUIDTXKZTM      127.5       134.6       0.5797684        0.6195436
#> 3 Dimethametryn IKYICRRUVNIHPP-QMMMGPOBSA-N IKYICRRUVNIHPP      159.6       166.1       0.7571080        0.7910301
#> 4       Irgarol HDHLIWCXDDZUFH-UHFFFAOYSA-N HDHLIWCXDDZUFH      162.0       171.2       0.7681929        0.8150460

# overwrites data from custom library
IMSLib <- data.frame(
    name = c("DEET", "Diglyme"), # (name column is not mandatory)
    InChIKey1 = c("MMOXZBCLCQITDF", "SBZXBUIDTXKZTM"), # NOTE: matching happens by first-block IK by default
    "CCS_[M+H]+" = c(150, 160),
    check.names = FALSE # NOTE: need this to allow special characters in column names (ie in CCS column)
)
suspList <- assignMobilities(suspList, from = IMSLib, overwrite = TRUE,
                             adducts = "[M+H]+", CCSParams = getCCSParams("mason-schamp_1/k"))

#> Calculating/Validating chemical data... Done!
#> Calculating/Validating chemical data... Done!
#> Calculating missing mobility/CCS values... Done!

suspList[, grepl("name|InChIKey|mobility|CCS", colnames(suspList))]

#>            name                    InChIKey      InChIKey1 CCS_[M+H]+ CCS_[M+Na]+ mobility_[M+H]+ mobility_[M+Na]+
#> 1          DEET MMOXZBCLCQITDF-UHFFFAOYSA-N MMOXZBCLCQITDF      150.0       150.2       0.7001616        0.7057198
#> 2       Diglyme SBZXBUIDTXKZTM-UHFFFAOYSA-N SBZXBUIDTXKZTM      160.0       134.6       0.7275526        0.6195436
#> 3 Dimethametryn IKYICRRUVNIHPP-QMMMGPOBSA-N IKYICRRUVNIHPP      159.6       166.1       0.7571080        0.7910301
#> 4       Irgarol HDHLIWCXDDZUFH-UHFFFAOYSA-N HDHLIWCXDDZUFH      162.0       171.2       0.7681929        0.8150460

8.2.6.3 Performing suspect screening

The screenSuspects() method function introduced before is also used to perform the suspect screening in IMS workflows. The IMSMatchParams argument configures how IMS data is used to match suspects and features. See ?getIMSMatchParams and the examples below for more details.

In post mobility assignment workflows, it is possible to perform the suspect screening before assignMobilities() is executed to assign the feature mobilities. In this case the IMSMatchParams argument can also be passed to assignMobilities() to filter out any suspect hits with deviating IMS data after feature mobilities have been assigned. This may be useful to e.g. first prioritize features with suspect screening and other steps before assigning mobilities to the remaining features.

Some examples are shown below:

# suspList is a suspect list with CCS and mobility data (see previous subsections)

# screen with default CCS matching parameters
fGroupsScr <- screenSuspects(fGroups, suspects = suspList, adduct = "[M+H]+",
                             IMSMatchParams = getIMSMatchParams("CCS"))

# match suspects on mobility with a +/- 0.1 tolerance
fGroupsScr <- screenSuspects(fGroups, suspects = suspList, adduct = "[M+H]+",
                             IMSMatchParams = getIMSMatchParams("mobility", window = 0.1, relative = FALSE))

# match suspects on CCS with a +/- 6% tolerance
fGroupsScr <- screenSuspects(fGroups, suspects = suspList, adduct = "[M+H]+",
                             IMSMatchParams = getIMSMatchParams("CCS", window = 0.06, relative = TRUE))

# post mobility assignment workflow with prior suspect screening
# regular non-IMS suspect screening
fGroupsScr <- screenSuspects(fGroups, suspects = suspList, adduct = "[M+H]+", onlyHits = TRUE)
# ... do other things such as more feature prioritization
# ... and assign mobilities to the remaining features, match already screened suspects by CCS
fGroupsScr <- assignMobilities(fGroupsScr, mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                               chromPeaksParams = getDefPeakParams("chrom", "piek"),
                               IMSMatchParams = getIMSMatchParams("CCS"))

8.2.6.4 Assigning feature mobilities from suspect data

In post mobility assignment workflows, the assignMobilities() method function can also be used to assign feature mobilities from suspect data by setting the fromSuspects argument to TRUE. This replaces the mobility assignment step from mobilograms (step 2), and copies the assigned reference value for a suspect directly to feature data. If both fromSuspects and mobPeaksParams are set, then the mobility detection from mobilograms is performed for features without a suspect hit. If a feature has multiple hits, it is unclear which suspect value should be used, and therefore no suspect data will be used for mobility assignment in this case. The IMSRange function argument is used to derive the mobility range for the feature. Assigning mobilities from suspect data is only supported if the suspect screening was already performed prior to calling assignMobilities().

Bypassing the need for peak detection for mobility assignment may be advantageous for low intensity features. However, the mobility values assigned to features are not verified against the raw data. The feature mobility boundaries are also not derived from experimental data, hence, the assigned mobility range to the feature may not cover the actual experimental range (i.e. the peak width in a mobilogram). Thus, when intensities are updated for IMS features (step 4), these can be superficially low (i.e. partial removal of signal) or high (i.e. inclusion of data of neighboring mobility peaks). With these limitations in mind, this approach is primarily intended for the following scenarios:

The mobility for a suspect is accurately known in advance, and no additional peak detection is needed. In this case the mobWindow argument is typically set to a narrow tolerance window.
There is no interest for accurate mobility (and CCS) assignment, and IMS data should only be used as a rough filtering step. In this scenario the mobWindow argument is typically set to a relatively large tolerance window.

Below are some example of how to use assignMobilities() to assign feature mobilities from suspect data:

# suspect screening must be performed in advance
# suspList is a suspect list with IMS data (see previous subsections)
fGroups <- screenSuspects(fGroups, suspects = suspList, adduct = "[M+H]+", onlyHits = TRUE)

# scenario #1: assume suspect data is accurate
fGroups <- assignMobilities(fGroups, fromSuspects = TRUE, mobWindow = 0.01,
                            chromPeakParams = getDefPeakParams("chrom", "piek"))

# scenario #2: wide tolerance window, no interest in accurate mobility assignment
# add fallback to mobility detection for features with no (or >1) suspect hit or if no suspect mobility data is available
# set IMSMatchParams to also filter out suspect hits with deviating mobilities
fGroups <- assignMobilities(fGroups, fromSuspects = TRUE, mobWindow = 0.1,
                            mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                            chromPeakParams = getDefPeakParams("chrom", "piek"),
                            IMSMatchParams = getIMSMatchParams("CCS"))

For more details see the reference manual (?assignMobilities_feat).

8.2.7 Componentization

The algorithms that use componentization to detect adducts, isotopes, homologous series etc. (e.g. CAMERA, cliqueMS and nontarget) currently do not support IMS data. They are not supported in direct mobility assignment workflows. However, in post mobility assignment workflows they can operate on the IMS precursors (either before or after calling assignMobilities()).

The other componentization algorithms (e.g. intensity clustering and transformation products) optionally include IMS features and IMS precursors during the componentization. This is controlled by the IMS function argument to the generateComponents() function, and can be set as following:

IMS=FALSE: Do not consider any IMS features (only supported in post mobility assignment workflows).
IMS=TRUE: Only consider IMS features and ignore any IMS precursors.
IMS="both": Consider both IMS features and IMS precursors.
IMS="maybe": Consider IMS precursors if present, and IMS features otherwise. This is the default value.

In the case that IMS features are not considered (i.e. IMS=FALSE or IMS="maybe"), then the componentization data from the IMS precursors is directly copied to the IMS features. This is useful when the componentization results for IMS precursors and IMS features are expected to be similar, which is often the case for the algorithms that support the IMS argument.

In post mobility assignment workflows, it is possible to perform the componentization prior to calling assignMobilities(). In this case the componentization results can be ‘expanded’ by copying the IMS precursor results to the IMS features afterwards. This is performed by the expandForIMS() method function:

# perform componentization
components <- generateComponents(fGroups, "intclust")
# assign mobilities
fGroups <- assignMobilities(fGroups, mobPeaksParams = getDefPeakParams("bruker_ims", "piek"),
                            chromPeaksParams = getDefPeakParams("chrom", "piek"))
# expand componentization results for IMS features
components <- expandForIMS(components, fGroups)

8.2.8 Annotation

IMS workflows bring several advantages to feature annotation. The generateMSPeakLists() function automatically filters MS and MS/MS spectra by the mobility range assigned to the feature, which can considerably improve the quality of peak lists. Furthermore, CCS data can be assigned to compound annotation candidates and used to eliminate unlikely candidates.

NOTE In post mobility assignment workflows it is important that the assignMobilities() method function is called prior to any feature annotation steps in order to take advantage IMS data during feature annotation.

8.2.8.1 MS peak lists

The generateMSPeakLists() function automatically filters MS and MS/MS spectra by mobility data assigned to features, and is therefore used similarly like non-IMS workflows. The function supports Bruker PASEF experiments, and can therefore assign m/z and mobility filtered MS/MS data to features. In post mobility assignment workflows, the MS and MS/MS data that will be assigned to IMS precursors are based on combined spectra for each IMS frame.

The m/z values in IMS-HRMS data are typically not (e.g. Agilent) or partially (e.g. Bruker) centroided. Since feature annotation algorithms are usually limited to centroided data, generateMSPeakLists() performs an additional centroiding step for IMS-HRMS data. The centroiding parameters, and some other advanced IMS specific parameters, are configured through the averaging parameters given to generateMSPeakLists() (avgFeatParams arguments). The default parameters can be changed with the IMS argument to getDefAvgPListParams(), which can be set to "bruker" or "agilent" for Bruker and Agilent IMS data, respectively. The default value for IMS is determined from the value determined from the previously discussed limits file. For example:

# generate peak lists with default parameters for Agilent data
mslists <- generateMSPeakLists(fGroups, avgFeatParams = getDefAvgPListParams(IMS = "agilent"))

see the reference manual for more details (?getDefAvgPListParams).

8.2.8.2 Compound annotation

Candidates from compound annotations can be matched with IMS data for features, similarly as was discussed for candidates from suspect screening. The assignMobilities() method function works similarly to assign IMS data to candidates and perform mobility and CCS conversions. The filter() method function can subsequently be used to eliminate candidates that match poorly with features (discussed later).

The assignMobilities() function has similar arguments as the method for suspect screening:

Function argument	Description
`fGroups`	The feature groups for which the `compounds` were generated.
`from`	Specifies from where IMS data is added. See the suspects section for more details.
`adduct`	Should match the value of the `adduct` argument that was passed to `generateCompounds()`. Set to `NULL` if adduct annotations are available for features or in sets workflows.
`CCSParams`	Parameters for the mobility and CCS conversions. See the previous discussion.
`overwrite`	Set to `TRUE` to overwrite any existing IMS data in the candidate list.
`IMS`	For which type of features IMS data should be added to the candidates: `FALSE` (only IMS precursors), `TRUE` (only IMS features, default), `"both"` (both IMS precursors and IMS features) or `"maybe"` (IMS precursors if available, otherwise IMS features).

NOTE If MetFrag with the PubChemLite database with CCS is used for compound annotation, then the CCS data is copied from the database and there is no need to set the from argument.

Some examples:

# generate compound candidates
compounds <- generateCompounds(fGroups, mslists, "metfrag", adduct = "[M+H]+", database = "comptox")
# perform CCS prediction with C3SDB and convert the values to mobilities
compounds <- assignMobilities(compounds, fGroups, from = "c3sdb", adduct = "[M+H]+",
                              CCSParams = getCCSParams("bruker"))

# generate compound candidates
# NOTE: if PubChemLite with CCS data is installed, then CCS data is automatically added
compounds <- generateCompounds(fGroups, mslists, "metfrag", adduct = "[M+H]+", database = "pubchemlite")
# overwrite CCS data from a custom library (candidates not in the library will be untouched)
IMSLib <- data.frame(
    name = c("Caffeine", "Acetaminophen"), # name column is not mandatory
    InChIKey = c("RYYVLZVUVIJVGH-UHFFFAOYSA-N", "RZVAJINKPMORJF-UHFFFAOYSA-N"),
    CCS = c(150, 160)
))
compounds <- assignMobilities(compounds, fGroups, from = IMSLib, adduct = "[M+H]+",
                              overwrite = TRUE)

For more details see the reference manual (?assignMobilities_comp).

8.2.8.3 Copying annotation data to IMS features with similar MS/MS data

The number of features in post mobility assignment workflows can be very large, considering that both IMS features and their IMS precursors are present. Since formula and compound annotation is primarily influenced by MS/MS data, it is possible to skip annotation for IMS features with highly similar MS/MS data as their IMS precursor, and copy the annotations from the IMS precursor result instead. The minIMSSpecSim argument to generateFormulas() and generateCompounds() sets the minimum spectral similarity threshold for when MS/MS data is considered similar.

# generate formulas: copy IMS precursor results when the spectral similarity is at least 0.9
formulas <- generateFormulas(fGroups, mslists, "genform", adduct = "[M+H]+", minIMSSpecSim = 0.9)

8.2.9 Sets workflows

There is basic functionality to combine IMS workflows and sets workflows. However, an important limitation currently is that there is no way to group IMS features across the different sets. This is because mobility values among polarities (e.g. [M+H]+ and [M-H]-) typically differ slightly and there is not a straightforward way to normalize for this. However, in post mobility assignment workflows grouping of IMS precursors across sets still occurs (similar to non-IMS workflows). Hence, the links between IMS features and IMS precursors can still give some indication which IMS features across sets are related. Thus, combined IMS and sets workflows are therefore mainly useful to e.g. process positive and negative sample analyses in one workflow, but lack other advantages of non-IMS sets workflows, such as easily relating features among sets and improving feature annotation with combined positive/negative MS/MS data.

Like non-IMS workflows, the makeSet() function is used to initialize the sets workflow.