diff options
Diffstat (limited to 'noao/twodspec/apextract/doc/apsum.hlp')
| -rw-r--r-- | noao/twodspec/apextract/doc/apsum.hlp | 402 |
1 files changed, 402 insertions, 0 deletions
diff --git a/noao/twodspec/apextract/doc/apsum.hlp b/noao/twodspec/apextract/doc/apsum.hlp new file mode 100644 index 00000000..6fa7ad0e --- /dev/null +++ b/noao/twodspec/apextract/doc/apsum.hlp @@ -0,0 +1,402 @@ +.help apsum Sep96 noao.twodspec.apextract +.ih +NAME +apsum -- Extract one dimensional sums across the apertures +.ih +USAGE +apsum input +.ih +PARAMETERS +.ls input +List of input images containing apertures to be extracted. +.le +.ls 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. +.le +.ls 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". +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le + +.ls 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. +.le +.ls 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. +.le +.ls recenter = no +Recenter the apertures? +.le +.ls resize = no +Resize the apertures? +.le +.ls edit = yes +Edit the apertures? The \fIinteractive\fR parameter must also be yes. +.le +.ls trace = yes +Trace the apertures? +.le +.ls fittrace = yes +Interactively fit the traced positions by a function? The \fIinteractive\fR +parameter must also be yes. +.le +.ls extract = yes +Extract the one dimensional aperture sums? +.le +.ls 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. +.le +.ls review = yes +Review the extracted spectra? The \fIinteractive\fR parameter must also be +yes. +.le + +.ls 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. +.le + +.ls 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. +.le +.ls weights = "none" +Type of extraction weighting. Note that if the \fIclean\fR parameter is +set then the weights used are "variance" regardless of the weights +specified by this parameter. The choices are: +.ls "none" +The pixels are summed without weights except for partial pixels at the +ends. +.le +.ls "variance" +The extraction is weighted by the variance based on the data values +and a poisson/ccd model using the \fIgain\fR and \fIreadnoise\fR +parameters. +.le +.le +.ls 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 \fBapprofile\fR). +.le +.ls clean = no +Detect and replace deviant pixels? +.le +.ls 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. +.le +.ls 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 \fIextras\fR parameter, flags wavelengths with +saturated pixels with a negative sigma. +.le +.ls 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. +.le +.ls 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. +.le +.ls lsigma = 4., usigma = 4. +Lower and upper rejection thresholds, given as a number of times the +estimated sigma of a pixel, for cleaning. +.le +.ls 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. +.le +.ih +ADDITIONAL PARAMETERS +I/O parameters and the default dispersion axis are taken from the +package parameters, the default aperture parameters from +\fBapdefault\fR, automatic aperture finding parameters from +\fBapfind\fR, recentering parameters from \fBaprecenter\fR, resizing +parameters from \fBapresize\fR, parameters used for centering and +editing the apertures from \fBapedit\fR, and tracing parameters from +\fBaptrace\fR. + +When this operation is performed from the task \fBapall\fR all +parameters except the package parameters are included in that task. +.ih +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 \fBapextract\fR for a more +detailed discussion of the aperture structures. + +The extracted spectra are recorded in one, two, or three dimensional +images depending on the \fIformat\fR and \fIextras\fR parameters. The +output image rootnames are specified by the \fIoutput\fR 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 \fIextras\fR=no only the extracted spectra are +output. If the format parameter \fIformat\fR="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 \fBonedspec\fR 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 \fBonedspec\fR, \fBechelle\fR, and +\fBmsred\fR 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 \fIextras\fR 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 \fBreferences\fR 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 \fBapextract\fR 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 \fIfind\fR +option, or interactively in the aperture editor, if the +\fIinteractive\fR and \fIedit\fR 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 \fBapfind\fR) which is ignored if +apertures are already defined, automatic recentering and resizing +algorithms (see \fBaprecenter\fR and \fBapresize\fR), an interactive +aperture editing function (see \fBapedit\fR), a spectrum position tracing +and trace function fit (see \fBaptrace\fR), and the main function of +this task, one dimensional spectrum extraction. + +Each function selection will produce a query for each input spectrum if +the \fIinteractive\fR 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 \fIinteractive\fR +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 \fBicfit\fR +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 (\fIbackground\fR = "median") or median samples during +fitting (\fIb_naverage\fR < -1). The background subtraction algorithm and +options are described in greater detail in \fBapsum\fR and +\fBapbackground\fR. + +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 \fIskybox\fR. + +For a more extended discussion about the background determination see +\fBapbackground\fR. + +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 \fIweights\fR +parameter. If the weights parameter is "none" and the \fIclean\fR +parameter is no then the simple sum of the pixels (with fractional +endpoints) is extracted. If the weights parameter is "variance" or if +the \fBclean\fR parameter is yes the pixels are weighted by their +estimated variance derived from a noise model based on the \fIgain\fR +and \fIreadnoise\fR 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 +\fIprofiles\fR 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 \fIclean\fR 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 \fIclean\fR 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 \fBapvariance\fR and \fBapprofiles\fR. +.ih +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 \fBapextract\fR package. +.ih +REVISIONS +.ls 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. +.le +.ih +SEE ALSO +apbackground, apvariance, approfile, +apdefault, apfind, aprecenter, apresize, apedit, aptrace, apall +.endhelp |