apsum input
input
List of input images containing apertures to be extracted.
output =
List of output rootnames for the 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 rootname.
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.
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.
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.
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 = no
Recenter the apertures?
resize = no
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 = no
Extract the raw spectrum (if variance weighting is used), the sky spectrum
(if background subtraction is used), and variance 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 = 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. A line of
INDEF selects the middle of the image along the dispersion axis.
A positive nsum takes a sum while a negative value selects a median
except that tracing always uses a sum.
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.
weights = none
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?
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.
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 = 3., usigma = 3.
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.
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.
When this operation is performed from the task apall all parameters except the package parameters are included in that task.
For each image in the input image list, the two dimensional spectra are extracted to one dimensional spectra by summing the pixels across the dispersion axis at each wavelength along the dispersion axis within a set of defined apertures. The extraction apertures consist of an aperture number, a beam number, a title, a center, limits relative to the center, a curve describing shifts of the aperture center across the dispersion axis as a function of the wavelength, and parameters for background fitting and subtraction. See apextract for a more detailed discussion of the aperture structures.
The extracted spectra are recorded in one, two, or three dimensional images depending on the format and extras parameters. The output image rootnames are specified by the output list. If the list is empty or shorter than the input list the missing names are taken to be the same as the input image names. Because the rootnames have extensions added it is common to default to the input names in order to preserve a naming relation between the input two dimensional spectra and the extracted spectra.
When the parameter extras=no only the extracted spectra are output. If the format parameter format="onedspec" the output aperture extractions are one dimensional images with names formed from the output rootname and a numeric extension given by the aperture number; i.e. root.0001 for aperture 1. Note that there will be as many output images as there are apertures for each input image, all with the same output rootname but with different aperture extensions. The aperture beam number associated with each aperture is recorded in the output image under the keyword BEAM-NUM. The output image name format and the BEAM-NUM entry in the image are chosen to be compatible with the onedspec package.
If the format parameter is "echelle" or "multispec" the output aperture extractions are put into a two dimensional image with a name formed from the output rootname and the extension ".ech" or ".ms". Each line in the output image corresponds to one aperture. Thus in this format there is one output image for each input image. These are the preferred output formats for reasons of compactness and ease of handling. These formats are compatible with the onedspec, echelle, and msred packages. The relation between the line and the aperture numbers is given by the header parameter APNUMn where n is the line and the value is the aperture number and other numeric information.
If the extras parameter is set to yes then the above formats become three dimensional. Each plane in the third dimension contains associated information for the spectra in the first plane. If variance weighted extractions are done the unweighted spectra are recorded. If background subtraction is done the background spectra are recorded. If variance weighted extractions are done the sigma spectrum (the estimated sigma of each spectrum pixel based on the individual variances of the pixels summed) is recorded. The order of the additional information is as given above. For example, an unweighted extraction with background subtraction will have one additional plane containing the sky spectra while a variance weighted extraction with background subtractions will have the variance weighted spectra, the unweighted spectra, the background spectra, and the sigma spectra in consecutive planes.
Aperture definitions may be inherited from those of other images by specifying a reference image with the references parameter. Images in the reference list are matched with those in the input list in order. If the reference image list is shorter than the number of input images, the last reference image is used for all remaining input images. Thus, a single reference image may be given for all the input images or different reference images may be given for each input image. The special reference name "last" may be used to select the last set apertures used in any of the apextract tasks.
If an aperture reference image is not specified or no apertures are found for the specified reference image, previously defined apertures for the input image are sought in the aperture database. Note that reference apertures supersede apertures for the input image. If no apertures are defined they may be created automatically, the find option, or interactively in the aperture editor, if the interactive and edit options are set.
The functions performed by the task are selected by a set of flag parameters. The functions are an automatic spectrum finding and aperture defining algorithm (see apfind) which is ignored if apertures are already defined, automatic recentering and resizing algorithms (see aprecenter and apresize), an interactive aperture editing function (see apedit), a spectrum position tracing and trace function fit (see aptrace), and the main function of this task, one dimensional spectrum extraction.
Each function selection will produce a query for each input spectrum if the interactive parameter is set. The queries are answered by "yes", "no", "YES", or "NO", where the upper case responses suppress the query for following images. There are other queries associated with tracing and extracted spectrum review which first ask whether the operation is to be done interactively and, if yes, lead to queries for each aperture. The cursor keys available during spectrum review are minimal, only the CURSOR MODE keys for expanding and adjusting the graph are available and the quit key 'q'. If the interactive parameter is not set then aperture editing, interactive trace fitting, and spectrum review are ignored.
Background sky subtraction is done during the extraction based on background regions and parameters defined by the default parameters or changed during the interactive setting of the apertures. The background subtraction options are to do no background subtraction, subtract the average, median, or minimum of the pixels in the background regions, or to fit a function and subtract the function from under the extracted object pixels. The background regions are specified in pixels from the aperture center and follow changes in center of the spectrum along the dispersion. The syntax is colon separated ranges with multiple ranges separated by a comma or space. The background fitting uses the icfit routines which include medians, iterative rejection of deviant points, and a choice of function types and orders. Note that it is important to use a method which rejects cosmic rays such as using either medians over all the background regions (background = "median") or median samples during fitting (b_naverage < -1). The background subtraction algorithm and options are described in greater detail in apsum and apbackground.
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 spectra features. This is most appropriate when the sky region is limited due to small slit length. The smoothing length is specified by the parameter skybox.
For a more extended discussion about the background determination see apbackground.
The aperture extractions consists of summing all the background subtracted pixel values at a given wavelength within the aperture limits. The aperture limits form a fixed width aperture but the center varies smoothly to follow changes in the position of the spectrum across the dispersion axis. At the ends of the aperture partial pixels are used.
The pixels in the sum may be weighted as specified by the weights parameter. If the weights parameter is "none" and the clean parameter is no then the simple sum of the pixels (with fractional endpoints) is extracted. If the weights parameter is "variance" or if the clean parameter is yes the pixels are weighted by their estimated variance derived from a noise model based on the gain and readnoise parameters and a smooth profile function. Normally the profile function is determined from the data being extracted. However, one may substitute a "profile" image as specified by the profiles parameter for computing the profile. This requires that the profile image have spectra of identical position and profile as the image being extracted. For example, this would likely be the case with fiber spectra and an off-telescope spectrograph and a strong flat field or object spectrum could be used for weak spectra. Note that experience has shown that even for very weak spectra there is little improvement with using a separate profile image but the user is free to experiment.
When the clean parameter is set pixels deviating by more than a specified number of sigma from the profile function are excluded from the variance weighted sum. Note that the clean parameter always selects variance weights. For a more complete discussion of the extraction sums, variance weighting, cleaning, the noise model, and profile function determination see apvariance and approfiles.
1. To simply extract the spectra from a multislit observation:
cl> apsum multislit1
The positions of the slits are defined using either automatic finding or with the aperture editor. The positions of the slits are traced if necessary and then the apertures are extracted to the image "multspec.ms". The steps of defining the slit positions and tracing can be done as part of this command or previously using the other tasks in the apextract package.
V2.11
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.
apbackground, apvariance, approfile, , apdefault, apfind, aprecenter, apresize, apedit, aptrace, apall,