checkRimLim {TargetSearch} | R Documentation

## 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 <- file.path(find.package("TargetSearchData"), "gc-ms-data")

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

    # Import RI markers (see ImportFameSettings())
    rim <- ImportFameSettings(file.path(cdfpath, "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)

[Package TargetSearch version 1.50.1 Index]