ncdf4_plot_peak: Plot peaks from ncdf4 files

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

Plot peaks from ncdf4 files

Description

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

Usage

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

Arguments

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.

Details

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.

Value

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

Note

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.

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

plotPeak, plotPeakSimple, ncdf4_data_extract, RIcorrect, updateRI

Examples

require(TargetSearchData)

# load CDF files, convert them and save them in a temporary directory
dest <- tempdir()
cdf <- tsd_cdffiles()[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))

acinostroza/TargetSearch documentation built on Nov. 13, 2024, 12:28 a.m.