APTRACE_DATABASE_COEFFICIENTS · EXAMPLES · REVISIONS · SEE_ALSO

## NAME

aptrace -- Trace spectra for aperture extraction

## USAGE

aptrace images

## PARAMETERS

- input
- List of input images to be traced.

- 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".

- 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.

- 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.

- 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.

- recenter = no
- Recenter the apertures?

- resize = yes
- Resize the apertures?

- edit = yes
- Edit the apertures? The
*interactive*parameter must also be yes.

- trace = yes
- Trace the apertures?

- fittrace = yes
- Interactively fit the traced positions by a function? The
*interactive*parameter must also be yes.

- 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.

- step = 10
- Step along the dispersion axis between determination of the spectrum positions.

- 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.

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.

- function = "legendre"
- Default trace fitting function. The fitting function types are "chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and "spline3" cubic spline.

- 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.

- 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.

- 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

- 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.

- 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.

- grow = 0.
- Default reject growing radius. Traced points within a distance given by this parameter of any rejected point are also rejected.

## ADDITIONAL PARAMETERS

I/O parameters and the default dispersion axis are taken from the
package parameters, the default aperture parameters from
**apdefault**
, automatic aperture finding parameters from
**apfind**
, recentering parameters from **aprecenter**
, resizing
parameters from **apresize**
, and parameters used for centering and
editing the apertures from **apedit**
.

When this operation is performed from the task **apall**
all parameters
except the package parameters are included in that task.

## 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
**apfind**
), automatically recentering apertures (see
**aprecenter**
), automatically resizing apertures (see
**apresize**
), and interactively editing the apertures prior to
tracing (see **apedit**
). Tracing is selected with the parameter
*trace*
. If the tracing is done interactively (the
*interactive*
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 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 *dispaxis*
. 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 **center1d**
algorithm and the centering parameters from the **apedit**
task.
(See help under **center1d**
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, *radius*
, 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 *threshold*
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
*nlost*
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 *threshold*
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 *plotfile*
.

Fitting the traced spectrum positions with a smooth function may be
performed interactively when parameters *fittrace*
and
*interactive*
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 **icfit**
. 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 *trace*
parameter.

## 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:

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

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

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

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

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

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

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

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

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

2. Legendre Polynomial

The polynomial can be expressed as the sum

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

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

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

3. Linear Spline

The linear spline is evaluated as

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

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

a = (j + 1) - s b = s - j

4. Cubic Spline

The cubic spline is evaluated as

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

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

z_0 = a**3 z_1 = 1 + 3 * a * (1 + a * b) z_2 = 1 + 3 * b * (1 + a * b) z_3 = b**3

## EXAMPLES

## REVISIONS

- 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".

## SEE ALSO

apdefault, apfind, aprecenter, apresize, apedit, apall, center1d, icfit, gtools