aptrace: Trace positions of spectra

Package: kpnocoude

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 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 c_i are the coefficients and the z_i are defined interactively 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 c_i are the coefficients and the z_i are defined interactively 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".