NAME
readROI - NMRWish command to Read a Region of Interest (ROI)
DESCRIPTION
The readROI command extracts a region of interest (ROI) from
a given spectrum. In this context, a region of interest is
an extract or projection of all or part of a given spectrum.
Some examples of ROIs include:
An individual 1D slice extracted from any dimension of a
multidimensional spectrum.
A 1D summation projection of a 2D region.
A 2D region extracted from a larger 2D spectrum.
A 2D plane extracted from any pair of dimensions in a 3D
or 4D spectrum.
A 2D strip created by summation projection of a 3D
region.
A 3D region extracted from a larger 3D or 4D spectrum.
Extracted regions can centered or aligned automatically
through interpolation, so that the extracted data
corresponds to the requested chemical shift coordinates
regardless of the digitization of the data. Furthermore,
extracted regions which exceed the measured chemical shift
window are unfolded and sign-adjusted automatically, so that
regions from related spectra can be manipulated or displayed
consistently even if they have differing spectral windows.
When creating an ROI, we specify the coordinates of a region
to extract from an original data set. We also specify how
this extracted region will be re-arranged to create the ROI
output.
Axis Names
The input region is specified on the basis of axis names.
The axis names are the ones specified during conversion of
the spectrum (conversion arguments -xLAB -yLAB etc). The
ROI commands assume that each axis in the spectrum has a
unique name.
As an alternative, the "generic" axis names "X_AXIS",
"Y_AXIS", etc can also be used.
Region Limits
The coordinates of the ND region to extract are specified in
terms of separate coordinates for each of the dimensions.
The coordinates for a given dimension can be specified as an
upper and lower bound, or as a center position and a +/-
width.
I. Arguments for Reading a Region
-in inName [None] 1D/2D Input Name or 3D/4D tem-
plate name.
-ndim finalDim [2] Dimension Count for ROI.
II. ROI Limits By Upper and
These arguments describe the region to extract by specifying
an axis name, and a starting point and ending point in that
axis. The coordinates can be specified with no units (i.e.
in points), or with the labels "hz", "ppm", or "%".
If no start and end points are given, the entire axis is
extracted.
-x xName [x1 xn] ROI X-Axis Source and Limits.
-y yName [y1 yn] ROI Y-Axis Source and Limits.
-z zName [z1 zn] ROI Z-Axis Source and Limits.
-a aName [a1 an] ROI A-Axis Source and Limits.
III. ROI Limits By Center and +/- Width
These arguments describe a region to extract by specifying
an axis name, a position on that axis, and a +/- width. The
coordinate and width can be specified with no units (i.e. in
points), or with the labels "hz", "ppm", or "%". If no
width is given, only a single point is extracted from that
axis (+/- 0).
-dx xName x0 [xW] ROI X-Axis Source, Center, Width.
-dy yName y0 [yW] ROI Y-Axis Source, Center, Width.
-dz zName z0 [zW] ROI Z-Axis Source, Center, Width.
-da aName a0 [aW] ROI A-Axis Source, Center, Width.
IV. Alignment Options
In some cases, the coordinates of the ROI may not correspond
directly to exact point locations in the spectrum. So,
alignment options are provided in an attempt to adjust the
ROI output so that its coordinates correspond more precisely
with the requested region. The alignment is currently done
via a crude linear interpolation, so it may not be very
accurate.
In these options, the "axisList" argument specifies which
dimensions of the ROI output should be adjusted, if any.
The values "X" "Y" "Z" etc can be given.
-center axisList [None] Align Center of ROI.
-left axisList [None] Align Left Edge of ROI.
-right axisList [None] Align Right Edge of ROI.
-edge axisList [None] Align Both Edges of ROI.
V. Arguments to Write a Region of Interest
-out outName Output Name for ROI result; if an output
template is
desired, use a pipeline to "pipe2xyz".
-ov Allow overwrite of existing data.
VI. Arguments for Report Generation:
-noverb Verbose Mode Off.
-verb Verbose Mode On.
VII. Examples
The following command prepares an HN 1D summation projection
from a 3D HNCO spectrum (note that the default default lim-
its are the full axis):
readROI -in hnco/ft/test%03d.ft3 -out h.dat -ndim 1 -x HN
-y N -z CO
The following command prepares an HN/N 2D summation projec-
tion from a 3D HNCO spectrum (note that the default output
dimension count is 2, and the default limits are the full
axis):
readROI -in hnco/ft/test%03d.ft3 -out hn.dat -x HN -y N
-z CO
The following two commands extract complementary 2D orthogo-
nal strips from a CBCANH 3D experiment, centered at the
location HN=8.724ppm, N=132.016ppm:
readROI -in cbcanh/ft/test%03d.ft3 -out strip1.dat -ov
-center X -dx HN 8.724ppm 0.12ppm -y CACB 0% 100% -dz N
132.016ppm 1
readROI -in cbcanh/ft/test%03d.ft3 -out strip2.dat -ov
-center X -dz HN 8.724ppm 1 -y CACB 0% 100% -dx N 132.016ppm
1.6ppm
readROI
readROI: Read a Region of Interest (ROI). Arguments for
Reading a Region of Interest (ROI):
-in inName [None] Input Name (Required).
-roi roiID [Current] ID Number for ROI.
-ndim finalDim [2] Dimension Count for ROI.
-key keyData [None] Key Data Label/Data Pairs.
ROI Limits By Upper and Lower Bounds;
-x xName [x1 xn] ROI X-Axis Source and Limits.
-y yName [y1 yn] ROI Y-Axis Source and Limits.
-z zName [z1 zn] ROI Z-Axis Source and Limits.
-a aName [a1 an] ROI A-Axis Source and Limits.
ROI Limits By Center and +/- Width:
-dx xName x0 [xW] ROI X-Axis Source, Center, Width.
-dy yName y0 [yW] ROI Y-Axis Source, Center, Width.
-dz zName z0 [zW] ROI Z-Axis Source, Center, Width.
-da aName a0 [aW] ROI A-Axis Source, Center, Width.
Alignment Options:
-center axisList [None] Align Center of ROI.
-left axisList [None] Align Left Edge of ROI.
-right axisList [None] Align Right Edge of ROI.
-edge axisList [None] Align Both Edges of ROI. Argu-
ments for Report Generation:
-noverb Verbose Mode Off.
-verb Verbose Mode On.
writeROI
writeROI: Write a Region of Interest (ROI). Arguments to
Write a Region of Interest.
-out outName Output Name for ROI result.
-roi roiID ID of ROI; Default is Current ROI.
-tty Suppress Check for I/O to TTY.
-ov Allow overwrite of existing data.
Strip Append Options (2D ROIs Only):
-init Initialize (delete) existing file;
Use prior to appending strips.
-append Append to the existing file.
-offset [0.0] Strip Axis Offset.
-step [0.0] Strip Axis Step Size;
Use 0.0 for no axis adjustment. Argu-
ments for Report Generation:
-noverb Verbose Mode Off.
-verb Verbose Mode On.