apedit: Edit apertures interactively

Package: ctioslit

Usage

apedit input

Parameters

input: List of input images for which apertures are to be edited.

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. If the reference image list is shorter than the input image list the last reference image is used for the remaining 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 = no: 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 = 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 graphed. A value of INDEF uses the middle of the image.

nsum = 10: Number of dispersion lines to be summed or medianed. The lines are taken around the specified dispersion line. A positive nsum selects a sum of lines and a negative selects a median of lines.

width = 5.: Width of spectrum profiles. This parameter is used for the profile centering algorithm in this and other tasks.

radius = 5.: The profile centering error radius for the centering algorithm.

threshold = 0.: Centering threshold for the centering algorithm. The range of pixel intensities near the initial centering position must exceed this threshold.

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. Parameters for the various functions of finding, recentering, and resizing are taken from the parameters for the appropriate task.

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

Cursor keys

When editing the apertures interactively the following cursor keys are available.

?    Print help
a    Toggle the ALL flag
b an Set background fitting parameters
c an Center aperture(s)
d an Delete aperture(s)
e an Extract spectra (see APSUM)
f    Find apertures up to the requested number (see APFIND)
g an Recenter aperture(s) (see APRECENTER)
i  n Set aperture ID
j  n Set aperture beam number
l ac Set lower limit of current aperture at cursor position
m    Define and center a new aperture on the profile near the cursor
n    Define a new aperture centered at the cursor
o  n Enter desired aperture number for cursor selected aperture and
     remaining apertures are reordered using apidtable and maxsep
     parameters (see APFIND for ordering algorithm)
q    Quit
r    Redraw the graph
s an Shift the center(s) of the current aperture to the cursor
     position
t ac Trace aperture positions (see APTRACE)
u ac Set upper limit of current aperture at cursor position
w    Window the graph using the window cursor keys
y an Set aperture limits to intercept the data at the cursor y
     position
z an Resize aperture(s) (see APRESIZE)
+  c Select the next aperture (in ID) to be the current aperture
-  c Select the previous aperture (in ID) to be the current aperture
I    Interrupt task immediately.  Database information is not saved.

The letter a following the key indicates if all apertures are affected when the ALL flag is set. The letter c indicates that the key affects the current aperture while the letter n indicates that the key affects the aperture whose center is nearest the cursor.

Colon commands

:show [file]       Print a list of the apertures (default STDOUT)
:parameters [file] Print current parameter values (default STDOUT)
:read [name]       Read from database (default current image)
:write [name]      Write to database (default current image)

The remaining colon commands are task parameters and print the current value if no value is given or reset the current value to that specified. Use :parameters to see current parameter values.

:apertures      :apidtable      :avglimits      :b_function
:b_grow         :b_high_reject  :b_low_reject   :b_naverage
:b_niterate     :b_order        :b_sample       :background
:bkg            :center         :clean          :database
:extras         :gain           :image          :line
:llimit         :logfile        :lower          :lsigma
:maxsep         :minsep         :npeaks         :nsubaps
:nsum           :order          :parameters     :peak
:plotfile       :r_grow         :radius         :read
:readnoise      :saturation     :shift          :show
:skybox         :t_function     :t_grow         :t_high_reject
:t_low_reject   :t_naverage     :t_niterate     :t_nsum
:t_order        :t_sample       :t_step         :t_width
:threshold      :title          :ulimit         :upper
:usigma         :weights        :width          :write
:ylevel         :t_nlost

Description

For each image in the input image list, apertures are defined and edited interactively. The aperture editor is invoked when the parameters interactive and edit are both yes. When this is the case the task will query whether to edit each image. The responses are "yes", "no", "YES", and "NO", where the upper case responses suppress queries for all following images.

When the aperture editor is entered a graph of the image lines or columns specified by the parameters line and nsum is drawn. In the apextract package a dispersion line is either a line or column in the image at one point along the dispersion axis. The dispersion axis may be defined in the image header under the keyword DISPAXIS or by the package parameter dispaxis. The parameter nsum determines how many dispersion lines surrounding the specified dispersion line are summed or medianed. This improves the signal in the profiles of weaker spectra. Once the graph is drawn an interactive cursor loop is entered. The set of cursor keys and colon commands is given above and may be printed when the task is running using the '?' key. The CURSOR MODE keys and graph formatting options are also available (see cursor and gtools).

A status line, usually at the bottom of the graphics terminal, indicates the current aperture and shows the ALL flag, 'a' key, if set. The concept of the current aperture is used by several of the aperture editing commands. Other commands operate on the aperture whose center is nearest the cursor. It is important to know which commands operate on the current aperture and which operate on the nearest aperture to the cursor.

The cursor keys and colon commands are used to define new apertures, delete existing apertures, modify the aperture number, beam number, title, center, and limits, set background fitting parameters, trace the positions of the spectra in the apertures, and extract aperture spectra. When creating new apertures default parameters are supplied in two ways; if no apertures are defined then the default parameters are taken from the task apdefault while if there is a current aperture then a copy of its parameters are made.

The keys for creating a new aperture are 'm' and 'n' and 'f'. The key 'm' marks a new aperture and centers the aperture on the profile nearest the cursor. The centering algorithm is described under the help topic center1d and the parameters controlling the centering are width, radius, and threshold. The key 'n' defines a new aperture at the position of the cursor without centering. This is used if there is no spectrum profile such as when defining sky apertures or when defining apertures in extended profiles. The 'f' key finds new apertures using the algorithm described in the task apfind. The number of apertures found in this way is limited by the parameter nfind and the number includes any previously defined apertures. The new aperture number, beam number, and title are assigned using the aperture assignment algorithm described in apfind.

The aperture number for the aperture nearest the cursor is changed with the 'j' key and the beam number is changed with the 'k' key. The user is prompted for a new aperture number or beam number. The aperture title may be set or changed with the :title colon command.

The 'o' key may be used to reorder or correct the aperture identifications and beam numbers. This is useful if the aperture numbers become disordered due to deletions and additions or if the first spectrum is missing when using the automatic identification algorithm. An aperture number is requested for the aperture pointed to by the cursor. The remaining apertures are reordered relative to this aperture number. There is a aperture number, beam number, and title assignment algorithm which uses information about the maximum separation between consecutive apertures, the direction of increasing aperture numbers, and an optional aperture identification table. See apfind for a description of the algorithm.

After defining a new aperture it becomes the current aperture. The current aperture is indicated on the status line and the '.', '+', and '-' keys are used to select a new current aperture.

Apertures are deleted with 'd' key. The aperture nearest the cursor is deleted.

The aperture center may be changed with the 'c', 's', and 'g' keys and the ":center value" colon command. The 'c' key applies the centering algorithm to the aperture nearest the colon. The 's' key shifts the center of the current aperture to the position of the cursor. The 'g' applies the aprecenter algorithm. The :center command sets the center of the current aperture to the value specified. Except for the last option these commands may be applied to all apertures if the ALL flag is set.

The aperture limits are defined relative to the aperture center. The limits may be changed with the 'l', 'u', 'y', and 'z' keys and with the ":lower value" and ":upper value" commands. The 'l' and 'u' keys set the lower and upper limits of the current aperture at the position of the cursor. The colon commands allow setting the limits explicitly. The 'y' key defines both limits for the nearest aperture as points at which the y cursor position intercepts the data profile. This requires that the aperture include a spectrum profile and that the y cursor value lie below the peak of the profile. The 'z' key applies the apresize algorithm. Except for the colon commands these commands may be applied to all apertures if the ALL flag is set.

The key 'b' modifies the background fitting parameters for the aperture nearest the cursor. The default background parameters are specified by the task apdefault. Note that even though background parameters are defined, background subtraction is not performed during extraction unless specified. When the 'b' key is used the icfit graphical interface is entered showing the background regions and function fit for the current image line. Note that the background regions are specified relative to the aperture center and follows changes in the aperture position.

The two types of extraction which may be specified are to average all points within a set of background regions or fit a function to the points in the background regions. In the first case only the background sample parameter is used. In the latter case the other parameters are also used in conjunction with the icfit function fitting commands. See apbackground for more on the background parameters.

Each aperture may have different background fitting parameters but newly defined apertures inherit the background fitting parameters of the last current aperture. This will usually be satisfactory since the background regions are defined relative to the aperture center rather than in absolute coordinates. If the ALL flag is set then all apertures will be given the same background parameters.

The algorithms used in the tasks apfind, aprecenter, apresize, aptrace, and apsum are available from the editor with the keys 'f', 'g', 'z', 't', and 'e' respectively. Excluding finding, if the ALL flag is not set then the nearest aperture to the cursor is used. This allows selective recentering, resizing, tracing and extracting. If the ALL flag is set then all apertures are traced or extracted. When extracting the output, rootname and profile name are queried.

Some general purpose keys window the graph 'w' using the gtools commands, redraw the graph 'r', and quit 'q'.

The final cursor key is the 'a' key. The cursor keys which modify the apertures were defined as operating on either the aperture nearest the cursor or the current aperture. The 'a' key allows these keys to affect all the apertures simultaneously. The 'a' key sets a flag which is shown on the status line when it is set. When set, the operation on one aperture is duplicated on the remaining apertures. The operations which apply to all apertures are set background 'b', center 'c', delete 'd', extract 'e', recenter 'g', set lower limit 'l', shift 's', trace 't', set upper limit 'u', set limits at the y cursor 'y', and resize 'z'. The 'b', 'l', 's', and 'u' keys first set the background, aperture limits, or shift for the appropriate aperture and then are applied to the other apertures relative to their centers.

All the parameters used in any of the operations may be examined or changed through colon commands. The :parameters command lists all parameter values and :show lists the apertures. The :read and :write are used to force an update or save the current apertures and to read apertures for the current image or from some other image. The commands all have optional arguments. For the commands which show information the argument specifies a file to which the information is to be written. The default is the standard output. The database read and write and the change image commands take an image name. If an image name is not given for the read and write commands the current image name is used. The change image command default is to print the current image name. The remaining commands take a value. If a value is not given then the current value is printed.

The aperture editor may be selected from nearly every task using the edit parameter.

Examples

The aperture editor is a very flexible and interactive tool for which it is impossible illustrate all likely uses. The following give some simple examples.

1. To define and edit apertures for image "n1.001":

cl> apedit n1.001

2. To define apertures for one image and then apply them to several other images:

cl> apedit n1.* ref=n1.001
Edit apertures for n1.001? (yes)
Edit apertures for n1.002? (yes) NO

Answer "yes" to the first query for editing n1.001. To the next query (for n1.002) respond with "NO". The remaining images then will not be edited interactively. Note that after defining the apertures for n1.001 they are recorded in the database and subsequent images will be able to use them as reference apertures.

3. Using the ":image name" and ":read image" colon commands and the 'f', 'g', 'z', 't' and 'e' keys the user can perform all the functions available in the package without ever leaving the editor. The 'a' key to set the ALL flag is very useful when dealing with many spectra in a single image.

Revisions

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