Using PROG_PATH /S1/Apps/Dan/bin
/s/Apps/DanBin/capp.sgi5 help
Documentation: capp.help Program: capp.c
Date Editted: November, 1994 Purpose: Contour Peak Picker
See Also: ps_contour.help and By: Dan Garrett
contour_sim.help


Program requires a minimum of three arguments:

capp <Data File> <Abs. Threshold> <Level Multiplier>

Optionally may also specify Starting and Ending chemical shifts:
<X Start> <X End> <Y Start> <Y End> <Z Start> <Z END>
where X and Y values are in PPM unless value is appended with a H or a h and Z
values are in slice number. All other options controlling the peak picker
are controlled through shell environment variables described below.

Do NOT invoke the program using
source capp.com
as this will pass the environment variables from the capp.com shell back
to the parent shell (ie the variables become defined in your window).
Make the capp.com file executable as in:
chmod +x capp.com
and then execute using:
capp.com


The <Data File> is the file name for the 2D, 3D or 4D NMR data files
which may be stored in a single file or a series of files in which each
file has a single 2D plane or 3D cube. Each file must have a 512 float
parameter header followed by a series of 32 bit floating point numbers
consisting of only the real points. If the NMR data are stored in a
series of 2D files then <Data File> should be the base name to the files
ie HNCA. The format for file names for a 3D experiment stored as a series
of 2D files is the base name appended with a three digit number indicating
the slice number (ie third dimension data point) with the extension .DAT,
ie HNCAzzz.DAT. The format for file names for a 4D experiment stored
as a series 2D files is the base name appended with a two digit number
indicating the fourth dimension data point and a three digit number indicating
the third dimension data point with the extension .DAT, ie HNCAaazzz.DAT.
The <Abs. Threshold> is the minimum absolute value for calculating contours.
The <Level Multiplier> specifies the separation between successive contour
levels to give exponentially increasing levels.


Program output can be controlled by a set of environment variables listed below.
However, default values will be used for environment variables that are not
set. To set environment variables use the unix command:
setenv <Environment-Variable> <Value of Variable>
Always use the same variable type as shown in the default, ie integer, real
or string. X dimension will be F2 (Acq) if data from NMRi is not transposed.
The Z dimension corresponds to the third dimension.

Since most of the environment variables described in ps_contour.help and
contour_sim.help are also utilized in capp.c only the differences between
the previous two programs and contour_sim.c environment variables are listed
below. Refer to ps_contour.help and contour_sim.help for more information.


Environment Default Purpose of Variable
Variable Value


*** Byte-Swap Variables *** Controls Byte-swapping of data
Floating point and integer representation differs between PC's
running Linux and Unix (ie Sun and SGi). Both float and int are
4 bytes in length. Only non-ASCII files such as NMR data,
*.XTRMA and *.CNTR files need to be byte-swapped when the
data was recorded under Linux and viewed under Unix.
The byte swapping is: ABCD <--> DCBA

DIAG_BYTE_SWAP 0 When set to non-zero show byte-swap diagnostics.
This will let you know whether byte-swapping
is taking place or not for each file.
BYTE_SWAP_AUTO 1 When possible automatically sense if byte-swapping
should be performed. Note NMRi data can NOT
automatically be sensed for byte-swapping.
BYTE_SWAP_RD_ACQ, BYTE_SWAP_RD_CNTR and
BYTE_SWAP_RD_XTRMA take precedence, ie
overide this, if they are set.
BYTE_SWAP_RD_ACQ - When set to non-zero force byte-swapping to
take place when reading processed NMR data.
If explicitly set to 0 then byte-swapping will
NOT occur when reading processed NMR data.
When BYTE_SWAP_RD_ACQ is not explicitly set
and auto-sense is enabled then byte-swapping
is determined when the header params are
read from the first plane only, ie byte-swapping
is NOT determined on a plane by plane basis.
BYTE_SWAP_RD_CNTR - When set to non-zero force byte-swapping to
take place when reading contour files.
If explicitly set to 0 then byte-swapping will
NOT occur when reading contour files. When
BYTE_SWAP_RD_CNTR is not explicitly set and
auto-sense is enabled then byte-swapping
is determined for each 2D contour plane by
counting the number of tokens which mark
the end of each contour list for both non-swapped
and swapped contour data.


*** Chart Variables *** Controls position, orientation and look of plot.

APPEND_FILE Not available in capp.c
PAGE_OUT Not available in capp.c
SPLIT_X Not available in capp.c
SPLIT_Y Not available in capp.c
OVERLAP_X Not available in capp.c
OVERLAP_Y Not available in capp.c

PLOT_ALL_SLICES 1 Will plot all slices independent of whether peaks
have been found on a given slice. If set to
0 then only the slices which have peaks found
will be plotted with desired annotation.
This is usefull when working up 4D data that
will have many slices with no peaks.
MARK_PEAKS 1 Mark contours with a rectangle or a pentagon to show
that a peak was found. A rectangle implies that
greatest intensity for peak is on this slice.
A pentagon implies that greatest intensity for peak
is on another slice. Pentagon pointing up implies
earlier slice, pentagon pointing down later slice.
MARK_ID 0 Mark peaks ID number for found peaks and + or - for
peaks with intensity on another slice.
X_LBL "X_Axis" Chemical shift header for X axis.
Y_LBL "Y_Axis" Chemical shift header for Y axis.
Z_LBL "Z_Axis" Chemical shift header for Z axis.
Other Chart Variables same as desciption in ps_contour.help


**** Spectral Expansion Variables ****

SLICE_START_Z 1 Starting Slice for peak picking.
SLICE_END_Z Z_SLICES Ending Slice for peak picking.
Z Aqcuisition variables MUST be set.

Other Spectral Expansion Variables same as desciption in ps_contour.help


**** Z Acquisition Variables ****

Z_SLICES 64 Total number of slices in 3D experiment.
All Z Aquisition variables must be set except
Z_FLIPPED, ie there are no default values.
AXIS_ON_PLANE "X_AXIS Y_AXIS" Which two axis are used to define the plane.
This decides what plane is contoured and displayed.
For 3D data can choose X_AXIS Z_AXIS and also
Y_AXIS Z_AXIS. This create a new subdirectory
using the basename with the extension
.XZ or .YZ. If DATA_GROUPED is SINGLE_DATA_FILE
then the name of contour subdirectory for XY
will also have the extension .XY.
DATA_HEADER_SZ 2048 Number of bytes in header.
DATA_GROUPED 2D_FLS Specifies the arrangement of NMR data. Options
are: 2D_FLS 3D_FLS 4D_FLS SINGLE_DATA_FILE.
The Zant format is similar to SINGLE_DATA_FILE,
but has not been tested, ie may be slight
differences in header parameters.
Other Z Acquisition Variables same as description in ps_contour.help


**** Ellipse Fitting Variables ****

WRITE_SIM_RMS 0 Write to file SIM_RMS a summary of the simulation.
This file contains a listing of how each contour
was fit to an ellipse and is usefull in determining
what parameters are best for setting up CAPP.
The * by the ID indicates that the contour would
be used to define the peak center as described
in ELL_PERC_MIDL_USE below. The parameters to
be optimized are ELL_MIN_RX, ELL_MAX_RX,
ELL_MIN_RY, ELL_MAX_RY, MIN_RX_RY, MAX_RX_RY.
WRITE_ONLY_PICKED_RMS 1 If 1 then will write to the SIM_RMS file only the peaks
that would be picked by CAPP. Setting to 0 lets
the program print out thos that would not
be picked by CAPP with a negative ID number
so you can see what the Rx and Ry are all peaks.
ELL_TBL_FRMT "6.3f" Format for X and Y columns in SIM_RMS file.
ELL_MIN_RX 0.3*dHz_X Minimum acceptable ellipse radius along X axis.
ELL_MAX_RX 5.0*dHz_X Maximum acceptable ellipse radius along X axis.
ELL_MIN_RY 0.3*dHz_Y Minimum acceptable ellipse radius along Y axis.
ELL_MAX_RY 5.0*dHz_Y Maximum acceptable ellipse radius along Y axis.
dHz_X and dHz_Y are the digital resolutions along
the X and Y axis (delta Hz).
MIN_RX_RY - Minimum acceptable ellipse radius ratio.
MAX_RX_RY - Maximum acceptable ellipse radius ratio.
MIN_RX_RY and MAX_RX_RY default to values consistent
with the largest and smallest ratio possible from
ELL_MIN_X, ELL_MAX_X ELL_MIN_Y & ELL_MAX_Y. That
is it is up to the user to set these explicitly.
PK_USE_PARAB_XY 1 If 1 then determine the center of peaks as a
3 point parabolic interpolation about the
3 tallest NMR points at the peak top. If 0
then uses the center of a defined set of contours
to determine the peak position. The defined
set of contours can be all the contours that
encircle a given peak, or it can be a small
number of contours when the params ELL_PERC_MIDL_USE
and ELL_FRACT_MIDL_LVL are also used. This
is very usefull for E-COSY data.
ELL_PERC_MIDL_USE 100 The percent number of contours to use from a peak
to define the peak position. Set this to a value
between 0.0 and 100.0 so that only a small number
of contours will be used to define the peak center.
This is used primarily for E-COSY type data to
accurately measure small splittings that are not
correctly measured using a 3 point parabolic
interpolation as done normally by CAPP and PIPP.
Setting this automatically sets PK_USE_PARAB_XY
to 0 so that peak posiitons in .PCK and .ASG
tables are the average center of the contours
which are displayed with an * in the SIM_RMS file.
The center of the contours is simply the
sum of the contour points divided by the
number of the contour points, ie the geometric
mean of the contour.
ELL_FRACT_MIDL_LVL 0.5 The fraction of the intensity that should be used
to define the contours that are used to define
the peak Position. This is only active if
ELL_PERC_MIDL_USE is also set.
MAX_DLTA_XO 20.0 Max. change (Hz) in ellipse center from optimization (X)
MAX_DLTA_YO 20.0 Max. change (Hz) in ellipse center from optimization (Y)
An estimate of the ellipse ellipse center is made
from the average of the contour points. If the
center chenges by more than MAX_DLTA_HZ_*as a
reslult the optimization than the ellipse is discared.
MIN_UNIQUE_X 0.75*dHz_X Minimum distance between two peaks that will be
MIN_UNIQUE_Y 0.75*dHz_X automatically picked by contour_sim or CAPP.
If center of ellipses define two peaks that are
this close or closer than only one peak will be kept.
For highly Zero-filled spectra such as E-COSY this
must be explicitly set to about 0.25*linewidth else
CAPP will incorectly put several peak ids on a
single peak.
ELL_MAX_RMS 10.0 Maximum acceptable root-mean-square deviation.
RMS between contour points to "nearest" point
on the ellipse model.
MAX_CIRCUM_DEV 20.0 Max. circumference deviation between contour and Ellipse.
Calc: 100.0*(Circum[Ell] - Circum[Con])/Circum[Ell]
ELL_NO_OPT 0 If set to 1 then will NOT do optimization on ellipse.
This will speed up contour_sim and CAPP by
a factor of 4 at the expense of having the ellipse
fit closely with the contours. When this is
set the Params ELL_MAX_RMS, ELL_RESOLUTION, all
the simplex params have no effect. However,
you should increase MAX_CIRCUM_DEV to 40 since
the circuference of the ellipse will be very
different than the contours.
ELL_RESOLUTION - Maximum deviation between an individual contour point
and the Closest ellipse point. This is used to
determine when a bracketed search on the ellipse
around the region that has the best ellipse point
should stop searching for the best point. If this
is too big the ellipse will poorly fit the contour
if this is too low the bracketed search may get
stuck. The default value is: 0.5*0.002*(dHz_X + dHz_Y)


**** Simplex Optimization Variables ****

SSM_X 0.2 Simplex Step Size Multiplier along the X axis.
SSM_Y 0.2 Simplex Step Size Multiplier along the Y axis.
SSM_X and SSM_Y define the initial step size for
simplex optimization. The values are first
multiplied by dHz_X and dHz_Y to get the step size
and then the step size is used to obtain the simplex
"p" and "q" parameters along each axis.
S_BEST 5.0 Simplex iterations are terminated if lowest RMS is less
than this value, ie a good ellipse has been found.
S_MIN_RANGE 1.0 Simplex iterations are terminated if difference between
lowest and highest RMS is less than this,
ie trapped in a local min.
S_ITER 50 Maximum number of Simplex iterations.


**** Peak Definition Variables ****

PK_FILE_NAME - Output file name for peak pick file table.
Defaults to base name for 3D dat files,
ie "HNF1.PCK"
READ_OLD_PK_TBL 0 Prior to performing Peak Picking the file given by
PK_FILE_NAME is read if <> 0. That is Peak
Picking will start from where it left off.
If the same slice is picked twice the peaks on that
slice will only be picked once, but cpu time will
be used to locate the peaks and then the duplicates
will be discarded.
PK_TBL_FRMT "%7.2f" Format for Peak Table Columns. To specify a seperate
format for each axis use double quotes as in:
"%8.3f %8.3f %6.1f"
PK_EXCLUDE_XY_DIAG 0 If set to 1 will exclude the X-Y Diagonal from Peak-Picking.
PK_WIDTH_XY_DIAG - Width of Diagonal (PPM), ie fabs(X-Y) <= PK_WIDTH_XY_DIAG
and peak is defined as a diagonal peak.
ANTIPHASE_FOLDOVER 0 If set to 1 then peaks near edge of third or fourth
dimension which have part of the resonance on the
last and the first slice have opposite phases.
ie 4D 13C/13C NOE. This is used in Peak-Picking
when slices adjacent to the first or the last
are probed for positive or negative peaks.
PK_X_DEV 10.0 Maximum deviation between centers of ellipses to be
defined as part of the same peak along X axis.
PK_Y_DEV 10.0 Maximum deviation between centers of ellipses to be
defined as part of the same peak along Y axis.
PK_MIN_LEVALS 2 Minimum number of contour levels to define a peak.


**** Ridge Definition Variables ****

Ridges Definition Variables are broken down into 2 groups:
Ridges Along X axis (at constant Y) and
Ridges Along Y axis (at constant X).
Within each group the variables are further broken down into
those that are used locate a ridge and those that are
used after a ridge has been found to determine if a peak
is part of the ridge or distinct from the ridge.

RIDGE_SUMM 1 Write to file RIDGE_SUMM a summary of the ridges found
and send to printer given by variable PRINTER.
Ridges Along Y axis (at constant X chemical shift)
Ridge Locator Variables:

RDG_MAX_XDEV 2*dHz_X Maximum X deviation in searching for ridges along Y.
RDG_MIN_YLENGTH .2*SW_Y Minimum length along Y that peaks are found to define a ridge.
RDG_MIN_YPKS 15 Minimum number of peaks along Y neaded to define a ridge.
If the sum of the peak widths along Y exceeds
RDG_MIN_YLENGTH then a ridge is located
independent of the number of peaks.
Determine If Peak Is on a Ridge Variables:

RDG_YWIDTH_FCTR 1.5 Multiplier to width standard deviation for determining
breadth of a ridge along Y.
RDG_YLVL_FCTR 1.5 Multiply to ridge contour level standard deviation for
determining height of a ridge along Y.
RDG_YUSE_CENTER_DEV 1 Use Deviation in Center position to calulate ridge
breadth if non-zero. Otherwise width
deviation will be used.
RDG_YMIN_LVLS 2 Minimum number of contour levels above the ridge
height for a peak on a ridge to be labeled a peak.

Ridges Along X axis (at constant Y chemical shift)
Ridge Locator Variables:

RDG_MAX_YDEV 2*dHz_Y Maximum Y deviation in searching for ridges along X.
RDG_MIN_XLENGTH .2*SW_X Minimum length along X that peaks are found to
define a ridge at this Y position.
RDG_MIN_XPKS 15 Minimum number of peaks along X neaded to define a ridge.
If the sum of the peak widths along X exceeds
RDG_MIN_XLENGTH then a ridge is located
independent of the number of peaks.

Determin If Peak Is on a Ridge Variables:

RDG_XWIDTH_FCTR 1.5 Multiplier to width standard deviation for determining
breadth of a ridge along X.
RDG_XLVL_FCTR 1.5 Multiply to ridge contour level standard deviation
for determining height of a ridge along X.
RDG_XUSE_CENTER_DEV 1 Use Deviation in Center position to calulate ridge
breadth if non-zero. Otherwise width deviation
will be used.
RDG_XMIN_LVLS 2 Minimum number of contour levels above the ridge
height for a peak on a ridge to be labeled a peak.



Version 4.3.2 ( 03/15/00 )


more /S1/Apps/Dan/bin/capp.help