diff options
Diffstat (limited to 'noao/twodspec/apextract/doc/apextract.hlp')
| -rw-r--r-- | noao/twodspec/apextract/doc/apextract.hlp | 365 |
1 files changed, 365 insertions, 0 deletions
diff --git a/noao/twodspec/apextract/doc/apextract.hlp b/noao/twodspec/apextract/doc/apextract.hlp new file mode 100644 index 00000000..401d93e7 --- /dev/null +++ b/noao/twodspec/apextract/doc/apextract.hlp @@ -0,0 +1,365 @@ +.help package Feb94 noao.twodspec.apextract +.ih +NAME +apextract -- Identify, manipulate, and extract spectra in 2D images +.ih +USAGE +apextract +.ih +PARAMETERS +.ls dispaxis = 2 +Image axis along which the spectra dispersion run. The dispersion axis +is 1 when the dispersion is along lines so that spectra are horizontal +when displayed normally. The dispersion axis is 2 when the dispersion +is along columns so that spectra are vertical when displayed normally. +This parameter is superseded when the dispersion axis is defined in +the image header by the parameter DISPAXIS. +.le +.ls database = "database" +Database for storing aperture definitions. Currently the database is +a subdirectory of text files with prefix "ap" followed by the entry name, +usually the image name. +.le +.ls verbose = no +Print detailed processing and log information? The output is to the +standard output stream which is the user's terminal unless redirected. +.le +.ls logfile = "" +Text logfile of operations performed. If a file name is specified +log and history information produced by all the tasks in the package +is appended to the file. +.le +.ls plotfile = "" +Binary plot metacode file of aperture locations, traces, rejected points, +etc. If a file name is given metacode plots are appended. The contents +of the file may be manipulated with the tasks in the \fBplot\fR package. +The most common is \fBgkimosaic\fR. Special plotfile names may be used +to select only particular plots or plots not normally output. These are +debugall, debugfitspec, debugaps, debugspec, debugfits, debugtrace, +and debugclean which plot everything, the fitted spectrum, the apertures, +the extracted spectrum, profile fit plots, the trace, and the rejected +points during cleaned extraction. +.le +.ls version = "APEXTRACT V3.0: August 1990" +Version of the package. This is the third major version of the package. +.le +.ih +DESCRIPTION +The primary function of the \fBapextract\fR package is the extraction of +spectra from two dimensional formats to one dimensional formats. In +other words, the pixels at each wavelength are summed, possibly +subtracting a background or sky from other pixels at that wavelength, +to produce a vector of spectral fluxes as a function of wavelength. +It has become common to have many spectra in one two dimensional +image produced by instruments using echelles, fibers, and aperture +masks. Thus, the package provides many features for the efficient +extractions of multiple spectra as well as single spectra. There are +also some additional, special purpose tasks for modeling spectra +and using the aperture definitions, described below, +to create masks and modified flat field images. + +The package assumes that one of the image axes is the dispersion axis, +specified by the \fIdispaxis\fR package parameter or image header +parameter of the same name, and the other is the spatial axes. +This means that all pixels at the same column or line (the +orientation may be in either direction) are considered to be at the +same wavelength. Even if this is not exactly +true the resolution loss is generally quite small and the simplicity and +absence of interpolation problems justify this approach. The +alternatives are to rotate the image with \fBrotate\fR or use the more +complex \fBlongslit\fR package. Though extraction is strictly along +lines and columns the position of the spectrum along the spatial axis +is allowed to shift smoothly with wavelength. This accounts for small +misalignments and distortions. + +The two dimensional regions occupied by the spectra are defined by +digital apertures having a fixed width but with spatial position smoothly +varying with wavelength. The apertures have a number of attributes. +The aperture definitions are created and modified by the tasks in this +package and stored in a database specified by the parameter \fIdatabase\fR. +The database is currently a directory containing simple text files +in a human readable format. The elements of an aperture definition +are as follows. + + +.ce +Elements of an Aperture Definition +.ls aperture +An integer aperture identification number. The aperture number +must be unique within a set of apertures. The aperture number is +the primary means of referencing an aperture and the resulting +extracted spectra. The aperture numbers are part of the extracted +spectra image headers. The numbers may be any integer and in any order +but the most typical case is to have sequential numbers beginning +with 1. +.le +.ls beam +An integer beam number. The beam number need not be unique; i.e. +several apertures may have the same beam number. The beam numbers are +recorded in the image headers of the extracted spectra. The beam +number is often used to identify types of spectra such as object, +sky, arc, etc. +.le +.ls center +A pair of numbers specifying the center of the aperture along the spatial +and dispersion axes in the two dimensional image. The center along +the dispersion is usually defined as the middle of the image. The +rest of the aperture parameters are defined relative to the aperture +center making it easy to move apertures. +.le +.ls low, high +Pairs of numbers specifying the lower and upper limits of the +aperture relative to the center along the spatial and dispersion axes. +The lower limits are usually negative and the upper limits positive +but there is no actual restriction; i.e. the aperture can actually +be offset from the center position. Currently the dispersion +aperture limits are such that the entire length of the image along the +dispersion axis is used. In the future this definition can be +easily used for objective prism spectra. +.le +.ls curve, axis +An IRAF "curfit" function specifying a shift to be added to the center +position along the spatial axis, given by the axis parameter which is +the complement of the dispersion axis parameter \fIdispaxis\fR, as a +function of the dispersion coordinate. This trace function is one of +the standard IRAF \fBicfit\fR types; a legendre polynomial, a chebyshev +polynomial, a linear spline, or a cubic spline. +.le +.ls background +Background definition parameters. For the "average" background subtraction +option only the set of background sample regions (defined relative to +the aperture center) are used. For the "fit" option the parameters +are those used by the \fBicfit\fR package for fitting a function to +the points in the background sample regions. +.le + +This information as well as the image (or database entry) name are stored +in a text file, with name given by the prefix "ap" followed by the entry +name, in the database directory. An example with the special entry name +"last", stored in the file "database$aplast", is given below. The "begin" +line marks the beginning of an aperture definition. + + +.ce +Sample Aperture Database Entry + +.nf +# Fri 17:43:41 03-Aug-90 +begin aperture last 1 70.74564 256. + image last + aperture 1 + beam 1 + center 70.74564 256. + low -5. -255. + high 5. 256. + background + xmin -100. + xmax 100. + function chebyshev + order 1 + sample -10:-6,6:10 + naverage -3 + niterate 0 + low_reject 3. + high_reject 3. + grow 0. + axis 1 + curve 5 + 2. + 1. + 1. + 512. + 0. +.fi + +There are a number of logical functions which may be performed to +create, modify, and use the aperture definitions. These functions +are: +.ls 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 \fIaperture +editor\fR. +.le +.ls o +Recenter apertures on the image spectrum profiles. +.le +.ls o +Resize apertures based on spectrum profile width. +.le +.ls o +Interactively define or adjust aperture definitions using a graphical +interface called the \fIaperture editor\fR. All function may also +be performed from this editor and, so, provides an alternative +method of processing and extracting spectra. +.le +.ls o +Trace the positions of 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. +.le +.ls o +Extract the flux in the apertures into one dimensional spectra in various +formats. This includes possible background subtraction, variance +weighting, and bad pixel rejection. +.le + +The package is logically organized around these functions. Each +function has a task devoted to it. The description of the parameters +and algorithms for each function are organized according to these +tasks; namely under the help topics \fBapdefault, apfind, aprecenter, +apresize, apedit, aptrace\fR, and \fBapsum\fR. However, each task has +parameters to allow selecting some or all of the other functions, hence +it is not necessary to use the individual tasks and often it is more +convenient to use just the extraction task for all operations. It is +also possible to perform all the functions from within a graphical +interface called the aperture editor. This is usually only used to +define and modify aperture definitions but it also has the capability +to trace spectra and extract them. + +Each of the functions has many different options and parameters. When +broken down into individual tasks the parameters are also sorted by +their function though there are then some mutual interdependencies. +This parameter decomposition was what was available prior to the +addition of the task \fBapall\fR. This is the central task of the +package which performs any and all of the functions required for the +extraction of spectra and also collects all the parameters into one +parameter set. It is recommended that \fBapall\fR be used because it +collects all the parameters in one place eliminating confusion over +where a particular parameter is defined. + +In summary, the package consists of a number of logical functions which +are documented by the individual tasks named for that function, but the +functions are also integrated into each task and the aperture editor to +providing many different ways for the user to choose to perform the +functions. + +The package menu and help summary is shown below. + + +.ce +The APEXTRACT Package Tasks + +.nf + apall apedit apflatten aprecenter apsum + apdefault apfind apmask apresize aptrace + apdemos apfit apnormalize apscatter + + apall - Extract 1D spectra (all parameters in one task) + apdefault - Set the default aperture parameters and apidtable + apdemos - Various tutorial demonstrations + apedit - Edit apertures interactively + apfind - Automatically find spectra and define apertures + apfit - Fit 2D spectra and output the fit, difference, + or ratio + apflatten - Remove overall spectral and profile shapes from + flat fields + apmask - Create and IRAF pixel list mask of the apertures + apnormalize - Normalize 2D apertures by 1D functions + aprecenter - Recenter apertures + apresize - Resize apertures + apscatter - Fit and subtract scattered light + apsum - Extract 1D spectra + aptrace - Trace positions of spectra + + Additional topics + + apbackground - Background subtraction algorithms + apextract - Package parameters and general description of + package + approfiles - Profile determination algorithms + apvariance - Extractions, variance weighting, cleaning, and + noise model +.fi + +The extracted spectra are recorded in one, two, or three dimensional +images depending on the \fIformat\fR and \fIextras\fR parameters. If +the \fIextras\fR parameter is set to yes the formats are three +dimensional with each plane in the third dimension containing +associated information for the spectra in the first plane. See +\fBapsum\fR for further details. When \fIextras\fR=no only the +extracted spectra are output. + +If the format parameter is "onedspec" the output extractions are one +dimensional images with names formed from an output rootname and an +aperture number extension; i.e. root.0001 for aperture 1. 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. This format is provided to be compatible with the original +format used by 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 ".ec" 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, ease of handling, and efficiency. +These formats are compatible with the \fBonedspec\fR, \fBechelle\fR, and +\fBmsred\fR packages. The format is a standard IRAF image with +specialized image header keywords. Below is an example of the keywords. + + +.ce +MULTISPEC/ECHELLE Format Image Header Keywords + +.nf + ap> imhead test.ms + test.ms[512,2,4][real]: Title + BANDID1 = 'spectrum - background fit, weights variance, clean yes' + BANDID2 = 'spectrum - background fit, weights none, clean no' + BANDID3 = 'background - background fit' + BANDID4 = 'sigma - background fit, weights variance, clean yes' + APNUM1 = '1 1 87.11 94.79' + APNUM2 = '2 1 107.11 114.79' + APID1 = 'Galaxy center' + APID2 = 'Galaxy edge' + WCSDIM = 3 + CTYPE1 = 'PIXEL ' + CTYPE2 = 'LINEAR ' + CTYPE3 = 'LINEAR ' + CRVAL1 = 1. + CRPIX1 = 1. + CD1_1 = 1. + CD2_2 = 1. + CD3_3 = 1. + LTM1_1 = 1. + LTM2_2 = 1. + LTM3_3 = 1. + WAT0_001= 'system=equispec + WAT1_001= 'wtype=linear label=Pixel + WAT2_001= 'wtype=linear + WAT3_001= 'wtype=linear +.fi + +The BANDIDn keywords describe the various elements of the 3rd dimension. +Except for the first one the other bands only occur when \fIextras\fR is +yes and when sky subtraction and/or variance and cleaning are done. The +relation between the line and the aperture numbers is given by the header +parameters APNUMn where n is the line and the value gives extraction and +coordinate information about the spectrum. The first field is the aperture +number and the second is the beam number. After dispersion calibration of +echelle format spectra the beam number becomes the order number. The other +two numbers are the aperture limits at the line or column at which the +aperture was defined. +The APID keywords provide an optional title for each extracted spectrum +in addition to the overall image title. + +The rest of the keywords are part of the IRAF World Coordinate System +(WCS). If the image being extracted has been previously calibrated +(say with \fBlongslit.transform\fR) then the dispersion coordinates +will be carried in CRVAL1 and CD1_1. + +There is one other value for the format parameter, "strip". This produces +two dimensional extractions rather than one dimensional extractions. +Each aperture is output to a two dimensional image with a width set by the +nearest integer which includes the aperture. The output names are +generated in the same way as for "onedspec" format. The aperture is +shifted by interpolation so that it is exactly aligned with the image +columns. If not variance weighting the actual image data is output +with appropriate shifting while for variance weighting and/or cleaning +the profile model is output (similar to \fBapfit\fR except for being +aligned). This format is that provided in the previous version of +the package by the \fBapstrip\fR task. It is now relegated to a +special case. +.endhelp |