roi {rNMR} | R Documentation |
Functions for creating, changing, selecting, and displaying Regions of Interest (ROIs). ROIs are user designated subsections of a spectrum, usually used to designate peaks. ROIs are defined by a chemical shift range and can be extracted from one or multiple spectra.
roi() rn(...) ra(w1Delta = globalSettings$roi.w1, w2Delta = globalSettings$roi.w2, p = globalSettings$roi.pad, noiseFilt = globalSettings$roi.noiseFilt, ...) rc(massCenter = TRUE, inTable) rmr(p = 1) rml(p = 1) rmu(p = 1) rmd(p = 1) rei(p = 1) red(p = 1) rci(p = 1) rcd(p = 1) re(table = NULL) rr() rs(preSel = NULL, parent = NULL, ...) rsf() rsAll() rdAll() rDel(roiNames) rSum(ask = TRUE, sumFiles, sumRois, sumType, normType = "none", normList = NA) rv() rvs(...) rvm(...) se(summary = NULL)
w1Delta |
positive numeric; the width of each ROI window in the indirect
dimension (in ppm). If NULL , the width is chosen automatically based
on data observed in the window. |
w2Delta |
positive numeric; the width of each ROI window in the direct
dimension (in ppm). If NULL , the width is chosen automatically based
on data observed in the window. |
p |
numeric; for the ra function, p is the padding
percentage to be added to peak widths in 2D spectra when creating ROIs. For
all other functions, p is the percentage of an ROI with which to move,
expand, or contract the ROI. |
table |
data.frame; an ROI table to edit. |
noiseFilt |
integer; either 0 , 1 or 2 . 0
does not apply a noise filter, 1 applies a mild filter (adjacent points
in the direct dimension must be above the noise threshold), and 2
applies a strong filter (all adjacent points must be above the noise
threshold. |
massCenter |
logical; TRUE centers peaks by center of mass,
FALSE centers peaks by maximum signal observed. |
inTable |
Used internally by rNMR. |
preSel |
integer; bypasses user prompts and indicates the plot from
which ROIs will be selected. 1 selects from a list, 2 from
the main plot window, 3 from the subplot window, and 4 from
the multiple file window. |
parent |
optional Tk toplevel object to set as a parent window for a newly created dialog. If provided, the dialog will appear near its parent and will bring the parent toplevel object to the front. This is particularly useful for displaying message or error dialogs in response to user interactions within rNMR GUIs. |
roiNames |
character vector; names of ROIs to be deleted. |
ask |
logical; if TRUE , a series of dialogs are displayed
to obtain input parameters from the user and all other arguments will be
ignored. |
sumFiles |
character string/vector; spectrum name(s) as returned by names(fileFolder). |
sumRois |
character string/vector; ROIs to be included in the summary. |
sumType |
character string; indicates how the ROI data should be
summarized, must be one of maximum , minimum , absMax ,
area , absArea , w1 , or w2 . |
normType |
character string; indicates how the ROI data should be
normalized, must be one of none , internal , crossSpec ,
signal/noise , or sum . |
normList |
characters string or vector; one or more files or ROIs
to be used when normalizing the ROI data (only applicable if normType is set
to internal or crossSpec . |
summary |
data.frame; an ROI summary to edit (just the data section). |
... |
Additional arguments can be passed to internal peak picking
functions (see addArg ). |
roi
displays the ROI GUI. The "Edit" tab allows users to edit, delete,
and create new ROIs using the buttons on the left side of the tab. ROIs can
be modified by selecting the desired edit mode using the move/expand/contract
radio buttons located along the top, followed by clicking on the appropriate
arrow button to adjust active ROIs by the increment provided in the center
box. The adjustment increment may be defined in units of percent (of the ROIs
current width or height) or by PPM. Only active (selected) ROIs will be
modified.
The "Select" tab provides an interface for selecting ROIs. Selected ROIs are
referred to as "active", as the majority of the available ROI functions are
performed only on those that are currently selected. Refer to the rs
function (below) for more on selecting ROIs.
Display options for ROIs are contained within the "Display" tab. The check boxes within the "Windows" section control where ROIs are displayed. The subplot window displays all ROIs from the current spectrum. The multiple file window displays active ROIs from selected spectra. The maximum intensity for each ROI may be displayed in this window using the "ROI Maxima" option. The options on the left side of the tab control how ROIs are displayed. Press the Apply button to save any changes made to the ROI appearance settings.
The "Auto" tab contains options for automatic ROI generation using the
ra()
function. The "Fixed W1", "Fixed W2", "Padding", and "Noise
Filter" options are passed to ra()
as the w1Delta
,
w2Delta
, p
, and noiseFilt
arguments, respectively,
defined above.
Data from ROIs across multiple files may be summarized using the "Summary" tab. To select which files to include in the summary, select "All", "Active", or "Custom". The "Active" option selects all files displayed in the multiple file window. A specific file set may be selected for included in the summary by selecting the "Custom" option. The ROI selection options function in the same manner. Spectral data from the specified files and ROIs may be summarized using the options provided in the "Type" drop-down menu. Data may be summarized by peak maximum, absolute max, minimum, area, absolute area, or by chemical shift (at the absolute maximum intensity).
The "custom" option found in the "Type" drop-down menu allows the ROI data to
be summarized using a custom function provided by the user. Note that this
option is provided as a convenience for experienced rNMR users and must
be used cautiously to avoid generating errors. Before the summary is
generated, a dialog will be displayed with the names of any functions that are
present in the global environment for the current R session. Functions used
to summarize ROI data must accept at least one argument and must be capable of
operating on matrices. When the summary is generated, the rSum()
function will pass the data contained within a single ROI for a single
spectrum as the first argument to the custom function selected from the
dialog. The data will match the format of the return value of the
ed
function, a list containing file parameters (labeled
"file.par"), shifts in each dimension (labeled "w1" and "w2"), and the
spectral data for the ROI as a transposed matrix (labeled "data"). The
graphics parameters for each file in the summary will be passed to the
function as a second argument (if applicable). See fileFolder
for a more detailed explanation of each of these sections. The summary
function must return a single numeric value and must be initialized within
the global environment before the summary is generated. For instance, the
"maximum" summary type option uses the following function to summarize data
from each ROI in each file:
function(x, parm){max(x$data)}
In this example, the ROI data is passed to argument x
and only the
maximum intensity within the matrix is returned. The graphics parameters for
the file containing the ROI data are passed to the parm
argument but
are not used. It may be helpful to look at the source code for the
rSum()
function to get a better feel for how ROI data is summarized
before using the custom summary option.
Summary data may be normalized by selecting from the "Normalization" drop-down menu. Selecting "internal" will normalize the data by an internal standard, designated by adding one or more ROIs to the "Normalization files/ROIs" list. Data collected from these standards will be collected under the same conditions as the summary data (i.e.- ROIs summarized by maximum intensity will be normalized by the mean maximum intensity of the designated ROIs). Selecting "across spectra" will normalize the data to ROI data from a particular file, or the mean of the data from several files (also designated using the "Normalization files/ROIs" list). Selecting "signal to noise" will normalize the summary data to the noise level in each file. The "constant sum" option normalizes the data by the constant sum of the spectral data from each file.
rn
ra
rc
rmr
rml
rmu
rmd
rei
red
rci
rcd
re
tableEdit
function. If the table
argument is provided,
this table will be edited and returned, the current ROI table will not be
affected. See import
for more information on ROI table
structure.rr
rs
rsf
rsAll
rdAll
rDel
rvs
rv
rSum
rvm
se
tableEdit
function. If the table
argument
is provided, this table will be edited and returned, the current ROI summary
will not be affected. See import
for more information on ROI
summary structure.Ian A. Lewis ialewis@nmrfam.wisc.edu, Seth C. Schommer schommer@nmrfam.wisc.edu
import
for importing/exporting ROI tables and summaries;
ed
for extracting data from ROI tables and summaries;
rNMR
for other rNMR help topics.