plotPeakRI: Plot peak RI across samples
In TargetSearch: A package for the analysis of GC-MS metabolite profiling data

Description Usage Arguments Details Value Author(s) See Also Examples

Plot peak RI of the quant mass of a given metabolite across samples. This function can be used to visualize the elution time of a metabolite in the RI and RT dimension, and in combination with the function sampleRI for fine tunning.

1
2
3

plotPeakRI(samples, Lib, libID, dev=NULL, mz=NULL, RI=NULL,
           method=c('RI', 'Intensity'), useRI=TRUE, main=NULL,
           col=NULL, int_range=c(2,6), cex_range=c(.7,6), key_width=2)

`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`.
`dev`	The allowed retention index (RI) deviation or `NULL`.
`mz`	A list of m/z values to search or `NULL`.
`RI`	The expected retention index or `NULL`.
`method`	A character vector used to decided what peak should be chosen in case there are ambiguous peaks. If `'RI'`, then the closest peak to the expected RI is chosen. If `'Intensity'`, then the highest is taken.
`useRI`	Logical. Should the RI or RT be displayed in the y-axis?
`main`	The title for the plot. If `NULL`, then the metabolite name is displayed.
`col`	A color vector (length > 2) to show different levels of peak intensity.
`int_range`	A length-two vector. The limits of the intensity for the color key. Note the the intensity is expressed in log10. Eg, a value of 2 represents a intensity of 100.
`cex_range`	The 'cex' range value of the points. lower-intense peaks are represented as points of smaller size.
`key_width`	The width in cm of the area allocated for the color key.

This function uses internally FindAllPeaks, so the same rules apply, i.e., the parameters dev, mz, and RI have preference over the settings of the metabolite indexed by libID.

In the plot, the x-axis are samples as defined by the object samples. The y-axis is retention index (RI) as shown on the left-hand-size. On the right-hand-size y-axis the approximate retention time (RT) is shown. This is because the RT varies across samples, therefore it is averaged for displays purposes. If useRI==FALSE, then the RT is displayed on the left hand size and the RI is averaged and shown on the left. Note that in either case, the RI is used for searching.

The point size is proportional to the log10 of the peak intensity. Their size is controlled by the parameters int_range and cex_range. By default, intensities of 100 (log10 => 2) or lower are shown with cex=0.7, while intensities greater than 1000000 (log10 => 6) as displaued with cex=6. This also affects the scaling of the color key.

The best peaks, selected acording to method, are shown with a black border, while the other are shown with no border and slightly transparent.

The output is the RI of the best peaks or invisible. Note that if no peak is found, then no plot is drawn.

Returns invisible or a numeric vector with the corresponding RI of the best peak chosen by method.

Alvaro Cuadros-Inostroza, Matthew Hannah, Henning Redestig

FindAllPeaks, sampleRI, ImportSamples, ImportLibrary

def.par <- par(no.readonly = TRUE) # save parameters for resetting

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

# get and set the RI file path
RIpath(sampleDescription) <- file.path(find.package("TargetSearchData"), "gc-ms-data")

# search all peaks of Valine (GC.3) and selective masses. Retention index
ri <- plotPeakRI(sampleDescription, refLibrary, 'GC.3')

# increase deviation, change m/z to search, change colors and title
main <- 'Valine'
cols <- c('red', 'blue', 'green')
ri <- plotPeakRI(sampleDescription, refLibrary, 'GC.3', dev=4000, mz=144,
                 main=main, col=cols)

# plot by RT instead. Note the RI is still returned
ri <- plotPeakRI(sampleDescription, refLibrary, 'GC.3', useRI=FALSE)

par(def.par) # reset to default