ri_plot_peak: Plot peak RI across samples - low level interface

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

Plot peak RI across samples - low level interface

Description

Plot retention index or time of peaks from RI files or samples. This is a low level interface to plotPeakRI that not relies on a metabolite library. This function is useful for quick peak data visualization.

Usage

ri_plot_peak(obj, massValues, timeRange, useRT = TRUE, showRT = useRT, sizefun = NULL, plot = TRUE, ...)

Arguments

obj	Either a tsSample object or a character vector of paths to RI files.
massValues	A numeric vector representing m/z values.
timeRange	A numeric vector of length 2 representing the lower and upper time limits.
useRT	Logical. If TRUE (default), the time range is expressed in seconds, otherwise if FALSE, the time range is in retention time index units.
showRT	Logical. Whether the x-axis of the resulting plot should represent seconds (TRUE) or retention index units (FALSE). This allows, for example, to search for a time range in seconds and display a graph in index units.
sizefun	A function that could be used to scale the point size of the plot via the parameter 'cex', for example, to scale the peak intensity. This function should take a numeric vector as input and return a positive value. If NULL, then a default function will be used. This function is called using the peak intensity as input.
plot	Logical. If FALSE nothing is plotted. This option may be used to simply extract the data from the RI files, but see also ri_data_extract.
...	Extra arguments, such as pch, col, ..., to be passed to the plotting functions. See details below.

Details

The function uses internally ri_data_extract wrapped with a call to lapply. Because the output of lapply is a list, the list is transformed to a matrix by calling rbind. A column of sample indices called sample is added so each row can be traced back to a sample.

The x-axis of the plot are indexed samples (or RI files), i.e., first sample is 1, second 2, and so on. The y-axis is retention time (RT) or retention index (RI) depending on the value of showRT. Note that you can search by RT and plot by RI depending on the value of useRT.

Plot styling can be achieved by passing plotting extra parameters such as col, pch, lty, and others (see par and plot). Because the styles can be applied per sample or per m/z value, it is possible to prefix a ‘s’ to those parameters to specify that the style applies to samples and no masses. The available parameters are scol, spch, sbg and scex. See examples and also the notes below.

The parameter sizefun is a function that takes a numeric vector as input and returns a positive value which correspond to the point size (parameter cex). This function will be applied on the peak intensities and the result will be used as cex. If NULL, the scaling function is implemented as (log10(x/100) * (9/8) + (1/2), where x is the peak intensity. Note that if either cex or scex is passed to the function, then sizefun will have no effect.

The logical parameter plot controls whether a plot is drawn. This might be useful for simply extracting the data for custom plotting with other packages such as ggplot2.

Value

Returns invisible or a five-column matrix (see below), where the number of rows correspond to the number of peaks (or points) in the searched range. If no peaks are found in the given range, then it returns NULL.

• RI retention time index or the peak.

• RT retention time.

• Intensity peak height intensity.

• mz the m/z of the peak.

• sample an integer representing the sample index.

Compare this list with ri_data_extract.

Note

This function is intended for advanced users and for debugging purposes when TargetSearch fails to detect a peak.

Not all graphical parameters passed by ... will work, in particular panel.first and panel.last are known to not work. Therefore, for more personalized plots, it is recommended to set plot=FALSE and use the returned data for plotting.

Author(s)

Alvaro Cuadros-Inostroza

See Also

plotPeakRI, ri_data_extract

Examples

require(TargetSearchData)

# get RI files from TargetSearchData
path <- tsd_data_path()
rifiles <- tsd_rifiles()

# simple plot no style
z <- ri_plot_peak(rifiles, massValues=c(144, 145, 100, 218), timeRange=c(255, 265))
# watch output data
head(z)

# add some style
ri_plot_peak(rifiles, massValues=c(144, 145, 100, 218), timeRange=c(255, 265),
             pch=1:4, col=1:4)
# display the Retention Index instead
ri_plot_peak(rifiles, massValues=c(144, 145, 100, 218), timeRange=c(255, 265),
             pch=1:4, col=1:4, showRT=FALSE)
# use RI index for the time range
ri_plot_peak(rifiles, massValues=c(144, 145, 100, 218), timeRange=c(267000, 275000),
             useRT=FALSE, pch=1:4, col=1:4)
# use styling per sample
scol <- rep(1:5, each=3)
ri_plot_peak(rifiles, massValues=c(144), timeRange=c(255, 265), pch=19, scol=scol)

# using a tsSample object can achieve the same results (RI files are in text format)
smp <- ImportSamplesFromDir(path, ftype = "text")
ri_plot_peak(smp, massValues=c(144), timeRange=c(255, 265), pch=19, scol=scol)

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