path: root/noao/twodspec/apextract/doc/old/apextract1.ms

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