plotPeakRI: Plot peak RI across samples

plotPeakRIR 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

See Also

The function ri_plot_peak which is a low level version of this function, as well as FindAllPeaks for details of the peak searching parameters. Check also referenced functions sampleRI, ImportSamples, and ImportLibrary

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 June 14, 2024, 8:03 a.m.