apscatter: Fit and subtract scattered light

Package: specred

Usage

apscatter input output

Parameters

input: List of input images in which to determine and subtract scattered light.

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.

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".

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.

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.

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.

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.

recenter = yes: Recenter the apertures?

resize = yes: Resize the apertures?

edit = yes: Edit the apertures? The interactive parameter must also be yes.

trace = yes: Trace the apertures?

fittrace = yes: Interactively fit the traced positions by a function? The interactive parameter must also be yes.

subtract = yes: Subtract the scattered light from the input images?

smooth = yes: Smooth the cross-dispersion fits along the dispersion?

fitscatter = yes: Fit the scattered light across the dispersion interactively? The interactive parameter must also be yes.

fitsmooth = yes: Smooth the cross-dispersion fits along the dispersion? The interactive parameter must also be yes.

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.

buffer = 1.: Buffer distance from the aperture edges to be excluded in selecting the scattered light pixels to be used.

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.

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.

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 apscat1 and apscat2. The parameters may be examined and edited by either typing their names or by typing ":e" when editing the main parameter set with eparam 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.

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").

order = 1 (apscat1 and apscat2): Number of polynomial terms or number of spline pieces for the fitting function.

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 ":".

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.

niterate = 5 (apscat1), niterate = 0 (apscat2): Number of sigma clipping rejection iterations.

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.

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.

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.

Additional parameters

I/O parameters and the default dispersion axis are taken from the package parameters, the default aperture parameters from apdefault, automatic aperture finding parameters from apfind, recentering parameters from aprecenter, resizing parameters from apresize, parameters used for centering and editing the apertures from apedit, and tracing parameters from aptrace.

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 icfit 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 icfit 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 icfit 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 apfind), automatically recentering or resizing the apertures (see aprecenter and apresize), interactively editing the apertures (see apedit), and tracing the positions of the spectra as a function of dispersion position (see aptrace). Though unlikely, the actual scattered light subtraction operation may be suppressed when the parameter subtract is no. If the scattered light determination and fitting is done interactively (the interactive 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 apscat1 for the first fits across the dispersion and apscat2 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.

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.

Revisions

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".