apall: Extract 1D spectra (all parameters in one task)

Package: argus

Usage

apall input

Parameters

input: List of input images.

output = "": List of output root names for extracted spectra. If the null string is given or the end of the output list is reached before the end of the input list then the input image name is used as the output root name. This will not conflict with the input image since an aperture number extension is added for onedspec format, the extension ".ms" for multispec format, or the extension ".ec" for echelle format.

apertures = "": Apertures to recenter, resize, trace, and extract. 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".

format = "multispec" (onedspec|multispec|echelle|strip): Format for output extracted spectra. "Onedspec" format extracts each aperture to a separate image while "multispec" and "echelle" extract multiple apertures for the same image to a single output image. The "multispec" and "echelle" format selections differ only in the extension added. The "strip" format produces a separate 2D image in which each column or line along the dispersion axis is shifted to exactly align the aperture based on the trace information.

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. Input images without/with a database entry are skipped silently.

profiles = "": List of profile images for variance weighting or cleanning. If variance weighting or cleanning a profile of each aperture is computed from the input image unless a profile image is specified, in which case the profile is computed from the profile image. The profile image must have the same dimensions and dispersion and it is assumed that the spectra have the same position and profile shape as in the object spectra. Use of a profile image is generally not required even for faint input spectra but the option is available for those who wish to use it.

PROCESSING PARAMETERS

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 extraction review 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.

extract = yes: Extract the one dimensional aperture sums?

extras = yes: Extract the raw spectrum (if variance weighting is used), the sky spectrum (if background subtraction is used), and sigma spectrum (if variance weighting is used)? This information is extracted to the third dimension of the output image.

review = yes: Review the extracted spectra? The interactive parameter must also be yes.

line = INDEF, nsum = 10: 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. A line of INDEF selects the middle of the image along the dispersion axis. A positive nsum selects a sum of lines and a negative selects a median of lines.

DEFAULT APERTURE PARAMETERS

lower = -5., upper = 5.: Default lower and upper aperture limits relative to the aperture center. These limits are used for apertures found with apfind and when defining the first aperture in apedit.

apidtable = "": Aperture identification table. This may be either a text file or an image. A text file consisting of lines with an aperture number, beam number, and aperture title or identification. An image will contain the keywords SLFIBnnn with string value consisting of aperture number, beam number, optional right ascension and declination, and aperture title. This information is used to assign aperture information automatically in apfind and apedit.

DEFAULT BACKGROUND PARAMETERS

b_function = "chebyshev": Default background fitting function. The fitting function types are "chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and "spline3" cubic spline.

b_order = 1: Default background function order. The order refers to the number of terms in the polynomial functions or the number of spline pieces in the spline functions.

b_sample = "-10:-6,6:10": Default background sample. The sample is given by a set of colon separated ranges each separated by either whitespace or commas. The string "*" refers to all points. Note that the background coordinates are relative to the aperture center and not image pixel coordinates so the endpoints need not be integer.

b_naverage = -3: Default number of points to average or median. Positive numbers average that number of sequential points to form a fitting point. Negative numbers median that number, in absolute value, of sequential points. A value of 1 does no averaging and each data point is used in the fit.

b_niterate = 0: Default number of rejection iterations. If greater than zero the fit is used to detect deviant fitting points and reject them before repeating the fit. The number of iterations of this process is given by this parameter.

b_low_reject = 3., b_high_reject = 3.: Default background lower and upper rejection sigmas. If greater than zero points deviating from the fit below and above the fit by more than this number of times the sigma of the residuals are rejected before refitting.

b_grow = 0.: Default reject growing radius. Points within a distance given by this parameter of any rejected point are also rejected.

APERTURE CENTERING PARAMETERS

width = 5.: Width of spectrum profiles. This parameter is used for the profile centering algorithm in this and other tasks.

radius = 10.: The profile centering error radius for the centering algorithm.

threshold = 0.: Centering threshold for the centering algorithm. The range of pixel intensities near the initial centering position must exceed this threshold.

AUTOMATIC FINDING AND ORDERING PARAMETERS

nfind: Maximum number of apertures to be defined. This is a query parameter so the user is queried for a value except when given explicitly on the command line.

minsep = 5.: Minimum separation between spectra. Weaker spectra or noise within this distance of a stronger spectrum are rejected.

maxsep = 1000.: Maximum separation between adjacent spectra. This parameter is used to identify missing spectra in uniformly spaced spectra produced by fiber spectrographs. If two adjacent spectra exceed this separation then it is assumed that a spectrum is missing and the aperture identification assignments will be adjusted accordingly.

order = "increasing": When assigning aperture identifications order the spectra "increasing" or "decreasing" with increasing pixel position (left-to-right or right-to-left in a cross-section plot of the image).

RECENTERING PARAMETERS

aprecenter = "": List of apertures to be used in shift calculation.

npeaks = INDEF: Select the specified number of apertures with the highest peak values to be recentered. If the number is INDEF all apertures will be selected. If the value is less than 1 then the value is interpreted as a fraction of total number of apertures.

shift = yes: Use the average shift from recentering the apertures selected by the aprecenter parameter to apply to the apertures selected by the apertures parameter. The recentering is then a constant shift for all apertures.

RESIZING PARAMETERS

llimit = INDEF, ulimit = INDEF: Lower and upper aperture size limits. If the parameter ylevel is INDEF then these limits are assigned to all apertures. Otherwise these parameters are used as limits to the resizing operation. A value of INDEF places the aperture limits at the image edge (for the dispersion line used).

ylevel = 0.1: Data level at which to set aperture limits. If it is INDEF then the aperture limits are set at the values given by the parameters llimit and ulimit. If it is not INDEF then it is a fraction of the peak or an actual data level depending on the parameter peak. It may be relative to a local background or to zero depending on the parameter bkg.

peak = yes: Is the data level specified by ylevel a fraction of the peak?

bkg = yes: Subtract a simple background when interpreting the ylevel parameter. The background is a slope connecting the first inflection points away from the aperture center.

r_grow = 0.: Change the lower and upper aperture limits by this fractional amount. The factor is multiplied by each limit and the result added to limit.

avglimits = no: Apply the average lower and upper aperture limits to all apertures.

TRACING PARAMETERS

t_nsum = 10: Number of dispersion lines to be summed at each step along the dispersion.

t_step = 10: Step along the dispersion axis between determination of the spectrum positions.

t_nlost = 3: Number of consecutive steps in which the profile is lost before quitting the tracing in one direction. To force tracing to continue through regions of very low signal this parameter can be made large. Note, however, that noise may drag the trace away before it recovers.

t_function = "legendre": Default trace fitting function. The fitting function types are "chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and "spline3" cubic spline.

t_order = 2: Default trace function order. The order refers to the number of terms in the polynomial functions or the number of spline pieces in the spline functions.

t_sample = "*": Default fitting sample. The sample is given by a set of colon separated ranges each separated by either whitespace or commas. The string "*" refers to all points.

t_naverage = 1: Default number of points to average or median. Positive numbers average that number of sequential points to form a fitting point. Negative numbers median that number, in absolute value, of sequential points. A value of 1 does no averaging and each data point is used in the

t_niterate = 0: Default number of rejection iterations. If greater than zero the fit is used to detect deviant traced positions and reject them before repeating the fit. The number of iterations of this process is given by this parameter.

t_low_reject = 3., t_high_reject = 3.: Default lower and upper rejection sigma. If greater than zero traced points deviating from the fit below and above the fit by more than this number of times the sigma of the residuals are rejected before refitting.

t_grow = 0.: Default reject growing radius. Traced points within a distance given by this parameter of any rejected point are also rejected.

EXTRACTION PARAMETERS

background = "none" (none|average|median|minimum|fit): Type of background subtraction. The choices are "none" for no background subtraction, "average" to average the background within the background regions, "median" to use the median in the background regions, "minimum" to use the minimum in the background regions, or "fit" to fit across the dispersion using the background within the background regions. Note that the "average" option does not do any medianing or bad pixel checking, something which is recommended. The fitting option is slower than the other options and requires additional fitting parameter.

skybox = 1: Box car smoothing length for sky background when using background subtraction. Since the background noise is often the limiting factor for good extraction one may box car smooth the sky to improve the statistics in smooth background regions at the expense of distorting the subtraction near spectral features. This is most appropriate when the sky regions are limited due to a small slit length.

weights = "none" (none|variance)

Type of extraction weighting. Note that if the clean parameter is set then the weights used are "variance" regardless of the weights specified by this parameter. The choices are:

"none": The pixels are summed without weights except for partial pixels at the ends.

"variance": The extraction is weighted by the variance based on the data values and a poisson/ccd model using the gain and readnoise parameters.

pfit = "fit1d" (fit1d|fit2d): Profile fitting algorithm to use with variance weighting or cleaning. When determining a profile the two dimensional spectrum is divided by an estimate of the one dimensional spectrum to form a normalized two dimensional spectrum profile. This profile is then smoothed by fitting one dimensional functions, "fit1d", along the lines or columns most closely corresponding to the dispersion axis or a special two dimensional function, "fit2d", described by Marsh (see approfile).

clean = no: Detect and replace deviant pixels?

saturation = INDEF: Saturation or nonlinearity level in data units. During variance weighted extractions wavelength points having any pixels above this value are excluded from the profile determination and the sigma spectrum extraction output, if selected by the extras parameter, flags wavelengths with saturated pixels with a negative sigma.

readnoise = 0.: Read out noise in photons. This parameter defines the minimum noise sigma. It is defined in terms of photons (or electrons) and scales to the data values through the gain parameter. A image header keyword (case insensitive) may be specified to get the value from the image.

gain = 1: Detector gain or conversion factor between photons/electrons and data values. It is specified as the number of photons per data value. A image header keyword (case insensitive) may be specified to get the value from the image.

lsigma = 4., usigma = 4.: Lower and upper rejection thresholds, given as a number of times the estimated sigma of a pixel, for cleaning.

nsubaps = 1: During extraction it is possible to equally divide the apertures into this number of subapertures. For multispec format all subapertures will be in the same file with aperture numbers of 1000*(subap-1)+ap where subap is the subaperture (1 to nsubaps) and ap is the main aperture number. For echelle format there will be a separate echelle format image containing the same subaperture from each order. The name will have the subaperture number appended. For onedspec format each subaperture will be in a separate file with extensions and aperture numbers as in the multispec format.

Additional parameters

Dispersion axis and I/O parameters are taken from the package parameters.

Description

This task provides functions for defining, modifying, tracing, and extracting apertures from two dimensional spectra. The functions desired are selected using switch parameters. When the task is run interactively queries are made at each step allowing additional control of the operations performed on each input image.

The functions, in the order in which they are generally performed, are summarized below.

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 aperture editor.

o: Recenter selected reference apertures on the image spectrum profiles.

o: Resize the selected reference apertures based on spectrum profile width.

o: Interactively define or adjust aperture definitions using a graphical interface called the aperture editor. All function may also be performed from this editor and, so, provides an alternative method of processing and extracting spectra.

o: Trace the positions of the selected 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.

o: Extract the flux in the selected apertures into one dimensional spectra in various formats. This includes possible background subtraction, variance weighting, and bad pixel rejection.

Each of these functions has different options and parameters. In addition to selecting any of these functions in this task, they may also be selected using the aperture editor and as individual commands (which themselves allow selection of other functions). When broken down into individual tasks the parameters are also sorted by their function though there are then some mutual parameter interdependencies. This functional decomposition is what was available prior to the addition of the apall task. It is recommended that this task be used because it collects all the parameters in one place eliminating confusion over where a particular parameter is defined. However, documenting the various functions is better organized in terms of the separate descriptions given for each of the functions; namely under the help topics apdefault, apfind, aprecenter, apresize, apedit, aptrace, and apsum.

Examples

1. This example may be executed if desired. First we create an artificial spectrum with four spectra and a background. After it is created you can display or plot it. Next we define the dispersion axis and set the verbose flag to better illustrate what is happening. The task APALL is run with the default parameters except for background fitting and subtracting added. The text beginning with # are comments of things to try and do.

ap> artdata
ar> unlearn artdata
ar> mk1dspec apdemo1d nl=50
ar> mk2dspec apdemo2d model=STDIN
apdemo1d 1. gauss 3 0 20 .01
apdemo1d .8 gauss 3 0 40 .01
apdemo1d .6 gauss 3 0 60 .01
apdemo1d .4 gauss 3 0 80 .01
[EOF=Control D or Control Z]
ar> mknoise apdemo2d background=100. rdnoise=3. poisson+
ar> bye
# Display or plot the spectrum
ap> dispaxis=2; verbose=yes
ap> unlearn apall
ap> apall apdemo2d back=fit
Searching aperture database ...
Find apertures for apdemo2d?  (yes):
Finding apertures ...
Number of apertures to be found automatically (1): 4
Jul 31 16:55: FIND - 4 apertures found for apdemo2d.
Resize apertures for apdemo2d?  (yes):
Resizing apertures ...
Jul 31 16:55: RESIZE - 4 apertures resized for apdemo2d.
Edit apertures for apdemo2d?  (yes):
# Get a list of commands with '?'
# See all the parameters settings with :par
# Try deleting and marking a spectrum with 'd' and 'm'
# Look at the background fitting parameters with 'b' (exit with 'q')
# Exit with 'q'
Trace apertures for apdemo2d?  (yes):
Fit traced positions for apdemo2d interactively?  (yes):
Tracing apertures ...
Fit curve to aperture 1 of apdemo2d interactively  (yes):
# You can use ICFIT commands to adjust the fit.
Fit curve to aperture 2 of apdemo2d interactively  (yes): n
Fit curve to aperture 3 of apdemo2d interactively  (no):
Fit curve to aperture 4 of apdemo2d interactively  (no): y
Jul 31 16:56: TRACE - 4 apertures traced in apdemo2d.
Write apertures for apdemo2d to apdemosdb  (yes):
Jul 31 16:56: DATABASE - 4 apertures for apdemo2d written to database.
Extract aperture spectra for apdemo2d?  (yes):
Review extracted spectra from apdemo2d?  (yes):
Extracting apertures ...
Review extracted spectrum for aperture 1 from apdemo2d?  (yes):
# Type 'q' to quit
Jul 31 16:56: EXTRACT - Aperture 1 from apdemo2d --> apdemo2d.ms
Review extracted spectrum for aperture 2 from apdemo2d?  (yes): N
Jul 31 16:56: EXTRACT - Aperture 2 from apdemo2d --> apdemo2d.ms
Jul 31 16:56: EXTRACT - Aperture 3 from apdemo2d --> apdemo2d.ms
Jul 31 16:57: EXTRACT - Aperture 4 from apdemo2d --> apdemo2d.ms

2. To extract a series of similar spectra noninteractively using a reference for the aperture definitions, then recentering and resizing but not retracing:

ap> apall fib*.imh ref=flat inter- trace-

Note that the interactive flag automatically turns off the edit, fittrace, and review options and the reference image eliminates the find (find only occurs if there are no initial apertures).

Revisions

APALL 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". The aperture ID table information may now be contained in the image header under the keywords SLFIBnnn. The "nsubaps" parameter now allows onedspec and echelle output formats. The echelle format is appropriate for treating each subaperture as a full echelle extraction.

APALL V2.10.3: The dispersion axis parameter was moved to purely a package parameter. As a final step when computing a weighted/cleaned spectrum the total fluxes from the weighted spectrum and the simple unweighted spectrum (excluding any deviant and saturated pixels) are computed and a "bias" factor of the ratio of the two fluxes is multiplied into the weighted spectrum and the sigma estimate. This makes the total fluxes the same. In this version the bias factor is recorded in the logfile if one is kept. Also a check is made for unusual bias factors. If the two fluxes disagree by more than a factor of two a warning is given on the standard output and the logfile with the individual total fluxes as well as the bias factor. If the bias factor is negative a warning is also given and no bias factor is applied. In the previous version a negative (inverted) spectrum would result.