apsum: Extract 1D spectra

Package: argus

Usage

apsum input

Parameters

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.

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.

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

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.

Description

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.

Examples

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

Revisions

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