| apsum | noao.twodspec.apextract | apsum |
apsum -- Extract one dimensional sums across the apertures
apsum input
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.
The "nsubaps" parameter now allows onedspec and echelle output formats. The echelle format is appropriate for treating each subaperture as a full echelle extraction.
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
