ri_plot_peak {TargetSearch} | R Documentation

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

### Author(s)

Alvaro Cuadros-Inostroza

### See Also

`plotPeakRI`, `ri_data_extract`

### Examples

    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)

[Package TargetSearch version 1.48.0 Index]