path: root/noao/twodspec/apextract/doc/apscatter.hlp

.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