Repatch (from linux) of OSX IRAF

1 files changed, 811 insertions, 0 deletions

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.