| aptrace | noao.twodspec.apextract | aptrace |
aptrace -- Trace spectra for aperture extraction
aptrace images
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.
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.
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.
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
apdefault, apfind, aprecenter, apresize, apedit, apall, center1d, icfit, gtools