ncdf4_plot_peak: Plot peaks from ncdf4 files
In TargetSearch: A package for the analysis of GC-MS metabolite profiling data

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

A simple function to plot m/z ion traces from a CDF-4 file. This new interface supersedes the function plotPeakSimple (but that can be used for CDF-3 files).

1	ncdf4_plot_peak(obj, massValues, timeRange, useRT = TRUE, showRT = useRT, plot = TRUE, ...)

`obj`	Either a `tsSample` object or a path to NetCDF format 4 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. This requires retention time corrected CDF files or an error will be raised.
`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.
`plot`	Logical. if `FALSE` nothing is plotted. This option may be used to simply extract the data from the CDF files, but see also `ncdf4_data_extract`.
`...`	Extra arguments, such as `pch`, `col`, ..., to be passed to the plotting functions. See details below.

The function takes a list of path to CDF-4 files or an object of class tsSample as input; a list a m/z values to select for; and a time range, which can be in seconds (default) or retention time index (RI) units. For the RI units to work, the CDF files must have been previously time corrected (See RIcorrect, updateRI).

The selection of the time range units depends on the parameter useRT. If TRUE, then the search will be restricted to the specified range in seconds, otherwise RI units will be used. However, the displayed time units are defined by the parameter showRT. The default behavior is to use the same time units that were search for, but using seconds to search and RI units to display is possible by setting showRT = !useRT (or the reverse). This is useful if the retention time correction was not performed correctly and you want to verify what retention time correspond to what retention index.

The logical parameter plot controls whether a plot is drawn. This might be useful for simply extracting the data used for the plot and not caring about the plot itself. The function ncdf4_data_extract can be used for that purpose as well (in fact that function is run under the hood).

Plot styling can be achieved by passing plotting extra parameters such as col, pch, lty, and others (see par and plot). There is however a caveat due to how this function is implemented: the function calls matlines once per each file (or sample), so parameters such as col, lty, etc., apply only to the m/z values, not to the samples.

If you want to display different color lines for different samples (for example), add a ‘s’ to the respective parameter name as a prefix. Currently, these parameters are allowed: scol, stype, slty, slwd, spch, sbg, scex. See the examples below for details.

Finally, all plotting parameters are cycled over and in case of conflicts, the ‘s’ parameters take precedence.

Either a named list, one element per sample or CDF file, or invisible. Each element is in itself a list with the following components (same as the output of ncdf4_data_extract).

Time Numeric vector: the retention time in seconds
Index Numeric vector: the retention time index (or zero if the file was was not retention time corrected
Intensity Matrix: Rows are the retention times (or scans) and columns are masses.
massRange Numeric vector of length 2: the mass range of the CDF

This function is only for CDF-4 files. Use the method ncdf4Convert or the function ncdf4_convert for conversion of CDF-3 files. You may also use function plotPeakSimple if you don't want to convert the files.

Alvaro Cuadros-Inostroza

plotPeak, plotPeakSimple, ncdf4_data_extract, RIcorrect, updateRI

require(TargetSearchData)

# load CDF files, convert them and save them in a temporary directory
path <- file.path(find.package("TargetSearchData"), "gc-ms-data")
dest <- tempdir()
cdf <- dir(path, pattern='*.cdf', full=TRUE)[1:3]
cdf <- sapply(cdf, function(x) ncdf4_convert(x, outFile=file.path(dest, basename(x))))

# plot single m/z on many cdf files
ncdf4_plot_peak(cdf, massValues=c(144), timeRange=c(255, 265))
# add some style (note the usage of `slty` and `scol`)
ncdf4_plot_peak(cdf, massValues=c(144), timeRange=c(255, 265), scol=1:3, slty=1:3,
                main='Example Plot')

# plot many m/z on single cdf file (colors are set by matlines)
ncdf4_plot_peak(cdf[1], massValues=c(144, 145, 100, 218), timeRange=c(255, 265))
# add some styling (here simply use `lty` and `col`)
ncdf4_plot_peak(cdf[1], massValues=c(144, 145, 100, 218), timeRange=c(255, 265),
               col=1:4, lty=1, main='Example Plot')

# multiple m/z and files is possible but it gets messy
ncdf4_plot_peak(cdf, massValues=c(144, 145, 218), timeRange=c(255, 265),
               scol=1:3, main='Example Plot')

# do not plot anything and just get the data
z <- ncdf4_plot_peak(cdf, massValues=c(144, 145, 218), timeRange=c(255, 265), plot=FALSE)
str(z)

# using a tsSample object can achieve the same results
smp <- ImportSamplesFromDir(dest)
ncdf4_plot_peak(smp, massValues=c(144), timeRange=c(255, 265))