apfind: Automatically find spectra and define apertures

Package: kpnoslit

Usage

apfind input

Parameters

input

List of input images in which spectra are to be identified and apertures defined automatically.

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 = no

Run this task interactively? If the task is not run interactively then all user queries are suppressed and interactive aperture editing is 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 and the parameter nfind must be greater than zero.

recenter = no

Recenter the apertures?

resize = no

Resize the apertures?

edit = yes

Edit the apertures? The interactive parameter must also be yes.

line = INDEF

The dispersion line (line or column perpendicular to the dispersion axis) to be used in finding the spectra. A value of INDEF selects the middle of the image.

nsum = 1

Number of dispersion lines to be summed or medianed. The lines are taken around the specified dispersion line. A positive value sums lines and a negative value medians lines.

nfind = 1

Maximum number of apertures to be defined. This is a query parameter so the user is queried for a value except when given explicitly on the command line.

minsep = 5.

Minimum separation between spectra. Weaker spectra or noise within this distance of a stronger spectrum are rejected.

maxsep = 1000.

Maximum separation between adjacent spectra. This parameter is used to identify missing spectra in uniformly spaced spectra produced by fiber spectrographs. If two adjacent spectra exceed this separation then it is assumed that a spectrum is missing and the aperture identification assignments will be adjusted accordingly.

order = "increasing"

When assigning aperture identifications order the spectra "increasing" or "decreasing" with increasing pixel position (left-to-right or right-to-left in a cross-section plot of the image).

Additional parameters

I/O parameters and the default dispersion axis are taken from the package parameters, the default aperture parameters are taken from the task apdefault, and parameters used for centering and editing the apertures are taken 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 spectra are identified and default apertures defined. The automatic aperture finding is performed only if 1) there are no apertures defined for the reference image, 2) there are no apertures defined for the input image, 3) the parameter find is yes, and 4) the parameter nfind is greater than zero.

The automatic finding algorithm uses the following steps. First, all local maxima are found. The maxima are sorted by peak value and the weaker of the peaks separated by less than the value given by the parameter minsep are rejected. Finally, at most the nfind strongests peaks are kept. Nfind is a query parameter, so if it is not specified explicitly on the command line, the desired number of spectra to be found is requested. After the peaks have been found the center1d algorithm is used to refine the centers of the profiles. Apertures having the default parameters set with the task apdefault are defined at each center. This algorithm is also available with the 'f' key in the task apedit with the change that existing apertures are kept and count toward the maximum number specified by nfind.

The automatic assignment of aperture numbers, beam numbers, and titles has several options. The simplest is when no aperture identification table, parameter apidtable, is specified and the maximum separation parameter, maxsep, is very large. In this case the aperture and beam numbers are sequential starting from one and numbered either from left-to-right or right-to-left depending on the order parameter. There are no aperture titles in this case. If two adjacent spectra are separated by more than the specified maximum then the aperture numbers jump by the integer part of the ratio of the separation to the specified maximum separation. This is used when the image is expected to have evenly spaced spectra, such as in multifiber spectrographs, in which some may be missing due to broken fibers. Finally, the aperture identification table (either a text file or an image having a set of SLFIBnnn keyowrds) may contain lines with aperture number, beam number, and (optional) title. The sequential numbers are then indices into this table. Note that the skipping of missing spectra and the ordering applies to entries in this table as well.

The ways in which the automatic method can fail for evenly spaced spectra with missing members are when the first spectrum is missing on the side from which the ordering begins and when the expected rather the actual number of spectra is used. In the first case one can use the interactive 'o' key of the aperture editing facility to specify the identity of any aperture and then all other apertures will be appropriately reidentified. If more spectra are sought than actually exist then noise spikes may be mistakenly found. This problem can be eliminated by specifying the actual number of spectra or minimized by using the threshold centering parameter.

The recenter parameter allows recentering apertures if defined by a reference image. Since the purpose of this task is to find new apertures it is usually the case that there are no reference images and recentering is not done. The default apertures are of fixed width. The resize parameter may be used to adjust the widths in a variety of ways. The aperture positions and any other parameters may also be edited with the aperture editing function if selected by the apedit parameter and the task is run interactively.

If the task is interactive the user is queried whether to perform various steps on each image. The queries may be answered with one of the four values "yes", "no", "YES" and "NO", where an upper case response suppresses all further queries to this question.

The aperture finding algorithm may be selected from nearly every task in the package.

Examples

cl> apfind image nfind=10

Revisions

APFIND 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". The aperture ID table information may now be contained in the image header under the keywords SLFIBnnn.

SEE ALSO center1d, apdefault, aprecenter, apresize, apedit, apall