From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/twodspec/apextract/doc/old/apextract1.ms | 811 ++++++++++++++++++++++++++ 1 file changed, 811 insertions(+) create mode 100644 noao/twodspec/apextract/doc/old/apextract1.ms (limited to 'noao/twodspec/apextract/doc/old/apextract1.ms') diff --git a/noao/twodspec/apextract/doc/old/apextract1.ms b/noao/twodspec/apextract/doc/old/apextract1.ms new file mode 100644 index 00000000..b586daad --- /dev/null +++ b/noao/twodspec/apextract/doc/old/apextract1.ms @@ -0,0 +1,811 @@ +.EQ +delim $$ +define sl '{s lambda}' +.EN +.RP +.TL +The IRAF APEXTRACT Package +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +.AB +The IRAF \fBapextract\fR package provides tools for the extraction of +one and two dimensional spectra from two dimensional images +such as echelle, long slit, multifiber, and multislit spectra. +Apertures of fixed spatial width define the regions of +the two dimensional images to be extracted at each point along the +dispersion axis. Apertures may follow changes in the positions of +the spectra as a function of position along the dispersion axis. +The spatial and dispersion axes may be oriented along either image axis. +Extraction to one dimensional spectra consists of a weighted sum of the pixels +within the apertures at each point along the dispersion axis. The +weighting options provide the simple sum of the pixel values and a +weighting by the expected uncertainty of each pixel. Two dimensional +extractions interpolate the spectra in the spatial axis to produce +image strips with the position of the spectra exactly aligned with one +of the image dimensions. The extractions also include optional +background subtraction, modeling, and bad pixel detection and replacement. +The tasks are flexible in their ability to define and edit apertures, +operate on lists of images, use apertures defined for reference +images, and operate both very interactively or noninteractively. +The extraction tasks are efficient and require only one pass through +the data. This paper describes the package organization, the tasks, +the algorithms, and the data structures. +.AE +.NH +Introduction +.PP +The IRAF \fBapextract\fR package provides tools for the extraction of +one and two dimensional aperture spectra from two dimensional format +images such as those produced by echelle, long slit, multifiber, and +multislit spectrographs. This type of data is becoming increasingly +common because of the efficiency of data collection and technological +improvements in spectrographs and detectors. The trend is to greater +and greater numbers of spectra per image. Extraction is one of the +fundamental operations performed on these types of two dimensional +spectral images, so a great deal of effort has gone into the design and +development of this package and to making it easy to use. +.PP +The tasks are flexible and have many options. To make the best use of +them it is important to understand how they work. This paper provides +a general description of the package organization, the tasks, the algorithms, +and the data structures. Specific descriptions of parameters +and usage may be found in the IRAF help pages for the tasks which +are included as appendices to this paper. The image reduction "cookbooks" +also provide examples of usage for specific instruments or types +of instruments. +.PP +Extraction of spectra consists of three logical steps. First, locating +the spectra in the two dimensional image. This includes defining the +dispersion direction, the positions of the spectra at some point +along the dispersion direction, the spatial extent or aperture to be +used for extraction, and possible information about where the background +for each spectrum is to be determined. This information is maintained +in the package as structures called \fIapertures\fR. The second step is +to measure the positions of the spectra at other points along the dispersion. +This process is called tracing. Tracing is optional if the spectra +are exactly aligned with the dispersion direction. The final step is +to extract the spectra into one or two dimensional images. +.PP +The \fBapextract\fR package identifies the image axes with the spatial +and dispersion axes. Thus, during extraction, pixels of constant +wavelength are assumed to be along a line or column. In this paper the +terms \fIslit\fR or \fIspatial\fR axis and \fIdispersion\fR or +\fIwavelength\fR axis are used to refer to the image axes corresponding +to the spatial and dispersion axes. To simplify the presentation a +cut across the dispersion axis will be called a line even though it +could also be a column. +.PP +Often a small degree of +misalignment between the image axes and the true dispersion and spatial +axes is not important. The main effect of misalignment is a broadening +of the spectral features due to the difference in wavelength on +opposite sides of the extraction aperture. If the misalignment is +significant, however, the image may be rotated with the task +\fBrotate\fR in the \fBimages\fR package or remapped with the +\fBlongslit\fR package tasks for coordinate rectification. +.PP +It does not matter which image axis is the dispersion axis since the +tasks work equally well in either orientation. However, the dispersion +axis must be defined, with the \fBtwodspec\fR task \fBsetdisp\fR, +before these tasks may be used. This task is a simple script which +adds the parameter DISPAXIS to the image headers. The \fBapextract\fR +tasks, like the \fBlongslit\fR tasks, look in the header to determine +the dispersion axis. +.NH +The APEXTRACT Package +.PP +In this section the organization of the \fBapextract\fR package and the +functions and parameters of the tasks are briefly described. More detailed +descriptions are given in the help pages for the tasks. The tasks in the +package are: + +.ce +.ft B +The APEXTRACT Tasks + +.ft L +.nf + apdefault - Set the default aperture parameters + apedit - Edit apertures interactively + apfind - Automatically find spectra and define apertures + apio - Set the I/O parameters for the APEXTRACT tasks + apnormalize - Normalize 2D apertures by 1D functions + apstrip - Extract two dimensional aperture strips + apsum - Extract one dimensional aperture sums + aptrace - Trace positions of spectra +.fi +.ft R + +.PP +The tasks are highly integrated so that each task includes some or all of +the functions and parameters of the other tasks. Thus, these tasks +reflect the logical organization of the extraction process rather than +a set of disparate tools. One reason for this organization is to group +the parameters by function into easy to manage \fIparameter sets +(psets)\fR. The tasks \fBapdefault\fR and \fBapio\fR are just psets +for specifying the default aperture parameters and the I/O parameters +of the package; in other words, they do nothing but provide a grouping +of parameters. Executing these tasks is a shorthand for the command +"eparam apdefault" or "eparam apio". +.PP +The input/output parameters in \fBapio\fR specify the aperture database, +an optional log file for brief, time stamped log information, an optional +metacode plot file for saving plots of the apertures, the traces, and the +quick look extracted spectra, and the graphics input and output devices +(almost always the user's terminal). One point about the plot file is +that the plots are recorded even if the user chooses not to view these +graphs as the task is run interactively or noninteractively. This allows +reviewing the traces and spectra with a tool like \fBgkimosaic\fR. +.PP +The default aperture parameters specify the aperture limits (basically +the width of the aperture and position relative to the center of the +spectrum) and the background fitting parameters. The background +parameters are the standard parameters used by the \fBicfit\fR package +with which the user is assumed to be familiar. For more on this see +the help information for \fBicfit\fR. +.PP +The other tasks are both psets and executable tasks. There are a +number features which are common to all these tasks. First, they +follow the same steps in defining apertures for the input images. +These steps are: +.IP (1) +If a reference image is specified then the database is searched for +apertures previously defined for this image. +.IP (2) +If apertures are found for the reference image they may be recentered +on the spectra in the input image at a specified line. This does not +change the shape of the apertures but only adds a shift in the center +coordinate of the apertures along the spatial axis. +.IP (3) +If a reference image is not specified or if no reference apertures are found +then the database is searched for previous apertures for the input image. +.IP (4) +If there are no apertures defined either from a reference image or previous +apertures for the input image then an automatic algorithm may be used to find +a specified number of spectra (based on peak values) and assign them default +apertures. +.IP (5) +Finally, a sophisticated graphical aperture editor may be used to examine, +define, and modify apertures. +.IP (6) +When tracing, extracting, or normalizing flat field spectra, +if no apertures have been defined by the steps above then a single default +aperture, centered in the image, is defined. + +Any apertures created, modified, or adopted from a reference image +may be recorded in the database for the input image. +.PP +The operations listed above are selected by parameters common to each of the +tasks. For example the parameter \fIedit\fR selects whether to enter +the aperture editor and is present in each of the executable tasks. +On the other hand the parameters specific to the aperture editor, +while accessed by any of the tasks, reside only in the parameter set of +the task \fBapedit\fR. In this way parameters are distributed +by logical function rather than including them in each task. +.PP +In addition to the aperture editing and finding functions available in +every task, some of the tasks include functions for tracing, extracting, +or normalizing the spectra. The tasks \fBapsum\fR and \fBapstrip\fR, +which extract one and two dimensional spectra, are at the top of the +hierarchy and include all the logical functions provided by the package. +Thus, in most cases the user need only use the task \fBapsum\fR to define +apertures, trace the spectra, and extract them. +.PP +Another feature common to the tasks is their interactive and noninteractive +modes. When the parameter \fIinteractive\fR is set to \fIno\fR then the +aperture editing, interactive trace fitting, and review of the extracted +one dimensional spectra functions of the package are bypassed. Note that +this means you do not have to explicitly set the parameter \fIedit\fR, +or those for other purely interactive functions, +to \fIno\fR when extracting spectra noninteractively. In the noninteractive +mode there are also no queries. +.PP +The interactive mode includes the interactive graphical functions of +aperture editing, trace fitting, and extraction review. In addition +the user is queried at each step. For example the user will be queried +whether to edit the apertures for a particular image if the task +parameter for editing is set. The queries have four responses: \fIyes, +no, YES,\fR and \fINO\fR. The lower case responses apply only to the +particular query. The upper case responses apply to any further +queries of the same type and suppress the query from appearing again. +This is particularly useful when dealing with many images or many +apertures. For example, when fitting the traced points interactively +the user may examine the first few and then say \fINO\fR to skip the +remaining apertures using the last defined fitting parameters. Note +that if a plot file is specified the graphs showing the traced points +and the fits are recorded even if they are not viewed interactively. +.NH +Algorithms +.PP +The \fBapextract\fR package consists of a number of logical functions or, +in computerese, algorithms. These algorithms manipulate the aperture +structure data and create output data in the form of images. In +this section the various algorithms are described. In addition to the +algorithms specific to the package, there are some general algorithms +and tools used which appear in other IRAF tasks. Specifically there are the +interactive curve fitting tools called \fBicfit\fR and the one +dimensional centering algorithm called \fBcenter1d\fR. These are +mentioned below and described in detail elsewhere in the help documentation. +.NH 2 +Finding Spectra +.PP +When dealing with images containing large numbers of spectra it may be +desirable to locate the spectra and define apertures automatically. The +\fBapfind\fR algorithm provides this ability from any of the executable +tasks and from the aperture editor using the 'f' key. It takes a cut +across the dispersion axis by summing one or more image lines. +All the local maxima are identified and ranked by intensity. Starting +with the highest maxima any other peaks within a specified minimum +separation are eliminated. The weakest remaining peaks exceeding the +specified number are eliminated next. The positions of the +spectra based on peak positions are refined by centering using the +\fBcenter1d\fR algorithm. Finally identical apertures are assigned +for each spectrum found. +.PP +When the algorithm is invoked by a task, with the parameter \fIfind\fR, +there must be no previous or reference apertures in the database. +The apertures assigned to the spectra have the parameters +specified in the \fBapdefault\fR pset. When the algorithm is invoked +from the aperture editor with the 'f' key then new apertures are +added to any existing apertures up to the total number of apertures, +existing plus new, given by the \fInfind\fR parameter. If there +is a current aperture then copies of it are used to define the +apertures for the new spectra. Thus, one method for defining many +apertures is to use the editor to define one aperture, set its +limits and background parameters, and then find the remaining apertures +automatically. +.NH 2 +Centering and Recentering +.PP +When new apertures are defined (except for a special key to mark apertures +without centering) or when apertures are recentered, either with the +centering key in the editor or with the task parameter \fIrecenter\fR, +the center is determined using the \fBcenter1d\fR algorithm. +This is described in the help documentation under the name \fBcenter1d\fR. +Briefly, the data line is convolved with an asymmetric function of specified +width. The convolution integral is evaluated using image interpolation. +The sign of the convolution acts as a gradient to move from the starting +position to the final position where the convolution is zero. This algorithm +is good to about 5% of a pixel. It has two important parameters; the +width of the convolution and the error distance between the starting +and final positions. The width of the convolution determines the scale +of features to which the centering is sensitive. The error distance is +the greatest change allowed in the initial positions. If this error +distance is exceeded then the centering fails and either a new aperture +is not defined or the position of an existing aperture is not changed. +.NH 2 +The Aperture Editor +.PP +The aperture editor is a sophisticated tool for defining and modifying +apertures. It may also be used to selectively trace and extract +spectra. Thus, the aperture editor may be used alone to perform all +the functions for extracting spectra. The aperture editor uses a +graphical presentation. A line or sum of lines is displayed. The +apertures are marked above the line and identified with the aperture +number. Information about the current aperture is shown on the status +line. The cursor is used to mark new apertures, shift the center or +aperture limits, and perform a variety of functions. Because there may +be many apertures which the user wants to modify in the same way there +is a mode switch to apply commands to all the apertures. The switch is +toggled with the 'a' key and the mode is indicated on the status line. +.PP +There are also a number of colon commands. These allow resetting parameters +explicitly rather than by cursor and interacting with the aperture +database and the image data. The background fitting parameters such as +the background regions and function order are set by switching to the +interactive curve fitting package \fBicfit\fR. The line being edited is +used to set the parameters. No background is actually extracted at this +stage. The ALL mode applies to the background parameters as well. +.PP +The aperture editor has many commands. For a description of the +commands see the help information for the task \fBapedit\fR. In +summary the aperture editor is used to interactively define apertures, +both centered on spectra and at arbitrary positions, adjust the limits +and background parameters, and possibly select apertures to be traced +and extracted. These functions may be applied independently on each +aperture for maximum flexibility or applied to all apertures for ease +of use with many apertures. +.NH 2 +Tracing +.PP +The spectra to be extracted are not always aligned exactly with the +image columns or lines. For consistent +extraction it is important that the same part of the spectrum profile +be extracted at each wavelength point. Thus, the extraction apertures +allow for shifts along the spatial axis at each wavelength. The +shifts are defined by a curve which is a function of the wavelength. +The curve is determined by tracing the positions of the spectrum +profile at a number of wavelengths and fitting a function to these +positions. +.PP +The \fIaptrace\fR algorithm performs the tracing and curve fitting. +The starting point along the dispersion axis (a line or column) for +the tracing is specified by the user. The positions of the spectrum +profiles are determined using the \fBcenter1d\fR algorithm +(see the previous section on centering and the help page for \fBcenter1d\fR). +The user specifies a step along the dispersion axis. At each step the +positions of the profiles are redetermined using the preceding +positions as the initial guesses. If the positions are lost at one step +an attempt is made to recover the spectrum in the next step. If this +also fails then tracing of that spectrum in that direction is finished. +In order to enhance and trace weak spectra the user may specify a number +of neighboring profiles to be summed before determining the profile positions. +In addition to the other centering parameters, there is also a +\fIthreshold\fR parameter to define a minimum contrast between the spectrum +and the background. +.PP +Once the positions have been traced from the starting point to the ends of the +aperture, or until the positions become indeterminate, a curve of a +specified type and order is fit to the positions as a function of +wavelength. The function fitting is performed with the \fBicfit\fR +tools (see the help documentation for \fBicfit\fR). The curve fitting +may be performed interactively or noninteractively. Note that when the +curve is fit interactively the actual positions measured are graphed. +However, the curve is stored in the aperture definition as an offset +relative to the aperture center. +.PP +The tracing requires that the spectrum profile be continuous and have +some kind of maxima. This means that arc calibration spectra or +arbitrary regions of an extended object in a long slit spectrum cannot +be traced. Flat topped spectra such as quartz lamp images taken through +slits can be measured provided the width of the centering function is +somewhat wider than the profile (to avoid centering on little peaks +within the slit). For images which cannot be traced, reference apertures +from images that can be traced are used. This is how apertures for +arc spectra are defined and extracted. For sky apertures or the +wings of extended objects the reference apertures can be shifted +by the aperture editor without altering the shape of the aperture. +.NH 2 +Sum Extraction +.PP +Sum extraction consists of the weighted sum of the pixels along the spatial axis +within the aperture limits at each point along the dispersion axis. +A background at each point along the dispersion may be determined by fitting a +function to data in the vicinity of the spectrum and subtracting the +function values estimated at each point within the aperture. The estimated +background may be output as a one dimensional spectrum. Other options +include the detection and replacement of deviant points such as due to +cosmic rays. +.PP +Denote the image axis nearest the spatial axis by the index $s$ and +the other image axis corresponding to the dispersion axis by $lambda$. +The weighted extraction is defined by the equation + +.EQ I (1) +f sub lambda~=~sum from s (W sub sl (I sub sl - B sub sl ) / P sub sl ) / +sum from s W sub sl +.EN + +where the sums are over all pixels along the spatial axis within some +aperture. The $W$ are weights, the $I$ are pixel intensities, +the $B$ are background intensities, and the $P$ are a normalized +profile model. +.PP +There are many possible choices for the extraction weights. The extraction +task \fBapsum\fR currently provides two: + +.EQ I (2a) +W sub sl~mark =~P sub sl +.EN +.EQ I (2b) +W sub sl~lineup =~P sub sl sup 2 / V sub sl +.EN + +where $V sub sl$ is the variance of the pixel intensities given by the +model + +.EQ I + V sub sl~=~v sub 0 + v sub 1~max (0,~I sub sl )~~~~if v sub 0~>~0 +.EN +.EQ I + V sub sl~=~v sub 1~max (1,~I sub sl )~~~~~~~~~if v sub 0~=~0 +.EN + +Substituting these weights in equation (1) yields the extraction equations + +.EQ I (3a) +f sub lambda~mark =~sum from s (I sub sl - B sub sl ) +.EN +.EQ I (3b) +f sub lambda~lineup =~sum from s (P sub sl (I sub sl - B sub sl ) / V sub sl ) / +sum from s (P sub sl sup 2 / V sub sl ) +.EN + +.PP +The first type of weighting (2a), called \fIprofile\fR weighting, weights +by the profile. Since the weights cancel this gives the simple extraction (3a) +consisting of the direct summation of the pixels within the aperture. +It has the virtue of being simple and computationally fast (since the +profile model does not have to be determined). +.PP +The second type of weighting (2b), called \fIvariance\fR weighting, +uses a model for the variance of the pixel intensities. +The model is based on Poisson statistics for a linear quantum detector. +The first term is commonly call the \fIreadout\fR noise and the second term +is the Poisson noise. The actual value of $v sub 1$ is the reciprocal of +the number of photons per digital intensity unit (ADU). A simple variant of +this type of weighting is to let $v sub 1$ equal zero. Since the actual +scale of the variance cancels we can then set $v sub 0$ to unity to obtain + +.EQ I (4) +f sub lambda~=~sum from s (P sub sl (I sub sl - B sub sl )) / +sum from s P sub sl sup 2 . +.EN + +The interpretation of this extraction is that the variance of the intensities +is constant. It gives greater weight to the stronger parts of the spectrum +profile than does the profile weighting (3a) since the weights are +$P sub sl sup 2$. Equation (4) has the virtue that one need not know the +readout noise or the ADU to photon number conversion. +.NH 3 +Optimal Extraction +.PP +Variance weighted extraction is sometimes called optimal extraction because +it is optimal in a statistical sense. Specifically, +the relative contribution of a pixel to the sum is related to the uncertainty +of its intensity. The uncertainty is measured by the expected variance of +a pixel with that intensity. The degree of optimality depends on how well +the relative variances of the pixels are known. +.PP +A discussion of the concepts behind optimal extraction is given in the paper +\fIAn Optimal Extraction Algorithm for CCD Spectroscopy\fR by Keith Horne +(\fBPASP\fR, June 1986). The weighting described in Horne's paper is the +same as the variance weighting described in this paper. The differences +in the algorithms are primarily in how the model profiles $P sub sl$ are +determined. +.NH 3 +Profile Determination +.PP +The profiles of the spectra along the spatial axis are determined when +either the detection and replacement of bad pixels or variance +weighting are specified. The requirements on the profiles are that +they have the same shape as the image profiles at a each dispersion +point and that they be as noise free and uncontaminated as possible. +The algorithm used to create these profiles is to average a specified +number of consecutive background subtracted image profiles immediately +preceding the wavelength to which a profile refers. When there are an +insufficient number of image profiles preceding the wavelength being +extracted then the following image profiles are also used to make up +the desired number. The image profiles are interpolated to a common +center before averaging using the curve given in the aperture +definition. The averaging reduces the noise in the image data while +the centering eliminates shifts in the spectrum as a function of +wavelength which would broaden the profile relative to the profile of a +single image line or column. It is assumed that the spectrum profile +changes slowly with wavelength so that by using profiles near a given +wavelength the average profile shape will correctly reflect the profile +of the spectrum at that wavelength. +.PP +The average profiles are determined in parallel with the extraction, +which proceeds sequentially through the image. Initially the first set +of spectrum profiles is read from the image and interpolated to a common +center. The profiles are averaged excluding the first profile to be +extracted; the image profiles in the average never include the image +profile to be extracted. Subsequently the average profile is updated +by adding the last extracted image profile and subtracting the image +profile which no longer belongs in the average. This allows each image +profile to be accessed and interpolated only once and makes the +averaging computationally efficient. This scheme also allows excluding +bad pixels from the average profile. The average profile is used to +locate and replace bad pixels in the image profile being extracted as +discussed in the following sections. Then when this profile is added +into the average for the next image profile the detected bad pixels are +no longer in the profile. +.PP +In summary this algorithm for determining the spectrum profile +has the following advantages: + +.IP (1) +No model dependent smoothing is done. +.IP (2) +There is no assumption required about the shape of the profile. +The only requirement is that the profile shape change slowly. +.IP (3) +Only one pass through the image is required and each image profile +is accessed only once. +.IP (4) +The buffered moving average is very efficient computationally. +.IP (5) +Bad pixels are detected and removed from the profile average as the +extraction proceeds. + +.NH 3 +Detection and Elimination of Bad Pixels +.PP +One of the important features of the aperture extraction package is the +detection and elimination of bad pixels. The average profile described +in the previous section is used to find pixels which deviate from this +profile. The algorithm is straightforward. A model spectrum of the +image profile is obtained by scaling the normalized profile to the +image profile. The scale factor is determined using chi-squared fitting: + +.EQ I (6) +M sub sl~=~P sub sl~left { sum from s ((I sub sl - B sub sl ) P sub sl / +V sub sl )~/~ sum from s (P sub sl sup 2 / V sub sl ) right } . +.EN + +The RMS of this fit is determined and pixels deviating by more than a +user specified factor times this RMS are rejected. The fit is then +repeated excluding the rejected points. These steps are repeated until +the user specified number of points have been rejected or no further deviant +points are detected. The rejected points in the image profile are then +replaced by their model values. +.PP +This algorithm is based only on the assumption that the spatial profile +of the spectrum (no matter what it is) changes slowly with wavelength. +It is very sensitive at detecting departures from the expected +profile. It has two problems currently. Because the input line is +first interpolated to the same center as the profile, single bad pixels +are generally broadened to two bad pixels, making it harder to find the +bad data. Also, in the first pass at the fit all of the image profile +is used so if there is a very badly deviant point and the rest of the +profile is weak then the scale factor may favor the bad pixel more than +the rest of the profile. This may result in rejecting good profile +points and not the bad pixel. +.NH 3 +Relation of Optimal Extraction to Model Extraction +.PP +Equation (1) defines the extraction process in terms of a weighted sum +of the pixel intensities. However, the actual extraction operations +performed by the task \fBapsum\fR are + +.EQ I (7a) +f sub lambda~mark =~sum from s (I sub sl - B sub sl ) +.EN +.EQ I (7b) +f sub lambda~lineup =~sum from s M sub sl +.EN + +where $M sub sl$ is the model spectrum fit to the background subtracted +image spectrum $(I sub sl - B sub sl )$ +defined in the previous section (equation 6). It is not obvious at first that +(7b) is equivalent to (3b). However, if one sums (6) and uses the fact +that the sum of the normalized profile is unity one is left with equation (3b). +.PP +Equations (6) and (7b) provide an alternate way to think about the +extracted one dimensional spectra. Sum extraction of the model spectrum +is used instead of the weighted sum for variance weighted extraction +because the model spectrum is a product of the profile determination +and the bad pixel cleaning process. It is then more convenient +and efficient to use the simple equations (7). +.NH 2 +Strip Extraction +.PP +The task \fBapstrip\fR uses one dimensional image interpolation +to shift the pixels along the spatial axis so that in the resultant +output image the center of the aperture is exactly aligned with the +image lines or columns. The cleaning of bad pixels is an option +in this extraction using the methods described above. In addition +the model spectrum, described above, may be extracted as a two +dimensional image. In fact, the only difference between strip extraction +and sum extraction is whether the final step of summing the pixels +in the aperture along the spatial axis is performed. +.PP +The primary use of \fBapstrip\fR is as a diagnostic tool. It +allows the user to see the background subtracted, cleaned, and/or model +spectrum as an image before it is summed to a one dimensional spectrum. +In addition the two dimensional format allows use of other IRAF tools such as +smoothing operators. When appropriate +it is a much simpler method of removing detector distortions and alignment +errors than the full two dimensional mapping and image transformation +available with the \fBlongslit\fR package. +.NH 2 +Aperture Normalization +.PP +The special algorithm/task \fBapnormalize\fR normalizes the two dimensional +image data within an aperture by a smooth function of the dispersion +coordinate. Unlike the extraction tasks the output of this algorithm is +a two dimensional image of the same format as the input image. This function +is used primarily for creating flat field images in which the large +scale shape of the quartz spectra and the variations in level between the +spectra are removed and the regions between the spectra, where there is no +signal, are set to unity. It may also be used to normalize two dimensional +spectra to a unit continuum at some point in the spectrum, such as the center. +.PP +The algorithm is to extract a one dimensional spectrum for each aperture, +fit a smooth function to the spectrum, and then divide this spectrum +back into the two dimensional image. Points outside the apertures are +set to 1. This is the same algorithm used in the \fBlongslit\fR package +by the task \fBresponse\fR except that it applies to arbitrary apertures +rather than to image sections. +.PP +Apertures are defined in the same way as for extraction. The normalization +spectrum may be obtained from a different aperture than the aperture to be +normalized. Generally the normalization apertures are either the same or +narrower than the apertures to be normalized. The continuum fitting also +uses the \fBicfit\fR package. Sample regions and iterative sigma clipping +are used to remove spectral lines from the continuum fits. +.PP +There are two commonly used approaches to fitting the extracted spectra +in flat field images. First, a constant function is fit. This has the +effect of simply normalizing the apertures to near unity without affecting +the shape of spectra in any way. This removes response effects at all scales, +from spectra flatten with this flat field. However, it does not +preserve total counts, it introduces the shape of the quartz spectrum, +and it removes the blaze function. The second approach is to fit the +large scale shape of the quartz spectra. This removes smaller scale +response effects such a fringing and individual pixel responses while +preserving the total counts by leaving the blaze function alone. There are +cases where each of these approaches is applicable. +.NH +Apertures +.PP +Apertures are the basic data structures used in the package; hence the +package name. An aperture defines a region of the two dimensional image +to be extracted. The aperture definitions are stored in a database. +An aperture consists of the following components: + +.IP ID +.br +An integer identification number. The identification number must be +unique. It is used as the default extension during extraction of +the spectra. Typically the IDs are consecutive positive integers +ordered by increasing or decreasing slit position. +.IP BEAM +.br +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 +the extracted spectrum. By default the beam number is the same as +the ID. +.IP CENTER[2] +.br +The center of the aperture along the slit and dispersion axes in the two +dimensional image. +.IP LOWER[2] +.br +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. +.IP UPPER[2] +.br +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. +.IP APAXIS +.br +The aperture or spatial axis. +.IP CURVE +.br +An offset to be added to the center position for the aperture axis as +a function of the wavelength. The function is one of the standard IRAF +types; a legendre polynomial, a chebyshev polynomial, a linear spline, +or a cubic spline. +.IP BACKGROUND +.br +Parameters for background subtraction along the aperture axis based on +the interactive curve fitting (\fBicfit\fR) tools. + +.PP +The aperture center is the only absolute coordinate (relative to the +image or image section). The other aperture parameters and the +background fitting regions are defined relative to the center. Thus, +an aperture may be repositioned easily by changing the center +coordinates. Also constant aperture size, shape (curve), and +background regions may be maintained for many apertures. +.PP +The edges of the aperture along the spatial axis at each point along the +dispersion axis are given by evaluating the offset curve at that dispersion +coordinate and adding the aperture center and the lower or upper limits +for the aperture axis. The edges of the aperture along the dispersion axis +do not have an offset curve and are currently fixed to define the entire +length of the image. In the future this may not be the case such as +in applications with objective prism spectra. +.PP +Apertures for a particular image may be defined in several ways. They +may be defined and modified graphically with an aperture editor. Default +apertures may be defined automatically with parameters from the +\fBapdefault\fR pset using an aperture finding algorithm. Another +method is to specify that the apertures for one image use the aperture +definitions from another "reference" image. In the rare cases where +apertures are not defined at the stage of tracing or extracting then +a single default aperture centered in the image is created. +.NH 2 +The Database +.PP +The aperture information is stored in a database. The structure and type of +database is expected to change in the future and as far as the package and +user need be concerned it is just a black box with some name specified in +the database name parameter. However, accepting that the database structure may +change it may be of use to the user to understand the nature of the current +text file / directory format database. The database is a directory containing +text files. It is automatically created if necessary. The aperture data +for all the apertures from a single image are stored in a text file +with the name given by the image name (with special characters replaced +with '_') prefixed with "ap". Updates of the aperture data are performed +by overwriting the database file. +.PP +The content of a file consists of a comment (beginning with a #) giving +the date created/updated, a record identification (there is one record +per aperture) with the image name, aperture number and aperture +coordinate in the aperture and dispersion axes. The following lines +give information about the aperture. The position and shape of an +aperture is given by a center coordinate along the aperture axis (given +by the axis keyword) and the dispersion axis. There are lower and +upper limits for the aperture relative to this center, again along both +axis. Currently the limits along the dispersion axis are the image +boundaries. The background keyword introduces the background +subtraction parameters. Finally there is an offset or trace function +which is added to the center at each point along the dispersion axis. +function. The offset is generally zero at the dispersion point +corresponding to the aperture center. +.PP +This offset or trace function is described by a \fBcurfit\fR array under +the keyword curve. The first value is the number of elements in this +array. The first element is a magic number specifying the function +type. The next number is the order or number of spline pieces. The +next two elements give the range over which the curve is defined. In +the \fBapextract\fR case it is the edges of the image along the dispersion. +The remaining elements are the function coefficients. The form of the +the function is specific to the IRAF \fBcurfit\fR math routines. Note that +the coefficients apply to an independent variable which is -1 at the +beginning of the defined range (element 3) and 1 at the end of the range +(element 4). For further details consult the IRAF group. +.PP +An example database file for one aperture from an image "ech001" is given +below. + +.ft L +.nf + # Fri 14:33:35 08-May-87 + begin aperture ech001 1 22.75604 100. + image ech001 + aperture 1 + beam 1 + center 22.75604 100. + low -2.680193 -99. + high 3.910698 100. + background + xmin -262. + xmax 262. + function chebyshev + order 1 + sample -10:-6,6:10 + naverage -3 + niterate 0 + low_reject 3. + high_reject 3. + grow 0. + axis 1 + curve 6 + 2. + 2. + 1. + 200. + -0.009295368 + -0.3061974 +.fi +.ft R +.NH +Future Developments +.PP +The IRAF extraction package \fBapextract\fR is going to continue to +evolve because the extraction of one and two dimensional spectra +from two dimensional images is an important part of reducing echelle, +longslit, multislit, and multiaperture spectra. Changes may include +some of the following: + +.IP (1) +Determine the actual variance from the data rather than using the Poisson +CCD model. Also output the variance vector if desired. +.IP (2) +The bad pixel detection and removal algorithm does not handle well the case +of a very strong cosmic ray event on top of a very weak spectrum profile. +A heuristic method to make the first fitting pass of the average +profile to the image data less prone to errors due to strong cosmic rays +is needed. Also the detection should be done by interpolating the profile +to the original image data rather than the other way around, in order to +avoid broadening cosmic rays by interpolation. +.IP (3) +The aperture definition structure is general enough to allow the aperture +limits along the dispersion dimension to be variable. Eventually aperture +definition and editing will be available using an image display. Then +both graphics and image display editing switches will be available. +An image display interface will make extraction of objective prism +spectra more convenient than it is now. +.IP (4) +Other types of extraction weighting may be added. -- cgit