From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 noao/twodspec/apextract/doc/apextract.hlp | 365 ++++++++++++++++++++++++++++++
 1 file changed, 365 insertions(+)
 create mode 100644 noao/twodspec/apextract/doc/apextract.hlp

(limited to 'noao/twodspec/apextract/doc/apextract.hlp')

diff --git a/noao/twodspec/apextract/doc/apextract.hlp b/noao/twodspec/apextract/doc/apextract.hlp
new file mode 100644
index 00000000..401d93e7
--- /dev/null
+++ b/noao/twodspec/apextract/doc/apextract.hlp
@@ -0,0 +1,365 @@
+.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
-- 
cgit 

