ncdf4_plot_peak {TargetSearch} | R Documentation

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

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

[Package TargetSearch version 1.48.0 Index]