Initial commit

1 files changed, 253 insertions, 0 deletions

diff --git a/noao/twodspec/apextract/doc/apscatter.hlp b/noao/twodspec/apextract/doc/apscatter.hlp
new file mode 100644
index 00000000..902c57a8
--- /dev/null
+++ b/noao/twodspec/apextract/doc/apscatter.hlp
@@ -0,0 +1,253 @@
+.help apscatter Sep96 noao.twodspec.apextract
+.ih
+NAME
+apscatter -- Fit and subtract scattered light
+.ih
+USAGE
+apscatter input output
+.ih
+PARAMETERS
+.ls input
+List of input images in which to determine and subtract scattered light.
+.le
+.ls output
+List of output scattered light subtracted images.  If no output images
+are specified or the end of the output list is reached before the end 
+of the input list then the output image will overwrite the input image.
+.le
+.ls apertures = ""
+Apertures to recenter, resize, trace, and extract.  All apertures are
+used to define the scattered light region.  This only applies
+to apertures read from the input or reference database.  Any new
+apertures defined with the automatic finding algorithm or interactively
+are always selected.  The syntax is a list comma separated ranges
+where a range can be a single aperture number, a hyphen separated
+range of aperture numbers, or a range with a step specified by "x<step>";
+for example, "1,3-5,9-12x2".
+.le
+.ls scatter = ""
+List of scattered light images.  This is the scattered light subtracted
+from the input image.  If no list is given or the end of the list is
+reached before the end of the input list then no scattered light image
+is created.
+.le
+.ls references = ""
+List of reference images to be used to define apertures for the input
+images.  When a reference image is given it supersedes apertures
+previously defined for the input image. The list may be null, "", or
+any number of images less than or equal to the list of input images.
+There are three special words which may be used in place of an image
+name.  The word "last" refers to the last set of apertures written to
+the database.  The word "OLD" requires that an entry exist
+and the word "NEW" requires that the entry not exist for each input image.
+.le
+
+.ls interactive = yes
+Run this task interactively?  If the task is not run interactively then
+all user queries are suppressed and interactive aperture editing, trace
+fitting, and interactive scattered light fitting are disabled.
+.le
+.ls find = yes
+Find the spectra and define apertures automatically?  In order for
+spectra to be found automatically there must be no apertures for the
+input image or reference image defined in the database.
+.le
+.ls recenter = yes
+Recenter the apertures?
+.le
+.ls resize = yes
+Resize the apertures?
+.le
+.ls edit = yes
+Edit the apertures?  The \fIinteractive\fR parameter must also be yes.
+.le
+.ls trace = yes
+Trace the apertures?
+.le
+.ls fittrace = yes
+Interactively fit the traced positions by a function?  The \fIinteractive\fR
+parameter must also be yes.
+.le
+.ls subtract = yes
+Subtract the scattered light from the input images?
+.le
+.ls smooth = yes
+Smooth the cross-dispersion fits along the dispersion?
+.le
+.ls fitscatter = yes
+Fit the scattered light across the dispersion interactively?
+The \fIinteractive\fR parameter must also be yes.
+.le
+.ls fitsmooth = yes
+Smooth the cross-dispersion fits along the dispersion?
+The \fIinteractive\fR parameter must also be yes.
+.le
+
+.ls line = INDEF, nsum = 1
+The dispersion line (line or column perpendicular to the dispersion
+axis) and number of adjacent lines (half before and half after unless
+at the end of the image) used in finding, recentering, resizing,
+and editing operations.  For tracing this is the starting line and
+the same number of lines are summed at each tracing point.  This is
+also the initial line for interactive fitting of the scattered light.
+A line of INDEF selects the middle of the image along the dispersion
+axis.  A positive nsum takes a sum and a negative value selects a
+median except that tracing always uses a sum.
+.le
+
+.ls buffer = 1.
+Buffer distance from the aperture edges to be excluded in selecting the
+scattered light pixels to be used.
+.le
+.ls apscat1 = ""
+Fitting parameters across the dispersion.  This references an additional
+set of parameters for the ICFIT package.  The default is the "apscat1"
+parameter set.  See below for additional information.
+.le
+.ls apscat2 = ""
+Fitting parameters along the dispersion.  This references an additional
+set of parameters for the ICFIT package.  The default is the "apscat2"
+parameter set.  See below for additional information.
+.le
+.ih
+ICFIT PARAMETERS FOR FITTING THE SCATTERED LIGHT
+There are two additional parameter sets which define the parameters used
+for fitting the scattered light across the dispersion and along the
+dispersion.  The default parameter sets are \fBapscat1\fR and \fBapscat2\fR.
+The parameters may be examined and edited by either typing their names
+or by typing ":e" when editing the main parameter set with \fBeparam\fR
+and with the cursor pointing at the appropriate parameter set name.
+These parameters are used by the ICFIT package and a further
+description may be found there.
+
+.ls function = "spline3" (apscat1 and apscat2)
+Fitting function for the scattered light across and along the dispersion.
+The choices are "legendre" polynomial, "chebyshev" polynomial,
+linear spline ("spline1"), and cubic spline ("spline3").
+.le
+.ls order = 1 (apscat1 and apscat2)
+Number of polynomial terms or number of spline pieces for the fitting function.
+.le
+.ls sample = "*" (apscat1 and apscat2)
+Sample regions for fitting points.  Intervals are separated by "," and an
+interval may be one point or a range separated by ":".
+.le
+.ls naverage = 1 (apscat1 and apscat2)
+Number of points within a sample interval to be subaveraged or submedianed to
+form fitting points.  Positive values are for averages and negative points
+for medians.
+.le
+.ls niterate = 5 (apscat1), niterate = 0 (apscat2)
+Number of sigma clipping rejection iterations.
+.le
+.ls low_reject = 5. (apscat1) , low_reject = 3. (apscat2)
+Lower sigma clipping rejection threshold in units of sigma determined
+from the RMS sigma of the data to the fit.
+.le
+.ls high_reject = 2. (apscat1) , high_reject = 3. (apscat2)
+High sigma clipping rejection threshold in units of sigma determined
+from the RMS sigma of the data to the fit.
+.le
+.ls grow = 0. (apscat1 and apscat2)
+Growing radius for rejected points (in pixels).  That is, any rejected point
+also rejects other points within this distance of the rejected point.
+.le
+.ih
+ADDITIONAL PARAMETERS
+I/O parameters and the default dispersion axis are taken from the
+package parameters, the default aperture parameters from
+\fBapdefault\fR, automatic aperture finding parameters from
+\fBapfind\fR, recentering parameters from \fBaprecenter\fR, resizing
+parameters from \fBapresize\fR, parameters used for centering and
+editing the apertures from \fBapedit\fR, and tracing parameters from
+\fBaptrace\fR.
+.ih
+DESCRIPTION
+The scattered light outside the apertures defining the two dimensional
+spectra is extracted, smoothed, and subtracted from each input image.  The
+approach is to first select the pixels outside the defined apertures
+and outside a buffer distance from the edge of any aperture at each
+point along the dispersion independently.  A one dimensional function
+is fit using the \fBicfit\fR package.  This fitting uses an iterative
+algorithm to further reject high values and thus fit the minima between
+the spectra.  (This even works reasonably well if no apertures are
+defined).  Because each fit is done independently the scattered light
+thus determined will not be smooth along the dispersion.  If desired
+each line along the dispersion in the scattered light surface may then
+be smoothed by again fitting a one dimensional function using the
+\fBicfit\fR package.  The final scattered light surface is then
+subtracted from the input image to form the output image.  The
+scattered light surface may be output if desired.
+
+The reason for using two one dimensional fits as opposed to a surface fit
+is that the actual shape of the scattered light is often not easily modeled
+by a simple two dimensional function.  Also the one dimensional function
+fitting offers more flexibility in defining functions and options as
+provided by the \fBicfit\fR package.
+
+The organization of the task is like the other tasks in the package
+which has options for defining apertures using a reference image,
+defining apertures through an automatic finding algorithm (see
+\fBapfind\fR), automatically recentering or resizing the apertures (see
+\fBaprecenter\fR and \fBapresize\fR), interactively editing the
+apertures (see \fBapedit\fR), and tracing the positions of the spectra
+as a function of dispersion position (see \fBaptrace\fR).  Though
+unlikely, the actual scattered light subtraction operation may be
+suppressed when the parameter \fIsubtract\fR is no.  If the scattered
+light determination and fitting is done interactively (the
+\fIinteractive\fR parameter set to yes) then the user is queried
+whether or not to do the fitting and subtraction for each image.  The
+responses are "yes", "no", "YES", or "NO", where the upper case
+queries suppress this query for the following images.  When the task is
+interactive there are further queries for each step of the operation
+which may also be answered both individually or collectively for all
+other input images using the four responses.
+
+When the scattered light operation is done interactively the user may
+set the fitting parameters for the scattered light functions both
+across and along the dispersion interactively.  Initially the central
+line or column is used but after exiting (with 'q') a prompt is given
+for selecting additional lines or columns and for changing the buffer
+distance.  Note that the point of the interactive stage is to set the
+fitting parameters.  When the entire image is finally fit the last set
+of fitting parameters are used for all lines or columns.
+
+The default fitting parameters are organized as separate parameter sets
+called \fBapscat1\fR for the first fits across the dispersion and
+\fBapscat2\fR for the second smoothing fits along the dispersion.
+Changes to these parameters made interactively during execution of
+this task are updated in the parameter sets.  The general idea for
+these parameters is that when fitting the pixels from between the
+apertures the iteration and rejection thresholds are set to eliminate
+high values while for smoothing along the dispersion a simple smooth
+function is all that is required.
+.ih
+EXAMPLES
+1.  To subtract the scattered light from a set of images to form a
+new set of images:
+
+	cl> apscatter raw* %raw%new%*
+
+This example uses a substitution in the names from raw to new.
+By default this would be done interactively
+
+2.  To subtract the scattered light in place and save the scattered light
+images:
+
+	cl> apscatter im* "" scatter="s//im*" ref=im1 interact-
+
+The prefix s is added to the original names for the scattered light.
+This operation is done noninteractively using a reference spectrum
+to define the apertures.
+.ih
+REVISIONS
+.ls APSCATTER V2.11
+The "apertures" parameter can be used to select apertures for resizing,
+recentering, tracing, and extraction.  This parameter name was previously
+used for selecting apertures in the recentering algorithm.  The new
+parameter name for this is now "aprecenter".
+.le
+.ih
+SEE ALSO
+apfind, aprecenter, apresize,  apedit, aptrace, apsum, apmask, icfit
+.endhelp