$<H1>$Help for 'process' program.$</H1>$
$<PRE>$
Date help created:  08 Jan 1994
Date last updated:  01 Nov 2001
$</PRE>$
'process' is a program that allows the processing of
multi-dimensional NMR data, typically starting with fid's
and finishing with spectra.  It includes the ability to
do Fourier transforms, phasing, baseline correction, etc.

The input data does not have to be blocked.
The input data cannot be deflated.

To run the program type

	process [<memory in Mwords>] <process 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 routine 'scripts_processed'
in the source file 'store.c' gives the exact requirement.)

The process script file must have the following format:

	input <par file of input data file>
	output <output (processed) data file>
	par <par file of output data file>	! this is optional
	exclude <dimension>	! this is optional for every dim
		! scripts are not run for excluded dimensions

followed by one or more lines of the form

	script <dimension> <command file>

or

	script_com <dimension>
		[ 'in-line' commands; see below ]
	end_script

for 1-dimensional processing, or

	<command> <dimensions> <one or more parameters>

for multi-dimensional processing.

Here <dimension> is the dimension to which the <command file>
should be applied.  Each command file (or group of 'in-line'
commands) has one or more lines of the form

	<command> <one or more parameters>

The dimension does not have to be given here because it is
specified with 'script' or 'script_com'.  Thus more than one
dimension can use the same command file.  Also, a given
dimension does not have to be processed, or can use more than
one command file (or more than one group of 'in-line' commands).

Note that the data is assumed to be real by default.
Also, points start counting from 1, not 0.  And points are
counted in terms of complex points, if the data is complex.

The list of commands can be obtained by typing

	process help $IREF$commands

It is recommended that commands be tested out on small data files
(e.g. one row for 1-dimensional commands) if uncertain about use.

Some typical examples can be obtained by typing

	process help $IREF$scripts

***commands

The following is the complete list of 1-dimensional commands,
grouped (approximately) according to function:
$<UL>$
$<LI>$$IREF$complex		- data is complex
$<LI>$$IREF$real		- data is real (default)
$<LI>$$IREF$complexify	- complexify real data
$<LI>$$IREF$reduce		- reduce complex data to real
$<LI>$$IREF$exchange	- exchange real and imaginary values
$<LI>$$IREF$conjugate	- conjugate complex data
$<LI>$$IREF$magnitude	- magnitude of (real or complex) data
$<LI>$$IREF$magnitude2	- magnitude squared of (real or complex) data

$<LI>$$IREF$lower		- new lower point of data
$<LI>$$IREF$upper		- new upper point of data
$<LI>$$IREF$range		- new lower and upper point of data
$<LI>$$IREF$shift		- shift data right
$<LI>$$IREF$cycle		- cycle data right or left
$<LI>$$IREF$reverse		- reverse order of data
$<LI>$$IREF$zerofill	- zero fill data
$<LI>$$IREF$set		- set real data to specified value
$<LI>$$IREF$set2		- set complex data to specified value
$<LI>$$IREF$scale		- scale real data by specified value
$<LI>$$IREF$scale2		- scale complex data by specified value
$<LI>$$IREF$mask_ppmm	- ++-- mask for data
$<LI>$$IREF$mirror_zero	- mirror data for zero dwell
$<LI>$$IREF$mirror_half	- mirror data for half dwell
$<LI>$$IREF$riri2rrii	- convert interlaced to sequential ordering for complex data
$<LI>$$IREF$rrii2riri	- convert sequential to interlaced ordering for complex data

$<LI>$$IREF$decay		- exponential weighting
$<LI>$$IREF$decay_sw	- exponential weighting
$<LI>$$IREF$gaussian	- gaussian weighting
$<LI>$$IREF$gaussian_sw	- gaussian weighting
$<LI>$$IREF$sinebell	- sinebell weighting
$<LI>$$IREF$sinebell2	- sinebell2 weighting
$<LI>$$IREF$inv_cosine	- inverse cosine weighting
$<LI>$$IREF$weight_file	- specified weighting

$<LI>$$IREF$convolve	- convolution to suppress water line using sine function
$<LI>$$IREF$conv_sine	- convolution to suppress water line using sine function
$<LI>$$IREF$conv_box	- convolution to suppress water line using box function
$<LI>$$IREF$conv_triangle	- convolution to suppress water using triangle function
$<LI>$$IREF$conv_gaussian	- convolution to suppress water line using gaussian function
$<LI>$$IREF$conv_file	- convolution to suppress water line using specified function

$<LI>$$IREF$phase		- phase data with pivot = 1
$<LI>$$IREF$phase2		- phase data with general pivot

$<LI>$$IREF$fft		- complex Fourier transform
$<LI>$$IREF$ifft		- inverse complex Fourier transform
$<LI>$$IREF$rft		- real Fourier transform
$<LI>$$IREF$irft		- inverse real Fourier transform
$<LI>$$IREF$cft		- cosine Fourier transform
$<LI>$$IREF$icft		- inverse cosine Fourier transform
$<LI>$$IREF$sft		- sine Fourier transform
$<LI>$$IREF$isft		- inverse sine Fourier transform
$<LI>$$IREF$hft		- Hilbert Fourier transform
$<LI>$$IREF$fftn		- normalised complex Fourier transform
$<LI>$$IREF$ifftn		- normalised inverse complex Fourier transform
$<LI>$$IREF$rftn		- approx. normalised real Fourier transform
$<LI>$$IREF$irftn		- approx. normalised inverse real Fourier transform
$<LI>$$IREF$cftn		- approx. normalised cosine Fourier transform
$<LI>$$IREF$icftn		- approx. normalised inverse cosine Fourier transform
$<LI>$$IREF$sftn		- normalised sine Fourier transform
$<LI>$$IREF$isftn		- normalised inverse sine Fourier transform

$<LI>$$IREF$avance		- first part of Bruker Avance transform
$<LI>$$IREF$avance2		- first part of Bruker Avance transform for given angle
$<LI>$$IREF$avance_phase	- second part of Bruker Avance transform

$<LI>$$IREF$base_const	- constant baseline correction
$<LI>$$IREF$base_const2	- constant baseline correction for fixed range
$<LI>$$IREF$base_poly	- polynomial baseline correction
$<LI>$$IREF$base_poly2	- polynomial baseline correction for fixed range
$<LI>$$IREF$base_trig	- trigonometric baseline correction
$<LI>$$IREF$base_trig2	- trigonometric baseline correction for fixed range
$<LI>$$IREF$base_points	- define baseline points
$<LI>$$IREF$base_subtract	- subtract specified baseline
$<LI>$$IREF$base_subtract2	- subtract specified baseline for fixed range

$<LI>$$IREF$lp_extend	- linear prediction of first or last points

$<LI>$$IREF$lp_forward	- linear prediction of last points
$<LI>$$IREF$lp_backward	- linear prediction of first points

$<LI>$$IREF$lp_first	- 'real' linear prediction of first points
$<LI>$$IREF$lp_first2	- 'complex' linear prediction of first points
$<LI>$$IREF$lp_last		- 'real' linear prediction of last points
$<LI>$$IREF$lp_last2	- 'complex' linear prediction of last points

$<LI>$$IREF$maxent		- 1-dimensional maximum entropy processing
$</UL>$
The following is the complete list of multi-dimensional commands:
$<UL>$
$<LI>$$IREF$maxent		- 1-dimensional maximum entropy processing
$<LI>$$IREF$maxent2		- 2-dimensional maximum entropy processing
$<LI>$$IREF$maxent3		- 3-dimensional maximum entropy processing

$<LI>$$IREF$interlace	- unwrap interlaced experiments
$</UL>$

Syntax and more details about <command> (where <command> is any
of the above commands) can be obtained by typing

	process help <command>

Read the source code to determine the exact algorithm implemented.

***scripts

'process' uses two types of files (in addition to par files and
data files):  script files and command files.  Script files are
similar in nature to those for other programs.  Command files
are similar to script files, but are specifically meant for
processing 1-dimensional commands.  The examples below should
provide ample illustration.  The script and command files are
indented for clarity.

The same command file can be used for processing in more than
one dimension.  Not all dimensions need to have a command file.
Any dimension can have more than one command file.  These
possibilities are all illustrated below.

Comments in files are everything in a line following the
occurence of the character '!'.

Note, the data is assumed to be real by default.

A typical process script file for a 3-dim. data file might be

	! typical script file that does processing in all 3 dims.

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.spc
	script 1 file1.com	! commands for dim. 1
	script 2 file2.com	! commands for dim. 2
	script 3 file2.com	! commands for dim. 3

where 'file1.com' might be

	! file1.com
	! typical command file for acquisition dimension

	complex		! data is complex
	conv_sine 8	! convolve with a half width of 8 points
			! do this to remove water signal
	sinebell 90	! do a 90 degree sinebell weighting
	zerofill 1	! zerofill once
	fft		! (complex) Fourier transform
	reduce		! reduce to real
	upper 512	! only save the first 512 points

and 'file2.com' might be

	! file2.com
	! typical command file for non-acquisition dimensions

	complex		! data is complex
	sinebell 90	! do a 90 degree sinebell weighting
	zerofill 1	! zerofill once
	fft		! (complex) Fourier transform
	phase 90 -180	! phase with phase0 = 90 and phase1 = -180
	reduce		! reduce to real

This script file uses the commands in 'file1.com' for processing
dimension 1, and those in 'file2.com' for dimensions 2 and 3.
The commands in a given command file are processed sequentially.

All of the rows in a given dimension are processed, which
eliminates the need for an explicit looping mechanism.

If baseline correction is needed in the third dimension then the
original process script file could be

	! typical script file that does processing in all 3 dims.

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.spc
	script 1 file1.com
	script 2 file2.com
	script 3 file2.com
	script 3 file3.com

where 'file3.com' might be

	! file3.com
	! only does baseline correction

	base_poly 4 2	! use window of half-width 4
			! use polynomial of degree 2

	! base_poly2 4 2 1 32	! this would fit only pts 1 to 32

If baseline correction is needed in dims. two and three then
the following process script file would work

	! typical script file that does processing in all 3 dims.

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.spc
	script 1 file1.com
	script 2 file2.com
	script 3 file2.com
	script 2 file3.com
	script 3 file3.com

An example of another process script file is

	! script file that does processing in dim. 1 only

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.fft1
	script 1 file1.com

where 'file1.com' is the same as above, and then to finish the
processing another possible process script file might be

	! script file that does maxent processing in dims. 2 and 3

	input /usr/people/wb104/edl387/edl387_5.fft1.par
	output /usr/people/wb104/edl387/edl387_5.max2
	maxent2 2 3 max2.dat

Here 'max2.dat' would be the 2-dim. maximum entropy script file.
More information on maxent script files can be obtained by typing

	process help $IREF$maxents

Alternatively, all the processing could be done at once by using

	! script file that does processing in all dims.
	! including maxent in dims. 2 and 3

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.max2
	script 1 file1.com
	maxent2 2 3 max2.dat

Another process script file for the same data file, doing maximum
entropy only in the third dimension might be

	! script file that does processing in all dims.
	! including maxent in dim. 3

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.max
	script 1 file1.com
	script 2 file2.com
	maxent 3 max.dat

Here 'max.dat' would be the 1-dim. maximum entropy script file.

Alternatively, the same processing could be accomplished by

	! script file that does processing in all dims.
	! including maxent in dim. 3

	input /usr/people/wb104/edl387/edl387_5.bin.par
	output /usr/people/wb104/edl387/edl387_5.max
	script 1 file1.com
	script 2 file2.com
	script 3 file4.com

where 'file4.com' would be

	! file4.com
	! maximum entropy processing

	maxent max.dat	! maximum entropy processing

***complex

complex
	This says that the data is complex.
	There are no parameters.
	[ source code = complex.c ]

***real

real
	This says that the data is real (this is the default).
	There are no parameters.
	[ source code = complex.c ]

***complexify

complexify
	This complexifies real data by setting the imaginary
	part to 0.
	There are no parameters.
	[ source code = complex.c ]

***reduce

reduce
	This reduces complex data to real data by throwing out the
	imaginary part.
	There are no parameters.
	[ source code = complex.c ]

***exchange

exchange
	This exchanges the real and imaginary parts of complex data.
	There are no parameters.
	[ source code = complex.c ]

***conjugate

conjugate
	This takes the (complex) conjugate of complex data.
	There are no parameters.
	[ source code = complex.c ]

***magnitude

magnitude
	This takes the magnitude of the data.
	For real data, this is the absolute value of the data.
	For complex data this is the square root of the sum of
	the squares of the real and imaginary part of the data.
	There are no parameters.
	[ source code = complex.c ]

***magnitude2

magnitude2
	This takes the magnitude squared of the data.
	For real data, this is the square of the data.
	For complex data this is the the sum of the squares
	of the real and imaginary part of the data.
	There are no parameters.
	[ source code = complex.c ]

***lower

lower <lower bound>
	This shifts data so that the origin is now at <lower bound>.
	If the data is complex, <lower bound> should be specified
	in terms of complex points.
	Note:  after use of $IREF$lower, point <lower bound> becomes
	point 1.  This can cause confusion if $IREF$lower is followed
	by $IREF$upper.  If both $IREF$lower and $IREF$upper need to be used
	then it is recommended that $IREF$range be used instead.
	As an example, 'lower 100' makes point 100 the new point 1.
	[ source code = arrange.c ]

***upper

upper <upper bound>
	This truncates data so that its last point is <upper bound>.
	If the data is complex, <upper bound> should be specified
	in terms of complex points.
	As an example, if the data has 1024 points (real or complex)
	and only the first 512 are to be kept, then use 'upper 512'.
	[ source code = arrange.c ]

***range

range <lower bound> <upper bound>
	This shifts and truncates data so that the origin is now
	at <lower bound> and so that the last point is <upper bound>.
	If the data is complex, <lower bound> and <upper bound>
	should be specified in terms of complex points.
	Note:  'range 131 400' is equivalent to 'upper 400'
	followed by 'lower 131' or 'lower 131' followed by
	'upper 270' (*not* 'upper 400').
	In this example, there are 270 points left after the $IREF$range.
	[ source code = arrange.c ]

***shift

shift <shift amount>
	This shifts the data by the positive amount <shift amount>.
	This shifts the data in the opposite direction to $IREF$lower.
	Thus a <shift amount> of 1 means that new_pt[2] = old_pt[1].
	The points at the left of the new data are made 0.
	$IREF$shift does not remove the points at the right, it makes
	the data longer.  Use $IREF$upper if it is desired to remove the
	points at the right.
	If the data is complex, <shift amount> should be specified
	in terms of complex points.
	As an example, 'shift 10' shifts the data to the right by
	10 points (real or complex).
	[ source code = arrange.c ]

***cycle

cycle <cycle amount>
	This cycles the data by <cycle amount>.
	If the data is complex, <cycle amount> should be specified
	in terms of complex points.
	A <cycle amount> of 1 means that new_pt[2] = old_pt[1].
	A <cycle amount> of -1 means that new_pt[1] = old_pt[2].
	As an example, 'cycle 10' cycles the data so that the old
	point 1 becomes the new point 11.
	[ source code = arrange.c ]

***reverse

reverse
	This reverses the data.  If there are n (complex/real)
	points then, for example, pt[1] and pt[n] are swapped.
	There are no parameters.
	[ source code = arrange.c ]

***zerofill

zerofill <n>
	This zero fills the data so that its final size is 2 to
	the power <n> times the original size (this is true
	independently of whether the original size is itself a
	power of 2).  <n> must be <= 4.
	As an example, 'zerofill 1' will double the size of
	the data, and would be a typical use of 'zerofill'.
	[ source code = arrange.c ]

***scale

scale <first point> <last point> <value>
	This multiplies each point between <first point>
	and <last point> (inclusive) of the data by <value>.
	The data must be real, for complex data use $IREF$scale2.
	As an example, 'scale 1 512 10.0' multiplies the
	points between 1 and 512 (inclusive) by a factor of 10.
	[ source code = arrange.c ]

***scale2

scale2 <first point> <last point> <real value> <imaginary value>
	This multiplies each point between <first point>
	and <last point> (inclusive) of the data by
	<real value> + i <imaginary value>.
	Note that this is complex multiplication, in particular
	this does not multiply the real points by <real value>
	and the imaginary points by <imaginary value>.
	The data must be complex, for real data use $IREF$scale.
	<first point> and <last point> must be specified
	in terms of complex points.
	As an example, 'scale2 1 512 0.0 1.0' multiplies the
	points between 1 and 512 (inclusive) by a factor of i.
	As another example, 'scale2 1 1 0.5 0.0' multiplies the
	first (complex) point by a factor of 0.5.
	[ source code = arrange.c ]

***set

set <first point> <last point> <value>
	This sets each point between <first point> and
	<last point> (inclusive) of the data to be <value>.
	The data must be real, for complex data use $IREF$set2.
	As an example, 'set 1 512 1.0' sets the data
	between points 1 and 512 (inclusive) to be 1.
	[ source code = arrange.c ]

***set2

set2 <first point> <last point> <real value> <imaginary value>
	This sets each point between <first point> and
	<last point> (inclusive) of the data to be
	<real value> + i <imaginary value>.
	The data must be complex, for real data use $IREF$set.
	<first point> and <last point> must be specified
	in terms of complex points.
	As an example, 'set2 1 512 1.0 0.0' sets the data
	between points 1 and 512 (inclusive) to be 1.
	[ source code = arrange.c ]

***mask_ppmm

mask_ppmm
	This is the ++-- mask needed to process some Bruker data.
	This multiplies points 3 and 4, and all other points
	equivalent to these modulo 4, by -1.
	This is not allowed on complex data.
	There are no parameters.
	[ source code = arrange.c ]

***mirror_zero

mirror_zero
	This mirrors the data for zero dwell.  This means that the
	data is extended in negative time by complex conjugating
	and reversing the existing data, excluding the first point.
	The data must be complex.
	There are no parameters.
	[ source code = arrange.c ]

***mirror_half

mirror_half
	This mirrors the data for half dwell.  This means that the
	data is extended in negative time by complex conjugating
	and reversing the existing data, including the first point.
	The data must be complex.
	There are no parameters.
	[ source code = arrange.c ]

***riri2rrii

riri2rrii
	This converts complex data for which the ordering is
	riri... (the Azara default) to rr...ii....

***rrii2riri

rrii2riri
	This converts complex data for which the ordering is
	rr...ii... to riri... (the Azara default).

***decay

decay <end value>
	This multiplies the data by a decaying exponential, 
	which, if there are n (complex/real) points,
	is 1 at point 1 and <end value> at point n.
	As an example, if n = 128, 'decay 0.5' multiplies the
	data by a decaying exponential which is 0.5 at point 128.
	And if n = 64, 'decay 0.75' multiplies the data by
	a decaying exponential which is 0.75 at point 64.
	See also $IREF$decay_sw, which has more intuitive usage.
	[ source code = weight.c ]

***decay_sw

decay_sw <line broadening (Hz)> <spectral width (Hz)>
	This multiplies the data by a decaying exponential,
	exp(-pi*LB*t), where LB is the entered line broadening
	(in Hz).
	This function will provide a matched filter (=> best
	possible S/N ratio) for lines (or multiplets) that are
	LB Hz wide, and will increase all linewidths by LB Hz.
	The spectral width (SW) is needed by the program in order
	to translate between point number, x, and the time value,
	t, used in the function, by t = x/(2*SW).  If a value of
	SW=0.0 is given, the program uses the value for SW which
	was entered in the par file (or the default).
	As an example, 'decay_sw 10 8500' has a line broadening
	of 10 Hz for a spectral width of 8500 Hz.
	[ source code = weight.c ]

***gaussian

gaussian <one fraction> <end value>
	This multiplies the data by the gaussian
	exp(a + b*x + c*x*x), where a, b and c are determined
	so that, if there are n (complex/real) points, the
	gaussian is 1, its maximum value, at point
	1 + <one fraction>*(n-1) and <end value> at point n.
	As an example, if n = 128, 'guassian 0.25 0.75'
	multiplies the data by a gaussian which is 1 at
	point 31.75 and which is 0.75 at point 128.
	See also $IREF$gaussian_sw, which has more intuitive usage.
	[ source code = weight.c ]

***gaussian_sw

gaussian_sw <line broadening (Hz)> <sharpening factor> <spectral width (Hz)>
	This multiplies the data by the gaussian
	exp(a + b*t + c*t*t).  If LB is the entered line
	broadening (in Hz) and s is the sharpening factor, then
	a = -ln2 / s^2, b = pi*LB and c = - (pi*LB*s)^2 / 4ln2.
	Note that LB must be *positive* for normal use, which is
	the *opposite* of the Bruker convention.
	The function converts a Lorentzian line (or multiplet) of
	width FWWH equal to LB to a Gaussian line of width FWWH
	equal to s * LB.  The maximum value of the multiplying
	function is 1, which is obtained at the fraction of the
	acquired time t/T = 2ln2 / (LB*pi*T*s^2).
	The spectral width (SW) is needed by the program in order
	to translate between point number, x, and the time value,
	t, used in the function, by t = x/(2*SW).  If a value of
	SW=0.0 is given, the program uses the value for SW which
	was entered in the par file (or the default).
	The suggested range of values for s are from 1.3 to 0.7
	(possibly 0.5).  Relative S/N ratio after processing
	(with S/N after matched filter = 100%) are ca. 88% for
	s=1.3, 75% for s=1, 44% for s=0.7 and 13% for s=0.5.
	Note that values of s>1 can still be advantageous, as
	they improve the S/N and as the resulting Gaussian will
	have narrower 'feet' than the original Lorentzian.
	See Ernst, Bodenhausen and Wokaun, section 4.1.3.2, or
	Ernst, Adv. Mag. Reson. 2 (1996) p. 1.
	As an example, 'gaussian_sw 10 0.7 8500' has a line
	broadening of 10 Hz for a spectral width of 8500 Hz,
	and with a sharpening factor of 0.7.
	[ source code = weight.c ]

***sinebell

sinebell <angle>
	This multiplies the data by a sine function with the given
	<angle> (specified in degrees) at point 1, and, if there
	are n (complex/real) points, with angle 180 degrees at
	point n+1 (*not* point n).
	As an example, 'sinebell 90' would be a typical use.
	This multiplies the data by a sine function which is
	1 at point 1 and 0 at point n+1.
	[ source code = weight.c ]

***sinebell2

sinebell2 <angle>
	This multiplies the data by a sine function squared with
	the given <angle> (specified in degrees) at point 1, and,
	if there are n (complex/real) points, with angle 180
	degrees at point n+1 (*not* point n).
	As an example, 'sinebell2 90' would be a typical use.
	This multiplies the data by the square of a sine
	function which is 1 at point 1 and 0 at point n+1.
	[ source code = weight.c ]

***inv_cosine

inv_cosine <frequency> <spectral width>
	This multiplies the data by the inverse cosine function
	1 / cos(d*x) (protected against dividing by zero),
	where d = 0.5 * PI * <frequency> / <spectral width>.
	[ source code = weight.c ]

***weight_file

weight_file <weight file>
	This multiplies the data by a function specified in the
	given <weight file>.
	If there are n (complex/real) points then there must be
	n values in <weight file> (in free format).
	As an example, 'weight_file edl387_5.wgt' would
	multiply the data by the values given in 'edl387_5.wgt'.
	[ source code = weight.c ]

***convolve

convolve <half width>
	This does the same thing as $IREF$conv_sine and is considered
	to be obsolete.
	[ source code = convolve.c and conv.c ]

***conv_sine

conv_sine <half width>
	This convolves the data with a sine function with the
	given <half width>, and subtracts the result from the data.
	Typically this is done on the acquisition fid before
	anything else is done, in order to remove a water signal
	that occurs at zero frequency.
	As an example, 'conv_sine 8' would be a typical use if
	there were 1024 data points.
	[ source code = convolve.c and conv.c ]

***conv_box

conv_box <half width>
	This convolves the data with a box function with the given
	<half width>, and subtracts the result from the data.
	(A box function is 1 inside the <half width> and 0 outside.)
	Typically this is done on the acquisition fid before
	anything else is done, in order to remove a water signal
	that occurs at zero frequency.
	As an example, 'conv_box 8' would be a typical use if
	there were 1024 data points.
	[ source code = convolve.c and conv.c ]

***conv_triangle

conv_triangle <half width>
	This convolves the data with a triangle function with the
	given <half width>, and subtracts the result from the data.
	(A triangle function is 1 at the maximum and decreases
	linearly to 0 at distance 1+<half width> from the maximum.)
	Typically this is done on the acquisition fid before
	anything else is done, in order to remove a water signal
	that occurs at zero frequency.
	As an example, 'conv_triangle 8' would be a typical use if
	there were 1024 data points.
	[ source code = convolve.c and conv.c ]

***conv_gaussian

conv_gaussian <half width> <end value>
	This convolves the data with a gaussian function with the
	given <half width> and equal to <end value> at <half width>
	from the maximum, and subtracts the result from the data.
	(A gaussian function is of the form exp(-a*x*x).)
	Typically this is done on the acquisition fid before
	anything else is done, in order to remove a water signal
	that occurs at zero frequency.
	As an example, 'conv_gaussian 8' would be a typical use if
	there were 1024 data points.
	[ source code = convolve.c and conv.c ]

***conv_file

conv_file <convolve file> <half width>
	This convolves the data with a function specified in the
	given <convolve file> and with the given <half width>,
	and subtracts the result from the data.
	Typically this is done on the acquisition
	fid before anything else is done, in order to remove a
	water signal that occurs at zero frequency.
	The convolution function is assumed to be 1 at the center
	and symmetric, thus only <half width> values need to be
	specified in the <convolve file>.
	As an example, 'conv_file edl387_5.conv 9' would be a
	typical use if there were 1024 data points, and in this
	case 'edl387_5.conv' might contain

		0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1

	(giving a triangular convolution function).
	[ source code = convolve.c and conv.c ]

***phase

phase <phase0> <phase1>
	This phases (complex) data with specified parameters
	<phase0> and <phase1> (both specified in degrees).
	(The pivot is assumed to be the first point.)
	This command is equivalent to 'phase2 <phase0> <phase1> 1'.
	The data must be complex.
	As an example, 'phase 90 -180' would be a typical use.
	[ source code = phase.c ]

***phase2

phase2 <phase0> <phase1> <pivot>
	This phases (complex) data with specified parameters
	<phase0> and <phase1> (both specified in degrees),
	and pivot <pivot> (the first point being point 1).
	The data must be complex.
	As an example, 'phase2 9 0 35' would be phasing
	with <phase0> = 9, <phase1> = 0 and <pivot> = 35.
	[ source code = phase.c ]

***fft

fft
	This does a complex Fourier transform.  The input data size
	does not have to be a power of 2 but the data is zero
	padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***ifft

ifft
	This does an inverse complex Fourier transform.  The input
	data size does not have to be a power of 2 but the data is
	zero padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***rft

rft
	This does a real Fourier transform.  The input data size
	does not have to be a power of 2 but the data is zero
	padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***irft

irft
	This does an inverse real Fourier transform.  The input
	data size does not have to be a power of 2 but the data is
	zero padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***cft

cft
	This does a cosine Fourier transform.  The input data size
	does not have to be a power of 2 but the data is zero
	padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***icft

icft
	This does an inverse cosine Fourier transform.  The input
	data size does not have to be a power of 2 but the data is
	zero padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***sft

sft
	This does a sine Fourier transform.  The input data size
	does not have to be a power of 2 but the data is zero
	padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***isft

isft
	This does an inverse sine Fourier transform.  The input
	data size does not have to be a power of 2 but the data is
	zero padded if it is not.
	This command is equivalent to $IREF$sft.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***hft

hft
	This does a Hilbert Fourier transform.  The input data size
	does not have to be a power of 2 but the data is zero
	padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***fftn

fftn
	This does a normalised complex Fourier transform.  The
	input data size does not have to be a power of 2 but the
	data is zero padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***ifftn

ifftn
	This does a normalised inverse complex Fourier transform.
	The input data size does not have to be a power of 2 but
	the data is zero padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***rftn

rftn
	This does an approximately normalised real Fourier
	transform.  The input data size does not have to be a
	power of 2 but the data is zero padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***irftn

irftn
	This does an approximately normalised inverse real
	Fourier transform.  The input data size does not have to
	be a power of 2 but the data is zero padded if it is not.
	The data must be complex.  There are no parameters.
	[ source code = fft.c and ft.c ]

***cftn

cftn
	This does an approximately normalised cosine Fourier
	transform.  The input data size does not have to be a
	power of 2 but the data is zero padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***icftn

icftn
	This does an approximately normalised inverse cosine
	Fourier transform.  The input data size does not have to
	be a power of 2 but the data is zero padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***sftn

sftn
	This does a normalised sine Fourier transform.  The input
	data size does not have to be a power of 2 but the data
	is zero padded if it is not.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***isftn

isftn
	This does a normalised inverse sine Fourier transform.
	The input data size does not have to be a power of 2 but
	the data is zero padded if it is not.
	This command is equivalent to $IREF$sftn.
	The data must be real.  There are no parameters.
	[ source code = fft.c and ft.c ]

***avance

avance <DSPFVS> <DECIM>
	This does the first part of the transform required for
	Bruker Avance data, with specified <DSPFVS>, <DECIM>
	and angle 180 degrees.  This does a left shift by a
	number of points calculated from <DSPFVS> and <DECIM>.
	For the second part of the transform use $IREF$avance_phase,
	which is required in combination with this command.
	This command would normally be done before convolution
	or weighting.
	For angle not 180 use $IREF$avance2.
	As an example, 'avance 12 24' has DSPFVS=12 and DECIM=24.
	[ source code = avance.c and avance_param.c ]

***avance2

avance2 <DSPFVS> <DECIM> <angle>
	This does the first part of the transform required for
	Bruker Avance data, with specified <DSPFVS>, <DECIM>
	and <angle>.  This does a left shift by a number
	of points calculated from <DSPFVS>, <DECIM> and <angle>.
	For the second part of the transform use $IREF$avance_phase,
	which is required in combination with this command.
	This command would normally be done before convolution
	or weighting.
	For angle 180 use $IREF$avance.
	As an example, 'avance2 12 24 90' has DSPFVS=12,
	DECIM=24 and angle=90.
	[ source code = avance.c and avance_param.c ]

***avance_phase

avance_phase
	This does the second part of the transform required for
	Bruker Avance data.  This does a phasing by piv = 1 and
	ph0 and ph1 calculated from the parameters as specified
	in $IREF$avance or $IREF$avance2, which must accompany this command.
	This command would normally be done just after the
	Fourier transform and before the usual phasing, and it
	must be done inside the same script as the first part
	of the transform.
	[ source code = avance.c and avance_param.c ]

***base_const

base_const <half width>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of half
	width <half width> and then fitting a constant to those
	baseline points.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	This command is equivalent to 'base_poly <half width> 0'.
	As an example, 'base_const 4' would fit a constant
	baseline, using a half-width of 4 points.
	[ source code = baseline.c and base.c ]

***base_const2

base_const2 <half width> <first point> <last point>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of size
	<half width> and then fitting a constant to those
	baseline points.
	Only the points from <first point> to <last point>
	(inclusive) are fitted.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	This command is equivalent to
	'base_poly2 <half width> 0 <first point> <last point>'.
	As an example, 'base_const2 4 1 512' would fit a
	constant baseline between points 1 and 512
	(inclusive), using a half-width of 4 points.
	[ source code = baseline.c and base.c ]

***base_poly

base_poly <half width> <degree>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of size
	<half width> and then fitting a polynomial of degree
	(order) <degree> to those baseline points.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	If <degree> = 0 this command is equivalent to
	'base_const <half width>'.
	As an example, 'base_poly 4 2' would fit the baseline
	using a second-order polynomial (i.e. a parabola) and
	a half-width of 4 points.
	[ source code = baseline.c, base.c and svd.c ]

***base_poly2

base_poly2 <half width> <degree> <first point> <last point>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of size
	<half width> and then fitting a polynomial of degree
	(order) <degree> to those baseline points.
	Only the points from <first point> to <last point>
	(inclusive) are fitted.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	If <degree> = 0 this command is equivalent to
	'base_const2 <half width> <first point> <last point>'.
	As an example, 'base_poly2 4 2 1 512' would fit the
	baseline between points 1 and 512 (inclusive) using a
	second-order polynomial (i.e. a parabola) and a
	half-width of 4 points.
	[ source code = baseline.c, base.c and svd.c ]

***base_trig

base_trig <half width> <order>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of size
	<half width> and then fitting trig functions of order
	<order> to those baseline points.  In fact, the number
	of functions used to do the fitting is 2*<order> + 1,
	the 2 being because cosines and sines are used,
	and the 1 being because a constant is also used.
	This fit only makes sense if the original data set
	contains the entire recorded spectral width.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	If <order> = 0 this command is equivalent to
	'base_const <half width>'.
	As an example, 'base_trig 4 2' would fit the baseline
	using five trig functions (1 constant, 2 cosines and
	2 sines) and a half-width of 4 points.
	[ source code = baseline.c, base.c and svd.c ]

***base_trig2

base_trig2 <half width> <order> <first point> <last point>
	This fits the baseline of a spectrum (not fid) by first
	finding baseline points using a shifting window of size
	<half width> and then fitting trig functions of order
	<order> to those baseline points.  In fact, the number
	of functions used to do the fitting is 2*<order> + 1,
	the 2 being because cosines and sines are used,
	and the 1 being because a constant is also used.
	Only the points from <first point> to <last point>
	(inclusive) are fitted.
	This fit only makes sense if the original data set
	contains the entire recorded spectral width.
	The data must be real.
	If $IREF$base_points has been used to define the baseline
	then the <half width> is ignored.
	If <order> = 0 this command is equivalent to
	'base_const2 <half width> <first point> <last point>'.
	As an example, 'base_trig2 4 2 1 512' would fit the
	baseline between points 1 and 512 (inclusive) using
	five trig functions (1 constant, 2 cosines and
	2 sines) and a half-width of 4 points.
	[ source code = baseline.c, base.c and svd.c ]

***base_points

base_points <base points file>
	This uses the points in the <base points file> to
	define the baseline points for subsequent baseline
	correction routines (by default the baseline is
	determined automatically by the program).  There
	must be a matching $IREF$end_base_points before the
	next use of $IREF$base_points or before a resumption
	of the automatic baseline determination.
	As an example, 'base_points edl387_5.base' might
	be used to define the baseline points.  The file
	'edl387_5.base' would need to contain the desired
	baseline points, using a free format.  If the number
	of points was 512 then each point would need to be
	in the range (1, 512).  No point can be repeated.
	For example, 'edl387_5.base' might contain

		1 5 19 25 480 490 501 505 510

	This $IREF$base_points command might be followed by
	'base_trig 4 2', for example, and then by
	'end_base_points' (so that the same baseline points
	are not used in the baseline correction routines in
	subsequent command files).

***end_base_points

end_base_points
	This matches the most recent $IREF$base_points and must
	occur before the next use of $IREF$base_points or before
	a resumption of automatic baseline determination
	(the default).

***base_subtract

base_subtract <base subtract file>
	This subtracts the values given in <base subtract file>
	from the data.
	The data must be real.
	If there are n points then there must be n values in
	<base subtract file> (in free format).
	As an example, 'base_subtract edl387_5.sub' would
	subtract the values given in 'edl387_5.sub' from the
	data.

***base_subtract2

base_subtract2 <base subtract file> <first point> <last point>
	This subtracts the values given in <base subtract file>
	from the data, from  <first point> to <last point>
	(inclusive).
	The data must be real.
	If n = <last point> - <first point> + 1, then there must
	be n values in <base subtract file> (in free format).
	As an example, 'base_subtract2 edl387_5.sub 1 256' would
	subtract the values given in 'edl387_5.sub' from the
	data, from points 1 to 256 inclusive.

***lp_extend

lp_extend <number predicted> <length of sequence> <cutoff>
	If <number predicted> is positive this does a linear
	prediction of <number predicted> points starting from
	the end of the existing data.
	If <number predicted> is negative this does a linear
	prediction of -<number predicted> points inserting
	these at the beginning of the existing data (i.e. not
	overwriting what is already there).
	The data must be complex.
	The <number predicted> points and <length of sequence>
	are to be specified in terms of complex points.
	<cutoff> must be between 0 and 1.  It gives the cutoff
	below which singular values are set to 0.
	It is recommended that <length of sequence> be between
	around MIN(n/4 to n/3, 15 to 20) where n is the number
	of complex points (in the data before linear prediction).
	(The algorithm does not need a <length of sequence> more
	than 15 to 20 and is unstable if this is too large.)
	It is recommended not to predict more than the
	number of points already in the data.
	A <cutoff> of around 0.0001 ought to work.
	The algorithm is based on the forward-backward
	method, see Zhu and Bax, JMR 100 (1992) 202-207.
	As an example, if there are originally 20 complex
	points in the data then 'lp_extend 20 6 0.0001' would
	predict forward another 20 points using a sequence of
	length 6 and a cutoff of 0.0001.
	As another example, if there are originally 20 complex
	points in the data then 'lp_extend -1 6 0.0001' would
	insert 1 initial point using a sequence of length 6
	and a cutoff of 0.0001.
	[ source code = lp_extend.c, fblp.c, csvd.c,
	complex.c, poly_roots.c, and linpack directory ]

***lp_forward

lp_forward <number predicted> <number of poles>
	This does a linear prediction of <number predicted>
	points starting from the end of the existing data.
	The <number predicted> points is to be specified
	in terms of complex points if the data is complex.
	For complex data the real and imaginary data are
	predicted separately.
	The <number of poles> should be an upper bound of the
	number of oscillators in a given row.  This should
	not be too large (e.g. 5 or 10).
	As an example, 'lp_forward 64 10' would predict
	forward 64 points using 10 poles.
	[ source code = lp_first.c, lp.c, lin_pred.c,
	complex.c and poly_roots.c ]

***lp_backward

lp_backward <number predicted> <number of poles>
	This does a linear prediction of the first
	<number predicted> points, which is to be specified in
	terms of complex points if the data is complex.
	For complex data the real and imaginary data are
	predicted separately.
	The number of points is not changed, instead the
	first <number predicted> points are overwritten.
	The <number of poles> should be an upper bound of the
	number of oscillators in a given row.  This should
	not be too large (e.g. 5 or 10).
	As an example, 'lp_forward 64 10' would predict
	forward 64 points using 10 poles.
	[ source code = lp_first.c, lp.c, lin_pred.c,
	complex.c and poly_roots.c ]

***lp_first

lp_first <number predicted> <length of sequence> <number of sequences> <cutoff>
	This does a linear prediction of the first
	<number predicted> points, using <number of sequences>
	sequences of the data of length <length of sequences> to
	do the prediction.  All of these are to be specified in
	terms of complex points if the data is complex.
	The number of points is not changed, instead the
	first <number predicted> points are overwritten.
	<number of sequences> must be >= <length of sequence>.
	For complex data, each real and imaginary data point
	is fitted separately.  For an inherently complex
	fitting of complex data, use $IREF$lp_first2.
	The algorithm uses singular value decomposition (svd)
	and <cutoff> is the value which determines which of the
	singular values are significant.  <cutoff> must be
	between 0 and 1.  This algorithm is not very good, and
	it is highly recommended that various parameter choices
	be tested on 1-dimensional rows before an entire
	multi-dimensional data file is processed using this.
	The baseline correction commands might give better results.
	As an example, 'lp_first 1 8 10 0.001' would predict point
	1 using 10 sequences of length 8, with a 0.001 cutoff.
	This means that points 2 through (10+8+1-1) = 18 are used
	to make the prediction, sequence 1 being points (2, 3,
	..., 9) and sequence 10 being points (11, 12, ..., 18).
	[ source code = lp_first.c, lp.c and svd.c ]

***lp_first2

lp_first2 <number predicted> <length of sequence> <number of sequences> <cutoff>
	This does a linear prediction of the first
	<number predicted> points, using <number of sequences>
	sequences of the data of length <length of sequences> to
	do the prediction.  All of these are to be specified in
	terms of complex points if the data is complex.
	The number of points is not changed, instead the
	first <number predicted> points are overwritten.
	<number of sequences> must be >= <length of sequence>.
	For complex data, each real and imaginary data point
	is fitted as one (complex) point.  For real data,
	$IREF$lp_first2 is exactly the same as $IREF$lp_first.
	The algorithm uses singular value decomposition (svd)
	and <cutoff> is the value which determines which of the
	singular values are significant.  <cutoff> must be
	between 0 and 1.  This algorithm is not very good, and
	it is highly recommended that various parameter choices
	be tested on 1-dimensional rows before an entire
	multi-dimensional data file is processed using this.
	The baseline correction commands might give better results.
	As an example, 'lp_first2 1 8 10 0.001' would predict point
	1 using 10 sequences of length 8, with a 0.001 cutoff.
	This means that points 2 through (10+8+1-1) = 18 are used
	to make the prediction, sequence 1 being points (2, 3,
	..., 9) and sequence 10 being points (11, 12, ..., 18).
	[ source code = lp_first.c, lp.c and svd.c ]

***lp_last

lp_last <number predicted> <length of sequence> <number of sequences> <cutoff>
	This does a linear prediction of the last
	<number predicted> points, using <number of sequences>
	sequences of the data of length <length of sequences> to
	do the prediction.  All of these are to be specified in
	terms of complex points if the data is complex.
	The predicted points start from the first point
	past the current last data point.
	<number of sequences> must be >= <length of sequence>.
	For complex data, each real and imaginary data point
	is fitted separately.  For an inherently complex
	fitting of complex data, use $IREF$lp_last2.
	The algorithm uses singular value decomposition (svd)
	and <cutoff> is the value which determines which of the
	singular values are significant.  <cutoff> must be
	between 0 and 1.  This algorithm is not very good, and
	it is highly recommended that various parameter choices
	be tested on 1-dimensional rows before an entire
	multi-dimensional data file is processed using this.
	As an example, 'lp_last 5 8 10 0.001' would predict five
	points after the current last point, using 10 sequences
	of length 8, with a 0.001 cutoff.  If the current number
	of points is 59, then points 60 through 64 are predicted,
	with points 43 through 59 used to make the prediction,
	sequence 1 being points (43, 44, ..., 50) and sequence
	10 being points (52, 53, ..., 59).
	[ source code = lp_last.c, lp.c and svd.c ]

***lp_last2

lp_last2 <number predicted> <length of sequence> <number of sequences> <cutoff>
	This does a linear prediction of the last
	<number predicted> points, using <number of sequences>
	sequences of the data of length <length of sequences> to
	do the prediction.  All of these are to be specified in
	terms of complex points if the data is complex.
	The predicted points start from the first point
	past the current last data point.
	<number of sequences> must be >= <length of sequence>.
	For complex data, each real and imaginary data point
	is fitted as one (complex) point.  For real data,
	$IREF$lp_last2 is exactly the same as $IREF$lp_last.
	The algorithm uses singular value decomposition (svd)
	and <cutoff> is the value which determines which of the
	singular values are significant.  <cutoff> must be
	between 0 and 1.  This algorithm is not very good, and
	it is highly recommended that various parameter choices
	be tested on 1-dimensional rows before an entire
	multi-dimensional data file is processed using this.
	As an example, 'lp_last2 5 8 10 0.001' would predict five
	points after the current last point, using 10 sequences
	of length 8, with a 0.001 cutoff.  If the current number
	of points is 59, then points 60 through 64 are predicted,
	with points 43 through 59 used to make the prediction,
	sequence 1 being points (43, 44, ..., 50) and sequence
	10 being points (52, 53, ..., 59).
	[ source code = lp_last.c, lp.c and svd.c ]

***maxent
$<PRE>$
maxent <maxent script file>		(in command files)
maxent <dim> <maxent script file>	(in script files)
$</PRE>$
	This does (1-dimensional) maximum entropy processing,
	using the script file <maxent script file> (in the
	dimension <dim>, if the command appears in a script file).
	The output data is real.
	For information about maxent script files, type
		process help $IREF$maxents
	[ source code = maxent.c, opus.c and mem.c ]

***maxent2

maxent2 <dim1> <dim2> <maxent script file>
	This does (2-dimensional) maximum entropy processing,
	using the script file <maxent script file> in the
	dimensions <dim1> and <dim2>.
	The output data is real.
	For information about maxent script files, type
		process help $IREF$maxents
	[ source code = maxent.c, opus.c and mem.c ]

***maxent3

maxent3 <dim1> <dim2> <dim3> <maxent script file>
	This does (3-dimensional) maximum entropy processing,
	using the script file <maxent script file> in the
	dimensions <dim1>, <dim2> and <dim3>.
	The output data is real.
	For information about maxent script files, type
		process help $IREF$maxents
	[ source code = maxent.c, opus.c and mem.c ]

***interlace

interlace <dim>
	This unwraps interlaced experiments, with the relevant
	dimension being d2 = <dim>.  It is implicit that the
	other dimension is d1 = 1.  The ideal time dependence
	of a peak located at (w1, w2) is assumed to be
		exp(i w1 t1) exp(i w2 t2)
	in the odd experiments (starting the count for these
	at 1) and
		exp(i w1 t1) exp(- i w2 t2)
	in the even experiments.  This data is replaced by
		exp(i w1 t1) cos(w2 t2)
	in the odd rows and
		exp(i w1 t1) sin(w2 t2)
	in the even rows.  Other conventions (experiments)
	can be accomodated by complex conjugation.
	It would normally be the case that this is the first
	command done when processing interlaced data.

***maxents

Maximum entropy processing has proved useful for producing
spectra in those dimensions that have few points.  It replaces
completely the usual processing on those dimensions in which
it is used.

Unlike other commands, only one maximum entropy processing is
allowed per use of the program 'process' (it would not make
sense to do more than one).

Currently there are 1-, 2- and 3-dimensional maxent algorithms,
and the input data must be complex in each of the dimensions.
A 'slice' of data is a 1-, 2- or 3-dim. subset of the data file.

Extensions could be written by writing new 'opus' and 'tropus'
routines (see opus.c) but it is not recommended without expert
advice.

Typical uses would be 1-dimensional or 2-dimensional maximum
entropy (maxent) for a 3-dimensional data file, or 2-dimensional
or 3-dimensional maxent for a 4-dimensional data file.

It is highly recommended that the maxent algorithm is tested on
a slice of data before it is run on the entire data file, to
make sure that convergence occurs for the choice of parameters.

The 2- and especially the 3-dimensional maxent algorithms can
easily lead to heavy demands on i/o to and from disk, but it is
usually the case that the maxent processing itself dominates the
processing time.

Maximum entropy processing requires the use of a script file.
Some of the commands must appear, but most are optional
(these have defaults).  Some of the commands are independent
of dimension, and these must appear at the top of the file
before the ones that depend on dimension.

Necessary commands at the top of the script file:

There are none.

Optional commands at the top of the script file:

iter <maximum number>
	This specifies the maximum number of iterations that the
	algorithm on one slice of data will use before giving up.
	Normally, the algorithm should converge in fewer
	iterations than this, and if it does not something is
	probably wrong.  By default, <maximum number> = 40
	(this should be adequate for 1-dimension, for 2- or
	3-dimensions, 10-20 or so should work).  As the number
	of iterations increases, the algorithm gets very slow.

positive
	This indicates that the spectrum has positive signal
	only.  Even if this is true, it often is best to leave
	this out, the algorithm seems to converge better with
	negative signal allowed.  By default, the spectrum is
	assumed not to be positive.

noise <noise level>
	This gives the noise level of the *input* data (not the
	spectrum).  It is probably best to experiment with this
	on a data slice.  By default, <noise level> = 100, but
	this is unlikely to be correct.

log <log file>
	This means that information provided by the algorithm
	will be written to <log file> for every iteration of
	every data slice.  By default, there is no log file.

	This information includes
		grade:  This should be near 0 if all is going well,
			except on iteration 0.  If it gets near 1,
			then the algorithm is not converging
			properly, and a smaller rate might help.
		omega:  This should increase monotonically to 1 as
			the algorithm proceeds.  An overshoot of 1
			may mean that the rate should be made
			smaller.
		status:  A status of 0 means the algorithm has
			converged.  Each digit of the status
			indicates that convergence has not yet
			happened (see mem.c for what they mean).

rate <relative step size>
	This gives the relative rate at which the algorithm
	takes step sizes.  If the algorithm is not converging
	then a smaller rate often helps.  By default,
	<relative step size> = 1.

def <level multiplier>
	The maxent algorithm starts out with a flat spectrum
	of a certain level.  This will multiply that level by
	<level multiplier>.  In general, this should not need
	to be used, but if convergence is a problem, then
	this is another parameter to play with.  By default,
	<level multiplier> = 1.

Necessary commands for each dimension of the script file:

dim <dimension>
	This starts the section for the given <dimension>.
	Note that dimensions are relative to the slice, not the
	entire file.  Thus, using 2-dimensional maxent on a
	4-dimensional data file will lead to use of 'dim 1' and
	'dim 2' in the script file.
	This must appear even for 1-dimensional maxent,
	in which case it would say 'dim 1'.

npts <number of points>
	This is the size of the spectrum (i.e. the output from
	the maximum entropy algorithm) in this dimension.

Optional commands for each dimension of the script file:

complex
	This indicates that the data is complex.
	The default for 'process' is that the data is real,
	and so it might be necessary to explictly include this
	for every dimension in the script.

ignore <point 1> ... <point N>
	This lists the points to ignore in the maxent processing.
	The points are specified in real points, even if the
	data is complex (this is because only half of a complex
	pair might be no good).  Thus 'ignore 1 2' might be
	used if the first (complex) data point is known to be
	corrupt.  Use sparingly.  By default, no points are ignored.

sample <point1> ... <point N>
	This lists the points that have been sampled in the input
	data set relative to the usual linearly (in time) sampled
	set.  The points are specified in real points, even if
	the data is complex (this is because only half of a complex
	pair might have been sampled).  If 'sample' occurs for a
	given dimension then the number of points listed must be
	equal to the number of points of the input data in that
	dimension.  Since the list of points might be lengthy,
	'sample' can occur more than once for a given dimension.
	As an example, if the number of input data points is 16
	then the following might be a use of 'sample':

		sample  1  2  3  4  7  8 11 12 ! first 8 points
		sample 15 16 21 22 27 28 31 32 ! remaining points

decay <end value>
	This multiplies the data by a decaying exponential, whose
	value is 1 at point 1 and <end value> at the last point.
	This is not normally needed, but experimentation with
	<end value> both greater and less than 1 is possible.
	By default, no multiplication is done.

phase <phase0> <phase1>
	This phases the data with specified parameters
	<phase0> and <phase1> (both specified in degrees).
	(The pivot is assumed to be the first point.)
	By default, no phasing is done.

A typical script file for 2-dimensional maxent might be

	! typical script file

	iter 20		! maximum number of iterations
	noise 50.0	! noise level
	rate 0.3	! relative step size
	log max2.log	! log file

	dim 1
	complex		! input data is complex
	npts 256	! output data size
	phase 180 -360	! phasing for this dim.

	dim 2
	complex		! input data is complex
	npts 128	! output data size
	phase 180 -360	! phasing for this dim.
