Help for 'peak_find' program.

Date help created:  25 Sep 1995
Date last updated:  18 Oct 1996
'peak_find' finds extrema in multi-dimensional NMR spectra. These extrema may or may not represent actual peaks. The companion program peak_fit will attempt to fit extrema.

The input data has to be blocked. The input data must be real.

To run the program type

	peak_find [<memory in Mwords>] <peak_find script file>

The <memory in Mwords> is optional. By default 2 Mwords (8 Mbytes) are allocated for the main storage. The more storage that is allocated the less i/o to and from disk is required, in general.

The program is still in its early stages of development. It can be used in conjunction with Per Kraulis' Ansig program by using the macros written by Colin Hardman.

The peak_find script file has dimension-independent key words, and one doubly-dimension-dependent key word, followed by, for zero or more dimensions, dimension-dependent key words. The dimension-independent key words, as well as the doubly-dimension-dependent key word, must appear before the dimension-dependent ones.

There must be no more than one key word per line.

Below <...> represents an argument for a key word and [...] represents a key word that is optional.

The syntax for the dimension-independent key words are

	input_data <par file of input data file>
	output_peak <output peak file>
	[ high <high level> ]
	[ low <low level> ]
	[ nonadjacent ]
	[ parabolic ]

The syntax for the doubly-dimension-dependent key word is

	[ exclude <dimension 1> <dimension 2> <delta> ]

The syntax for the dimension-dependent key words (the first one is non-optional if any of the other ones appear) are

	dim <dimension>
	[ buffer <buffer size> ]
	[ range <first point> <last point> ]
	[ nonperiodic ]

A description of the key words may be obtained by typing

	peak_find help <key word>

A description of the format of the output peak file (the input peak file for peak_fit) may be obtained by typing

	peak_find help peak_format

peak_format

The peak file produced by the program has an ascii tab-separated format, with two header lines followed by one line (record; row) per extremum. The first header line contains the column titles. The second header line contains an 'N' in each column. The first column contains the extremum value (title 'extr') and the remaining columns contain the extremum position in points (title 'pntD') and ppm (title 'ppmD') in each dimension, D. If the parabolic option is chosen then the point values are given to the nearest 0.1 point (but no more than 0.4 point from the extremum center), and in addition an estimated (relative) magnitude (title 'magn') is given.

As an example, in 2D the titles would be

	extr	pnt1	ppm1	pnt2	ppm2

without the parabolic option and

	extr	pnt1	ppm1	pnt2	ppm2	magn

with the parabolic option.

input_data

input_data <par file of input data file>

	This specifies the input data file, and must be the
	first key word in the script file.

output_peak

output_peak <output peak file>

	This specifies the output peak file.  A description of the
	format may be obtained by typing

		peak_find help peak_format

high

[ high <high level> ]

	This indicates the level above which an extremum of
	the input data file is considered to be valid.
	At least one of the key words high or low must occur.
	If both appear then <high level> must be greater than
	<low level>.
	In general <high level> will be greater than 0.

low

[ low <low level> ]

	This indicates the level below which an extremum of
	the input data file is considered to be valid.
	At least one of the key words low or high must occur.
	If both appear then <low level> must be less than
	<high level>.
	In general <low level> will be less than 0.

nonadjacent

[ nonadjacent ]

	In N dimensions there are two possible nearest-neighbor
	conditions that can be used to determine whether a
	given point is an extremum.  The first just looks
	at points which differ in one dimension from the chosen
	point by +-1.  The second looks at points which differ
	in one or more dimensions from the chosen point by +-1.
	The first condition involves looking at 2N points, the
	second at 3^N - 1 points.  The following table is a
	summary the of number of points that need to be checked
	to determine whether a given point is a local extremum:

	dimension    first cond.    second cond.    ratio
	    1             2               2          1.0
	    2             4               8          2.0
	    3             6              26          4.3
	    4             8              80         10.0

	By default the first condition is used.  The nonadjacent
	key word means that instead the second condition is used.

parabolic

[ parabolic ]

	This means that a parabolic fit will be made in each
	dimension to approximately determine the peak offset 
	from the extremum center.  In addition an approximate
	(relative) peak magnitude (giving an estimate of the
	peak volume, with sign) is determined.

exclude

[ exclude <dimension 1> <dimension 2> <delta> ]

	This excludes the consideration of any extremum whose
	ppm value in <dimension 1> is within <delta> of the
	ppm value in <dimension 2>.

dim

dim <dimension>

	If any dimension-dependent key word is used for a given
	dimension then dim must be the first such key word.

buffer

[ buffer <buffer size> ]

	Taken together over all dimensions this defines a
	hypercube around any extremum inside of which no other
	extremum is considered.  The extrema are sorted in
	decreasing order of absolute extremum value, and this
	is the order in which these hypercubes are determined.
	A <buffer size> of p means that the hypercube has a
	side of length 2*p+1 points in the given dimension.
	By default the <buffer size> in each dimension is 0.
	(Thus by default all extrema are considered.)

range

[ range <first point> <last point> ]

	This restricts the range of points in the given
	dimension in which the search for extrema are
	undertaken.
	By default <first point> is 1, and <last point> is
	the number of data points in the given dimension.

nonperiodic

[ nonperiodic ]

	This specifies that the input data (spectrum) is
	nonperiodic (i.e. does not contain the entire spectral
	width).
	By default the input data is assumed to be periodic.

Azara help: peak_find / W. Boucher / azara@bioc.cam.ac.uk