diff options
Diffstat (limited to 'noao/twodspec/apextract/doc/apscatter.hlp')
| -rw-r--r-- | noao/twodspec/apextract/doc/apscatter.hlp | 253 |
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 |