FindAllPeaks: Extract peaks from chromatogram files - low level function

In acinostroza/TargetSearch: A package for the analysis of GC-MS metabolite profiling data

Extract peaks from chromatogram files - low level function

Description

This function extracts all peaks of a given metabolite in a given retention time (RT) or retention index (RI) window. This function is intended for fine-tuning metabolite search parameters.

Usage

FindAllPeaks(samples, Lib, libID, dev=NULL, mz=NULL, RI=NULL, RT=NULL,
         mz_type = c('selMass', 'quantMass', 'topMass'),
         columns = NULL)

Arguments

samples	A tsSample object created by ImportSamples function.
Lib	A tsLib object created by ImportLibrary function.
libID	An index (integer or character) value representing the respective metabolite in the reference library Lib. It must be a scalar.
dev	The allowed retention index (RI) deviation or NULL. See details below.
mz	A list of m/z values to search or NULL.
RI	The expected retention index or NULL.
RT	The expected retention time to search for instead of retention index, or NULL.
mz_type	whether to search for the selective, quantification or top masses of the respective metabolite.
columns	Either NULL, a character vector, or an integer vector. In most cases, leave it as NULL. This parameter is used to configure the column names or positions of RI text files. See the documentation on the text2bin function for further details.

Details

The function searches for all peaks of a metabolite in all samples within a time window (RT or RI). The parameters dev, mz, RI, and RT have preference over the settings of the metabolite indexed by libID. Moreover, the parameter RI has preference of over RT (see below). In fact, if all of these parameters are not NULL, then refLib and libID are not used.

The metabolite search can be performed using retention index (RI) or retention time (RT). To search using RI, either specify the value by setting RI, or set both RI and RT to NULL, which defaults to searching by the library RI. To search using RT, you must set RI to NULL and set dev to a value (i.e., not NULL), otherwise an error will be thrown. See examples below.

The dev parameter can either be NULL (as stated above), or a numeric vector. If the length is equal to 1, then the RI search window is the given RI plus or minus dev. If the length is 2, then the search window is from RI + dev[1] to RI + dev[2]. Note than in this case dev[1] is usually a negative value. An error is raised if the length is greater than 2. Note that as mentioned above, this parameter is required to search by RT. Needless to say, the dev parameter units should correspond with the units of RI or RT accordingly.

The columns parameter is only needed for custom text RI files. There is (usually) no need to change it.

Value

It returns a matrix in which each row represent a hit. Note that there can be zero rows if no hits are found. The columns are named and these are:

Int	Peak intensity
RI	Retention Index
RI	Retention Time
mz	the searched m/z value
fid	the respective file or sample index. An integer value.

Note

This is an internal function not intended to be invoked directly, but it is exposed for convenience and advanced users.

In the future it may replace FindPeaks.

See also the function ri_data_extract which offers a similar functionality but with different input parameters.

Author(s)

Alvaro Cuadros-Inostroza

See Also

FindPeaks, ri_data_extract,

Examples

# load pre-calculated example data files and objects
require(TargetSearchData)
data(TSExample)

# get and set the RI file path
RIpath(sampleDescription) <- tsd_data_path()

# search all peaks of Valine (GC.3) and selective masses
peaks <- FindAllPeaks(sampleDescription, refLibrary, 'GC.3')
head(peaks)

# a numeric index is also allowed
peaks <- FindAllPeaks(sampleDescription, refLibrary, 3)
head(peaks)

# an asymmetric deviation search
peaks <- FindAllPeaks(sampleDescription, refLibrary, 'GC.3', dev=c(-1000, 2000))
head(peaks)

# search arbitrary masses at arbitrary RI. The reference library and ID
# must be set set to NULL.
peaks <- FindAllPeaks(sampleDescription, NULL, NULL, dev=3000, RI=270000, mz=c(144, 100))
head(peaks)

# to search for RT, set the RT parameter to not NULL
peaks <- FindAllPeaks(sampleDescription, refLibrary, 'GC.3', dev=3.0, RT=250)
peaks <- FindAllPeaks(sampleDescription, NULL, NULL, dev=3.0, RT=250, mz=c(144, 100))

## Not run: 
    # note that 'dev' is required; this throws an error
    peaks <- FindAllPeaks(sampleDescription, NULL, NULL, RT=250, mz=c(144, 100))

## End(Not run)

acinostroza/TargetSearch documentation built on Nov. 13, 2024, 12:28 a.m.