path: root/noao/twodspec/apextract/doc/old/Tutorial.hlp

.help Tutorial Sep86 "Apextract Tutorial"
.ih
TOPICS
The APEXTRACT tutorial consists of a number of topics.  The topics are brief
and describe the simplest operations.  More sophisticated discussions are
available for the tasks in the printed documentation and through the on-line
\fBhelp\fR facility; i.e. "help taskname".  To obtain information
on a particular topic type "tutor topic" where the topic is one of the
following:

.nf
			TOPICS

         topics - List of topics
       overview - An overview of the \fBapextract\fR tasks
   organization - How the package is organized
      apertures - Definition of apertures
       defining - How to define apertures
     references - Using reference images to define apertures
        queries - Description of interactive queries
	 cosmic - Problems with cosmic ray removal
	    all - Print all of this tutorial
.fi
.ih
OVERVIEW
The \fBapextract\fR tasks extract spectra from two dimensional images.
One image axis is the dispersion axis and the other image axis is the
aperture axis.  The user defines apertures whose position along the
aperture axis is a function of position along the dispersion axis and
whose width is fixed.  There are two types of aperture extractions.
\fIStrip\fR extraction produces two dimensional images in which the
center of the aperture is exactly centered along one of the lines or
columns of the image and the edges of the image just include the
edges of the aperture.  \fISum\fR extraction sums the pixels across
the aperture at each point along the dispersion to produce a one
dimensional spectrum.  The extraction algorithms include
fitting and subtracting a background, modeling the profiles across the
dispersion, detecting and removing deviant pixels which do not fit the
model profiles, and weighting the pixels in the sum extraction according
to the signal-to-noise.

To extract spectra one must define the dispersion axis by placing the
parameter DISPAXIS in the image headers using the task \fBsetdisp\fR.
Then apertures are defined either automatically, interactively, or by
reference to an image in which apertures have been previously defined.
Initially the apertures are aligned parallel to the dispersion axis
but if the spectra are not aligned with the dispersion axis and have
profiles which can be traced then the position of the aperture along
the aperture axis can be made a function of position along the dispersion
axis.  Finally, the extraction operation is performed for each aperture.
.ih
ORGANIZATION
The tasks in the \fBapextract\fR package are highly integrated.  This
means that tasks call each other.  For example, the aperture
editing task may be called from the finding, tracing, or extraction
tasks.  Also from within the aperture editor the finding, tracing, and
extraction tasks may be run on selected apertures.  This organization
provides the flexibility to process images either step-by-step,
image-by-image, or very interactively from the aperture editor.  For
example, one may defined apertures for all the images, trace all the
images, and then extract all the images or, alternatively, define,
trace, and extract each image individually.

This organization also implies that parameters from many tasks are used
during the execution of a single task.  For example, the editing
parameters are used in any of the tasks which may enter the interactive
editing task.  Two tasks, \fBapio\fR and \fBapdefault\fR, only set
parameters but these parameters are package parameters which affect all
the other tasks.  There are two effects of this parameter
organization.  First, only parameters from the task being executed may
be specified on the command line or with menu mode.  However, the
parameters are logically organized and the parameter list for any
particular task is not excessively long or complex.  For example, the
number of parameters potentially used by the task \fBapsum\fR is 57
parameters instead of just the parameters logically related to the
extraction itself.

Another feature of the package organization is the ability to
control the flow and interactivity of the tasks.  The parameter
\fIinteractive\fR selects whether the user will be queried about various
operations and if the aperture editor, trace fitting, and extraction
review will be performed.  The parameters \fBdbwrite,
find, recenter, edit, trace, fittrace, sum, review\fR, and
\fBstrip\fR select which operations may be performed by a particular
task.  When a task is run interactively the user is queried about
whether to perform each operation on each image.  A query may be answered
individually or as a group.  In the latter case the query will not be
repeated for other images but will always take the specified action.
This allows the user to begin interactively and then reduce
the interactivity as the images are processed and parameters are refined.
For additional discussion of these parameters see the topic QUERIES.

Finally, the package has attempted to provide good logging facilities.
There are log files for both time stamped text output and plots.
The text log is still minimal but the plot logging is complete
and allows later browsing and hardcopy review of batch processing.
See \fBapio\fR for further discussion.

This package organization is somewhat experimental.  Let us know what
you think.
.ih
APERTURES
An aperture consists of the following elements:

.ls id    
An integer aperture identification number.  The identification number
must be unique.  The aperture number is used as the default extension
of the extracted spectra.
.le
.ls beam    
An integer beam number.  The beam number need not be unique; i.e.
several apertures may have the same beam number.  The beam number will
be recorded in the image header of the extracted spectrum.  Note that
the \fBonedspec\fR package restricts the beam numbers to the range 0 to
49.
.le
.ls cslit, cdisp
The center of the aperture along the slit and dispersion axes in the two
dimensional image.
.le
.ls lslit, ldisp
The lower limits of the aperture, relative to the aperture center,
along the slit and dispersion axes.  The lower limits need not be less
than the center.
.le
.ls uslit, udisp
The upper limits of the aperture, relative to the aperture center,
along the slit and dispersion axes.  The upper limits need not be greater
than the center.
.le
.ls curve
An shift to be added to the center position for the slit axis which is
a function of position along the dispersion axis.  The function is one
of the standard IRAF \fBicfit\fR types; a legendre polynomial, a chebyshev
polynomial, a linear spline, or a cubic spline.
.le
.ls background
Background fitting parameters used by the \fBicfit\fR package for background
subtraction.  Background parameters need not be used if background
subtraction is not needed.  The background sample regions are specified
relative to aperture center.
.le

The aperture center is the only absolute coordinate relative to the
image or image section.  The size and shape of the aperture are
specified relative to the aperture center.  The center and aperture
limits in image coordinates along the slit axis are functions of the
dispersion coordinate, lambda, given by

.nf
	center(lambda) = cslit + curve(lambda)
	 lower(lambda) = center(lambda) + lslit
	 upper(lambda) = center(lambda) + uslit
.fi

Note that both the lower and upper constants are added to the center
defined by the aperture center and the curve offset.  The aperture limits
along the dispersion axis are constant,

.nf
	        center(s) = cdisp
	         lower(s) = center(s) + ldisp
	         upper(s) = center(s) + udisp
.fi

Usually the aperture size along the dispersion is equal to the entire image.
.ih
DEFINING APERTURES
If a reference image is specified the \fBapextract\fR tasks first search
the database for it's apertures.  Note that this supercedes any apertures
previously defined for the input image.  If no reference apertures are
found then the apertures for the input image are sought.
If no apertures are defined at this point then apertures
may be defined automatically, interactively, or, by default, in the center
of the image.  The automatic method, \fBapfind\fR, locates spectra as peaks
across the dispersion and then defines default apertures given by the
parameters from \fBapdefault\fR.  The algorithm is controlled
by specifying the number of apertures and a minimum separation between
spectra.  Only the strongest peaks are selected.

The interactive method, \fBapedit\fR, allows the user to mark the positions
of apertures and to adjust the aperture parameters such as the limits.
The aperture editor may be used edit apertures defined by any of the
other methods.

If no apertures are defined when tracing or extraction is begun, that is
following the optional editing, then a default aperture is defined
centered along the aperture axis of the image.  This ultimate default
may be useful for spectra defined by image sections; i.e. the image
section is a type of aperture.  Image sections are sometimes used with
multislit spectra.
.ih
REFERENCE IMAGES
The \fBapextract\fR tasks define apertures for an input image by
first searching the database for apertures recorded under the name
of the reference image.  Use of a reference image implies
superceding the input image apertures.  Reference images are specified
by an image list which is paired with
the input image list.  If the number of reference images
is less than the number of input images then the last reference image
is used for all following images.  Generally, the reference image list
consists of the null string if reference images are not to be used,
a single image which is applied to all input images, or a list
which exactly matches the input list.  The special reference image
name "last" may be used to refer to the last apertures written to
the database; usually the previous input image.

The task parameter \fIrecenter\fR specifies whether the
reference apertures are to be recentered on the spectra in the input
image.  If recentering is desired the \fBcenter1d\fR centering algorithm
is used with centering parameters taken from the task \fBapedit\fR.
The spectra in the image must all have well defined profiles for the
centering.  It does not make sense to center an aperture defined for
a region of sky or background or for an arc spectrum.

Recentering is used when the only change between two spectra is
a shift along the aperture axis.  This can reduce the number of
images which must be traced if tracing is required by using a
traced reference image and just recentering on the next spectra.
Recentering of a traced reference image is also useful when
the spectra are too weak to be traced reliably.  Recentering would be
most commonly used with echelle or multiaperture spectra.

Recentering is not used when extracting sky or arc calibration spectra
from long slit or multislit images.  This is because it is desirable
to extract from the same part of the detector as the object spectra and
because recentering does not make sense when there is no profile across
the aperture.  Centering or recentering is also not used when dealing
with apertures covering parts of extended objects in long slit spectra.
.ih
QUERIES
When the interactive parameter is specified as yes in a task then the user
is queried at each step of the task.  The queries refer to either a
particular image or a particular aperture in an image.  The acceptable
responses to the queries are the strings "yes", "no", "YES", and "NO".
The lower case answers refer only to the specific query.  The upper
case answers apply to all repetitions of query for other images and
apertures.  The upper case reponses then suppress the query and take
the specified action every time.  This allows tasks to be highly interactive
by querying at each step and for each image or to skip or perform
each step for all images without queries.

The two steps of fitting a function to traced positions and reviewing
one dimensional extracted spectra, selected with the parameters
\fIaptrace.fittrace\fR and \fIapsum.review\fR have two levels of queries.
First a query is made for the image being traced or extracted.  If
the answer is "yes" or "YES" then a query is made for each aperture.
A response of "YES" or "NO" applies only to the remaining apertures
and not to apertures of a later image.
.ih
COSMIC RAYS
The cleaning and modeling features available during aperture extraction
are fairly good.  They are described in the documentation for the
tasks.  It can only go so far towards discriminating cosmic rays
because of problems described below.  Further work on the algorithm may
improve the performance but it is best, when feasible, to first
eliminate at least the strongest cosmic rays from the data before
extracting.  One recommended method is to use \fBlineclean\fR with a
high rejection threshold and a high order.

There are two difficult problems encountered in using the
\fBapextract\fR tasks for cosmic ray detection.  First, the spectral
profiles are first interpolated to a common center before comparison
with the average profile model.  The interpolation often splits single
strong spikes into two high points of half the intensity, as is
intuitively obvious.  Furthermore, for very strong spikes there is
ringing in the interpolator which makes the interpolated profile depart
significantly from the original profile.  The fact that the
interpolated profile now has two or more deviant points makes it much
harder to decide which points are in the profile.  This leads to the
second problem.  The average profile model is scaled to fit the
spectrum profile.  When there are several high points it is very
difficult to discriminate between a higher scale factor and bad
points.  The algorithm has been enhanced to initially exclude the point which
most pulls the scale factor to higher values.  If there are two high
points due to the interpolator splitting a strong spike then this helps
but does not eliminate errors in the extracted spectra.
.endhelp