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

plotPeakRI

R Documentation

Plot peak RI across samples

Description

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 tuning.

Usage

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

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`.
`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`.
`RT`	The expected retention time to search for instead of 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 (or RT) 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 that the intensity is expressed in log10, for example, a value of 2 represents an 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.

Details

This function uses internally FindAllPeaks, so the same rules apply, i.e., the parameters dev, mz, RI, and RT 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 general, the RI of the library or the RI given by the user is used for peak searching, regardless of the value of parameter useRI. To search for RT instead, then the parameter RT is required, as well as the deviation parameter dev, as in the function FindAllPeaks.

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 displayed with cex=6. This also affects the scaling of the color key.

The best peaks, selected according 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.

Value

Returns invisible or a numeric vector with the corresponding RI of the best peak chosen by method. The RI is returned even when the parameters useRI is set to TRUE or the parameter RT is specified.

For a more comprehensive output (but less nicer plot), check the function ri_plot_peak.

Author(s)

Alvaro Cuadros-Inostroza

Examples

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) <- tsd_data_path()

# 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 and used for searching
ri <- plotPeakRI(sampleDescription, refLibrary, 'GC.3', useRI=FALSE)

# same, but search by RT instead of RI. Note that the deviation 'dev' is
# required
ri2 <- plotPeakRI(sampleDescription, refLibrary, 'GC.3', useRI=FALSE, RT=261, dev=2)

stopifnot(ri == ri2) # should be the same

par(def.par) # reset to default

acinostroza/TargetSearch documentation built on Nov. 22, 2024, 3:31 p.m.