.help Tutorial Sep86 "Apextract Tutorial" .ih TOPICS The APEXTRACT tutorial consists of a number of topics. The topics are brief and describe the simplest operations. More sophisticated discussions are available for the tasks in the printed documentation and through the on-line \fBhelp\fR facility; i.e. "help taskname". To obtain information on a particular topic type "tutor topic" where the topic is one of the following: .nf TOPICS topics - List of topics overview - An overview of the \fBapextract\fR tasks organization - How the package is organized apertures - Definition of apertures defining - How to define apertures references - Using reference images to define apertures queries - Description of interactive queries cosmic - Problems with cosmic ray removal all - Print all of this tutorial .fi .ih OVERVIEW The \fBapextract\fR tasks extract spectra from two dimensional images. One image axis is the dispersion axis and the other image axis is the aperture axis. The user defines apertures whose position along the aperture axis is a function of position along the dispersion axis and whose width is fixed. There are two types of aperture extractions. \fIStrip\fR extraction produces two dimensional images in which the center of the aperture is exactly centered along one of the lines or columns of the image and the edges of the image just include the edges of the aperture. \fISum\fR extraction sums the pixels across the aperture at each point along the dispersion to produce a one dimensional spectrum. The extraction algorithms include fitting and subtracting a background, modeling the profiles across the dispersion, detecting and removing deviant pixels which do not fit the model profiles, and weighting the pixels in the sum extraction according to the signal-to-noise. To extract spectra one must define the dispersion axis by placing the parameter DISPAXIS in the image headers using the task \fBsetdisp\fR. Then apertures are defined either automatically, interactively, or by reference to an image in which apertures have been previously defined. Initially the apertures are aligned parallel to the dispersion axis but if the spectra are not aligned with the dispersion axis and have profiles which can be traced then the position of the aperture along the aperture axis can be made a function of position along the dispersion axis. Finally, the extraction operation is performed for each aperture. .ih ORGANIZATION The tasks in the \fBapextract\fR package are highly integrated. This means that tasks call each other. For example, the aperture editing task may be called from the finding, tracing, or extraction tasks. Also from within the aperture editor the finding, tracing, and extraction tasks may be run on selected apertures. This organization provides the flexibility to process images either step-by-step, image-by-image, or very interactively from the aperture editor. For example, one may defined apertures for all the images, trace all the images, and then extract all the images or, alternatively, define, trace, and extract each image individually. This organization also implies that parameters from many tasks are used during the execution of a single task. For example, the editing parameters are used in any of the tasks which may enter the interactive editing task. Two tasks, \fBapio\fR and \fBapdefault\fR, only set parameters but these parameters are package parameters which affect all the other tasks. There are two effects of this parameter organization. First, only parameters from the task being executed may be specified on the command line or with menu mode. However, the parameters are logically organized and the parameter list for any particular task is not excessively long or complex. For example, the number of parameters potentially used by the task \fBapsum\fR is 57 parameters instead of just the parameters logically related to the extraction itself. Another feature of the package organization is the ability to control the flow and interactivity of the tasks. The parameter \fIinteractive\fR selects whether the user will be queried about various operations and if the aperture editor, trace fitting, and extraction review will be performed. The parameters \fBdbwrite, find, recenter, edit, trace, fittrace, sum, review\fR, and \fBstrip\fR select which operations may be performed by a particular task. When a task is run interactively the user is queried about whether to perform each operation on each image. A query may be answered individually or as a group. In the latter case the query will not be repeated for other images but will always take the specified action. This allows the user to begin interactively and then reduce the interactivity as the images are processed and parameters are refined. For additional discussion of these parameters see the topic QUERIES. Finally, the package has attempted to provide good logging facilities. There are log files for both time stamped text output and plots. The text log is still minimal but the plot logging is complete and allows later browsing and hardcopy review of batch processing. See \fBapio\fR for further discussion. This package organization is somewhat experimental. Let us know what you think. .ih APERTURES An aperture consists of the following elements: .ls id An integer aperture identification number. The identification number must be unique. The aperture number is used as the default extension of the extracted spectra. .le .ls beam An integer beam number. The beam number need not be unique; i.e. several apertures may have the same beam number. The beam number will be recorded in the image header of the extracted spectrum. Note that the \fBonedspec\fR package restricts the beam numbers to the range 0 to 49. .le .ls cslit, cdisp The center of the aperture along the slit and dispersion axes in the two dimensional image. .le .ls lslit, ldisp The lower limits of the aperture, relative to the aperture center, along the slit and dispersion axes. The lower limits need not be less than the center. .le .ls uslit, udisp The upper limits of the aperture, relative to the aperture center, along the slit and dispersion axes. The upper limits need not be greater than the center. .le .ls curve An shift to be added to the center position for the slit axis which is a function of position along the dispersion axis. The function is one of the standard IRAF \fBicfit\fR types; a legendre polynomial, a chebyshev polynomial, a linear spline, or a cubic spline. .le .ls background Background fitting parameters used by the \fBicfit\fR package for background subtraction. Background parameters need not be used if background subtraction is not needed. The background sample regions are specified relative to aperture center. .le The aperture center is the only absolute coordinate relative to the image or image section. The size and shape of the aperture are specified relative to the aperture center. The center and aperture limits in image coordinates along the slit axis are functions of the dispersion coordinate, lambda, given by .nf center(lambda) = cslit + curve(lambda) lower(lambda) = center(lambda) + lslit upper(lambda) = center(lambda) + uslit .fi Note that both the lower and upper constants are added to the center defined by the aperture center and the curve offset. The aperture limits along the dispersion axis are constant, .nf center(s) = cdisp lower(s) = center(s) + ldisp upper(s) = center(s) + udisp .fi Usually the aperture size along the dispersion is equal to the entire image. .ih DEFINING APERTURES If a reference image is specified the \fBapextract\fR tasks first search the database for it's apertures. Note that this supercedes any apertures previously defined for the input image. If no reference apertures are found then the apertures for the input image are sought. If no apertures are defined at this point then apertures may be defined automatically, interactively, or, by default, in the center of the image. The automatic method, \fBapfind\fR, locates spectra as peaks across the dispersion and then defines default apertures given by the parameters from \fBapdefault\fR. The algorithm is controlled by specifying the number of apertures and a minimum separation between spectra. Only the strongest peaks are selected. The interactive method, \fBapedit\fR, allows the user to mark the positions of apertures and to adjust the aperture parameters such as the limits. The aperture editor may be used edit apertures defined by any of the other methods. If no apertures are defined when tracing or extraction is begun, that is following the optional editing, then a default aperture is defined centered along the aperture axis of the image. This ultimate default may be useful for spectra defined by image sections; i.e. the image section is a type of aperture. Image sections are sometimes used with multislit spectra. .ih REFERENCE IMAGES The \fBapextract\fR tasks define apertures for an input image by first searching the database for apertures recorded under the name of the reference image. Use of a reference image implies superceding the input image apertures. Reference images are specified by an image list which is paired with the input image list. If the number of reference images is less than the number of input images then the last reference image is used for all following images. Generally, the reference image list consists of the null string if reference images are not to be used, a single image which is applied to all input images, or a list which exactly matches the input list. The special reference image name "last" may be used to refer to the last apertures written to the database; usually the previous input image. The task parameter \fIrecenter\fR specifies whether the reference apertures are to be recentered on the spectra in the input image. If recentering is desired the \fBcenter1d\fR centering algorithm is used with centering parameters taken from the task \fBapedit\fR. The spectra in the image must all have well defined profiles for the centering. It does not make sense to center an aperture defined for a region of sky or background or for an arc spectrum. Recentering is used when the only change between two spectra is a shift along the aperture axis. This can reduce the number of images which must be traced if tracing is required by using a traced reference image and just recentering on the next spectra. Recentering of a traced reference image is also useful when the spectra are too weak to be traced reliably. Recentering would be most commonly used with echelle or multiaperture spectra. Recentering is not used when extracting sky or arc calibration spectra from long slit or multislit images. This is because it is desirable to extract from the same part of the detector as the object spectra and because recentering does not make sense when there is no profile across the aperture. Centering or recentering is also not used when dealing with apertures covering parts of extended objects in long slit spectra. .ih QUERIES When the interactive parameter is specified as yes in a task then the user is queried at each step of the task. The queries refer to either a particular image or a particular aperture in an image. The acceptable responses to the queries are the strings "yes", "no", "YES", and "NO". The lower case answers refer only to the specific query. The upper case answers apply to all repetitions of query for other images and apertures. The upper case reponses then suppress the query and take the specified action every time. This allows tasks to be highly interactive by querying at each step and for each image or to skip or perform each step for all images without queries. The two steps of fitting a function to traced positions and reviewing one dimensional extracted spectra, selected with the parameters \fIaptrace.fittrace\fR and \fIapsum.review\fR have two levels of queries. First a query is made for the image being traced or extracted. If the answer is "yes" or "YES" then a query is made for each aperture. A response of "YES" or "NO" applies only to the remaining apertures and not to apertures of a later image. .ih COSMIC RAYS The cleaning and modeling features available during aperture extraction are fairly good. They are described in the documentation for the tasks. It can only go so far towards discriminating cosmic rays because of problems described below. Further work on the algorithm may improve the performance but it is best, when feasible, to first eliminate at least the strongest cosmic rays from the data before extracting. One recommended method is to use \fBlineclean\fR with a high rejection threshold and a high order. There are two difficult problems encountered in using the \fBapextract\fR tasks for cosmic ray detection. First, the spectral profiles are first interpolated to a common center before comparison with the average profile model. The interpolation often splits single strong spikes into two high points of half the intensity, as is intuitively obvious. Furthermore, for very strong spikes there is ringing in the interpolator which makes the interpolated profile depart significantly from the original profile. The fact that the interpolated profile now has two or more deviant points makes it much harder to decide which points are in the profile. This leads to the second problem. The average profile model is scaled to fit the spectrum profile. When there are several high points it is very difficult to discriminate between a higher scale factor and bad points. The algorithm has been enhanced to initially exclude the point which most pulls the scale factor to higher values. If there are two high points due to the interpolator splitting a strong spike then this helps but does not eliminate errors in the extracted spectra. .endhelp