diff options
Diffstat (limited to 'noao/twodspec/apextract/doc/apedit.hlp')
| -rw-r--r-- | noao/twodspec/apextract/doc/apedit.hlp | 374 |
1 files changed, 374 insertions, 0 deletions
diff --git a/noao/twodspec/apextract/doc/apedit.hlp b/noao/twodspec/apextract/doc/apedit.hlp new file mode 100644 index 00000000..324f6e5d --- /dev/null +++ b/noao/twodspec/apextract/doc/apedit.hlp @@ -0,0 +1,374 @@ +.help apedit Sep96 noao.twodspec.apextract +.ih +NAME +apedit -- Edit apertures +.ih +USAGE +apedit input +.ih +PARAMETERS +.ls input +List of input images for which apertures are to be edited. +.le +.ls 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". +.le +.ls 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. +.le + +.ls 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. +.le +.ls 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. +.le +.ls recenter = no +Recenter the apertures? +.le +.ls resize = no +Resize the apertures? +.le +.ls edit = yes +Edit the apertures? The \fIinteractive\fR parameter must also be yes. +.le + +.ls 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. +.le +.ls 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. +.le +.ls width = 5. +Width of spectrum profiles. This parameter is used for the profile +centering algorithm in this and other tasks. +.le +.ls radius = 5. +The profile centering error radius for the centering algorithm. +.le +.ls threshold = 0. +Centering threshold for the centering algorithm. The range of pixel intensities +near the initial centering position must exceed this threshold. +.le +.ih +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 \fBapdefault\fR. 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 \fBapall\fR all parameters +except the package parameters are included in that task. +.ih +CURSOR KEYS +When editing the apertures interactively the following cursor keys are +available. + +.nf +? 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) +. n Select the aperture nearest the cursor for current aperture ++ 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. +.fi + +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. +.ih +COLON COMMANDS + +.nf +: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) +.fi + +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. + +.nf +: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 +.fi +.ih +DESCRIPTION +For each image in the input image list, apertures are defined and edited +interactively. The aperture editor is invoked when the parameters +\fIinteractive\fR and \fIedit\fR 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 \fIline\fR and \fInsum\fR is +drawn. In the \fBapextract\fR 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 \fIdispaxis\fR. The +parameter \fBnsum\fR 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 \fBcursor\fR and \fBgtools\fR). + +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 \fBapdefault\fR 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 \fBcenter1d\fR and the parameters controlling the centering are +\fIwidth\fR, \fIradius\fR, and \fIthreshold\fR. 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 \fBapfind\fR. The +number of apertures found in this way is limited by the parameter +\fBnfind\fR 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 \fBapfind\fR. + +The aperture number for the aperture \fInearest\fR 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 +\fBapfind\fR 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 \fInearest\fR 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 \fInearest\fR the colon. The 's' key shifts the center +of the \fIcurrent\fR aperture to the position of the cursor. The 'g' +applies the \fBaprecenter\fR algorithm. The :center command sets the +center of the \fIcurrent\fR 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 \fIcurrent\fR aperture at the position +of the cursor. The colon commands allow setting the limits explicitly. +The 'y' key defines both limits for the \fInearest\fR 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 \fBapresize\fR 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 +\fInearest\fR the cursor. The default background parameters are +specified by the task \fBapdefault\fR. Note that even though +background parameters are defined, background subtraction is not +performed during extraction unless specified. +When the 'b' key is used the \fBicfit\fR 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 \fBicfit\fR function fitting commands. +See \fBapbackground\fR 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 \fBapfind, aprecenter, apresize, aptrace\fR, +and \fBapsum\fR 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 \fBgtools\fR +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 +\fBedit\fR parameter. +.ih +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: + +.nf + cl> apedit n1.* ref=n1.001 + Edit apertures for n1.001? (yes) + Edit apertures for n1.002? (yes) NO +.fi + +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. +.ih +.ih +REVISIONS +.ls 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. +.le +SEE ALSO +.nf +apdefault, apfind, aprecenter, apresize, aptrace, apsum, apall +center1d, cursor, gtools, icfit +.fi +.endhelp |