checkRimLim: Visually check retention index marker limits

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

Visually check retention index marker limits

Description

A function to visually check if the retention time search limits of the retention index markers (aka FAMEs) are correct or need some adjustment.

Usage

checkRimLim(samples, rim, layout, show = TRUE, single = TRUE, extend = 0.5,
  rect.col = "#e7e7e7", mar = c(2, 2, 2, 2), oma = c(3, 3, 2, 0.5),
  cex.main = 1, type = "l", ...)

Arguments

samples	A tsSample object created by ImportSamples.
rim	A tsRim object describing the retention index markers. See ImportFameSettings.
layout	A vector of the form c(nr, nc) to arrange the panel by nr rows and nc columns. If missing then the layout is created automatically.
show	Logical. If FALSE the plot is not shown, but the data points can be used for further inspection or for custom plots.
single	Logical. If TRUE a single sample will be selected randomly for plotting. This was the old default behavior. If FALSE all samples will be used for plotting (but see note below).
extend	a numeric coefficient to extend the time window search of the respective time marker. Defaults to 0.5.
rect.col	the color for the background rectangle which indicates the current retention time limits.
mar	the subplots margins, passed to par().
oma	the outer plot margins, passed to par().
cex.main	The magnification to be used for main titles, passed to par().
type	A character vector indicating the type of plots. Default "l" for lines. Passed to matplot().
...	extra plotting arguments passed to matplot() such as col, lty, pch, lwd.

Details

The function takes a tsSample object and creates a panel plot of the m/z traces around the area in which a marker is expected to be, one panel for each marker. By default, a single (random) sample is chosen (see option single) for plotting, but it is also possible to visualize many samples at the same time (but see note below).

For multiple sample visualization, it is recommended to use sub-setting for the samples and rim arguments in order to avoid over crowded plots, specially when there are several samples and several retention index markers. See the examples below.

Plotting options such as col, lty, pch, lwd can be passed; these are in turn passed to matplot(). Note that these are passed to each panel; it not possible to pass different options to different panels (for example to have different line colors). Moreover, using options such as xlim and ylim may result in ‘empty’ plots (because each panel needs its own limits). If different styles are required, then either make your own function from the output or use subsets of the rim (tsRim) object.

Value

The output value is either invisible or it depends on the option single. If this option is TRUE (the old behavior), then the output will be a list of n times 2 matrices, each element corresponding to a retention marker. Columns are retention time and intensities of the respective marker's m/z. The rows can be as many data points are within the search window.

If single=FALSE, the output is a list whose length is equal to length(samples) and its names are equal to sampleNames(samples). Each element is in turn a list with exactly the same structure described in the paragraph above.

Note

If single=TRUE, all CDF files will be scanned, which can take a significant amount of time to parse, in particular, if there are hundred of them. Also due to this, each panel of the plot could be extremely crowded. It is therefore recommended to use sample sub-setting to reduce this number, as shown in the examples below.

See Also

matplot for plotting parameters, par for inner and outer margins parameters, tsSample, sampleNames, tsRim, ImportFameSettings

Examples

require(TargetSearchData)

# get the cdf path TargetSearchData
cdfpath <- tsd_data_path()

# import samples (see ImportSamples() for details)
samples <- ImportSamples(tsd_file_path("samples.txt"), CDFpath = cdfpath)

# Import RI markers (see ImportFameSettings())
rim <- ImportFameSettings(tsd_file_path("rimLimits.txt"))

# choose a sample at random and plot the m/z traces around the retention time window
ret <- checkRimLim(samples, rim)

# to choose a specific sample and marker, use subsetting
ret <- checkRimLim(samples[3], rim[1:2])

# to display many samples at the same time, set the option `single` to `FALSE` and select a subset
# of samples (recommended). In this example the first three samples are chosen.
ret <- checkRimLim(samples[1:3], rim, single=FALSE)

# in general, visualizing all samples (as shown below) at the same time it is not recommended
# for large number of samples.
## Not run: 
  ret <- checkRimLim(samples, rim, single=FALSE)

## End(Not run)

acinostroza/TargetSearch documentation built on Nov. 22, 2024, 3:31 p.m.