path: root/noao/twodspec/apextract/doc/aptrace.hlp

.help aptrace Sep96 noao.twodspec.apextract
.ih
NAME
aptrace -- Trace spectra for aperture extraction
.ih
USAGE
.nf
aptrace images
.fi
.ih
PARAMETERS
.ls input
List of input images to be traced.
.le
.ls apertures = ""
Apertures to recenter, resize, trace, and extract.  This only applies
to apertures read from the input or reference database.  Any new
apertures defined with the automatic finding algorithm or interactively
are always selected.  The syntax is a list comma separated ranges
where a range can be a single aperture number, a hyphen separated
range of aperture numbers, or a range with a step specified by "x<step>";
for example, "1,3-5,9-12x2".
.le
.ls references = ""
List of reference images to be used to define apertures for the input
images.  When a reference image is given it supersedes apertures
previously defined for the input image. The list may be null, "", or
any number of images less than or equal to the list of input images.
There are three special words which may be used in place of an image
name.  The word "last" refers to the last set of apertures written to
the database.  The word "OLD" requires that an entry exist
and the word "NEW" requires that the entry not exist for each input image.
.le

.ls interactive = yes
Run this task interactively?  If the task is not run interactively then
all user queries are suppressed and interactive aperture editing and trace
fitting are disabled.
.le
.ls find = yes
Find the spectra and define apertures automatically?  In order for
spectra to be found automatically there must be no apertures for the
input image or reference image defined in the database.
.le
.ls recenter = no
Recenter the apertures?
.le
.ls resize = yes
Resize the apertures?
.le
.ls edit = yes
Edit the apertures?  The \fIinteractive\fR parameter must also be yes.
.le
.ls trace = yes
Trace the apertures?
.le
.ls fittrace = yes
Interactively fit the traced positions by a function?  The \fIinteractive\fR
parameter must also be yes.
.le

.ls line = INDEF, nsum = 1
The dispersion line (line or column perpendicular to the dispersion
axis) and number of adjacent lines (half before and half after unless
at the end of the image) used in finding, recentering, resizing,
and editing operations.  For tracing this is the starting line and
the same number of lines are summed at each tracing point.  A line of
INDEF selects the middle of the image along the dispersion axis.
A positive nsum selects the number of lines to sum while a negative
value selects a median.  Tracing always uses a sum.
.le
.ls step = 10
Step along the dispersion axis between determination of the spectrum
positions.
.le
.ls nlost = 3
Number of consecutive steps in which the profile is lost before quitting
the tracing in one direction.  To force tracing to continue through
regions of very low signal this parameter can be made large.  Note,
however, that noise may drag the trace away before it recovers.
.le

The following parameters are the defaults used to fit the traced positions
by a function of the dispersion line.  These parameters are those used by
the ICFIT package.
.ls function = "legendre"
Default trace fitting function.  The fitting function types are
"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and
"spline3" cubic spline.
.le
.ls order = 2
Default trace function order.  The order refers to the number of
terms in the polynomial functions or the number of spline pieces in the spline
functions.
.le
.ls sample = "*"
Default fitting sample.  The sample is given by a set of colon separated
ranges each separated by either whitespace or commas.  The string "*" refers
to all points.
.le
.ls naverage = 1
Default number of points to average or median.  Positive numbers
average that number of sequential points to form a fitting point.
Negative numbers median that number, in absolute value, of sequential
points.  A value of 1 does no averaging and each data point is used in the
.le
.ls niterate = 0
Default number of rejection iterations.  If greater than zero the fit is
used to detect deviant traced positions and reject them before repeating the
fit.  The number of iterations of this process is given by this parameter.
.le
.ls low_reject = 3., high_reject = 3.
Default lower and upper rejection sigma.  If greater than zero traced
points deviating from the fit below and above the fit by more than this
number of times the sigma of the residuals are rejected before refitting.
.le
.ls grow = 0.
Default reject growing radius.  Traced points within a distance given by this
parameter of any rejected point are also rejected.
.le
.ih
ADDITIONAL PARAMETERS
I/O parameters and the default dispersion axis are taken from the
package parameters, the default aperture parameters from
\fBapdefault\fR, automatic aperture finding parameters from
\fBapfind\fR, recentering parameters from \fBaprecenter\fR, resizing
parameters from \fBapresize\fR, and parameters used for centering and
editing the apertures from \fBapedit\fR.

When this operation is performed from the task \fBapall\fR all parameters
except the package parameters are included in that task.
.ih
DESCRIPTION
For each image in the input image list the position of the spectrum
within each aperture are determined at a number of points along the
dispersion axis and a smooth function is fit to these positions.  The
fitted curve defines a shift to be added to the aperture center at each
wavelength.  Other options allow defining apertures using a reference
image, defining apertures through an automatic finding algorithm (see
\fBapfind\fR), automatically recentering apertures (see
\fBaprecenter\fR), automatically resizing apertures (see
\fBapresize\fR), and interactively editing the apertures prior to
tracing (see \fBapedit\fR).  Tracing is selected with the parameter
\fItrace\fR.  If the tracing is done interactively (the
\fIinteractive\fR parameter set to yes) then the user is queried
whether or not to trace each image.  The responses are "yes", "no",
"YES", or "NO", where the upper case queries suppress this query
for the following images.

The tracing begins with the specified dispersion line.  A dispersion
line is a line or column of the image perpendicular to the dispersion
axis.  The dispersion axis is defined in the image header or by the
package parameter \fIdispaxis\fR.  If the starting dispersion line is
INDEF then the middle dispersion line of the image is used.  The
positions of the spectra are determined using the \fBcenter1d\fR
algorithm and the centering parameters from the \fBapedit\fR task.
(See help under \fBcenter1d\fR for a description of the one dimensional
position measuring algorithm.) The positions are redetermined at other
points along the dispersion axis by stepping from the starting line in
steps specified by the user.  A number of dispersion lines around each
dispersion line to be measured may be summed to improve the position
determinations, particularly for weak profiles.  This number usually is
set equal to the tracing step.

It is important to understand how to set the step size and the
relationship between the step size and the centering error radius.
Larger steps reduce the computational time, which is an important
consideration.  However, if the step is too large then the tracing may
fail to follow the systematic changes in the positions of the
spectrum.  The centering error radius, \fIradius\fR, is used to limit
the maximum position change between two successive steps.  If the
positions of a spectrum changes by more than the specified amount or
the data contrast falls below the \fIthreshold\fR parameter then
the position is marked as lost.

The centering radius should be large enough to follow changes in the
spectrum positions from point to point but small enough to detect an error
in the tracing by a sudden abrupt change in position, such as caused by
crowding with other spectra or by the disappearance of the spectrum.  The
\fInlost\fR parameter determines how many consecutive steps the position
may fail to be found before tracing in that direction is stopped.  If this
parameter is small the trace will stop quickly upon loss of the profile
while if it is very large it will continue to try and recover the profile.

The parameter \fIthreshold\fR checks for the vanishing of a spectrum by
requiring a minimum range in the data used for centering.  If the
tracing fails when the spectra are strong and well defined the problem
is usually that the step size is too large and/or the centering error
radius is too small.

The traced positions of a spectrum include some measurement variation
from point to point.  Since the actual position of the spectrum in the
image should be a smooth curve, a function of the dispersion line is fit
to the measured points.  The fitted function is stored as part of the
aperture description.  It is an offset to be added to the aperture's
center as a function of the dispersion line.  Even if the fitting is not
done interactively plots of the trace and the fit are recorded in the
plot file or device specified by the parameter \fIplotfile\fR.

Fitting the traced spectrum positions with a smooth function may be
performed interactively when parameters \fIfittrace\fR and
\fIinteractive\fR are yes.  This allows changing the default fitting
parameters.  The function fitting is done with the interactive curve
fitting tools described under the help topic \fBicfit\fR.  There are
two levels of queries when fitting the spectrum positions
interactively; prompts for each image and prompts for each aperture in
an image.  These prompts may be answered individually with the lower
case responses "yes" or "no" or answered for all further prompts with
the responses "YES" or "NO".  Responding with "yes" or "YES" to the
image prompt allows interactive fitting of the traced positions for the
spectra.  Prompts are then given for each aperture in the image.  When
an spectrum is not fit interactively the last set of fitting parameters
are used (initially the default function and order given by the task
parameters).  Note that answering "YES" or "NO" to a aperture prompt
applies to all further aperture in the current image only.  Responding
with "no" or "NO" to the image prompt fits the spectrum positions for
all apertures in all images with the last set of fitting parameters.

The tracing may also be done from the interactive aperture editor with
the 't' key.  The aperture tracing algorithm may be selected from many
of the tasks in the package with the \fItrace\fR parameter.
.ih
APTRACE DATABASE COEFFICIENTS
The path of an aperture is described by a function that gives an additive
offset relative to the aperture center as stored under the database keyword
center.  The function is saved in the database as a series of
coefficients.  The section containing the coefficients starts with the
keyword "curve" and the number of coefficients.

The first four coefficients define the type of function, the order
or number of spline pieces, and the range of the independent variable
(the line or column coordinate along the dispersion).  The first
coefficient is the function type code with values:

.nf
	Code	Type
	   1	Chebyshev polynomial
	   2	Legendre polynomial
	   3	Cubic spline
	   4	Linear spline
.fi

The second coefficient is the order (actually the number of terms) of
the polynomial or the number of pieces in the spline.

The next two coefficients are the range of the independent variable over
which the function is defined.  These values are used to normalize the
input variable to the range -1 to 1 in the polynomial functions.  If the
independent variable is x and the normalized variable is n, then

.nf
	n = (2 * x - (xmax + xmin)) / (xmax - xmin)
.fi

where xmin and xmax are the two coefficients.

The spline functions divide the range into the specified number of
pieces.  A spline coordinate s and the nearest integer below s,
denoted as j, are defined by

.nf
	s = (x - xmin) / (xmax - xmin) * npieces
	j = integer part of s
.fi

where npieces are the number of pieces.

The remaining coefficients are those for the appropriate function.
The number of coefficients is either the same as the function order
for the polynomials, npieces+1 for the linear spline, or npieces + 3
for the cubic spline.

1. Chebyshev Polynomial

The polynomial can be expressed as the sum

.nf
	y = sum from i=1 to order {c_i * z_i}
.fi

where the c_i are the coefficients and the z_i are defined
interactively as:

.nf
	z_1 = 1
	z_2 = n
	z_i = 2 * n * z_{i-1} - z_{i-2}
.fi

2. Legendre Polynomial

The polynomial can be expressed as the sum

.nf
	y = sum from i=1 to order {c_i * z_i}
.fi

where the c_i are the coefficients and the z_i are defined
interactively as:

.nf
	z_1 = 1
	z_2 = n
	z_i = ((2*i-3) * n * z_{i-1} - (i-2) * z_{i-2}) / (i - 1)
.fi

3. Linear Spline

The linear spline is evaluated as

.nf
	y = c_j * a + c_{j+1} * b
.fi

where j is as defined earlier and a and b are fractional difference
between s and the nearest integers above and below

.nf
	a = (j + 1) - s
	b = s - j
.fi

4.  Cubic Spline

The cubic spline is evaluated as

.nf
	y = sum from i=0 to 3 {c_{i+j} * z_i}
.fi

where j is as defined earlier.  The term z_i are computed from
a and b, as defined earlier, as follows

.nf
	z_0 = a**3
	z_1 = 1 + 3 * a * (1 + a * b)
	z_2 = 1 + 3 * b * (1 + a * b)
	z_3 = b**3
.fi
.ih
EXAMPLES
.ih
REVISIONS
.ls APTRACE V2.11
The "apertures" parameter can be used to select apertures for resizing,
recentering, tracing, and extraction.  This parameter name was previously
used for selecting apertures in the recentering algorithm.  The new
parameter name for this is now "aprecenter".
.le
.ih
SEE ALSO
apdefault, apfind, aprecenter, apresize, apedit, apall,
center1d, icfit, gtools
.endhelp