apresize: Resize apertures

Package: hydra

Usage

apresize input

Parameters

input: List of input images in which apertures are to be resized.

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.

recenter = no: Recenter the apertures?

resize = yes: 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 resizing 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 takes a sum and a negative value selects a median.

llimit = INDEF, ulimit = INDEF: Lower and upper aperture size limits. If the parameter ylevel is INDEF then these limits are assigned to all apertures. Otherwise these parameters are used as limits to the resizing operation. A value of INDEF places the aperture limits at the image edge (for the dispersion line used).

ylevel = 0.1: Data level at which to set aperture limits. If it is INDEF then the aperture limits are set at the values given by the parameters llimit and ulimit. If it is not INDEF then it is a fraction of the peak or an actual data level depending on the parameter peak. It may be relative to a local background or to zero depending on the parameter bkg.

peak = yes: Is the data level specified by ylevel a fraction of the peak?

bkg = yes: Subtract a simple background when interpreting the ylevel parameter. The background is a slope connecting the first minima away from the aperture center.

r_grow = 0.: Change the lower and upper aperture limits by this fractional amount. The factor is multiplied by each limit and the result added to limit.

avglimits = no: Apply the average lower and upper aperture limits to all apertures.

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, automatic aperture finding parameters are taken from apfind, 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, the aperture limits are redefined to be either specified values or by finding the points at which the spectrum profile, linearly interpolated, first crosses a specified value moving away from the aperture center at the specified dispersion line. In the latter case the limits may then be increased or decreased by a specified percentage, a maximum lower and upper limit, may be imposed, and the independent limits may be averaged and the single values applied to all the apertures.

The simplest resizing choice is to reset all the aperture limits to the values specified by llimit and ulimit. This option is selected if the parameter ylevel is INDEF.

There are several options for specifying a data level at which an aperture is sized. The most common method (the default) is to specify a fraction of the peak value since this is data independent and physically reasonable. This is done by setting the fraction with the parameter ylevel and the parameter peak to yes. If the peak parameter is no then the level is a data value.

The levels may be relative to zero, as might be used with fibers or high dispersion / high signal-to-noise data, or relative to a local linear background, as would be appropriate for slit data having a significant background. A background is found and used if the parameter bkg is set. The background determination is very simple. Starting at the peak two background points are found, one in each direction, which are inflection points; i.e. the first pixels which are less than their two neighbors. A linear slope is fit and subtracted for the purposes of measuring the peak and setting the aperture limits. Note that if the slope is significant the actual limits may not correspond to the intercepts of a line at constant data value.

Once aperture limits, a distance relative to the center, are determined they are increased or decreased by a percentage, expressed as a fraction, given by the parameter r_grow. To illustrate the operation, if xlow is the initial lower limit then the final lower limit will be:

xlow final = xlow * (1 + r_grow)

A value of zero leaves the aperture limits unchanged.

After the aperture limits are found, based on the above steps, a fixed lower limit, given by the parameter llimit, is applied to the lower aperture points and, similarly, a fixed upper limit is applied to the upper aperture points. This feature protects against absurdly wide apertures.

Finally, if the parameter avglimits is set the individual aperture limits are averaged to form an average aperture. This average aperture is then assigned to all apertures. This option allows keeping common aperture sizes but allowing variation due to seeing changes.

The resizing algorithm is available in the interactive aperture editor. Here one may select individual apertures or all apertures using the 'a' switch. The resizing algorithm described above is selected using the 'z' key. An simple alternative is the 'y' key which resizes apertures to the y level marked by the cursor.

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 resizing algorithm may be selected from nearly every task in the package with the resize parameter.

Examples

1. To resize all apertures to the range -4 to 4:

cl> apresize image llimit=-4 ulimit=4 ylevel=INDEF

2. To resize all aperture to a point which is 5% of the peak relative to a local background:

cl> apresize image ylevel=.05 peak+ bkg+

3. To resize all apertures to the point where the data exceeds 100 data units:

cl> apresize image ylevel=100 peak- bkg-

4. To resize all apertures to default values of the task except averaging all the results at the end:

cl> apresize image avg+

Revisions

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