.help package Feb94 noao.twodspec.apextract
.ih
NAME
apextract -- Identify, manipulate, and extract spectra in 2D images
.ih
USAGE
apextract
.ih
PARAMETERS
.ls dispaxis = 2
Image axis along which the spectra dispersion run.  The dispersion axis
is 1 when the dispersion is along lines so that spectra are horizontal
when displayed normally.  The dispersion axis is 2 when the dispersion
is along columns so that spectra are vertical when displayed normally.
This parameter is superseded when the dispersion axis is defined in
the image header by the parameter DISPAXIS.
.le
.ls database = "database"
Database for storing aperture definitions.  Currently the database is
a subdirectory of text files with prefix "ap" followed by the entry name,
usually the image name.
.le
.ls verbose = no
Print detailed processing and log information?  The output is to the
standard output stream which is the user's terminal unless redirected.
.le
.ls logfile = ""
Text logfile of operations performed.  If a file name is specified
log and history information produced by all the tasks in the package
is appended to the file.
.le
.ls plotfile = ""
Binary plot metacode file of aperture locations, traces, rejected points,
etc.  If a file name is given metacode plots are appended.  The contents
of the file may be manipulated with the tasks in the \fBplot\fR package.
The most common is \fBgkimosaic\fR.  Special plotfile names may be used
to select only particular plots or plots not normally output.  These are
debugall, debugfitspec, debugaps, debugspec, debugfits, debugtrace,
and debugclean which plot everything, the fitted spectrum, the apertures,
the extracted spectrum, profile fit plots, the trace, and the rejected
points during cleaned extraction.
.le
.ls version = "APEXTRACT V3.0: August 1990"
Version of the package.  This is the third major version of the package.
.le
.ih
DESCRIPTION
The primary function of the \fBapextract\fR package is the extraction of
spectra from two dimensional formats to one dimensional formats.  In
other words, the pixels at each wavelength are summed, possibly
subtracting a background or sky from other pixels at that wavelength,
to produce a vector of spectral fluxes as a function of wavelength.
It has become common to have many spectra in one two dimensional
image produced by instruments using echelles, fibers, and aperture
masks.  Thus, the package provides many features for the efficient
extractions of multiple spectra as well as single spectra.  There are
also some additional, special purpose tasks for modeling spectra
and using the aperture definitions, described below,
to create masks and modified flat field images.

The package assumes that one of the image axes is the dispersion axis,
specified by the \fIdispaxis\fR package parameter or image header
parameter of the same name, and the other is the spatial axes.
This means that all pixels at the same column or line (the
orientation may be in either direction) are considered to be at the
same wavelength.  Even if this is not exactly
true the resolution loss is generally quite small and the simplicity and
absence of interpolation problems justify this approach.  The
alternatives are to rotate the image with \fBrotate\fR or use the more
complex \fBlongslit\fR package.  Though extraction is strictly along
lines and columns the position of the spectrum along the spatial axis
is allowed to shift smoothly with wavelength.  This accounts for small
misalignments and distortions.

The two dimensional regions occupied by the spectra are defined by
digital apertures having a fixed width but with spatial position smoothly
varying with wavelength.  The apertures have a number of attributes.
The aperture definitions are created and modified by the tasks in this
package and stored in a database specified by the parameter \fIdatabase\fR.
The database is currently a directory containing simple text files
in a human readable format.  The elements of an aperture definition
are as follows.


.ce
Elements of an Aperture Definition
.ls aperture
An integer aperture identification number.  The aperture number
must be unique within a set of apertures.  The aperture number is
the primary means of referencing an aperture and the resulting
extracted spectra.  The aperture numbers are part of the extracted
spectra image headers.  The numbers may be any integer and in any order
but the most typical case is to have sequential numbers beginning
with 1.
.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 numbers are
recorded in the image headers of the extracted spectra.  The beam
number is often used to identify types of spectra such as object,
sky, arc, etc.
.le
.ls center
A pair of numbers specifying the center of the aperture along the spatial
and dispersion axes in the two dimensional image.  The center along
the dispersion is usually defined as the middle of the image.  The
rest of the aperture parameters are defined relative to the aperture
center making it easy to move apertures.
.le
.ls low, high
Pairs of numbers specifying the lower and upper limits of the
aperture relative to the center along the spatial and dispersion axes.
The lower limits are usually negative and the upper limits positive
but there is no actual restriction; i.e. the aperture can actually
be offset from the center position.  Currently the dispersion
aperture limits are such that the entire length of the image along the
dispersion axis is used.  In the future this definition can be
easily used for objective prism spectra.
.le
.ls curve, axis
An IRAF "curfit" function specifying a shift to be added to the center
position along the spatial axis, given by the axis parameter which is
the complement of the dispersion axis parameter \fIdispaxis\fR, as a
function of the dispersion coordinate.  This trace 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 definition parameters.  For the "average" background subtraction
option only the set of background sample regions (defined relative to
the aperture center) are used.  For the "fit" option the parameters
are those used by the \fBicfit\fR package for fitting a function to
the points in the background sample regions.
.le

This information as well as the image (or database entry) name are stored
in a text file, with name given by the prefix "ap" followed by the entry
name, in the database directory.  An example with the special entry  name
"last", stored in the file "database$aplast", is given below. The "begin"
line marks the beginning of an aperture definition.


.ce
Sample Aperture Database Entry

.nf
# Fri 17:43:41 03-Aug-90
begin	aperture last 1 70.74564 256.
	image	last
	aperture	1
	beam	1
	center	70.74564 256.
	low	-5. -255.
	high	5. 256.
	background
		xmin -100.
		xmax 100.
		function chebyshev
		order 1
		sample -10:-6,6:10
		naverage -3
		niterate 0
		low_reject 3.
		high_reject 3.
		grow 0.
	axis	1
	curve	5
		2.
		1.
		1.
		512.
		0.
.fi

There are a number of logical functions which may be performed to
create, modify, and use the aperture definitions.  These functions
are:
.ls o
Automatically find a specified number of spectra and assign default
apertures.  Apertures may also be inherited from another image or
defined using an interactive graphical interface called the \fIaperture
editor\fR.
.le
.ls o
Recenter apertures on the image spectrum profiles.
.le
.ls o
Resize apertures based on spectrum profile width.
.le
.ls o
Interactively define or adjust aperture definitions using a graphical
interface called the \fIaperture editor\fR.  All function may also
be performed from this editor and, so, provides an alternative
method of processing and extracting spectra.
.le
.ls o
Trace the positions of spectra profiles from a starting image line
or column to other image lines or columns and fit a smooth function.
The trace function is used to shift the center of the apertures
at each dispersion point in the image.
.le
.ls o
Extract the flux in the apertures into one dimensional spectra in various
formats.  This includes possible background subtraction, variance
weighting, and bad pixel rejection.
.le

The package is logically organized around these functions.  Each
function has a task devoted to it.  The description of the parameters
and algorithms for each function are organized according to these
tasks; namely under the help topics \fBapdefault, apfind, aprecenter,
apresize, apedit, aptrace\fR, and \fBapsum\fR.  However, each task has
parameters to allow selecting some or all of the other functions, hence
it is not necessary to use the individual tasks and often it is more
convenient to use just the extraction task for all operations.  It is
also possible to perform all the functions from within a graphical
interface called the aperture editor.  This is usually only used to
define and modify aperture definitions but it also has the capability
to trace spectra and extract them.

Each of the functions has many different options and parameters.  When
broken down into individual tasks the parameters are also sorted by
their function though there are then some mutual interdependencies.
This parameter decomposition was what was available prior to the
addition of the task \fBapall\fR.  This is the central task of the
package which performs any and all of the functions required for the
extraction of spectra and also collects all the parameters into one
parameter set.  It is recommended that \fBapall\fR be used because it
collects all the parameters in one place eliminating confusion over
where a particular parameter is defined.

In summary, the package consists of a number of logical functions which
are documented by the individual tasks named for that function, but the
functions are also integrated into each task and the aperture editor to
providing many different ways for the user to choose to perform the
functions.

The package menu and help summary is shown below.


.ce
The APEXTRACT Package Tasks

.nf
     apall        apedit       apflatten    aprecenter   apsum
     apdefault    apfind       apmask       apresize     aptrace
     apdemos      apfit        apnormalize  apscatter

          apall - Extract 1D spectra (all parameters in one task)
      apdefault - Set the default aperture parameters and apidtable
        apdemos - Various tutorial demonstrations
         apedit - Edit apertures interactively
	 apfind - Automatically find spectra and define apertures
	  apfit - Fit 2D spectra and output the fit, difference,
		  or ratio
      apflatten - Remove overall spectral and profile shapes from
		  flat fields
         apmask - Create and IRAF pixel list mask of the apertures
    apnormalize - Normalize 2D apertures by 1D functions
     aprecenter - Recenter apertures
       apresize - Resize apertures
      apscatter - Fit and subtract scattered light
          apsum - Extract 1D spectra
	aptrace - Trace positions of spectra

		Additional topics

   apbackground - Background subtraction algorithms
      apextract - Package parameters and general description of
		  package
     approfiles - Profile determination algorithms
     apvariance - Extractions, variance weighting, cleaning, and
		  noise model
.fi

The extracted spectra are recorded in one, two, or three dimensional
images depending on the \fIformat\fR and \fIextras\fR parameters.  If
the \fIextras\fR parameter is set to yes the formats are three
dimensional with each plane in the third dimension containing
associated information for the spectra in the first plane.  See
\fBapsum\fR for further details.  When \fIextras\fR=no only the
extracted spectra are output.

If the format parameter is "onedspec" the output extractions are one
dimensional images with names formed from an output rootname and an
aperture number extension; i.e. root.0001 for aperture 1.  There will
be as many output images as there are apertures for each input image,
all with the same output rootname but with different aperture
extensions.  This format is provided to be compatible with the original
format used by the \fBonedspec\fR package.

If the format parameter is "echelle" or "multispec" the output aperture
extractions are put into a two dimensional image with a name formed from
the output rootname and the extension ".ec" or ".ms".  Each line in
the output image corresponds to one aperture.  Thus in this format
there is one output image for each input image.  These are the preferred
output formats for reasons of compactness, ease of handling, and efficiency.
These formats are compatible with the \fBonedspec\fR, \fBechelle\fR, and
\fBmsred\fR packages.  The format is a standard IRAF image with
specialized image header keywords.  Below is an example of the keywords.


.ce
MULTISPEC/ECHELLE Format Image Header Keywords

.nf
    ap> imhead test.ms
    test.ms[512,2,4][real]: Title
	BANDID1 = 'spectrum - background fit, weights variance, clean yes'
	BANDID2 = 'spectrum - background fit, weights none, clean no'
	BANDID3 = 'background - background fit'
	BANDID4 = 'sigma - background fit, weights variance, clean yes'
	APNUM1  = '1 1 87.11 94.79'
	APNUM2  = '2 1 107.11 114.79'
	APID1   = 'Galaxy center'
	APID2   = 'Galaxy edge'
	WCSDIM  =                    3
	CTYPE1  = 'PIXEL   '
	CTYPE2  = 'LINEAR  '
	CTYPE3  = 'LINEAR  '
	CRVAL1  =                   1.
	CRPIX1  =                   1.
	CD1_1   =                   1.
	CD2_2   =                   1.
	CD3_3   =                   1.
	LTM1_1  =                   1.
	LTM2_2  =                   1.
	LTM3_3  =                   1.
	WAT0_001= 'system=equispec
	WAT1_001= 'wtype=linear label=Pixel
	WAT2_001= 'wtype=linear
	WAT3_001= 'wtype=linear
.fi

The BANDIDn keywords describe the various elements of the 3rd dimension.
Except for the first one the other bands only occur when \fIextras\fR is
yes and when sky subtraction and/or variance and cleaning are done.  The
relation between the line and the aperture numbers is given by the header
parameters APNUMn where n is the line and the value gives extraction and
coordinate information about the spectrum.  The first field is the aperture
number and the second is the beam number.  After dispersion calibration of
echelle format spectra the beam number becomes the order number.  The other
two numbers are the aperture limits at the line or column at which the
aperture was defined.
The APID keywords provide an optional title for each extracted spectrum
in addition to the overall image title.

The rest of the keywords are part of the IRAF World Coordinate System
(WCS).  If the image being extracted has been previously calibrated
(say with \fBlongslit.transform\fR) then the dispersion coordinates
will be carried in CRVAL1 and CD1_1.

There is one other value for the format parameter, "strip".  This produces
two dimensional extractions rather than one dimensional extractions.
Each aperture is output to a two dimensional image with a width set by the
nearest integer which includes the aperture.  The output names are
generated in the same way as for "onedspec" format.  The aperture is
shifted by interpolation so that it is exactly aligned with the image
columns.  If not variance weighting the actual image data is output
with appropriate shifting while for variance weighting and/or cleaning
the profile model is output (similar to \fBapfit\fR except for being
aligned).  This format is that provided in the previous version of
the package by the \fBapstrip\fR task.  It is now relegated to a
special case.
.endhelp
