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

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

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.

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

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

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

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.

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

Alvaro Cuadros-Inostroza

plotPeakRI, ri_data_extract

require(TargetSearchData)

# get RI files from TargetSearchData
path <- file.path(find.package("TargetSearchData"), "gc-ms-data")
rifiles <- dir(path, pattern='RI_*', full=TRUE)

# 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)