diff options
Diffstat (limited to 'noao/imred/echelle/doc')
| -rw-r--r-- | noao/imred/echelle/doc/Tutorial.hlp | 184 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/doecslit.hlp | 1230 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/doecslit.ms | 1479 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/dofoe.hlp | 1155 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/dofoe.ms | 1371 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/ecidentify.hlp | 770 | ||||
| -rw-r--r-- | noao/imred/echelle/doc/ecreidentify.hlp | 117 |
7 files changed, 6306 insertions, 0 deletions
diff --git a/noao/imred/echelle/doc/Tutorial.hlp b/noao/imred/echelle/doc/Tutorial.hlp new file mode 100644 index 00000000..655ca307 --- /dev/null +++ b/noao/imred/echelle/doc/Tutorial.hlp @@ -0,0 +1,184 @@ +.help Tutorial Aug86 "Echelle Tutorial" +.ih +TOPICS +The echelle tutorial consists of a number of different topics. To obtain help +on a particular topic type "tutor topic" where the topic is one of the +following: + +.nf + TOPICS + + topics - List of topics + overview - An overview of the echelle reduction process + dataio - Reading and writing data tapes + tracing - Tracing the positions of the orders + extraction - Extracting one or two dimensional spectra + references - Additional references + all - Print all of the tutorial +.fi + +The topics are kept brief and describe the simplest operations. More +sophisticated discussions are available for all the tasks in the printed +documentation and through the on-line \fBhelp\fR facility; i.e. "help taskname". +.ih +OVERVIEW +The \fBechelle\fR package provides for the extraction of the orders from +two dimensional echelle images into one dimensional spectra. After extraction +the one dimensional spectra are wavelength and flux calibrated. The usual +flow of the reductions is +.ls (1) +Read data from tape. +.le +.ls (2) +Set the dispersion axis in the image headers using the task \fBsetdisp\fR. +This is required by many of the tasks which follow. +.le +.ls (3) +Trace one or more images to define the positions of the orders within the +two dimensional format. +.le +.ls (4) +Extract the orders into one dimensional spectra. +.le +.ls (5) +Use arc calibration spectra to determine wavelength solutions. +.le +.ls (6) +Apply the wavelength solutions to the other spectra and rebin the spectra +into linear or logarithmic wavelength intervals. +.le +.ls (7) +Determine flux calibrations using standard star observations. +.le +.ls (8) +Apply the flux calibrations to the other object spectra. +.le +.ls (9) +Save the reductions as FITS images and make plots of the spectra. +.le + +There are many variations on these steps possible with the great flexibility +of the reduction tools at your disposal. The most important one to mention +is that the orders may be extracted as two dimensional strips in order to +apply more complex geometric distortion corrections using the \fBlongslit\fR +package. +.ih +DATAIO +To read CCD Camera format tapes use \fBrcamera\fR from the \fBmtlocal\fR +package. FITS format tapes are read and written with \fBrfits\fR and +\fBwfits\fR from the \fBdataio\fR package. Remember you need to +\fBallocate\fR the tape drive before you can read or write tapes and +you should \fBdeallocate\fR the tapes when you are through with the +tape drive. + +.nf + ec> allocate mta + ec> deallocate mta + ec> rcamera mta 1-99 ech datatype=r >rcam.log & + ec> rfits mta 1-99 ech datatype=r >rfits.log & + ec> wfits mta spectra* +.fi +.ih +TRACING +The positions of the orders across the image dispersion axis as a function +of position along the dispersion axis are determined by the task \fBtrace\fR. +There are three steps in tracing an image; defining the initial positions of +the orders at one point along the dispersion, automatically determining +the positions at other points in steps from the starting point, and fitting +smooth curves to the positions as a function of dispersion position. The +first and last steps are interactive, at least initially. After the first +image other images may be traced noninteractively. + +Select an image with narrow, strong profiles and run trace: + + ec> trace imagename + +When you are asked if you want to edit the apertures respond with "yes". +The central cut across the dispersion is graphed. Position the cursor +over the first order to be traced and type 'm'. Adjust the width of the +extraction aperture with the 'l', 'u', or 'y' keys or specify the lower +and upper widths explicitly with ":lower value" or ":upper value". +If background subtraction is to be used type 'b' and set the background +fitting parameters (see the \fBbackground\fR tutorial) +Now mark the remaining orders with the 'm' key. The widths of the +previous aperture are preserved for each new aperture. When you are +satisfied with the marked apertures type 'q'. + +The positions of the orders are now traced in steps from the initial point. +Once the positions have been traced you are asked whether to fit the +traced apertures interactively. Respond with "yes". You will now be +asked specifically if the first aperture is to be fit. Respond with "yes" +again. The traced positions are graphed along with a fitted curve. You now +have many options for adjusting the fit. The most important one is the +order which is set by typing ":order value", where value is the desired +order, and then 'f' to refit the data. For full information of the +options see the help for \fBicfit\fR. When you are satisfied type 'q'. + +You are then prompted for the next order. The previous fitting parameters +will be used so at this point you may want to just answer "NO" to skip +the interactive fitting of the other traced orders, though the graphs of the +fit will still be displayed. + +You now have several options about how to define the positions of the +orders in your other images. + +.ls (1) +You may apply the tracing to all other observations with no +further tracing. This is done by specifying the traced image +as the "reference" in the extraction process. +.le +.ls (2) +You may maintain the same shape of the traces and correct for +shifts in the positions of the orders across the dispersion +by recentering each aperture. This is done +with the task \fBapedit\fR or the editing switch during extraction +using the first traced image as the reference. The apertures are +recenter using the 'c' key. +.le +.ls (3) +Finally, you may retrace other images either from scratch or +using the first traced image as the initial reference. In the latter +case the tracing may be done noninteractively as a batch process. +.le +.ih +EXTRACTION +There are two types of extraction; to one dimensional spectra or +to two dimensional strips. The second type of extraction is accomplished +by the task \fBstripextract\fR in the \fBtwodspec.apextract\fR package +and is used if further reductions using the \fBlongslit\fR package are +desired. Normally, however, one ignores the small geometric distortion +in which curves of constant wavelength differ slightly from the image +dispersion axis. + +Extraction of the traced echelle orders is performed by the task +\fBsumextract\fR. The pixels within each aperture at each point along +the dispersion axis are summed to produce one dimensional spectra, one +for each order and each extracted image. The sum may be weighted +in two ways; "profile" or "variance" weighting. The variance weighting +may require that you know the CCD readout noise and photon/ADU conversion. +For a description of the weights see the help for \fBsumextract\fR +or the paper "The APEXTRACT Package". The spectra may also be cleaned +of cosmic rays and bad pixels at the same time and have a background +subtracted. The background subtraction parameters must be set when +defining the apertures or later using the apedit mode in \fBapedit\fR, +\fBtrace\fR, or \fBsumextract\fR. See the tutorial on \fBbackground\fR +for further information. + +Once the extraction parameters have been set simply type + + ec> sumextract images + +where images is the list of images to be extracted. If each image has +not been traced then a traced reference image should be given. +One may correct for shifts relative to the traced image by setting the +switch to edit the apertures and then recentering each aperture before +extracting. If there is no aperture editing then the extractions may +be done as a background or batch process. +.ih +REFERENCES +.ls (1) +Pilachowski, C. and J. V. Barnes, \fINotes on the IRAF for Reduction of +Echelle/CCD Data\fR, NOAO Central Computer Services, 1986. This document +is also available in the \fBIRAF User Handbook , Vol. 2B -- NOAO Cookbooks\fR. +.le +.endhelp diff --git a/noao/imred/echelle/doc/doecslit.hlp b/noao/imred/echelle/doc/doecslit.hlp new file mode 100644 index 00000000..7bf69f00 --- /dev/null +++ b/noao/imred/echelle/doc/doecslit.hlp @@ -0,0 +1,1230 @@ +.help doecslit Feb93 noao.imred.echelle +.ih +NAME +doecslit -- Echelle slit spectra reduction task +.ih +USAGE +doecslit objects +.ih +SUMMARY +\fBDoecslit\fR subtracts background sky or scattered light, extracts, +wavelength calibrates, and flux calibrates multiorder echelle slit spectra +which have been processed to remove the detector characteristics; i.e. CCD +images have been bias, dark count, and flat field corrected. The spectra +should be oriented such that pixels of constant wavelength are aligned with +the image columns or lines. Small departures from this alignment are not +critical resulting in only a small loss of resolution. Single order +observations should be reduced with \fBdoslit\fR. +.ih +PARAMETERS +.ls objects +List of object images to be processed. Previously processed spectra are +ignored unless the \fIredo\fR flag is set or the \fIupdate\fR flag is set +and dependent calibration data has changed. If the images contain the +keyword IMAGETYP then only those with a value of "object" or "OBJECT" +are used and those with a value of "comp" or "COMPARISON" are added +to the list of arcs. Extracted spectra are ignored. +.le +.ls apref = "" +Aperture reference spectrum. This spectrum is used to define the basic +extraction apertures and is typically a bright star spectrum. +.le +.ls arcs = "" (at least one if dispersion correcting) +List of arc calibration spectra. These spectra are used to define +the dispersion functions. The first spectrum is used to mark lines +and set the dispersion function interactively and dispersion functions +for all other arc spectra are derived from it. If the images contain +the keyword IMAGETYP then only those with a value of "comp" or +"COMPARISON" are used. All others are ignored as are extracted spectra. +.le +.ls arctable = "" (optional) (refspectra) +Table defining which arc spectra are to be assigned to which object +spectra (see \fBrefspectra\fR). If not specified an assignment based +on a header parameter, \fIsparams.sort\fR, such as the Julian date +is made. +.le +.ls standards = "" (at least one if flux calibrating) +List of standard star spectra. The standard stars must have entries in +the calibration database (package parameter \fIechelle.caldir\fR). +.le + +.ls readnoise = 0., gain = 1. (apsum) +Read out noise in photons and detector gain in photons per data value. +This parameter defines the minimum noise sigma and the conversion between +photon Poisson statistics and the data number statistics. Image header +keywords (case insensitive) may be specified to obtain the values from the +image header. +.le +.ls datamax = INDEF (apsum.saturation) +The maximum data value which is not a cosmic ray. +When cleaning cosmic rays and/or using variance weighted extraction +very strong cosmic rays (pixel values much larger than the data) can +cause these operations to behave poorly. If a value other than INDEF +is specified then all data pixels in excess of this value will be +excluded and the algorithms will yield improved results. +This applies only to the object spectra and not the standard star or +arc spectra. For more +on this see the discussion of the saturation parameter in the +\fBapextract\fR package. +.le +.ls norders = 10 (apfind) +Number of orders to be found automatically. +.le +.ls width = 5. (apedit) +Approximate full width of the spectrum profiles. This parameter is used +to define a width and error radius for the profile centering algorithm, +and defaults for the aperture limits and background regions. +.le + +.ls dispcor = yes +Dispersion correct spectra? This may involve either defining a nonlinear +dispersion coordinate system in the image header or resampling the +spectra to uniform linear wavelength coordinates as selected by +the parameter \fIsparams.linearize\fR. +.le +.ls extcor = no +Extinction correct the spectra? +.le +.ls fluxcal = no +Flux calibrate the spectra using standard star observations? +.le +.ls resize = no (apresize) +Resize the defaults apertures for each object based on the spectrum profile? +.le +.ls clean = no (apsum) +Detect and correct for bad pixels during extraction? This is the same +as the clean option in the \fBapextract\fR package. If yes this also +implies variance weighted extraction. In addition the datamax parameters +can be useful. +.le +.ls trace = yes (non-quicklook mode only) (aptrace) +Allow tracing each object spectrum separately? If not set then the trace +from the aperture reference is used, with recentering to allow for shifts +across the dispersion. If set then each object and standard star +image is retraced. Retracing is NOT done in quicklook mode. +.le +.ls background = "none" (apsum, apscatter) +Type of background light subtraction. The choices are "none" for no +background subtraction, "scattered" for a global scattered light +subtraction, "average" to average the background within background regions, +"median" to use the median in background regions, "minimum" to use the +minimum in background regions, or "fit" to fit across the dispersion using +the background within background regions. The scattered light option fits +and subtracts a smooth global background and modifies the input images. +This is a slow operation and so is NOT performed in quicklook mode. The +other background options are local to each aperture. The "fit" option uses +additional fitting parameters from \fBsparams\fR and the "scattered" option +uses parameters from \fBapscat1\fR and \fBapscat2\fR. +.le +.ls splot = no +Plot the final spectra? In quicklook mode a noninteractive, stacked plot +is automatically produced using the task \fBspecplot\fR while in +non-quicklook mode a query is given and the task \fBsplot\fR is used for +interactive plotting. +.le +.ls redo = no +Redo operations previously done? If no then previously processed spectra +in the objects list will not be processed unless required by the +update option. +.le +.ls update = no +Update processing of previously processed spectra if the aperture +reference image, the dispersion reference image, or standard star +calibration data are changed? +.le +.ls quicklook = no +Extract and calibrate spectra with minimal interaction? In quicklook mode +only aperture reference definitions, the initial dispersion function +solution, and the standard star setup are done interactively. Scattered +light subtraction and individual object tracing are not performed. +Normally the \fIsplot\fR option is set in this mode to produce an automatic +final spectrum plot for each object. It is recommended that this mode not be +used for final reductions. +.le +.ls batch = no +Process spectra as a background or batch job provided there are no interactive +steps remaining. +.le +.ls listonly = no +List processing steps but don't process? +.le + +.ls sparams = "" (pset) +Name of parameter set containing additional processing parameters. This +parameter is only for indicating the link to the parameter set +\fBsparams\fR and should not be given a value. The parameter set may be +examined and modified in the usual ways (typically with "epar +sparams" or ":e sparams" from the parameter editor). The parameters are +described below. +.le + +.ce +-- GENERAL PARAMETERS -- +.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, +editing, and tracing operations. A line of INDEF selects the middle of the +image along the dispersion axis. +.le +.ls extras = no (apsum) +Include raw unweighted and uncleaned spectra, the background spectra, and +the estimated sigma spectra in a three dimensional output image format. +See the discussion in the \fBapextract\fR package for further information. +.le + +.ce +-- AUTOMATIC APERTURE RESIZING PARAMETERS -- +.ls ylevel = 0.05 (apresize) +Fraction of the peak to set aperture limits during automatic resizing. +.le + +.ce +-- TRACE PARAMETERS -- +.ls t_step = 10 (aptrace) +Step along the dispersion axis between determination of the spectrum +positions. Note the \fInsum\fR parameter is also used to enhance the +signal-to-noise at each step. +.le +.ls t_function = "spline3", t_order = 2 (aptrace) +Default trace fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.le +.ls t_niterate = 1, t_low = 3., t_high = 3. (aptrace) +Default number of rejection iterations and rejection sigma thresholds. +.le + +.ce +-- BACKGROUND AND SCATTERED LIGHT PARAMETERS -- +.ls b_function = "legendre", b_order = 1 (apsum) +Default background fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.le +.ls b_naverage = -100 (apsum) +Default number of points to average or median. Positive numbers +average that number of sequential points to form a fitting point. +Negative numbers median that number, in absolute value, of sequential +points. A value of 1 does no averaging and each data point is used in the +fit. +.le +.ls b_niterate = 0 (apsum) +Default number of rejection iterations. If greater than zero the fit is +used to detect deviant fitting points and reject them before repeating the +fit. The number of iterations of this process is given by this parameter. +.le +.ls b_low_reject = 3., b_high_reject = 3. (apsum) +Default background lower and upper rejection sigmas. If greater than zero +points deviating from the fit below and above the fit by more than this +number of times the sigma of the residuals are rejected before refitting. +.le +.ls buffer = 1. (apscatter) +Buffer distance from the edge of any aperture for data to be included +in the scattered light determination. This parameter may be modified +interactively. +.le +.ls apscat1 = "", apscat2 = "" (apscatter) +Parameter sets for the fitting functions across and along the dispersion. +These parameters are those used by \fBicfit\fR. These parameters are +usually set interactively. +.le + +.ce +-- APERTURE EXTRACTION PARAMETERS -- +.ls weights = "none" (apsum) (none|variance) +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" (apsum and approfile) (fit1d|fit2d) +Type of profile fitting algorithm to use. The "fit1d" algorithm is +preferred except in cases of extreme tilt. +.le +.ls lsigma = 3., usigma = 3. (apsum) +Lower and upper rejection thresholds, given as a number of times the +estimated sigma of a pixel, for cleaning. +.le + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- +.ls threshold = 10. (identify/reidentify) +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.le +.ls coordlist = "linelist$thar.dat" (ecidentify) +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelist$". +.le +.ls match = 1. (ecidentify) +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.le +.ls fwidth = 4. (ecidentify) +Approximate full base width (in pixels) of arc lines. +.le +.ls cradius = 10. (reidentify) +Radius from previous position to reidentify arc line. +.le +.ls i_function = "legendre", i_xorder = 3, i_yorder = 3 (ecidentify) +The default function, function order for the pixel position dependence, and +function order for the aperture number dependence to be fit to the arc +wavelengths. The functions choices are "chebyshev" or "legendre". +.le +.ls i_niterate = 3, i_low = 3.0, i_high = 3.0 (ecidentify) +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.le +.ls refit = yes (ecreidentify) +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the arc reference then a new +dispersion function of the same type as in the reference image is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised fitted coordinates without changing the +form of the dispersion function. +.le + +.ce +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- +.ls select = "interp" (refspectra) +Selection method for assigning wavelength calibration spectra. +Note that an arc assignment table may be used to override the selection +method and explicitly assign arc spectra to object spectra. +The automatic selection methods are: +.ls average +Average two reference spectra without regard to any sort parameter. +If only one reference spectrum is specified then it is assigned with a +warning. If more than two reference spectra are specified then only the +first two are used and a warning is given. +This option is used to assign two reference spectra, with equal weights, +independent of any sorting parameter. +.le +.ls following +Select the nearest following spectrum in the reference list based on the +sorting parameter. If there is no following spectrum use the nearest preceding +spectrum. +.le +.ls interp +Interpolate between the preceding and following spectra in the reference +list based on the sorting parameter. If there is no preceding and following +spectrum use the nearest spectrum. The interpolation is weighted by the +relative distances of the sorting parameter. +.le +.ls match +Match each input spectrum with the reference spectrum list in order. +This overrides the reference aperture check. +.le +.ls nearest +Select the nearest spectrum in the reference list based on the sorting +parameter. +.le +.ls preceding +Select the nearest preceding spectrum in the reference list based on the +sorting parameter. If there is no preceding spectrum use the nearest following +spectrum. +.le +.le +.ls sort = "jd" (setjd and refspectra) +Image header keyword to be used as the sorting parameter for selection +based on order. The header parameter must be numeric but otherwise may +be anything. Common sorting parameters are times or positions. +.le +.ls group = "ljd" (setjd and refspectra) +Image header keyword to be used to group spectra. For those selection +methods which use the group parameter the reference and object +spectra must have identical values for this keyword. This can +be anything but it must be constant within a group. Common grouping +parameters are the date of observation "date-obs" (provided it does not +change over a night) or the local Julian day number. +.le +.ls time = no, timewrap = 17. (refspectra) +Is the sorting parameter a 24 hour time? If so then the time origin +for the sorting is specified by the timewrap parameter. This time +should precede the first observation and follow the last observation +in a 24 hour cycle. +.le + +.ce +-- DISPERSION CORRECTION PARAMETERS -- +.ls linearize = yes (dispcor) +Interpolate the spectra to a linear dispersion sampling? If yes the +spectra will be interpolated to a linear or log linear sampling using +the linear dispersion parameters specified by other parameters. If +no the nonlinear dispersion function(s) from the dispersion function +database are assigned to the input image world coordinate system +and the spectral data is not interpolated. Note the interpolation +function type is set by the package parameter \fIinterp\fR. +.le +.ls log = no (ecdispcor) +Use linear logarithmic wavelength coordinates? Linear logarithmic +wavelength coordinates have wavelength intervals which are constant +in the logarithm of the wavelength. +.le +.ls flux = yes (ecdispcor) +Conserve the total flux during interpolation? If \fIno\fR the output +spectrum is interpolated from the input spectrum at each output +wavelength coordinate. If \fIyes\fR the input spectrum is integrated +over the extent of each output pixel. This is slower than +simple interpolation. +.le + +.ce +-- SENSITIVITY CALIBRATION PARAMETERS -- +.ls bandwidth = 10., bandsep = 10. (standard) +Interpolated bandpass grid. If INDEF then the same bandpasses as in the +calibration files are used otherwise the calibration data is interpolated +to the specified set of bandpasses. +.le +.ls s_interact = yes (standard) +Display the bandpasses on the standard star data and allow interactive +addition and deletion of bandpasses. +.le +.ls s_function = "spline3", s_order = 1 (sensfunc) +Function and order used to fit the sensitivity data. The function types are +"chebyshev" polynomial, "legendre" polynomial, "spline3" cubic spline, +and "spline1" linear spline. +Order of the sensitivity fitting function. The value corresponds to the +number of polynomial terms or the number of spline pieces. The default +values may be changed interactively. +.le +.ls fnu = no (calibrate) +The default calibration is into units of F-lambda. If \fIfnu\fR = yes then +the calibrated spectrum will be in units of F-nu. +.le + +.ce +PACKAGE PARAMETERS +.ls dispaxis = 2 +Default dispersion axis. The dispersion axis is 1 for dispersion +running along image lines and 2 for dispersion running along image +columns. If the image header parameter DISPAXIS is defined it has +precedence over this parameter. The default value defers to the +package parameter of the same name. +.le +.ls extinction = "onedstds$kpnoextinct.dat" (standard, sensfunc, calibrate) +Extinction file for a site. There are two extinction files in the +NOAO standards library, onedstds$, for KPNO and CTIO. These extinction +files are used for extinction and flux calibration. +.le +.ls caldir (standard) +Standard star calibration directory. A directory containing standard +star data files. Note that the directory name must end with '/'. +There are a number of standard star calibrations directories in the NOAO +standards library, onedstds$. +.le +.ls observatory = "observatory" (observatory) +The default observatory to use for latitude dependent computations. +If the OBSERVAT keyword in the image header it takes precedence over +this parameter. +.le +.ls interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) (dispcor) +Spectrum interpolation type used when spectra are resampled. The choices are: + +.nf + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.fi +.le +.ls database = "database" +Database name used by various tasks. This is a directory which is created +if necessary. +.le +.ls verbose = no +Verbose output? If set then almost all the information written to the +logfile is also written to the terminal except when the task is a +background or batch process. +.le +.ls logfile = "logfile" +If specified detailed text log information is written to this file. +.le +.ls plotfile = "" +If specified metacode plots are recorded in this file for later review. +Since plot information can become large this should be used only if +really desired. +.le +.ih +ENVIRONMENT PARAMETERS +The environment parameter \fIimtype\fR is used to determine the extension +of the images to be processed and created. This allows use with any +supported image extension. For STF images the extension has to be exact; +for example "d1h". +.ih +DESCRIPTION +\fBDoecslit\fR subtracts background sky or scattered light, extracts, +wavelength calibrates, and flux calibrates multiorder echelle slit spectra +which have been processed to remove the detector characteristics; i.e. CCD +images have been bias, dark count, and flat field corrected. The spectra +should be oriented such that pixels of constant wavelength are aligned with +the image columns or lines. Small departures from this alignment are not +critical resulting in only a small loss of resolution. Single order +observations should be reduced with \fBdoslit\fR. + +The task is a command language script which collects and combines the +functions and parameters of many general purpose tasks to provide a single, +complete data reduction path and a degree of guidance, automation, and +record keeping. In the following description and in the parameter section +the various general tasks used are identified. Further +information about those tasks and their parameters may be found in their +documentation. \fBDoecslit\fR also simplifies and consolidates parameters +from those tasks and keeps track of previous processing to avoid +duplications. + +The general organization of the task is to do the interactive setup steps, +such as the aperture definitions and reference dispersion function +determination, first using representative calibration data and then perform +the majority of the reductions automatically, possibly as a background +process, with reference to the setup data. In addition, the task +determines which setup and processing operations have been completed in +previous executions of the task and, contingent on the \fIredo\fR and +\fIupdate\fR options, skip or repeat some or all the steps. + +The description is divided into a quick usage outline followed by details +of the parameters and algorithms. The usage outline is provided as a +checklist and a refresher for those familiar with this task and the +component tasks. It presents only the default or recommended usage +since there are many variations possible. + +\fBUsage Outline\fR + +.ls 6 [1] +The images are first processed with \fBccdproc\fR for overscan, +zero level, dark count, and flat field corrections. +.le +.ls [2] +Set the \fBdoecslit\fR parameters with \fBeparam\fR. Specify the object +images to be processed, an aperture reference image (usually a bright +star spectrum) to use in finding the orders and defining the +aperture parameters, one or more arc images, and one or more standard +star images. If there are many object, arc, or standard star images +you might prepare "@ files". Set the detector and data +specific parameters. Select the processing options desired. +Finally you might wish to review the \fBsparams\fR algorithm parameters +though the defaults are probably adequate. +.le +.ls [3] +Run the task. This may be repeated multiple times with different +observations and the task will generally only do the setup steps +once and only process new images. Queries presented during the +execution for various interactive operations may be answered with +"yes", "no", "YES", or "NO". The lower case responses apply just +to that query while the upper case responses apply to all further +such queries during the current execution and no further queries of that +type will be made. +.le +.ls [4] +The specified number of orders (ranked by peak strength) in the aperture +reference image are located and default fixed width apertures are +assigned. If the resize option is set the apertures are resized by finding +the level which is 5% (the default) of the peak above local background. +You then have the option of entering the aperture editing loop to check the +aperture positions, sizes, and background fitting parameters. This is +highly recommended. Note that it is important that the aperture numbers be +sequential with the orders and if any orders are skipped the aperture +numbers should also skip. It is also important to verify the background +regions with the 'b' key. Usually you want any changes made to the +background definitions to apply to all apertures so use the 'a' key to +select all apertures before modifying the background parameters. To exit +the background mode and then to exit the review mode use 'q'. +.le +.ls [5] +The order positions at a series of points along the dispersion are measured +and a function is fit to these positions. This may be done interactively +to examine the traced positions and adjust the fitting parameters. To exit +the interactive fitting type 'q'. Not all orders need be examined and the +"NO" response will quit the interactive fitting using the last defined +fitting parameters on the remaining traces. +.le +.ls [6] +Apertures are now defined for all standard and object images. This is only +done if there are no previous aperture definitions for the image. The +aperture references previously defined are used as the initial set of +apertures for each image. The apertures are then recentered by an average +shift over all orders and resized if that option is selected. +The apertures may also be retraced and interactively examined +for each image if the tracing option is selected and quicklook mode is not. +.le +.ls [7] +If scattered light subtraction is selected the scattered light parameters +are set using the aperture reference image and the task \fBapscatter\fR. +The purpose of this is to interactively define the aperture buffer distance +for the scattered light and the cross and parallel dispersion fitting +parameters. The fitting parameters are taken from and recorded in the +parameter sets \fBapscat1\fR and \fBapscat2\fR. All other scattered light +subtractions are done noninteractively with these parameters. Note that +the scattered light correction modifies the input images. Scattered light +subtraction is not done in quicklook mode. +.le +.ls [8] +If dispersion correction is selected the first arc in the arc list is +extracted. The dispersion function is defined using the task +\fBecidentify\fR. Identify a few arc lines in a few orders with 'm' and +'o' and use the 'l' line list identification command to automatically add +additional lines and fit the dispersion function. Check the quality of the +dispersion function fit with 'f'. When satisfied exit with 'q'. +.le +.ls [9] +If the flux calibration option is selected the standard star spectra are +processed (if not done previously). The images are background subtracted, +extracted, and wavelength calibrated. The appropriate arc +calibration spectra are extracted and the dispersion function refit +using the arc reference spectrum as a starting point. The standard star +fluxes through the calibration bandpasses are compiled. You are queried +for the name of the standard star calibration data file. Because echelle +spectra are often at much higher dispersion than the calibration data, +interpolated bandpasses may be defined with the bandpass parameters in +\fBsparams\fR and checked or modified interactively. + +After all the standard stars are processed a sensitivity function is +determined using the interactive task \fBsensfunc\fR. Finally, the +standard star spectra are extinction corrected and flux calibrated +using the derived sensitivity function. +.le +.ls [10] +The object spectra are now automatically background subtracted +(an alternative to scattered light subtraction), +extracted, wavelength calibrated, and flux calibrated. +.le +.ls [11] +The option to examine the final spectra with \fBsplot\fR may be given. +To exit type 'q'. In quicklook mode the spectra are plotted +noninteractively with \fBspecplot\fR. +.le +.ls [12] +The final spectra will have the same name as the original 2D images +with a ".ec" extension added. +.le + +\fBSpectra and Data Files\fR + +The basic input consists of echelle slit object, standard star, and arc +calibration spectra stored as IRAF images. +The type of image format is defined by the +environment parameter \fIimtype\fR. Only images with that extension will +be processed and created. +The raw CCD images must be +processed to remove overscan, bias, dark count, and flat field effects. +This is generally done using the \fBccdred\fR package. Flat fields which +are not contaminated by low counts between the apertures may be prepared +with the task \fBapflatten\fR (recommended) or \fBapnormalize\fR. Lines of +constant wavelength across the orders should be closely aligned with one of +the image axes. Sometimes the orders are aligned rather than the spectral +features. This will result in a small amount of resolution loss but is +often acceptable. In some cases one may correct for misalignment with the +\fBrotate\fR task. More complex geometric problems and observations of +extended objects should be handled by the \fBlongslit\fR package and single +order observations should be processed by \fBdoslit\fR. + +The aperture reference spectrum is generally a bright star. The arc +spectra are comparison arc lamp observations (they must all be of the same +type). The assignment of arc calibration exposures to object exposures is +generally done by selecting the nearest in time and interpolating. +However, the optional \fIarc assignment table\fR may be used to explicitly +assign arc images to specific objects. The format of this file is +described in task \fBrefspectra\fR. + +The final reduced spectra are recorded in two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ec" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, order, and wavelength +information. When the \fIextras\fR parameter is set the lines in the +third dimension contain additional information (see +\fBapsum\fR for further details). These spectral formats are accepted by the +one dimensional spectroscopy tasks such as the plotting tasks \fBsplot\fR +and \fBspecplot\fR. The special task \fBscopy\fR may be used to extract +specific apertures or to change format to individual one dimensional +images. The task \fBscombine\fR is used to combine or merge orders into +a single spectrum. + +\fBPackage Parameters\fR + +The \fBechelle\fR package parameters set parameters which change +infrequently and define the standard I/O functions. The extinction file +is used for making extinction corrections and the standard star +calibration directory is used for determining flux calibrations from +standard star observations. The calibration directories contain data files +with standard star fluxes and band passes. The available extinction +files and flux calibration directories may be listed using the command: +.nf + + cl> page onedstds$README + +.fi +The extinction correction requires computation of an air mass using the +task \fBsetairmass\fR. The air mass computation needs information +about the observation and, in particular, the latitude of the observatory. +This is determined using the OBSERVAT image header keyword. If this +keyword is not present the observatory parameter is used. See the +task \fBobservatory\fR for more on defining the observatory parameters. + +The spectrum interpolation type is used whenever a spectrum needs to be +resampled for linearization or performing operations between spectra +with different sampling. The "sinc" interpolation may be of interest +as an alternative but see the cautions given in \fBonedspec.package\fR. + +The verbose parameter selects whether to print everything which goes +into the log file on the terminal. It is useful for monitoring +what the \fBdoecslit\fR task does. The log and plot files are useful for +keeping a record of the processing. A log file is highly recommended. +A plot file provides a record of the apertures, traces, and extracted +spectra but can become quite large. +The plotfile is most conveniently viewed and printed with \fBgkimosaic\fR. + +\fBProcessing Parameters\fR + +The input images are specified by image lists. The lists may be +a list of explicit comma separate image names, @ files, or image +templates using pattern matching against file names in the directory. +To allow wildcard image lists to be used safely and conveniently the +image lists are checked to remove extracted images (the .ec images) +and to automatically identify object and arc spectra. Object and arc +images are identified by the keyword IMAGETYP with values of "object", +"OBJECT", "comp", or "COMPARISON" (the current practice at NOAO). +If arc images are found in the object list they are transferred to the +arc list while if object images are found in the arc list they are ignored. +All other image types, such as biases, darks, or flat fields, are +ignored. This behavior allows simply specifying all images with a wildcard +in the object list with automatic selections of arc spectra or a +wildcard in the arc list to automatically find the arc spectra. +If the data lack the identifying information it is up to the user +to explicitly set the proper lists. + +As mentioned earlier, all the arc images must be of the same type; +that is taken with the same arc lamp. The aperture reference parameter +is a single image name which is usually a bright star. + +The next set of parameters describe the noise characteristics and the +general layout of the orders. The read out noise and gain are used when +"cleaning" cosmic rays and when using variance or optimal weighting. These +parameters must be fairly accurate. Note that these are the effective +parameters and must be adjusted if previous processing has modified the +pixel values; such as with an unnormalized flat field. + +The general direction in which the orders run is specified by the +dispersion axis parameter. Recall that ideally it is the direction +of constant wavelength which should be aligned with an image axis and +the dispersion direction will not be aligned because of the cross-dispersion. +The \fInorders\fR parameter is used to automatically find the orders. The +specified number of the brightest peaks are found. Generally after finding the +orders the aperture definitions are reviewed and adjusted interactively. +The profile width should be approximately the full width at the profile +base. The default aperture limits and background regions are all +derived from this width parameter. + +The next set of parameters select the processing steps and options. The +various calibration steps may be done simultaneously, that is at the same +time as the basic extractions, or in separate executions of the task. +Typically, all the desired operations are done at the same time. +Dispersion correction requires at least one arc spectrum and flux +calibration requires dispersion correction and at least one standard star +observation. + +The \fIresize\fR option resets the edges of the extraction apertures based +on the profile for each object and standard star order. The default +resizing is to the 5% point relative to the peak measured above the +background. This allows following changes in the seeing. However, one +should consider the consequences of this if attempting to flux calibrate +the observations. Except in quicklook mode, the apertures for each object +and standard star observation may be reviewed graphically and further +adjustments made to the aperture width and background regions. + +The apertures for each observation are adjusted for small shifts relative +to the reference aperture definitions. If you think this is not sufficient, +say to account for rotation of the detector or for differing atmospheric +dispersion, the \fItrace\fR option allows redefining the aperture trace +functions for each observation. Note this is only allowed in non-quicklook +mode. + +The \fIclean\fR option invokes a profile +fitting and deviant point rejection algorithm as well as a variance weighting +of points in the aperture. See the next section for more about +requirements to use this option. + +The \fIbackground\fR option selects a type of correction for background +or scattered light. If the type is "scattered" a global scattered light +is fit to the data between the apertures and subtracted from the images. +\fINote that the input images are modified by this operation\fR. +This option is slow and is not allowed in quicklook +mode. Alternatively, a local background may be subtracted using +background regions defined for each aperture. The background may be +within the slit for a sky subtraction or outside of the slit for a +local scattered light subtraction. The data in the regions +may be averaged, medianed, or the minimum value used. Another choice +is to fit the data in the background regions by a function and interpolate +to the object aperture. + +Generally once a spectrum has been processed it will not be reprocessed if +specified as an input spectrum. However, changes to the underlying +calibration data can cause such spectra to be reprocessed if the +\fIupdate\fR flag is set. The changes which will cause an update are a new +reference image, adding the scattered light subtraction option, a new arc +reference image, and new standard stars. If all input spectra are to be +processed regardless of previous processing the \fIredo\fR flag may be +used. Note that reprocessing clobbers the previously processed output +spectra. + +The final step is to plot the spectra if the \fIsplot\fR option is +selected. In non-quicklook mode there is a query which may be +answered either in lower or upper case. The plotting uses the interactive +task \fBsplot\fR. In quicklook mode the plot appears noninteractively +using the task \fBspecplot\fR. + +The \fIquicklook\fR option provides a simpler, less interactive, mode. +The quicklook mode automatically assigns the reference apertures to +the object and standard star observations without interactive review +or tracing, does not do the time consuming scattered light correction, +and the \fIsplot\fR option selects a noninteractive plot to be +shown at the end of processing of each object and standard star +spectrum. While the algorithms used in quicklook mode are nearly the same +as in non-quicklook mode and the final results may be the same it is +recommended that the greater degree of monitoring and review in +non-quicklook mode be used for careful final reductions. + +The batch processing option allows object spectra to be processed as a +background or batch job. This will occur only if the interactive +\fIsplot\fR option is not active; either not set, turned off during +processing with "NO", or in quicklook mode. In batch processing the +terminal output is suppressed. + +The \fIlistonly\fR option prints a summary of the processing steps +which will be performed on the input spectra without actually doing +anything. This is useful for verifying which spectra will be affected +if the input list contains previously processed spectra. The listing +does not include any arc spectra which may be extracted to dispersion +calibrate an object spectrum. + +The last parameter (excluding the task mode parameter) points to +another parameter set for the algorithm parameters. The default +parameter set is called \fBsparams\fR. The algorithm parameters are +discussed further in the next section. + +\fBAlgorithms and Algorithm Parameters\fR + +This section summarizes the various algorithms used by the +\fBdoecslit\fR task and the parameters which control and modify the +algorithms. The algorithm parameters available to you are +collected in the parameter set \fBsparams\fR. These parameters are +taken from the various general purpose tasks used by the \fBdoecslit\fR +processing task. Additional information about these parameters and +algorithms may be found in the help for the actual +task executed. These tasks are identified below. The aim of this +parameter set organization is to collect all the algorithm parameters +in one place separate from the processing parameters and include only +those which are relevant for echelle slit data. The parameter values +can be changed from the defaults by using the parameter editor, +.nf + +cl> epar sparams + +.fi +or simple typing \fIsparams\fR. +The parameter editor can also be entered when editing the \fBdoecslit\fR +parameters by typing \fI:e\fR when positioned at the \fIsparams\fR +parameter. + +\fBAperture Definitions\fR + +The first operation is to define the extraction apertures, which include the +aperture width, background regions, and position dependence with +wavelength, for the input echelle slit spectra and, if flux calibration is +selected, the standard star spectra. This is done only for spectra which +do not have previously defined apertures unless the \fIredo\fR option is +set to force all definitions to be redone. Thus, apertures may be +defined separately using the \fBapextract\fR tasks. This is particularly +useful if one needs to use reference images to define apertures for very +weak spectra which are not well centered or traced by themselves. + +Initially apertures are defined for a specified \fIaperture reference\fR +image. The selected number of orders are found automatically by selecting +the highest peaks in a cut across the dispersion. Apertures are assigned +with a width given by the \fIwidth\fR parameter and numbered sequentially. +The background regions are also defined in terms of the width parameter +starting at one width distance from the profile center and extending to two +widths on both sides of the profile. As an example, if the width parameter +is 5 pixels the default aperture limits are +/- 2.5 pixels and the +background sample regions will be "-10:-5,5:10". If the \fIresize\fR +parameter is set the aperture limits are adjusted to a specified point on +the spectrum profile (see \fBapresize\fR). + +A query is then given allowing the aperture definitions to be reviewed and +modified. Queries made by \fBdoecslit\fR generally may be answered with either +lower case "yes" or "no" or with upper case "YES" or "NO". The upper +case responses apply to all further queries and so are used to eliminate +further queries of that kind. + +Reviewing the aperture definitions is highly recommended to check the +aperture numbering, aperture limits, and background regions. The aperture +numbers must be linearly related, with a slope of +/- 1, to the true order +numbers though absolute order numbers need not be known. The key point is +that if an order is skipped the aperture numbers must also skip. The +background regions are checked with the 'b' key. Typically one adjusts all +the background regions at the same time by selecting all apertures with +the 'a' key first. To exit the background and aperture editing steps type +'q'. + +Next the positions of the orders at various points along the dispersion +are measured and "trace functions" are fit. The user is asked whether +to fit each trace function interactively. This is selected to adjust +the fitting parameters such as function type and order. When +interactively fitting a query is given for each aperture. After the +first aperture one may skip reviewing the other traces. + +After the aperture reference image is done all the object and standard star +images are checked for aperture definitions and those without definitions +are assigned apertures. The assignment consists of inheriting the aperture +from the reference aperture image, recentering the apertures based on an +average shift that best centers all the apertures, resizing the apertures +if the resize option is selected, and retracing the spectral orders if the +retracing option is selected. Retracing is only allowed in non-quicklook +mode (set by the \fIquicklook\fR parameter). Also interactive review of +the aperture definitions is only done in +non-quicklook mode. In quicklook mode the aperture definitions are all set +noninteractively without retracing. It is recommended that quicklook only +be used for initial quick extractions and calibration and that for final +reductions one at least review the aperture definitions and possibly +retrace each observation. + +The above steps are all performed using tasks from the \fBapextract\fR +package and parameters from the \fBsparams\fR parameters. As a quick +summary, the dispersion direction of the spectra are determined from the +package \fBdispaxis\fR parameter if not defined in the image header. The default +line or column for finding the object position on the slit and the number +of image lines or columns to sum are set by the \fIline\fR and \fInsum\fR +parameters. A line of INDEF (the default) selects the middle of the +image. The automatic finding algorithm is described for the task +\fBapfind\fR and basically finds the strongest peaks. The resizing is +described in the task \fBapresize\fR and the parameters used are also +described there. The tracing is +done as described in \fBaptrace\fR and consists of stepping along the image +using the specified \fIt_step\fR parameter. The function fitting uses the +\fBicfit\fR commands with the other parameters from the tracing section. + +\fBBackground or Scattered Light Subtraction\fR + +In addition to not subtracting any sky or scattered light there are two +approaches to subtracting background light. The first is to determine +a smooth global scattered light component. The second is to subtract +a locally determined background at each point along the dispersion and +for each aperture. This can be either for a sky subtraction if the +background regions are within the slit or scattered light if the +background regions are outside of the slit. Note that background +subtraction is only done for object and standard star images and not +for arc spectra. Also, the global scattered light option is not done +in quicklook mode. + +The global scattered light fitting and subtraction is done with the task +\fBapscatter\fR. The function fitting parameters are set interactively +using the aperture reference spectrum. All other subtractions are done +noninteractively with the same set of parameters. The scattered light is +subtracted from the input images, thus modifying them, and one might wish +to first make backups of the original images. + +The scattered light is measured between the apertures using a specified +buffer distance from the aperture edges. The scattered light pixels are +fit by a series of one dimensional functions across the dispersion. The +independent fits are then smoothed along the dispersion by again fitting +low order functions. These fits then define the smooth scattered light +surface to be subtracted from the image. The fitting parameters are +defined and recorded in the two parameter sets \fIapscat1\fR and +\fIapscat2\fR. The scattered light algorithm is described more fully in +\fBapscatter\fR. This algorithm is relatively slow. + +Local background subtraction is done during extraction based on background +regions and parameters defined by the default background parameters or +changed during interactive review of the apertures. The background +subtraction options are to 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. + +\fBExtraction\fR + +The actual extraction of the spectra is done by summing across the +fixed width apertures at each point along the dispersion. +The default is to simply sum the pixels using +partial pixels at the ends. There is an option to weight the +sum based on a Poisson variance model using the \fIreadnoise\fR and +\fIgain\fR detector parameters. Note that if the \fIclean\fR +option is selected the variance weighted extraction is used regardless +of the \fIweights\fR parameter. The sigma thresholds for cleaning +are also set in the \fBsparams\fR parameters. + +The cleaning and variance weighting options require knowing the effective +(i.e. accounting for any image combining) read out noise and gain. +These numbers need to be adjusted if the image has been processed +such that the intensity scale has a different origin (such as +a scattered light subtraction) or scaling (such as caused by unnormalized +flat fielding). These options also require using background subtraction +if the profile does not go to zero. For optimal extraction and +cleaning to work it is recommended that any flat fielding be done +using flat fields produced by \fBapflatten\fR, no scattered light +correction, and using background subtraction if there is any +appreciable sky or to compensate for scattered light. +For further discussion of cleaning and variance weighted extraction see +\fBapvariance\fR and \fBapprofiles\fR as well as \fBapsum\fR. + +\fBDispersion Correction\fR + +If dispersion correction is not selected, \fIdispcor\fR=no, then the object +spectra are simply extracted. The extracted spectra may be plotted +by setting the \fIsplot\fR option. This produces a query and uses +the interactive \fBsplot\fR task in non-quicklook mode and uses +\fBspecplot\fR noninteractively in quicklook mode. + +Dispersion corrections are applied to the extracted spectra if the +\fIdispcor\fR processing parameter is set. There +are three basic steps involved; determining the dispersion functions +relating pixel position to wavelength, assigning the appropriate +dispersion function to a particular observation, and either storing +the nonlinear dispersion function in the image headers or resampling the +spectra to evenly spaced pixels in wavelength. + +The first arc spectrum in the arc list is used to define the reference +dispersion solution. It is extracted using the reference aperture definition. +Note extractions of arc spectra are not background or scattered light +subtracted. The interactive task \fBecidentify\fR is used to define the +dispersion function. The idea is to mark some lines in a few orders whose +wavelengths are known (with the line list used to supply additional lines after +the first few identifications define the approximate wavelengths) and to fit a +function giving the wavelength from the aperture number and pixel position. + +The arc dispersion function parameters are for \fBecidentify\fR and it's +related partner \fBecreidentify\fR. The parameters define a line list for +use in automatically assigning wavelengths to arc lines, a centering width +(which should match the line widths at the base of the lines), the +dispersion function type and orders, parameters to exclude bad lines from +function fits, and defining whether to refit the dispersion function as +opposed to simply determining a zero point shift. The defaults should +generally be adequate and the dispersion function fitting parameters may be +altered interactively. One should consult the help for the two tasks for +additional details of these parameters and the interactive operation of +\fBecidentify\fR. + +Once the reference dispersion function is defined other arc spectra are +extracted as required by the object spectra. The assignment of arcs is +done either explicitly with an arc assignment table (parameter +\fIarctable\fR) or based on a header parameter such as a time. +This assignments are made by the task +\fBrefspectra\fR. When two arcs are assigned to an object spectrum an +interpolation is done between the two dispersion functions. This makes an +approximate correction for steady drifts in the dispersion. + +The tasks \fBsetjd\fR and \fBsetairmass\fR are automatically run on all +spectra. This computes and adds the header parameters for the Julian date +(JD), the local Julian day number (LJD), the universal time (UTMIDDLE), and +the air mass at the middle of the exposure. The default arc assignment is +to use the Julian date grouped by the local Julian day number. The +grouping allows multiple nights of data to be correctly assigned at the +same time. + +In non-quicklook mode the arc spectra assigned to each object are +extracted using the same apertures as the object. This accounts for +changes in the recentering, aperture sizes, and tracing functions. +In quicklook mode the arc spectra are extracted using the reference +apertures. When the same arc is used for several object images this +allows the arc spectrum to only be extracted once. + +Defining the dispersion function for a new arc extraction is done with +the task \fBecreidentify\fR. This is done noninteractively with log +information recorded about the line reidentifications and the fit. + +The last step of dispersion correction is setting the dispersion +of the object image from the arc images. There are two choices here. +If the \fIlinearize\fR parameter is not set the nonlinear dispersion +function is stored in the image header. Other IRAF tasks interpret +this information when dispersion coordinates are needed for plotting +or analysis. This has the advantage of not requiring the spectra +to be interpolated and the disadvantage that the dispersion +information is only understood by IRAF tasks and cannot be readily +exported to other analysis software. + +If the \fIlinearize\fR parameter is set then the spectra are resampled to a +linear dispersion relation either in wavelength or the log of the +wavelength. For echelle spectra each order is linearized independently so +that the wavelength interval per pixel is different in different orders. +This preserves most of the resolution and avoids over or under sampling of +the highest or lowest dispersion orders. The wavelength limits are +taken from the limits determined from the arc reference spectrum and +the number of pixels is the same as the original images. The dispersion +per pixel is then derived from these constraints. + +The linearization algorithm parameters allow selecting the interpolation +function type, whether to conserve flux per pixel by integrating across the +extent of the final pixel, and whether to linearize to equal linear or +logarithmic intervals. The latter may be appropriate for radial velocity +studies. The default is to use a fifth order polynomial for interpolation, +to conserve flux, and to not use logarithmic wavelength bins. These +parameters are described fully in the help for the task \fBdispcor\fR which +performs the correction. + +\fBFlux Calibration\fR + +Flux calibration consists of an extinction correction and an instrumental +sensitivity calibration. The extinction correction only depends on the +extinction function defined by the package parameter \fIextinct\fR and +determination of the airmass from the header parameters (the air mass is +computed by \fBsetairmass\fR as mentioned earlier). The sensitivity +calibration depends on a sensitivity calibration spectrum determined from +standard star observations for which there are tabulated absolute fluxes. +The task that applies both the extinction correction and sensitivity +calibration to each extracted object spectrum is \fBcalibrate\fR. Consult +the manual page for this task for more information. + +Generation of the sensitivity calibration spectrum is done before +processing any object spectra since it has two interactive steps and +requires all the standard star observations. The first step is tabulating +the observed fluxes over the same bandpasses as the calibrated absolute +fluxes. For very high resolution it may be the case that the measured +calibration bandpasses are too large or sparse. In this case one must +interpolate the calibration data to bandpasses appropriate for the data. +If the bandpass widths and separations are given as INDEF then the same +bandpasses as in the calibration file are used. Otherwise a uniform grid +of bandpasses is interpolated. Using interpolated bandpasses is not +rigorous but is sometimes the only choice for echelle spectra. + +The standard star tabulations are done after each standard star is +extracted and dispersion corrected. You are asked for the name of the +standard star as tabulated in the absolute flux data files in the directory +\fIcaldir\fR defined by the package parameters. If the \fIinteract\fR +parameter is yes the bandpasses can be displayed on the data and you can +interactively add or delete bandpasses. The tabulation of the standard star +observations over the standard bandpasses is done by the task +\fBstandard\fR. The tabulated data is stored in the file \fIstd\fR. Note +that if the \fIredo\fR flag is not set any new standard stars specified in +subsequent executions of \fBdoecslit\fR are added to the previous data in +the data file, otherwise the file is first deleted. Modification of the +tabulated standard star data, such as by adding new stars, will cause any +spectra in the input list which have been previously calibrated to be +reprocessed if the \fIupdate\fR flag is set. + +After the standard star calibration bandpass fluxes are tabulated the +information from all the standard stars is combined to produce a +sensitivity function for use by \fBcalibrate\fR. The sensitivity function +determination is interactive and uses the task \fBsensfunc\fR. This task +allows fitting a smooth sensitivity function to the ratio of the observed +to calibrated fluxes verses wavelength. The types of manipulations one +needs to do include deleting bad observations, possibly removing variable +extinction (for poor data), and possibly deriving a revised extinction +function. This is a complex operation and one should consult the manual +page for \fBsensfunc\fR. The sensitivity function is saved as one +dimensional spectra (one per order) with the root name \fIsens\fR. +Deletion of these images will also cause reprocessing to occur if the +\fIupdate\fR flag is set. +.ih +EXAMPLES +1. The following example uses artificial data and may be executed +at the terminal (with IRAF V2.10). This is similar to the sequence +performed by the test procedure "demos doecslit". + +.nf +ec> demos mkecslit +Creating example longslit in image demoobj ... +Creating example longslit in image demostd ... +Creating example longslit in image demoarc ... +ec> echelle.verbose=no +ec> echelle.caldir=onedstds$spechayescal/ +ec> doecslit Bdemoobj apref=Bdemostd arcs=Bdemoarc stand=Bdemostd \ +>>> norders=3 extcor+ fluxcal+ resize+ splot+ +Set reference aperture for Bdemostd +Edit apertures for Bdemostd? (yes): +<Check background with 'b', exit background and review with 'q'> +Fit traced positions for Bdemostd interactively? (yes): +Fit curve to aperture 1 of Bdemostd interactively (yes): +<Exit with 'q'> +Fit curve to aperture 2 of Bdemostd interactively (yes): N +Edit apertures for Bdemoobj? (yes): +<Check background with 'b', exit background and review with 'q'> +Fit traced positions for Bdemoobj interactively? (yes): N +Extract arc reference image Bdemoarc +Determine dispersion solution for Bdemoarc +<Type 'm' at first strong line (pixel 156) and identify it as 4965> +<Type 'k' to go to next order> +<Mark 52->5002, 74->5003.6, 155->5009.3> +<Type 'k' to go to next order and mark 18->5044.7, 231->5059.8> +<Type 'f' to see the fit residuals> +<Type 'q' to quit fit and then 'q' to exit> +Extract standard star spectrum Bdemostd +Assign arc spectra for Bdemostd +Extract and reidentify arc spectrum Bdemoarc +Dispersion correct Bdemostd +B...ec.imh: ap = 1, w1 = 4953.9, w2 = 4972.2, dw = 0.071, nw = 256 +B...ec.imh: ap = 2, w1 = 4998.3, w2 = 5016.5, dw = 0.071, nw = 256 +B...ec.imh: ap = 3, w1 = 5043.5, w2 = 5061.6, dw = 0.070, nw = 256 +Compile standard star fluxes for Bdemostd +Bdemostd.ec.imh[1]: Artificial Echelle Spectrum +Star name in calibration list: hz14 +Bdemostd.ec.imh[1]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!) (no): y +<Exit with 'q'> +Bdemostd.ec.imh[2]: Artificial Echelle Spectrum +Bdemostd.ec.imh[2]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!) (y): N +Bdemostd.ec.imh[3]: Artificial Echelle Spectrum +Bdemostd.ec.imh[3]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!) (N): +Compute sensitivity function +Fit aperture 1 interactively? (no|yes|NO|YES) (no|yes|NO|YES) (yes): +<Exit with 'q'> +Sensitivity function for aperture 1 --> sens.0001 +Fit aperture 2 interactively? (no|yes|NO|YES) (no|yes|NO|YES) (yes): N +Sensitivity function for aperture 2 --> sens.0002 +Sensitivity function for aperture 3 --> sens.0003 +Flux and/or extinction calibrate standard stars +Standard stars: +Splot spectrum? (no|yes|NO|YES) (yes): +Image line/aperture to plot (0:) (1): +<Exit with 'q'> +Extract object spectrum Bdemoobj +Assign arc spectra for Bdemoobj +Extract and reidentify arc spectrum Bdemoarc +Dispersion correct Bdemoobj +B...ec.imh: ap = 1, w1 = 4953.9, w2 = 4972.2, dw = 0.071, nw = 256 +B...ec.imh: ap = 2, w1 = 4998.3, w2 = 5016.5, dw = 0.071, nw = 256 +B...ec.imh: ap = 3, w1 = 5043.5, w2 = 5061.6, dw = 0.070, nw = 256 +Extinction correct Bdemoobj +Flux calibrate Bdemoobj +Bdemoobj.ec.imh: +Splot spectrum? (no|yes|NO|YES) (yes): +Image line/aperture to plot (0:) (1): +<Exit with 'q'> +.fi +.ih +REVISIONS +.ls DOECSLIT V2.10.3 +The image format type to be +processed is selected with the \fIimtype\fR environment parameter. The +dispersion axis parameter is now a package parameter. Images will only +be processed if the have the CCDPROC keyword. A \fIdatamax\fR parameter +has been added to help improve cosmic ray rejection. A bug which +alphabetized the arc spectra was fixed. +.le +.ih +SEE ALSO +apbackground, apedit, apfind, approfiles, aprecenter, apresize, apsum, aptrace, +apvariance, calibrate, ccdred, center1d, ctioslit, dispcor, +echelle.doecslit, ecidentify, ecreidentify, icfit, kpnocoude, kpnoslit, +msred, observatory, onedspec.package, refspectra, sensfunc, setairmass, setjd, +splot, standard +.endhelp diff --git a/noao/imred/echelle/doc/doecslit.ms b/noao/imred/echelle/doc/doecslit.ms new file mode 100644 index 00000000..a93f3e8b --- /dev/null +++ b/noao/imred/echelle/doc/doecslit.ms @@ -0,0 +1,1479 @@ +.nr PS 9 +.nr VS 11 +.de V1 +.ft CW +.nf +.. +.de V2 +.fi +.ft R +.. +.de LS +.br +.in +2 +.. +.de LE +.br +.sp .5v +.in -2 +.. +.ND February 1993 +.TL +Guide to the Slit Spectra Reduction Task DOECSLIT +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +.DY + +.AB +\fBDoecslit\fR subtracts background sky or scattered light, extracts, +wavelength calibrates, and flux calibrates multiorder echelle slit spectra +which have been processed to remove the detector characteristics; i.e. CCD +images have been bias, dark count, and flat field corrected. The spectra +should be oriented such that pixels of constant wavelength are aligned with +the image columns or lines. Small departures from this alignment are not +critical resulting in only a small loss of resolution. Single order +observations should be reduced with \fBdoslit\fR. +.AE +.NH +Introduction +.LP +\fBDoecslit\fR subtracts background sky or scattered light, extracts, +wavelength calibrates, and flux calibrates multiorder echelle slit spectra +which have been processed to remove the detector characteristics; i.e. CCD +images have been bias, dark count, and flat field corrected. The spectra +should be oriented such that pixels of constant wavelength are aligned with +the image columns or lines. Small departures from this alignment are not +critical resulting in only a small loss of resolution. Single order +observations should be reduced with \fBdoslit\fR. +.LP +The task is a command language script which collects and combines the +functions and parameters of many general purpose tasks to provide a single, +complete data reduction path and a degree of guidance, automation, and +record keeping. In the following description and in the parameter section +the various general tasks used are identified. Further +information about those tasks and their parameters may be found in their +documentation. \fBDoecslit\fR also simplifies and consolidates parameters +from those tasks and keeps track of previous processing to avoid +duplications. +.LP +The general organization of the task is to do the interactive setup steps, +such as the aperture definitions and reference dispersion function +determination, first using representative calibration data and then perform +the majority of the reductions automatically, possibly as a background +process, with reference to the setup data. In addition, the task +determines which setup and processing operations have been completed in +previous executions of the task and, contingent on the \f(CWredo\fR and +\f(CWupdate\fR options, skip or repeat some or all the steps. +.LP +The description is divided into a quick usage outline followed by details +of the parameters and algorithms. The usage outline is provided as a +checklist and a refresher for those familiar with this task and the +component tasks. It presents only the default or recommended usage +since there are many variations possible. +.NH +Usage Outline +.LP +.IP [1] 6 +The images are first processed with \fBccdproc\fR for overscan, +zero level, dark count, and flat field corrections. +.IP [2] +Set the \fBdoecslit\fR parameters with \fBeparam\fR. Specify the object +images to be processed, an aperture reference image (usually a bright +star spectrum) to use in finding the orders and defining the +aperture parameters, one or more arc images, and one or more standard +star images. If there are many object, arc, or standard star images +you might prepare "@ files". Set the detector and data +specific parameters. Select the processing options desired. +Finally you might wish to review the \fBsparams\fR algorithm parameters +though the defaults are probably adequate. +.IP [3] +Run the task. This may be repeated multiple times with different +observations and the task will generally only do the setup steps +once and only process new images. Queries presented during the +execution for various interactive operations may be answered with +"yes", "no", "YES", or "NO". The lower case responses apply just +to that query while the upper case responses apply to all further +such queries during the current execution and no further queries of that +type will be made. +.IP [4] +The specified number of orders (ranked by peak strength) in the aperture +reference image are located and default fixed width apertures are +assigned. If the resize option is set the apertures are resized by finding +the level which is 5% (the default) of the peak above local background. +You then have the option of entering the aperture editing loop to check the +aperture positions, sizes, and background fitting parameters. This is +highly recommended. Note that it is important that the aperture numbers be +sequential with the orders and if any orders are skipped the aperture +numbers should also skip. It is also important to verify the background +regions with the 'b' key. Usually you want any changes made to the +background definitions to apply to all apertures so use the 'a' key to +select all apertures before modifying the background parameters. To exit +the background mode and then to exit the review mode use 'q'. +.IP [5] +The order positions at a series of points along the dispersion are measured +and a function is fit to these positions. This may be done interactively +to examine the traced positions and adjust the fitting parameters. To exit +the interactive fitting type 'q'. Not all orders need be examined and the +"NO" response will quit the interactive fitting using the last defined +fitting parameters on the remaining traces. +.IP [6] +Apertures are now defined for all standard and object images. This is only +done if there are no previous aperture definitions for the image. The +aperture references previously defined are used as the initial set of +apertures for each image. The apertures are then recentered by an average +shift over all orders and resized if that option is selected. +The apertures may also be retraced and interactively examined +for each image if the tracing option is selected and quicklook mode is not. +.IP [7] +If scattered light subtraction is selected the scattered light parameters +are set using the aperture reference image and the task \fBapscatter\fR. +The purpose of this is to interactively define the aperture buffer distance +for the scattered light and the cross and parallel dispersion fitting +parameters. The fitting parameters are taken from and recorded in the +parameter sets \fBapscat1\fR and \fBapscat2\fR. All other scattered light +subtractions are done noninteractively with these parameters. Note that +the scattered light correction modifies the input images. Scattered light +subtraction is not done in quicklook mode. +.IP [8] +If dispersion correction is selected the first arc in the arc list is +extracted. The dispersion function is defined using the task +\fBecidentify\fR. Identify a few arc lines in a few orders with 'm' and 'o' +and use the 'l' line list identification command to automatically add +additional lines and fit the dispersion function. Check the quality of the +dispersion function fit with 'f'. When satisfied exit with 'q'. +.IP [9] +If the flux calibration option is selected the standard star spectra are +processed (if not done previously). The images are background subtracted, +extracted, and wavelength calibrated. The appropriate arc +calibration spectra are extracted and the dispersion function refit +using the arc reference spectrum as a starting point. The standard star +fluxes through the calibration bandpasses are compiled. You are queried +for the name of the standard star calibration data file. Because echelle +spectra are often at much higher dispersion than the calibration data +interpolated bandpasses may be defined with the bandpass parameters in +\fBsparams\fR and checked or modified interactively. +.IP +After all the standard stars are processed a sensitivity function is +determined using the interactive task \fBsensfunc\fR. Finally, the +standard star spectra are extinction corrected and flux calibrated +using the derived sensitivity function. +.IP [10] +The object spectra are now automatically background subtracted +(an alternative to scattered light subtraction), +extracted, wavelength calibrated, and flux calibrated. +.IP [11] +The option to examine the final spectra with \fBsplot\fR may be given. +To exit type 'q'. In quicklook mode the spectra are plotted +noninteractively with \fBspecplot\fR. +.IP [12] +The final spectra will have the same name as the original 2D images +with a ".ec" extension added. +.NH +Spectra and Data Files +.LP +The basic input consists of echelle slit object, standard star, and arc +calibration spectra stored as IRAF images. +The type of image format is defined by the +environment parameter \fIimtype\fR. Only images with that extension will +be processed and created. +The raw CCD images must be +processed to remove overscan, bias, dark count, and flat field effects. +This is generally done using the \fBccdred\fR package. Flat fields which +are not contaminated by low counts between the apertures may be prepared +with the task \fBapflatten\fR (recommended) or \fBapnormalize\fR. Lines of +constant wavelength across the orders should be closely aligned with one of +the image axes. Sometimes the orders are aligned rather than the spectral +features. This will result in a small amount of resolution loss but is +often acceptable. In some cases one may correct for misalignment with the +\fBrotate\fR task. More complex geometric problems and observations of +extended objects should be handled by the \fBlongslit\fR package and single +order observations should be processed by \fBdoslit\fR. +.LP +The aperture reference spectrum is generally a bright star. The arc +spectra are comparison arc lamp observations (they must all be of the same +type). The assignment of arc calibration exposures to object exposures is +generally done by selecting the nearest in time and interpolating. +However, the optional \fIarc assignment table\fR may be used to explicitly +assign arc images to specific objects. The format of this file is +described in task \fBrefspectra\fR. +.LP +The final reduced spectra are recorded in two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ec" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, order, and wavelength +information. When the \f(CWextras\fR parameter is set the lines in the +third dimension contain additional information (see +\fBapsum\fR for further details). These spectral formats are accepted by the +one dimensional spectroscopy tasks such as the plotting tasks \fBsplot\fR +and \fBspecplot\fR. The special task \fBscopy\fR may be used to extract +specific apertures or to change format to individual one dimensional +images. The task \fBscombine\fR is used to combine or merge orders into +a single spectrum. +.NH +Package Parameters +.LP +The \fBechelle\fR package parameters, shown in Figure 1, set parameters +which change infrequently and define the standard I/O functions. +.KS + +.ce +Figure 1: Package Parameter Set for the ECHELLE Package + +.V1 +cl> epar echelle + I R A F + Image Reduction and Analysis Facility +PACKAGE = imred + TASK = echelle + +(extinct= onedstds$kpnoextinct.dat) Extinction file +(caldir = onedstds$spechayescal/) Standard star calibration directory +(observa= observatory) Observatory of data +(interp = poly5) Interpolation type +(dispaxi= 2) Image axis for 2D images +(nsum = 1) Number of lines/columns to sum for 2D images + +(databas= database) Database +(verbose= no) Verbose output? +(logfile= logfile) Text log file +(plotfil= ) Plot file + +(records= ) Record number extensions +(version= ECHELLE V3: July 1991) + +.KE +.V2 +The extinction file +is used for making extinction corrections and the standard star +calibration directory is used for determining flux calibrations from +standard star observations. The calibration directories contain data files +with standard star fluxes and band passes. The available extinction +files and flux calibration directories may be listed using the command: +.V1 + + cl> page onedstds$README + +.V2 +The extinction correction requires computation of an air mass using the +task \fBsetairmass\fR. The air mass computation needs information +about the observation and, in particular, the latitude of the observatory. +This is determined using the OBSERVAT image header keyword. If this +keyword is not present the observatory parameter is used. See the +task \fBobservatory\fR for more on defining the observatory parameters. +.LP +The spectrum interpolation type is used whenever a spectrum needs to be +resampled for linearization or performing operations between spectra +with different sampling. The "sinc" interpolation may be of interest +as an alternative but see the cautions given in \fBonedspec.package\fR. +.LP +The verbose parameter selects whether to print everything which goes +into the log file on the terminal. It is useful for monitoring +everything that the task does. The log and plot files are useful for +keeping a record of the processing. A log file is highly recommended. +A plot file provides a record of the apertures, traces, and extracted +spectra but can become quite large. +.NH +Processing Parameters +.LP +The \fBdoecslit\fR parameters are shown in Figure 2. +.KS + +.ce +Figure 2: Parameter Set for DOECSLIT + +.V1 + I R A F + Image Reduction and Analysis Facility +PACKAGE = echelle + TASK = doecslit + +objects = List of object spectra +(apref = ) Aperture reference spectrum +(arcs = ) List of arc spectra +(arctabl= ) Arc assignment table (optional) +(standar= ) List of standard star spectra +.KE +.V1 + +(readnoi= 0.) Read out noise sigma (photons) +(gain = 1.) Photon gain (photons/data number) +(datamax= INDEF) Max data value / cosmic ray threshold +(norders= 10) Number of orders +(width = 5.) Width of profiles (pixels) + +(dispcor= yes) Dispersion correct spectra? +(extcor = no) Extinction correct spectra? +(fluxcal= no) Flux calibrate spectra? +(resize = no) Resize object apertures? +(clean = no) Detect and replace bad pixels? +(trace = yes) Trace object spectra? +(backgro= none) Background to subtract +(splot = no) Plot the final spectra? +(redo = no) Redo operations if previously done? +(update = no) Update spectra if cal data changes? +(quicklo= no) Approximate quicklook reductions? +(batch = no) Extract objects in batch? +(listonl= no) List steps but don't process? + +(sparams= ) Algorithm parameters + +.V2 +The input images are specified by image lists. The lists may be +a list of explicit comma separate image names, @ files, or image +templates using pattern matching against file names in the directory. +To allow wildcard image lists to be used safely and conveniently the +image lists are checked to remove extracted images (the .ec images) +and to automatically identify object and arc spectra. Object and arc +images are identified by the keyword IMAGETYP with values of "object", +"OBJECT", "comp", or "COMPARISON" (the current practice at NOAO). +If arc images are found in the object list they are transferred to the +arc list while if object images are found in the arc list they are ignored. +All other image types, such as biases, darks, or flat fields, are +ignored. This behavior allows simply specifying all images with a wildcard +in the object list with automatic selections of arc spectra or a +wildcard in the arc list to automatically find the arc spectra. +If the data lack the identifying information it is up to the user +to explicitly set the proper lists. +.LP +As mentioned earlier, all the arc images must be of the same type; +that is taken with the same arc lamp. The aperture reference parameter +is a single image name which is usually a bright star. +.LP +The next set of parameters describe the noise characteristics and the +general layout of the orders. The read out noise and gain are used when +"cleaning" cosmic rays and when using variance or optimal weighting. These +parameters must be fairly accurate. Note that these are the effective +parameters and must be adjusted if previous processing has modified the +pixel values; such as with an unnormalized flat field. +.LP +The general direction in which the orders run is specified by the +dispersion axis parameter. Recall that ideally it is the direction +of constant wavelength which should be aligned with an image axis and +the dispersion direction will not be aligned because of the cross-dispersion. +The \f(CWnorders\fR parameter is used to automatically find the orders. The +specified number of the brightest peaks are found. Generally after finding the +orders the aperture definitions are reviewed and adjusted interactively. +The profile width should be approximately the full width at the profile +base. The default aperture limits and background regions are all +derived from this width parameter. +.LP +The next set of parameters select the processing steps and options. The +various calibration steps may be done simultaneously, that is at the same +time as the basic extractions, or in separate executions of the task. +Typically, all the desired operations are done at the same time. +Dispersion correction requires at least one arc spectrum and flux +calibration requires dispersion correction and at least one standard star +observation. +.LP +The \f(CWresize\fR option resets the edges of the extraction apertures based +on the profile for each object and standard star order. The default +resizing is to the 5% point relative to the peak measured above the +background. This allows following changes in the seeing. However, one +should consider the consequences of this if attempting to flux calibrate +the observations. Except in quicklook mode, the apertures for each object +and standard star observation may be reviewed graphically and further +adjustments made to the aperture width and background regions. +.LP +The apertures for each observation are adjusted for small shifts relative +to the reference aperture definitions. If you think this is not sufficient, +say to account for rotation of the detector or for differing atmospheric +dispersion, the \f(CWtrace\fR option allows redefining the aperture trace +functions for each observation. Note this is only allowed in non-quicklook +mode. +.LP +The \f(CWclean\fR option invokes a profile +fitting and deviant point rejection algorithm as well as a variance weighting +of points in the aperture. See the next section for more about +requirements to use this option. +.LP +The \f(CWbackground\fR option selects a type of correction for background +or scattered light. If the type is "scattered" a global scattered light +is fit to the data between the apertures and subtracted from the images. +\fINote that the input images are modified by this operation\fR. +This option is slow and is not allowed in quicklook +mode. Alternatively, a local background may be subtracted using +background regions defined for each aperture. The background may be +within the slit for a sky subtraction or outside of the slit for a +local scattered light subtraction. The data in the regions +may be averaged, medianed, or the minimum value used. Another choice +is to fit the data in the background regions by a function and interpolate +to the object aperture. +.LP +Generally once a spectrum has been processed it will not be reprocessed if +specified as an input spectrum. However, changes to the underlying +calibration data can cause such spectra to be reprocessed if the +\f(CWupdate\fR flag is set. The changes which will cause an update are a new +reference image, adding the scattered light subtraction option, a new arc +reference image, and new standard stars. If all input spectra are to be +processed regardless of previous processing the \f(CWredo\fR flag may be +used. Note that reprocessing clobbers the previously processed output +spectra. +.LP +The final step is to plot the spectra if the \f(CWsplot\fR option is +selected. In non-quicklook mode there is a query which may be +answered either in lower or upper case. The plotting uses the interactive +task \fBsplot\fR. In quicklook mode the plot appears noninteractively +using the task \fBspecplot\fR. +.LP +The \f(CWquicklook\fR option provides a simpler, less interactive, mode. +The quicklook mode automatically assigns the reference apertures to +the object and standard star observations without interactive review +or tracing, does not do the time consuming scattered light correction, +and the \f(CWsplot\fR option selects a noninteractive plot to be +shown at the end of processing of each object and standard star +spectrum. While the algorithms used in quicklook mode are nearly the same +as in non-quicklook mode and the final results may be the same it is +recommended that the greater degree of monitoring and review in +non-quicklook mode be used for careful final reductions. +.LP +The batch processing option allows object spectra to be processed as a +background or batch job. This will occur only if the interactive +\f(CWsplot\fR option is not active; either not set, turned off during +processing with "NO", or in quicklook mode. In batch processing the +terminal output is suppressed. +.LP +The \f(CWlistonly\fR option prints a summary of the processing steps +which will be performed on the input spectra without actually doing +anything. This is useful for verifying which spectra will be affected +if the input list contains previously processed spectra. The listing +does not include any arc spectra which may be extracted to dispersion +calibrate an object spectrum. +.LP +The last parameter (excluding the task mode parameter) points to +another parameter set for the algorithm parameters. The default +parameter set is called \fBsparams\fR. The algorithm parameters are +discussed further in the next section. +.NH +Algorithms and Algorithm Parameters +.LP +This section summarizes the various algorithms used by the +\fBdoecslit\fR task and the parameters which control and modify the +algorithms. The algorithm parameters available to you are +collected in the parameter set \fBsparams\fR. These parameters are +taken from the various general purpose tasks used by the \fBdoecslit\fR +processing task. Additional information about these parameters and +algorithms may be found in the help for the actual +task executed. These tasks are identified below. The aim of this +parameter set organization is to collect all the algorithm parameters +in one place separate from the processing parameters and include only +those which are relevant for echelle slit data. The parameter values +can be changed from the defaults by using the parameter editor, +.V1 + +cl> epar sparams + +.V2 +or simple typing \f(CWsparams\fR. +The parameter editor can also be entered when editing the \fBdoecslit\fR +parameters by typing \f(CW:e\fR when positioned at the \f(CWsparams\fR +parameter. Figure 3 shows the parameter set. +.KS + +.ce +Figure 3: Algorithm Parameter Set + +.V1 +cl> epar sparams + I R A F + Image Reduction and Analysis Facility +PACKAGE = echelle + TASK = sparams + +(line = INDEF) Default dispersion line +(nsum = 10) Number of dispersion lines to sum +(extras = no) Extract sky, sigma, etc.? + + -- AUTOMATIC APERTURE RESIZING PARAMETERS -- +(ylevel = 0.05) Fraction of peak or intensity for resizing +.KE +.V1 + + -- TRACE PARAMETERS -- +(t_step = 10) Tracing step +(t_funct= spline3) Trace fitting function +(t_order= 2) Trace fitting function order +(t_niter= 1) Trace rejection iterations +(t_low = 3.) Trace lower rejection sigma +(t_high = 3.) Trace upper rejection sigma + + -- BACKGROUND AND SCATTERED LIGHT PARAMETERS -- +(b_funct= legendre) Background function +(b_order= 1) Background function order +(b_naver= -100) Background average or median +(b_niter= 0) Background rejection iterations +(b_low = 3.) Background lower rejection sigma +(b_high = 3.) Background upper rejection sigma +(buffer = 1.) Buffer distance from apertures +(apscat1= ) Fitting parameters across the dispersion +(apscat2= ) Fitting parameters along the dispersion + + -- APERTURE EXTRACTION PARAMETERS -- +(weights= none) Extraction weights (none|variance) +(pfit = fit1d) Profile fitting algorithm (fit1d|fit2d) +(lsigma = 3.) Lower rejection threshold +(usigma = 3.) Upper rejection threshold + + -- ARC DISPERSION FUNCTION PARAMETERS -- +(coordli= linelist$thar.dat) Line list +(match = 1.) Line list matching limit in Angstroms +(fwidth = 4.) Arc line widths in pixels +(cradius= 10.) Centering radius in pixels +(i_funct= legendre) Echelle coordinate function +(i_xorde= 3) Order of coordinate function along dispersion +(i_yorde= 3) Order of coordinate function across dispersion +(i_niter= 3) Rejection iterations +(i_low = 3.) Lower rejection sigma +(i_high = 3.) Upper rejection sigma +(refit = yes) Refit coordinate function when reidentifying + + -- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- +(select = interp) Selection method for reference spectra +(sort = jd) Sort key +(group = ljd) Group key +(time = no) Is sort key a time? +(timewra= 17.) Time wrap point for time sorting + + -- DISPERSION CORRECTION PARAMETERS -- +(lineari= yes) Linearize (interpolate) spectra? +(log = no) Logarithmic wavelength scale? +(flux = yes) Conserve flux? + + -- SENSITIVITY CALIBRATION PARAMETERS -- +(bandwid= 10.) Bandpass widths +(bandsep= 10.) Bandpass separation +(s_inter= yes) Graphic interaction to examine/define bandpasses +(s_funct= spline3) Fitting function +(s_order= 1) Order of sensitivity function +(fnu = no) Create spectra having units of FNU? + +.V2 +.NH 2 +Aperture Definitions +.LP +The first operation is to define the extraction apertures, which include the +aperture width, background regions, and position dependence with +wavelength, for the input echelle slit spectra and, if flux calibration is +selected, the standard star spectra. This is done only for spectra which +do not have previously defined apertures unless the \f(CWredo\fR option is +set to force all definitions to be redone. Thus, apertures may be +defined separately using the \fBapextract\fR tasks. This is particularly +useful if one needs to use reference images to define apertures for very +weak spectra which are not well centered or traced by themselves. +.LP +Initially apertures are defined for a specified \fIaperture reference\fR +image. The selected number of orders are found automatically by selecting +the highest peaks in a cut across the dispersion. Apertures are assigned +with a width given by the \f(CWwidth\fR parameter and numbered sequentially. +The background regions are also defined in terms of the width parameter +starting at one width distance from the profile center and extending to two +widths on both sides of the profile. As an example, if the width parameter +is 5 pixels the default aperture limits are +/- 2.5 pixels and the +background sample regions will be "-10:-5,5:10". If the \f(CWresize\fR +parameter is set the aperture limits are adjusted to a specified point on +the spectrum profile (see \fBapresize\fR). +.LP +A query is then given allowing the aperture definitions to be reviewed and +modified. Queries made by \fBdoecslit\fR generally may be answered with either +lower case "yes" or "no" or with upper case "YES" or "NO". The upper +case responses apply to all further queries and so are used to eliminate +further queries of that kind. +.LP +Reviewing the aperture definitions is highly recommended to check the +aperture numbering, aperture limits, and background regions. The aperture +numbers must be linearly related, with a slope of +/- 1, to the true order +numbers though absolute order numbers need not be known. The key point is +that if an order is skipped the aperture numbers must also skip. The +background regions are checked with the 'b' key. Typically one adjusts all +the background regions at the same time by selecting all apertures with +the 'a' key first. To exit the background and aperture editing steps type +'q'. +.LP +Next the positions of the orders at various points along the dispersion +are measured and "trace functions" are fit. The user is asked whether +to fit each trace function interactively. This is selected to adjust +the fitting parameters such as function type and order. When +interactively fitting a query is given for each aperture. After the +first aperture one may skip reviewing the other traces. +.LP +After the aperture reference image is done all the object and standard star +images are checked for aperture definitions and those without definitions +are assigned apertures. The assignment consists of inheriting the aperture +from the reference aperture image, recentering the apertures based on an +average shift that best centers all the apertures, resizing the apertures +if the resize option is selected, and retracing the spectral orders if the +retracing option is selected. Retracing is only allowed in non-quicklook +mode (set by the \f(CWquicklook\fR parameter). Also interactive review of +the aperture definitions is only done in +non-quicklook mode. In quicklook mode the aperture definitions are all set +noninteractively without retracing. It is recommended that quicklook only +be used for initial quick extractions and calibration and that for final +reductions one at least review the aperture definitions and possibly +retrace each observation. +.LP +The above steps are all performed using tasks from the \fBapextract\fR +package and parameters from the \fBsparams\fR parameters. As a quick +summary, the dispersion direction of the spectra are determined from the +package \fBdispaxis\fR parameter if not defined in the image header. The default +line or column for finding the object position on the slit and the number +of image lines or columns to sum are set by the \f(CWline\fR and \f(CWnsum\fR +parameters. A line of INDEF (the default) selects the middle of the +image. The automatic finding algorithm is described for the task +\fBapfind\fR and basically finds the strongest peaks. The resizing is +described in the task \fBapresize\fR and the parameters used are also +described there. The tracing is +done as described in \fBaptrace\fR and consists of stepping along the image +using the specified \f(CWt_step\fR parameter. The function fitting uses the +\fBicfit\fR commands with the other parameters from the tracing section. +.NH 2 +Background or Scattered Light Subtraction +.LP +In addition to not subtracting any sky or scattered light there are two +approaches to subtracting background light. The first is to determine +a smooth global scattered light component. The second is to subtract +a locally determined background at each point along the dispersion and +for each aperture. This can be either for a sky subtraction if the +background regions are within the slit or scattered light if the +background regions are outside of the slit. Note that background +subtraction is only done for object and standard star images and not +for arc spectra. Also, the global scattered light option is not done +in quicklook mode. +.LP +The global scattered light fitting and subtraction is done with the task +\fBapscatter\fR. The function fitting parameters are set interactively +using the aperture reference spectrum. All other subtractions are done +noninteractively with the same set of parameters. The scattered light is +subtracted from the input images, thus modifying them, and one might wish +to first make backups of the original images. +.LP +The scattered light is measured between the apertures using a specified +buffer distance from the aperture edges. The scattered light pixels are +fit by a series of one dimensional functions across the dispersion. The +independent fits are then smoothed along the dispersion by again fitting +low order functions. These fits then define the smooth scattered light +surface to be subtracted from the image. The fitting parameters are +defined and recorded in the two parameter sets \f(CWapscat1\fR and +\f(CWapscat2\fR. The scattered light algorithm is described more fully in +\fBapscatter\fR. This algorithm is relatively slow. +.LP +Local background subtraction is done during extraction based on background +regions and parameters defined by the default background parameters or +changed during interactive review of the apertures. The background +subtraction options are to 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 (\f(CWbackground\fR = +"median") or median samples during fitting (\f(CWb_naverage\fR < -1). The +background subtraction algorithm and options are described in greater +detail in \fBapsum\fR and \fBapbackground\fR. +.NH 2 +Extraction +.LP +The actual extraction of the spectra is done by summing across the +fixed width apertures at each point along the dispersion. +The default is to simply sum the pixels using +partial pixels at the ends. There is an option to weight the +sum based on a Poisson variance model using the \f(CWreadnoise\fR and +\f(CWgain\fR detector parameters. Note that if the \f(CWclean\fR +option is selected the variance weighted extraction is used regardless +of the \f(CWweights\fR parameter. The sigma thresholds for cleaning +are also set in the \fBsparams\fR parameters. +.LP +The cleaning and variance weighting options require knowing the effective +(i.e. accounting for any image combining) read out noise and gain. +These numbers need to be adjusted if the image has been processed +such that the intensity scale has a different origin (such as +a scattered light subtraction) or scaling (such as caused by unnormalized +flat fielding). These options also require using background subtraction +if the profile does not go to zero. For optimal extraction and +cleaning to work it is recommended that any flat fielding be done +using flat fields produced by \fBapflatten\fR, no scattered light +correction, and using background subtraction if there is any +appreciable sky or to compensate for scattered light. +For further discussion of cleaning and variance weighted extraction see +\fBapvariance\fR and \fBapprofiles\fR as well as \fBapsum\fR. +.NH 2 +Dispersion Correction +.LP +If dispersion correction is not selected, \f(CWdispcor\fR=no, then the object +spectra are simply extracted. The extracted spectra may be plotted +by setting the \f(CWsplot\fR option. This produces a query and uses +the interactive \fBsplot\fR task in non-quicklook mode and uses +\fBspecplot\fR noninteractively in quicklook mode. +.LP +Dispersion corrections are applied to the extracted spectra if the +\f(CWdispcor\fR processing parameter is set. There +are three basic steps involved; determining the dispersion functions +relating pixel position to wavelength, assigning the appropriate +dispersion function to a particular observation, and either storing +the nonlinear dispersion function in the image headers or resampling the +spectra to evenly spaced pixels in wavelength. +.LP +The first arc spectrum in the arc list is used to define the reference +dispersion solution. It is extracted using the reference aperture definition. +Note extractions of arc spectra are not background or scattered light +subtracted. The interactive task \fBecidentify\fR is used to define the +dispersion function. The idea is to mark some lines in a few orders whose +wavelengths are known (with the line list used to supply additional lines after +the first few identifications define the approximate wavelengths) and to fit a +function giving the wavelength from the aperture number and pixel position. +.LP +The arc dispersion function parameters are for \fBecidentify\fR and it's +related partner \fBecreidentify\fR. The parameters define a line list for +use in automatically assigning wavelengths to arc lines, a centering width +(which should match the line widths at the base of the lines), the +dispersion function type and orders, parameters to exclude bad lines from +function fits, and defining whether to refit the dispersion function as +opposed to simply determining a zero point shift. The defaults should +generally be adequate and the dispersion function fitting parameters may be +altered interactively. One should consult the help for the two tasks for +additional details of these parameters and the interactive operation of +\fBecidentify\fR. +.LP +Once the reference dispersion function is defined other arc spectra are +extracted as required by the object spectra. The assignment of arcs is +done either explicitly with an arc assignment table (parameter +\f(CWarctable\fR) or based on a header parameter such as a time. +This assignments are made by the task +\fBrefspectra\fR. When two arcs are assigned to an object spectrum an +interpolation is done between the two dispersion functions. This makes an +approximate correction for steady drifts in the dispersion. +.LP +The tasks \fBsetjd\fR and \fBsetairmass\fR are automatically run on all +spectra. This computes and adds the header parameters for the Julian date +(JD), the local Julian day number (LJD), the universal time (UTMIDDLE), and +the air mass at the middle of the exposure. The default arc assignment is +to use the Julian date grouped by the local Julian day number. The +grouping allows multiple nights of data to be correctly assigned at the +same time. +.LP +In non-quicklook mode the arc spectra assigned to each object are +extracted using the same apertures as the object. This accounts for +changes in the recentering, aperture sizes, and tracing functions. +In quicklook mode the arc spectra are extracted using the reference +apertures. When the same arc is used for several object images this +allows the arc spectrum to only be extracted once. +.LP +Defining the dispersion function for a new arc extraction is done with +the task \fBecreidentify\fR. This is done noninteractively with log +information recorded about the line reidentifications and the fit. +.LP +The last step of dispersion correction is setting the dispersion +of the object image from the arc images. There are two choices here. +If the \f(CWlinearize\fR parameter is not set the nonlinear dispersion +function is stored in the image header. Other IRAF tasks interpret +this information when dispersion coordinates are needed for plotting +or analysis. This has the advantage of not requiring the spectra +to be interpolated and the disadvantage that the dispersion +information is only understood by IRAF tasks and cannot be readily +exported to other analysis software. +.LP +If the \f(CWlinearize\fR parameter is set then the spectra are resampled to a +linear dispersion relation either in wavelength or the log of the +wavelength. For echelle spectra each order is linearized independently so +that the wavelength interval per pixel is different in different orders. +This preserves most of the resolution and avoids over or under sampling of +the highest or lowest dispersion orders. The wavelength limits are +taken from the limits determined from the arc reference spectrum and +the number of pixels is the same as the original images. The dispersion +per pixel is then derived from these constraints. +.LP +The linearization algorithm parameters allow selecting the interpolation +function type, whether to conserve flux per pixel by integrating across the +extent of the final pixel, and whether to linearize to equal linear or +logarithmic intervals. The latter may be appropriate for radial velocity +studies. The default is to use a fifth order polynomial for interpolation, +to conserve flux, and to not use logarithmic wavelength bins. These +parameters are described fully in the help for the task \fBdispcor\fR which +performs the correction. +.NH 2 +Flux Calibration +.LP +Flux calibration consists of an extinction correction and an instrumental +sensitivity calibration. The extinction correction only depends on the +extinction function defined by the package parameter \f(CWextinct\fR and +determination of the airmass from the header parameters (the air mass is +computed by \fBsetairmass\fR as mentioned earlier). The sensitivity +calibration depends on a sensitivity calibration spectrum determined from +standard star observations for which there are tabulated absolute fluxes. +The task that applies both the extinction correction and sensitivity +calibration to each extracted object spectrum is \fBcalibrate\fR. Consult +the manual page for this task for more information. +.LP +Generation of the sensitivity calibration spectrum is done before +processing any object spectra since it has two interactive steps and +requires all the standard star observations. The first step is tabulating +the observed fluxes over the same bandpasses as the calibrated absolute +fluxes. For very high resolution it may be the case that the measured +calibration bandpasses are too large or sparse. In this case one must +interpolate the calibration data to bandpasses appropriate for the data. +If the bandpass widths and separations are given as INDEF then the same +bandpasses as in the calibration file are used. Otherwise a uniform grid +of bandpasses is interpolated. Using interpolated bandpasses is not +rigorous but is sometimes the only choice for echelle spectra. +.LP +The standard star tabulations are done after each standard star is +extracted and dispersion corrected. You are asked for the name of the +standard star as tabulated in the absolute flux data files in the directory +\f(CWcaldir\fR defined by the package parameters. If the \f(CWinteract\fR +parameter is yes the bandpasses can be displayed on the data and you can +interactively add or delete bandpasses. The tabulation of the standard star +observations over the standard bandpasses is done by the task +\fBstandard\fR. The tabulated data is stored in the file \f(CWstd\fR. Note +that if the \f(CWredo\fR flag is not set any new standard stars specified in +subsequent executions of \fBdoecslit\fR are added to the previous data in +the data file, otherwise the file is first deleted. Modification of the +tabulated standard star data, such as by adding new stars, will cause any +spectra in the input list which have been previously calibrated to be +reprocessed if the \f(CWupdate\fR flag is set. +.LP +After the standard star calibration bandpass fluxes are tabulated the +information from all the standard stars is combined to produce a +sensitivity function for use by \fBcalibrate\fR. The sensitivity function +determination is interactive and uses the task \fBsensfunc\fR. This task +allows fitting a smooth sensitivity function to the ratio of the observed +to calibrated fluxes verses wavelength. The types of manipulations one +needs to do include deleting bad observations, possibly removing variable +extinction (for poor data), and possibly deriving a revised extinction +function. This is a complex operation and one should consult the manual +page for \fBsensfunc\fR. The sensitivity function is saved as one +dimensional spectra (one per order) with the root name \f(CWsens\fR. +Deletion of these images will also cause reprocessing to occur if the +\f(CWupdate\fR flag is set. +.NH +References +.NH 2 +IRAF Introductory References +.LP +Work is underway on a new introductory guide to IRAF. Currently, the +work below is the primary introduction. +.IP +P. Shames and D. Tody, \fIA User's Introduction to the IRAF Command +Language\fR, Central Computer Services, NOAO, 1986. +.NH 2 +CCD Reductions +.IP +F. Valdes, \fIThe IRAF CCD Reduction Package -- CCDRED\fR, Central +Computer Services, NOAO, 1987. +.IP +F. Valdes, \fIUser's Guide to the CCDRED Package\fR, Central +Computer Services, NOAO, 1988. Also on-line as \f(CWhelp ccdred.guide\fR. +.IP +P. Massey, \fIA User's Guide to CCD Reductions with IRAF\fR, Central +Computer Services, NOAO, 1989. +.NH 2 +Aperture Extraction Package +.IP +F. Valdes, \fIThe IRAF APEXTRACT Package\fR, Central Computer Services, +NOAO, 1987 (out-of-date). +.NH 2 +Task Help References +.LP +Each task in the \fBspecred\fR packages and tasks used by \fBdofibers\fR have +help pages describing the parameters and task in some detail. To get +on-line help type +.V1 + +cl> help \fItaskname\fR + +.V2 +The output of this command can be piped to \fBlprint\fR to make a printed +copy. + +.V1 + apall - Extract 1D spectra (all parameters in one task) + apdefault - Set the default aperture parameters and apidtable + 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 + + bplot - Batch plots of spectra + calibrate - Apply extinction and flux calibrations to spectra + continuum - Fit the continuum in spectra + deredden - Apply interstellar extinction corrections + dispcor - Dispersion correct spectra + dopcor - Doppler correct spectra + ecidentify - Identify features in spectrum for dispersion solution +ecreidentify - Automatically identify features in spectra + refspectra - Assign wavelength reference spectra to other spectra + sarith - Spectrum arithmetic + scombine - Combine spectra + scopy - Select and copy apertures in different spectral formats + sensfunc - Create sensitivity function + setairmass - Compute effective airmass and middle UT for an exposure + setjd - Compute and set Julian dates in images + slist - List spectrum header parameters + specplot - Stack and plot multiple spectra + splot - Preliminary spectral plot/analysis + standard - Identify standard stars to be used in sensitivity calc + + doecslit - Process Echelle slit spectra + demos - Demonstrations and tests + + Additional help topics + + onedspec.package - Package parameters and general description of package + apextract.package - Package parameters and general description of package + approfiles - Profile determination algorithms + apvariance - Extractions, variance weighting, cleaning, and noise model + center1d - One dimensional centering algorithm + icfit - Interactive one dimensional curve fitting + +.V2 +.SH +Appendix A: DOECSLIT Parameters +.LP +.nr PS 8 +.nr VS 10 +objects +.LS +List of object images to be processed. Previously processed spectra are +ignored unless the \f(CWredo\fR flag is set or the \f(CWupdate\fR flag is set +and dependent calibration data has changed. If the images contain the +keyword IMAGETYP then only those with a value of "object" or "OBJECT" +are used and those with a value of "comp" or "COMPARISON" are added +to the list of arcs. Extracted spectra are ignored. +.LE +apref = "" +.LS +Aperture reference spectrum. This spectrum is used to define the basic +extraction apertures and is typically a bright star spectrum. +.LE +arcs = "" (at least one if dispersion correcting) +.LS +List of arc calibration spectra. These spectra are used to define +the dispersion functions. The first spectrum is used to mark lines +and set the dispersion function interactively and dispersion functions +for all other arc spectra are derived from it. If the images contain +the keyword IMAGETYP then only those with a value of "comp" or +"COMPARISON" are used. All others are ignored as are extracted spectra. +.LE +arctable = "" (optional) (refspectra) +.LS +Table defining which arc spectra are to be assigned to which object +spectra (see \fBrefspectra\fR). If not specified an assignment based +on a header parameter, \f(CWsparams.sort\fR, such as the Julian date +is made. +.LE +standards = "" (at least one if flux calibrating) +.LS +List of standard star spectra. The standard stars must have entries in +the calibration database (package parameter \f(CWechelle.caldir\fR). +.LE + +readnoise = 0., gain = 1. (apsum) +.LS +Read out noise in photons and detector gain in photons per data value. +This parameter defines the minimum noise sigma and the conversion between +photon Poisson statistics and the data number statistics. Image header +keywords (case insensitive) may be specified to obtain the values from the +image header. +.LE +datamax = INDEF (apsum.saturation) +.LS +The maximum data value which is not a cosmic ray. +When cleaning cosmic rays and/or using variance weighted extraction +very strong cosmic rays (pixel values much larger than the data) can +cause these operations to behave poorly. If a value other than INDEF +is specified then all data pixels in excess of this value will be +excluded and the algorithms will yield improved results. +This applies only to the object spectra and not the standard star or +arc spectra. For more +on this see the discussion of the saturation parameter in the +\fBapextract\fR package. +.LE +norders = 10 (apfind) +.LS +Number of orders to be found automatically. +.LE +width = 5. (apedit) +.LS +Approximate full width of the spectrum profiles. This parameter is used +to define a width and error radius for the profile centering algorithm, +and defaults for the aperture limits and background regions. +.LE + +dispcor = yes +.LS +Dispersion correct spectra? This may involve either defining a nonlinear +dispersion coordinate system in the image header or resampling the +spectra to uniform linear wavelength coordinates as selected by +the parameter \f(CWsparams.linearize\fR. +.LE +extcor = no +.LS +Extinction correct the spectra? +.LE +fluxcal = no +.LS +Flux calibrate the spectra using standard star observations? +.LE +resize = no (apresize) +.LS +Resize the default apertures for each object based on the spectrum profile? +.LE +clean = no (apsum) +.LS +Detect and correct for bad pixels during extraction? This is the same +as the clean option in the \fBapextract\fR package. If yes this also +implies variance weighted extraction. In addition the datamax parameters +can be useful. +.LE +trace = yes (non-quicklook mode only) (aptrace) +.LS +Allow tracing each object spectrum separately? If not set then the trace +from the aperture reference is used, with recentering to allow for shifts +across the dispersion. If set then each object and standard star +image is retraced. Retracing is NOT done in quicklook mode. +.LE +background = "none" (apsum, apscatter) +.LS +Type of background light subtraction. The choices are "none" for no +background subtraction, "scattered" for a global scattered light +subtraction, "average" to average the background within background regions, +"median" to use the median in background regions, "minimum" to use the +minimum in background regions, or "fit" to fit across the dispersion using +the background within background regions. The scattered light option fits +and subtracts a smooth global background and modifies the input images. +This is a slow operation and so is NOT performed in quicklook mode. The +other background options are local to each aperture. The "fit" option uses +additional fitting parameters from \fBsparams\fR and the "scattered" option +uses parameters from \fBapscat1\fR and \fBapscat2\fR. +.LE +splot = no +.LS +Plot the final spectra? In quicklook mode a noninteractive, stacked plot +is automatically produced using the task \fBspecplot\fR while in +non-quicklook mode a query is given and the task \fBsplot\fR is used for +interactive plotting. +.LE +redo = no +.LS +Redo operations previously done? If no then previously processed spectra +in the objects list will not be processed unless required by the +update option. +.LE +update = no +.LS +Update processing of previously processed spectra if the aperture +reference image, the dispersion reference image, or standard star +calibration data are changed? +.LE +quicklook = no +.LS +Extract and calibrate spectra with minimal interaction? In quicklook mode +only aperture reference definitions, the initial dispersion function +solution, and the standard star setup are done interactively. Scattered +light subtraction and individual object tracing are not performed. +Normally the \f(CWsplot\fR option is set in this mode to produce an automatic +final spectrum plot for each object. It is recommended that this mode not be +used for final reductions. +.LE +batch = no +.LS +Process spectra as a background or batch job provided there are no interactive +steps remaining. +.LE +listonly = no +.LS +List processing steps but don't process? +.LE + +sparams = "" (pset) +.LS +Name of parameter set containing additional processing parameters. This +parameter is only for indicating the link to the parameter set +\fBsparams\fR and should not be given a value. The parameter set may be +examined and modified in the usual ways (typically with "epar sparams" +or ":e sparams" from the parameter editor). The parameters are +described below. +.LE + +.ce +-- GENERAL PARAMETERS -- + +line = INDEF, nsum = 10 +.LS +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, +editing, and tracing operations. A line of INDEF selects the middle of the +image along the dispersion axis. +.LE +extras = no (apsum) +.LS +Include raw unweighted and uncleaned spectra, the background spectra, and +the estimated sigma spectra in a three dimensional output image format. +See the discussion in the \fBapextract\fR package for further information. +.LE + +.ce +-- AUTOMATIC APERTURE RESIZING PARAMETERS -- + +ylevel = 0.05 (apresize) +.LS +Fraction of the peak to set aperture limits during automatic resizing. +.LE + +.ce +-- TRACE PARAMETERS -- + +t_step = 10 (aptrace) +.LS +Step along the dispersion axis between determination of the spectrum +positions. Note the \f(CWnsum\fR parameter is also used to enhance the +signal-to-noise at each step. +.LE +t_function = "spline3", t_order = 2 (aptrace) +.LS +Default trace fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.LE +t_niterate = 1, t_low = 3., t_high = 3. (aptrace) +.LS +Default number of rejection iterations and rejection sigma thresholds. +.LE + +.ce +-- BACKGROUND AND SCATTERED LIGHT PARAMETERS -- + +b_function = "legendre", b_order = 1 (apsum) +.LS +Default background fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.LE +b_naverage = -100 (apsum) +.LS +Default number of points to average or median. Positive numbers +average that number of sequential points to form a fitting point. +Negative numbers median that number, in absolute value, of sequential +points. A value of 1 does no averaging and each data point is used in the +fit. +.LE +b_niterate = 0 (apsum) +.LS +Default number of rejection iterations. If greater than zero the fit is +used to detect deviant fitting points and reject them before repeating the +fit. The number of iterations of this process is given by this parameter. +.LE +b_low_reject = 3., b_high_reject = 3. (apsum) +.LS +Default background lower and upper rejection sigmas. If greater than zero +points deviating from the fit below and above the fit by more than this +number of times the sigma of the residuals are rejected before refitting. +.LE +buffer = 1. (apscatter) +.LS +Buffer distance from the edge of any aperture for data to be included +in the scattered light determination. This parameter may be modified +interactively. +.LE +apscat1 = "", apscat2 = "" (apscatter) +.LS +Parameter sets for the fitting functions across and along the dispersion. +These parameters are those used by \fBicfit\fR. These parameters are +usually set interactively. +.LE + +.ce +-- APERTURE EXTRACTION PARAMETERS -- + +weights = "none" (apsum) (none|variance) +.LS +Type of extraction weighting. Note that if the \f(CWclean\fR parameter is +set then the weights used are "variance" regardless of the weights +specified by this parameter. The choices are: + +"none" +.LS +The pixels are summed without weights except for partial pixels at the +ends. +.LE +"variance" +.LS +The extraction is weighted by the variance based on the data values +and a poisson/ccd model using the \f(CWgain\fR and \f(CWreadnoise\fR +parameters. +.LE +.LE +pfit = "fit1d" (apsum and approfile) (fit1d|fit2d) +.LS +Type of profile fitting algorithm to use. The "fit1d" algorithm is +preferred except in cases of extreme tilt. +.LE +lsigma = 3., usigma = 3. (apsum) +.LS +Lower and upper rejection thresholds, given as a number of times the +estimated sigma of a pixel, for cleaning. +.LE + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- + +threshold = 10. (identify/reidentify) +.LS +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.LE +coordlist = "linelist$thar.dat" (ecidentify) +.LS +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelist$". +.LE +match = 1. (ecidentify) +.LS +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.LE +fwidth = 4. (ecidentify) +.LS +Approximate full base width (in pixels) of arc lines. +.LE +cradius = 10. (reidentify) +.LS +Radius from previous position to reidentify arc line. +.LE +i_function = "legendre", i_xorder = 3, i_yorder = 3 (ecidentify) +.LS +The default function, function order for the pixel position dependence, and +function order for the aperture number dependence to be fit to the arc +wavelengths. The functions choices are "chebyshev" or "legendre". +.LE +i_niterate = 3, i_low = 3.0, i_high = 3.0 (ecidentify) +.LS +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.LE +refit = yes (ecreidentify) +.LS +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the arc reference then a new +dispersion function of the same type as in the reference image is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised fitted coordinates without changing the +form of the dispersion function. +.LE + +.ce +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- + +select = "interp" (refspectra) +.LS +Selection method for assigning wavelength calibration spectra. +Note that an arc assignment table may be used to override the selection +method and explicitly assign arc spectra to object spectra. +The automatic selection methods are: + +average +.LS +Average two reference spectra without regard to any sort parameter. +If only one reference spectrum is specified then it is assigned with a +warning. If more than two reference spectra are specified then only the +first two are used and a warning is given. +This option is used to assign two reference spectra, with equal weights, +independent of any sorting parameter. +.LE +following +.LS +Select the nearest following spectrum in the reference list based on the +sorting parameter. If there is no following spectrum use the nearest preceding +spectrum. +.LE +interp +.LS +Interpolate between the preceding and following spectra in the reference +list based on the sorting parameter. If there is no preceding and following +spectrum use the nearest spectrum. The interpolation is weighted by the +relative distances of the sorting parameter. +.LE +match +.LS +Match each input spectrum with the reference spectrum list in order. +This overrides the reference aperture check. +.LE +nearest +.LS +Select the nearest spectrum in the reference list based on the sorting +parameter. +.LE +preceding +.LS +Select the nearest preceding spectrum in the reference list based on the +sorting parameter. If there is no preceding spectrum use the nearest following +spectrum. +.LE +.LE +sort = "jd" (setjd and refspectra) +.LS +Image header keyword to be used as the sorting parameter for selection +based on order. The header parameter must be numeric but otherwise may +be anything. Common sorting parameters are times or positions. +.LE +group = "ljd" (setjd and refspectra) +.LS +Image header keyword to be used to group spectra. For those selection +methods which use the group parameter the reference and object +spectra must have identical values for this keyword. This can +be anything but it must be constant within a group. Common grouping +parameters are the date of observation "date-obs" (provided it does not +change over a night) or the local Julian day number. +.LE +time = no, timewrap = 17. (refspectra) +.LS +Is the sorting parameter a 24 hour time? If so then the time origin +for the sorting is specified by the timewrap parameter. This time +should precede the first observation and follow the last observation +in a 24 hour cycle. +.LE + +.ce +-- DISPERSION CORRECTION PARAMETERS -- + +linearize = yes (dispcor) +.LS +Interpolate the spectra to a linear dispersion sampling? If yes the +spectra will be interpolated to a linear or log linear sampling using +the linear dispersion parameters specified by other parameters. If +no the nonlinear dispersion function(s) from the dispersion function +database are assigned to the input image world coordinate system +and the spectral data is not interpolated. Note the interpolation +function type is set by the package parameter \f(CWinterp\fR. +.LE +log = no (ecdispcor) +.LS +Use linear logarithmic wavelength coordinates? Linear logarithmic +wavelength coordinates have wavelength intervals which are constant +in the logarithm of the wavelength. +.LE +flux = yes (ecdispcor) +.LS +Conserve the total flux during interpolation? If \f(CWno\fR the output +spectrum is interpolated from the input spectrum at each output +wavelength coordinate. If \f(CWyes\fR the input spectrum is integrated +over the extent of each output pixel. This is slower than +simple interpolation. +.LE + +.ce +-- SENSITIVITY CALIBRATION PARAMETERS -- + +bandwidth = 10., bandsep = 10. (standard) +.LS +Interpolated bandpass grid. If INDEF then the same bandpasses as in the +calibration files are used otherwise the calibration data is interpolated +to the specified set of bandpasses. +.LE +s_interact = yes (standard) +.LS +Display the bandpasses on the standard star data and allow interactive +addition and deletion of bandpasses. +.LE +s_function = "spline3", s_order = 1 (sensfunc) +.LS +Function and order used to fit the sensitivity data. The function types are +"chebyshev" polynomial, "legendre" polynomial, "spline3" cubic spline, +and "spline1" linear spline. +Order of the sensitivity fitting function. The value corresponds to the +number of polynomial terms or the number of spline pieces. The default +values may be changed interactively. +.LE +fnu = no (calibrate) +.LS +The default calibration is into units of F-lambda. If \f(CWfnu\fR = yes then +the calibrated spectrum will be in units of F-nu. +.LE + +.ce +PACKAGE PARAMETERS + +dispaxis = 2 +.LS +Default dispersion axis. The dispersion axis is 1 for dispersion +running along image lines and 2 for dispersion running along image +columns. If the image header parameter DISPAXIS is defined it has +precedence over this parameter. The default value defers to the +package parameter of the same name. +.LE +extinction = "onedstds$kpnoextinct.dat" (standard, sensfunc, calibrate) +.LS +Extinction file for a site. There are two extinction files in the +NOAO standards library, onedstds$, for KPNO and CTIO. These extinction +files are used for extinction and flux calibration. +.LE +caldir (standard) +.LS +Standard star calibration directory. A directory containing standard +star data files. Note that the directory name must end with '/'. +There are a number of standard star calibrations directories in the NOAO +standards library, onedstds$. +.LE +observatory = "observatory" (observatory) +.LS +The default observatory to use for latitude dependent computations. +If the OBSERVAT keyword in the image header it takes precedence over +this parameter. +.LE +interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) (dispcor) +.LS +Spectrum interpolation type used when spectra are resampled. The choices are: + +.V1 + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.V2 +.LE +database = "database" +.LS +Database name used by various tasks. This is a directory which is created +if necessary. +.LE +verbose = no +.LS +Verbose output? If set then almost all the information written to the +logfile is also written to the terminal except when the task is a +background or batch process. +.LE +logfile = "logfile" +.LS +If specified detailed text log information is written to this file. +.LE +plotfile = "" +.LS +If specified metacode plots are recorded in this file for later review. +Since plot information can become large this should be used only if +really desired. +.LE + +.ce +ENVIRONMENT PARAMETERS +.LP +The environment parameter \fIimtype\fR is used to determine the extension +of the images to be processed and created. This allows use with any +supported image extension. For STF images the extension has to be exact; +for example "d1h". diff --git a/noao/imred/echelle/doc/dofoe.hlp b/noao/imred/echelle/doc/dofoe.hlp new file mode 100644 index 00000000..6dfab76a --- /dev/null +++ b/noao/imred/echelle/doc/dofoe.hlp @@ -0,0 +1,1155 @@ +.help dofoe Feb93 noao.imred.echelle +.ih +NAME +dofoe -- Fiber Optic Echelle (FOE) data reduction task +.ih +USAGE +dofoe objects +.ih +SUMMARY +The \fBdofoe\fR reduction task is specialized for scattered light +subtraction, extraction, flat fielding, and wavelength calibration of Fiber +Optic Echelle (FOE) spectra. There may be one fiber or two fibers where +the second fiber is illuminated by an arc calibration during arc and object +exposures and a flat field during flat field exposures. It is a command +language script which collects and combines the functions and parameters of +many general purpose tasks to provide a single complete data reduction +path. The task provides a degree of guidance, automation, and record +keeping necessary when dealing with the complexities of reducing this type +of data. +.ih +PARAMETERS +.ls objects +List of object spectra to be processed. Previously processed spectra are +ignored unless the \fIredo\fR flag is set or the \fIupdate\fR flag is set and +dependent calibration data has changed. Extracted spectra are ignored. +.le +.ls apref = "" +Aperture reference spectrum. This spectrum is used to define the basic +extraction apertures and is typically a flat field spectrum. +.le +.ls flat = "" (optional) +Flat field spectrum. If specified the one dimensional flat field spectrum +is extracted and used to make flat field calibrations. +.le +.ls arcs = "" (at least one if dispersion correcting) +List of arc spectra. The first arc in the list is used to create a +dispersion solution interactively. All other arc spectra will be +automatically reidentified. +.le +.ls arctable = "" (optional) (refspectra) +Table defining arc spectra to be assigned to object spectra (see +\fBrefspectra\fR). If not specified an assignment based on a header +parameter, \fIparams.sort\fR, such as the observation time is made. +.le + +.ls readnoise = "0." (apsum) +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." (apsum) +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 datamax = INDEF (apsum.saturation) +The maximum data value which is not a cosmic ray. +When cleaning cosmic rays and/or using variance weighted extraction +very strong cosmic rays (pixel values much larger than the data) can +cause these operations to behave poorly. If a value other than INDEF +is specified then all data pixels in excess of this value will be +excluded and the algorithms will yield improved results. +This applies only to the object spectra and not the flat field or +arc spectra. For more +on this see the discussion of the saturation parameter in the +\fBapextract\fR package. +.le +.ls norders = 12 (apfind) +Number of orders to be found. This number is used during the automatic +definition of the apertures from the aperture reference spectrum. Note +that when there is a second fiber for simultaneous arcs the specified +number will be automatically doubled for finding both sets of orders. +So in either case specify only the number of orders from a single fiber. +The interactive review of the aperture assignments allows verification +and adjustments to the automatic aperture definitions. +.le +.ls width = 4. (apedit) +Approximate base full width of the fiber profiles. This parameter is used +for the profile centering algorithm. +.le +.ls arcaps = "2x2" +When there is only a single fiber set this parameter to "". When there is +a second fiber used to create simultaneous arcs during the object exposures +this parameter specifies a list of aperture numbers for the arc fibers. +Since the object and arc fiber orders are paired the default setting +expects the even number apertures to be the are apertures. This should be +checked interactively. +.le + +.ls fitflat = yes (flat1d) +Fit and divide the extracted flat field orders by a smooth function +in order to normalize the wavelength response? If not done the flat field +spectral shape (which includes the blaze function) will be divided +out of the object spectra, thus altering the object data values. +If done only the small scale response variations are included in the +flat field and the object spectra will retain their observed flux +levels and blaze function. +.le +.ls background = "none" (apsum, apscatter) +Type of background light subtraction. The choices are "none" for no +background subtraction, "scattered" for a global scattered light +subtraction, "average" to average the background within background regions, +"median" to use the median in background regions, "minimum" to use the +minimum in background regions, or "fit" to fit across the dispersion using +the background within background regions. The scattered light option fits +and subtracts a smooth global background and modifies the input images. +This is a slow operation and so is NOT performed in quicklook mode. The +other background options are local to each aperture at each point along the +dispersion. The "fit" option uses additional fitting parameters from +\fBparams\fR and the "scattered" option uses parameters from \fBapscat1\fR +and \fBapscat2\fR. +.le +.ls clean = yes (apsum) +Detect and correct for bad pixels during extraction? This is the same +as the clean option in the \fBapextract\fR package. If yes this also +implies variance weighted extraction and requires reasonably good values +for the readout noise and gain. In addition the datamax parameters +can be useful. +.le +.ls dispcor = yes +Dispersion correct spectra? Depending on the \fIparams.linearize\fR +parameter this may either resample the spectra or insert a dispersion +function in the image header. +.le +.ls redo = no +Redo operations previously done? If no then previously processed spectra +in the objects list will not be processed (unless they need to be updated). +.le +.ls update = no +Update processing of previously processed spectra if aperture, flat +field, or dispersion reference definitions are changed? +.le +.ls batch = no +Process spectra as a background or batch job. +.le +.ls listonly = no +List processing steps but don't process? +.le + +.ls params = "" (pset) +Name of parameter set containing additional processing parameters. The +default is parameter set \fBparams\fR. The parameter set may be examined +and modified in the usual ways (typically with "epar params" or ":e params" +from the parameter editor). Note that using a different parameter file +is not allowed. The parameters are described below. +.le + +.ce +-- PACKAGE PARAMETERS + +Package parameters are those which generally apply to all task in the +package. This is also true of \fBdofoe\fR. +.ls observatory = "observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. For FOE data the image headers +identify the observatory as "kpno" so this parameter is not used. +For data from other observatories this parameter may be used +as describe in \fBobservatory\fR. +.le +.ls interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) +Spectrum interpolation type used when spectra are resampled. The choices are: + +.nf + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.fi +.le +.ls dispaxis = 2 +Default dispersion axis. The dispersion axis is 1 for dispersion +running along image lines and 2 for dispersion running along image +columns. If the image header parameter DISPAXIS is defined it has +precedence over this parameter. +.le +.ls database = "database" +Database (directory) used for storing aperture and dispersion information. +.le +.ls verbose = no +Print verbose information available with various tasks. +.le +.ls logfile = "logfile", plotfile = "" +Text and plot log files. If a filename is not specified then no log is +kept. The plot file contains IRAF graphics metacode which may be examined +in various ways such as with \fBgkimosaic\fR. +.le +.ls records = "" +Dummy parameter to be ignored. +.le +.ls version = "ECHELLE: ..." +Version of the package. +.le + +.ce +PARAMS PARAMETERS + +The following parameters are part of the \fBparams\fR parameter set and +define various algorithm parameters for \fBdofoe\fR. + +.ce +-- GENERAL PARAMETERS -- +.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, +editing, and tracing operations. A line of INDEF selects the middle of the +image along the dispersion axis. +.le +.ls extras = no (apsum) +Include extra information in the output spectra? When cleaning or using +variance weighting the cleaned and weighted spectra are recorded in the +first 2D plane of a 3D image, the raw, simple sum spectra are recorded in +the second plane, and the estimated sigmas are recorded in the third plane. +.le + +.ce +-- DEFAULT APERTURE LIMITS -- +.ls lower = -3., upper = 3. (apdefault) +Default lower and upper aperture limits relative to the aperture center. +These limits are used when the apertures are first found and may be +resized automatically or interactively. +.le + +.ce +-- AUTOMATIC APERTURE RESIZING PARAMETERS -- +.ls ylevel = 0.05 (apresize) +Data level at which to set aperture limits during automatic resizing. +It is a fraction of the peak relative to a local background. +.le + +.ce +-- TRACE PARAMETERS -- +.ls t_step = 10 (aptrace) +Step along the dispersion axis between determination of the spectrum +positions. Note the \fInsum\fR parameter is also used to enhance the +signal-to-noise at each step. +.le +.ls t_function = "spline3", t_order = 2 (aptrace) +Default trace fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.le +.ls t_niterate = 1, t_low = 3., t_high = 3. (aptrace) +Default number of rejection iterations and rejection sigma thresholds. +.le + +.ce +-- DEFAULT BACKGROUND PARAMETERS -- +.ls buffer = 1. (apscatter) +Buffer distance from the edge of any aperture for data to be included +in the scattered light determination. This parameter may be modified +interactively. +.le +.ls apscat1 = "", apscat2 = "" (apscatter) +Parameter sets for the fitting functions across and along the dispersion. +These parameters are those used by \fBicfit\fR. These parameters are +usually set interactively. +.le +.ls b_function = "legendre", b_order = 1 (apsum) +Default background fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.le +.ls b_naverage = -100 (apsum) +Default number of points to average or median. Positive numbers +average that number of sequential points to form a fitting point. +Negative numbers median that number, in absolute value, of sequential +points. A value of 1 does no averaging and each data point is used in the +fit. +.le +.ls b_niterate = 0 (apsum) +Default number of rejection iterations. If greater than zero the fit is +used to detect deviant fitting points and reject them before repeating the +fit. The number of iterations of this process is given by this parameter. +.le +.ls b_low_reject = 3., b_high_reject = 3. (apsum) +Default background lower and upper rejection sigmas. If greater than zero +points deviating from the fit below and above the fit by more than this +number of times the sigma of the residuals are rejected before refitting. +.le +.ls b_smooth = 10 (apsum) +Box car smoothing length for background when using background +subtraction. Since the background noise is often the limiting factor +for good extraction one may box car smooth the background to improve the +statistics. +.le + + +.ce +-- APERTURE EXTRACTION PARAMETERS -- +.ls weights = "none" (apsum) +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" (apsum) (fit1d|fit2d) +Profile fitting algorithm for cleaning and variance weighted extractions. +The default is generally appropriate for FOE data but users +may try the other algorithm. See \fBapprofiles\fR for further information. +.le +.ls lsigma = 3., usigma = 3. (apsum) +Lower and upper rejection thresholds, given as a number of times the +estimated sigma of a pixel, for cleaning. +.le + +.ce +-- FLAT FIELD FUNCTION FITTING PARAMETERS -- +.ls f_interactive = no (fit1d) +Fit the one dimensional flat field order spectra interactively? +This is used if \fIfitflat\fR is set and a two dimensional flat field +spectrum is specified. +.le +.ls f_function = "spline3", f_order = 20 (fit1d) +Function and order used to fit the composite one dimensional flat field +spectrum. The functions are "legendre", "chebyshev", "spline1", and +"spline3". The spline functions are linear and cubic splines with the +order specifying the number of pieces. +.le + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- +.ls threshold = 10. (identify/reidentify) +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.le +.ls coordlist = "linelist$thar.dat" (ecidentify) +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelist$". +.le +.ls match = 1. (ecidentify) +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.le +.ls fwidth = 4. (ecidentify) +Approximate full base width (in pixels) of arc lines. +.le +.ls cradius = 4. (reidentify) +Radius from previous position to reidentify arc line. +.le +.ls i_function = "chebyshev", i_xorder = 3, i_yorder = 3 (ecidentify) +The default function, function order for the pixel position dependence, and +function order for the aperture number dependence to be fit to the arc +wavelengths. The functions choices are "chebyshev" or "legendre". +.le +.ls i_niterate = 3, i_low = 3.0, i_high = 3.0 (ecidentify) +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.le +.ls refit = yes (ecreidentify) +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the arc reference then a new +dispersion function of the same type as in the reference image is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised fitted coordinates without changing the +form of the dispersion function. +.le + +.ce +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- +.ls select = "interp" (refspectra) +Selection method for assigning wavelength calibration spectra. +Note that an arc assignment table may be used to override the selection +method and explicitly assign arc spectra to object spectra. +The automatic selection methods are: +.ls average +Average two reference spectra without regard to any sort parameter. +If only one reference spectrum is specified then it is assigned with a +warning. If more than two reference spectra are specified then only the +first two are used and a warning is given. +This option is used to assign two reference spectra, with equal weights, +independent of any sorting parameter. +.le +.ls following +Select the nearest following spectrum in the reference list based on the +sorting parameter. If there is no following spectrum use the nearest preceding +spectrum. +.le +.ls interp +Interpolate between the preceding and following spectra in the reference +list based on the sorting parameter. If there is no preceding and following +spectrum use the nearest spectrum. The interpolation is weighted by the +relative distances of the sorting parameter. +.le +.ls match +Match each input spectrum with the reference spectrum list in order. +This overrides the reference aperture check. +.le +.ls nearest +Select the nearest spectrum in the reference list based on the sorting +parameter. +.le +.ls preceding +Select the nearest preceding spectrum in the reference list based on the +sorting parameter. If there is no preceding spectrum use the nearest following +spectrum. +.le +.le +.ls sort = "jd", group = "ljd" (refspectra) +Image header keywords to be used as the sorting parameter for selection +based on order and to group spectra. +A null string, "", or the word "none" may be use to disable the sorting +or grouping parameters. +The sorting parameter +must be numeric but otherwise may be anything. The grouping parameter +may be a string or number and must simply be the same for all spectra within +the same group (say a single night). +Common sorting parameters are times or positions. +In \fBdofoe\fR the Julian date (JD) and the local Julian day number (LJD) +at the middle of the exposure are automatically computed from the universal +time at the beginning of the exposure and the exposure time. Also the +parameter UTMIDDLE is computed. +.le +.ls time = no, timewrap = 17. (refspectra) +Is the sorting parameter a 24 hour time? If so then the time origin +for the sorting is specified by the timewrap parameter. This time +should precede the first observation and follow the last observation +in a 24 hour cycle. +.le + +.ce +-- DISPERSION CORRECTION PARAMETERS -- +.ls linearize = yes (dispcor) +Interpolate the spectra to a linear dispersion sampling? If yes the +spectra will be interpolated to a linear or log linear sampling +If no the nonlinear dispersion function(s) from the dispersion function +database are assigned to the input image world coordinate system +and the spectral data are not interpolated. +.le +.ls log = no (dispcor) +Use linear logarithmic wavelength coordinates? Linear logarithmic +wavelength coordinates have wavelength intervals which are constant +in the logarithm of the wavelength. +.le +.ls flux = yes (dispcor) +Conserve the total flux during interpolation? If \fIno\fR the output +spectrum is interpolated from the input spectrum at each output +wavelength coordinate. If \fIyes\fR the input spectrum is integrated +over the extent of each output pixel. This is slower than +simple interpolation. +.le +.ih +ENVIRONMENT PARAMETERS +The environment parameter \fIimtype\fR is used to determine the extension +of the images to be processed and created. This allows use with any +supported image extension. For STF images the extension has to be exact; +for example "d1h". +.ih +DESCRIPTION +The \fBdofoe\fR reduction task is specialized for scattered light +subtraction, extraction, flat fielding, and wavelength calibration of Fiber +Optic Echelle (FOE) spectra. There may be one fiber or two fibers where +the second fiber is illuminated by an arc calibration during arc and object +exposures and a flat field during flat field exposures. When there is +just one fiber the parameter \fIarcaps\fR is set to "" and when there are +two fibers the parameter is used to select which of the defined +apertures are the orders from the simultaneous arc fiber. + +This task is a command language script which collects and combines the +functions and parameters of many general purpose tasks to provide a single +complete data reduction path. The task provides a degree of guidance, +automation, and record keeping necessary when dealing with the complexities +of reducing this type of data. + +The general organization of the task is to do the interactive setup steps +first using representative calibration data and then perform the majority +of the reductions automatically, possibly as a background process, with +reference to the setup data. In addition, the task determines which setup +and processing operations have been completed in previous executions of the +task and, contingent on the \fIredo\fR and \fIupdate\fR options, skip or +repeat some or all the steps. + +The description is divided into a quick usage outline followed by details +of the parameters and algorithms. The usage outline is provided as a +checklist and a refresher for those familiar with this task and the +component tasks. It presents only the default or recommended usage. Since +\fBdofoe\fR combines many separate, general purpose tasks the description +given here refers to these tasks and leaves some of the details to their +help documentation. + +\fBUsage Outline\fR + +.ls 6 [1] +The images must first be processed with \fBccdproc\fR for overscan, +bias, and dark corrections. +.le +.ls [2] +Set the \fBdofoe\fR parameters with \fBeparam\fR. Specify the object +images to be processed, the flat field image as the aperture reference and +the flat field, and one or more arc images. If there are many +object or arc spectra per setup you might want to prepare "@ files". +Verify and set the format parameters, particularly the number of orders to be +extracted and processed. The processing parameters are set +for simple extraction and dispersion correction but dispersion correction +can be turned off for quicklook or background subtraction and cleaning +may be added. +.le +.ls [3] +Run the task. This may be repeated multiple times with different +observations and the task will generally only do the setup steps +once and only process new images. Queries presented during the +execution for various interactive operations may be answered with +"yes", "no", "YES", or "NO". The lower case responses apply just +to that query while the upper case responses apply to all further +such queries during the execution and no further queries of that +type will be made. +.le +.ls [4] +The apertures are defined using the specified aperture reference image +which is usually a flat field in which both the object and arc fibers are +illuminated. The specified number of orders are found automatically and +sequential apertures assigned. The resize option sets the aperture size to +the widths of the profiles at a fixed fraction of the peak height. +.le +.ls [5] +The automatic order identification and aperture assignment is based on peak +height and may be incorrect. The interactive aperture editor is entered +with a plot of the apertures. When there is a second simultaneous arc +fiber it is essential that the object and arc +fiber orders are properly paired with the arc fibers having even aperture +numbers and the object fibers having odd aperture numbers. It is also +required that no orders be skipped in the region of interest. Missing +orders are added with the 'm' key. Once all orders have been marked the +aperture numbers are resequenced with 'o'. If local background subtraction +is selected the background regions should be checked with the 'b' key. +Preceding this with the 'a' key allows any changes to the background +regions to be applied to all orders. To exit type 'q'. +.le +.ls [6] +The order positions at a series of points along the dispersion are measured +and a function is fit to these positions. This may be done interactively to +adjust the fitting parameters. Not all orders need be examined and the "NO" +response will quit the interactive fitting. To exit the interactive +fitting type 'q'. +.le +.ls [7] +If flat fielding is to be done the flat field spectra are extracted. A +smooth function is fit to each flat field spectrum to remove the large +scale spectral signature. The final response spectra are normalized to a +unit mean over all fibers. +.le +.ls [8] +If scattered light subtraction is selected the scattered light parameters +are set using the aperture reference image and the task \fBapscatter\fR. +The purpose of this is to interactively define the aperture buffer distance +for the scattered light and the cross and parallel dispersion fitting +parameters. The fitting parameters are taken from and recorded in the +parameter sets \fBapscat1\fR and \fBapscat2\fR. All other scattered light +subtractions are done noninteractively with these parameters. Note that +the scattered light correction modifies the input images. +.le +.ls [9] +If dispersion correction is selected the first arc in the arc list is +extracted. One fiber is used to identify the arc lines and define the +dispersion function using the task \fBecidentify\fR. Identify a few arc +lines in a few orders with 'm' and 'k' or 'o', use the 'l' line list +identification command to automatically add additional lines and fit the +dispersion function. Check the quality of the dispersion function fit +with 'f'. When satisfied exit with 'q'. +.le +.ls [10] +If there is a second fiber the dispersion function is automatically +determined using the task \fBecreidentify\fR. +.le +.ls [11] +The arc reference spectrum is dispersion corrected. +If the spectra are resampled to a linear dispersion system +(which will be the same for all spectra) the dispersion parameters +determined from the dispersion solution are printed. +.le +.ls [12] +The object spectra are now automatically background subtracted (an +alternative to scattered light subtraction), extracted, flat fielded, +and dispersion corrected. Any new dispersion function reference arcs +assigned to the object images are automatically extracted and +dispersion functions determined. A zero point wavelength correction +is computed from the simultaneous arc fiber spectrum and applied to +the object spectrum if orders from the second fiber have been identified +with the \fIarcaps\fR parameter. +.le +.ls [13] +The final spectra will have the same name as the original 2D images +with a ".ec" extension added. +.le + +\fBSpectra and Data Files\fR + +The basic input consists of single or dual fiber FOE object and calibration +spectra stored as IRAF images. The \fIarcaps\fR parameter is used to +discriminate between the two cases. The type of image format is defined by +the environment parameter \fIimtype\fR. Only images with that extension +will be processed and created. The raw CCD images must be processed to +remove overscan, bias, and dark count effects. This is generally done +using the \fBccdred\fR package. Flat fielding is generally not done at +this stage but as part of \fBdofoe\fR. The calibration spectra are flat +field observations in all fibers, comparison arc lamp spectra in all +fibers, and, for dual fiber model, arc spectra in one fiber while the +second fiber observes the object. If for some reason the flat field or +calibration arc spectra have separate exposures for the two fibers the +separate exposures may simply be added. + +The assignment of arc calibration exposures to object exposures is +generally done by selecting the nearest in time and interpolating. +However, the optional \fIarc assignment table\fR may be used to explicitly +assign arc images to specific objects. The format of this file is +described in the task \fBrefspectra\fR. + +The final reduced spectra are recorded in two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ec" extension. Each line in the reduced image is a one dimensional +spectrum (an echelle order) with associated aperture and wavelength +information. When the \fIextras\fR parameter is set the lines in the +third dimension contain additional information (see +\fBapsum\fR for further details). These spectral formats are accepted by the +one dimensional spectroscopy tasks such as the plotting tasks \fBsplot\fR +and \fBspecplot\fR. The special task \fBscopy\fR may be used to extract +specific apertures or to change format to individual one dimensional +images. The task \fBscombine\fR is used to combine or merge orders into +a single spectrum. + +\fBPackage Parameters\fR + +The \fBechelle\fR package parameters set parameters affecting all the tasks +in the package. Some of the parameters are not applicable to the +\fBdofoe\fR task. The observatory parameter is only required for data +without an OBSERVAT header parameter (currently included in NOAO data). +The spectrum interpolation type might be changed to "sinc" but with the +cautions given in \fBonedspec.package\fR. The dispersion axis parameter is +only needed if a DISPAXIS image header parameter is not defined. The other +parameters define the standard I/O functions. The verbose parameter +selects whether to print everything which goes into the log file on the +terminal. It is useful for monitoring what the \fBdofoe\fR task does. The +log and plot files are useful for keeping a record of the processing. A +log file is highly recommended. A plot file provides a record of +apertures, traces, and extracted spectra but can become quite large. +The plotfile is most conveniently viewed and printed with \fBgkimosaic\fR. + +\fBProcessing Parameters\fR + +The input images are specified by image lists. The lists may be +a list of explicit, comma separate image names, @ files, or image +templates using pattern matching against file names in the directory. +The aperture reference spectrum is used to find the orders and trace +them. Thus, this requires an image with good signal in both fibers +which usually means a flat field spectrum. It is recommended that +flat field correction be done using one dimensional extracted spectra +rather than as two dimensional images. This is done if a flat field +spectrum is specified. The arc assignment table is used to specifically +assign arc spectra to particular object spectra and the format +of the file is described in \fBrefspectra\fR. + +The detector read out noise and gain are used for cleaning and variance +(optimal) extraction. The dispersion axis defines the wavelength direction +of spectra in the image if not defined in the image header by the keyword +DISPAXIS. The width parameter (in pixels) is used for the profile +centering algorithm (\fBcenter1d\fR). + +The number of orders selects the number of orders for a single +fiber and "pairs" of object and arc +fiber profiles for dual fibers. The number specified will be +automatically found based on the strongest peaks. +In the dual fiber case it is important that both elements of a pair be found, +so no orders be skipped, and the aperture numbers must be sequential with +arc profiles having even aperture numbers and object profiles having +odd numbers in the region of interest, the automatic identification is +just a starting point for the interactive review. The even/odd +relationship between object and arc profiles is set by the \fIarcaps\fR +parameter and so may be reversed if desired. + +The next set of parameters select the processing steps and options. The +flat fitting option allows fitting and removing the overall shape of the +flat field spectra while preserving the pixel-to-pixel response +corrections. This is useful for maintaining the approximate object count +levels, including the blaze function, and not introducing the reciprocal of +the flat field spectrum into the object spectra. If not selected the flat +field will remove the blaze function from the observations and introduce +some wavelength dependence from the flat field lamp spectrum. + +The \fIbackground\fR option selects the type of correction for background or +scattered light. If the type is "scattered" a global scattered light is +fit to the data between the apertures and subtracted from the images. +\fINote that the input images are modified by this operation\fR. This +option is slow. Alternatively, a local background may be subtracted using +background regions defined for each aperture. The data in the regions may +be averaged, medianed, or the minimum value used. Another choice is to fit +the data in the background regions by a function and interpolate to the +object aperture. + +The \fIclean\fR option invokes a profile fitting and deviant point rejection +algorithm as well as a variance weighting of points in the aperture. These +options require knowing the effective (i.e. accounting for any image +combining) read out noise and gain. For a discussion of cleaning and +variance weighted extraction see \fBapvariance\fR and \fBapprofiles\fR. + +The dispersion correction option selects whether to extract arc spectra, +determine a dispersion function, assign them to the object spectra, and, +possibly, resample the spectra to a linear (or log-linear) wavelength +scale. + +Generally once a spectrum has been processed it will not be reprocessed if +specified as an input spectrum. However, changes to the underlying +calibration data can cause such spectra to be reprocessed if the +\fIupdate\fR flag is set. The changes which will cause an update are a new +reference image, new flat field, adding the scattered light option, and a +new arc reference image. If all input spectra are to be processed +regardless of previous processing the \fIredo\fR flag may be used. Note +that reprocessing clobbers the previously processed output spectra. + +The \fIbatch\fR processing option allows object spectra to be processed as +a background or batch job. The \fIlistonly\fR option prints a summary of +the processing steps which will be performed on the input spectra without +actually doing anything. This is useful for verifying which spectra will +be affected if the input list contains previously processed spectra. The +listing does not include any arc spectra which may be extracted to +dispersion calibrate an object spectrum. + +The last parameter (excluding the task mode parameter) points to another +parameter set for the algorithm parameters. The way \fBdofoe\fR works +this may not have any value and the parameter set \fBparams\fR is always +used. The algorithm parameters are discussed further in the next section. + +\fBAlgorithms and Algorithm Parameters\fR + +This section summarizes the various algorithms used by the \fBdofoe\fR +task and the parameters which control and modify the algorithms. The +algorithm parameters available to the user are collected in the parameter +set \fBparams\fR. These parameters are taken from the various general +purpose tasks used by the \fBdofoe\fR processing task. Additional +information about these parameters and algorithms may be found in the help +for the actual task executed. These tasks are identified in the parameter +section listing in parenthesis. The aim of this parameter set organization +is to collect all the algorithm parameters in one place separate from the +processing parameters and include only those which are relevant for +FOE data. The parameter values can be changed from the +defaults by using the parameter editor, +.nf + + cl> epar params + +.fi +or simple typing \fIparams\fR. The parameter editor can also be +entered when editing the \fBdofoe\fR parameters by typing \fI:e +params\fR or simply \fI:e\fR if positioned at the \fIparams\fR +parameter. + +\fBAperture Definitions\fR + +The first operation is to define the extraction apertures, which include the +aperture width, background regions, and position dependence with +wavelength, for the object and arc orders of interest. This is done +on a reference spectrum which is usually a flat field taken through +all fibers. Other spectra will inherit the reference apertures and +apply a correction for any shift of the orders across the dispersion. +The reference apertures are defined only once unless the \fIredo\fR +option is set. + +The selected number of orders are found automatically by selecting the +highest peaks in a cut across the dispersion. Note that the specified +number of orders is multiplied by two in defining the apertures when +there is a second fiber. Apertures +are assigned with a limits set by the \fIlower\fR and +\fIupper\fR parameter and numbered sequentially. A query is then +given allowing the aperture limits to be "resized" based on the profile +itself (see \fBapresize\fR). + +A cut across the orders is then shown with the apertures marked and +an interactive aperture editing mode is entered (see \fBapedit\fR). +For \fBdofoe\fR the aperture identifications and numbering is particularly +critical. When there is a single fiber the aperture numbers must +be sequential with the order numbers. If an order is skipped then the +aperture number must also be skipped. + +For dual fibers all "pairs" of object and arc orders in the region of +interest must be defined without skipping any orders. The orders must +also be numbered sequentially (though the direction does not matter) +so that the arc apertures are either all even or all odd as defined +by the \fIarcaps\fR parameter (the default is even numbers for the +arc apertures). The 'o' key will provide the necessary reordering. + +If local background subtraction is used the background regions should +also be checked with the 'b' key. Typically one adjusts all +the background regions at the same time by selecting all apertures with +the 'a' key first. To exit the background and aperture editing steps type +'q'. + +Next the positions of the orders at various points along the dispersion are +measured and "trace functions" are fit. The user is asked whether to fit +each trace function interactively. This is selected to adjust the fitting +parameters such as function type and order. When interactively fitting a +query is given for each aperture. After the first aperture one may skip +reviewing the other traces by responding with "NO". Queries made by +\fBdofoe\fR generally may be answered with either lower case "yes" or "no" +or with upper case "YES" or "NO". The upper case responses apply to all +further queries and so are used to eliminate further queries of that kind. + +The above steps are all performed using tasks from the \fBapextract\fR +package and parameters from the \fBparams\fR parameters. As a quick +summary, the dispersion direction of the spectra are determined from the +package \fBdispaxis\fR parameter if not defined in the image header. The +default line or column for finding the orders and the number of image lines +or columns to sum are set by the \fIline\fR and \fInsum\fR parameters. A +line of INDEF (the default) selects the middle of the image. The automatic +finding algorithm is described for the task \fBapfind\fR and basically +finds the strongest peaks. The resizing is described in the task +\fBapresize\fR and the parameters used are also described there and +identified in the PARAMETERS section. The tracing is done as described in +\fBaptrace\fR and consists of stepping along the image using the specified +\fIt_step\fR parameter. The function fitting uses the \fBicfit\fR commands +with the other parameters from the tracing section. + +\fBBackground or Scattered Light Subtraction\fR + +In addition to not subtracting any background scattered light there are two +approaches to subtracting this light. The first is to determine a smooth +global scattered light component. The second is to subtract a locally +determined background at each point along the dispersion and for each +aperture. Note that background subtraction is only done for object images +and not for arc images. + +The global scattered light fitting and subtraction is done with the task +\fBapscatter\fR. The function fitting parameters are set interactively +using the aperture reference spectrum. All other subtractions are done +noninteractively with the same set of parameters. The scattered light is +subtracted from the input images, thus modifying them, and one might wish +to first make backups of the original images. + +The scattered light is measured between the apertures using a specified +buffer distance from the aperture edges. The scattered light pixels are +fit by a series of one dimensional functions across the dispersion. The +independent fits are then smoothed along the dispersion by again fitting +low order functions. These fits then define the smooth scattered light +surface to be subtracted from the image. The fitting parameters are +defined and recorded in the two parameter sets \fIapscat1\fR and +\fIapscat2\fR. The scattered light algorithm is described more fully in +\fBapscatter\fR. This algorithm is relatively slow. + +Local background subtraction is done during extraction based on background +regions and parameters defined by the default background parameters or +changed during interactive review of the apertures. The background +subtraction options are to 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 smoothing parameter \fIb_smooth\fR is may be used +to provide some additional local smoothing of the background light. +The background subtraction algorithm and options are described in greater +detail in \fBapsum\fR and \fBapbackground\fR. + +\fBExtraction\fR + +The actual extraction of the spectra is done by summing across the fixed +width apertures at each point along the dispersion. The default is to +simply sum the pixels using partial pixels at the ends. There is an +option to weight the sum based on a Poisson noise model using the +\fIreadnoise\fR and \fIgain\fR detector parameters. Note that if the +\fIclean\fR option is selected the variance weighted extraction is used +regardless of the \fIweights\fR parameter. The sigma threshold for +cleaning are also set in the \fBparams\fR parameters. + +The cleaning and variance weighting options require knowing the effective +(i.e. accounting for any image combining) read out noise and gain. These +numbers need to be adjusted if the image has been processed such that the +intensity scale has a different origin (such as a scattered light +subtraction) or scaling (such as caused by unnormalized flat fielding). +These options also require using background subtraction if the profile does +not go to zero. For optimal extraction and cleaning to work it is +recommended that any scattered light be accounted for by local background +subtraction rather than with the scattered light subtraction and the +\fIfitflat\fR option be used. The \fIb_smooth\fR parameter is also +appropriate in this application and improves the optimal extraction results +by reducing noise in the background signal. For further discussion of +cleaning and variance weighted extraction see \fBapvariance\fR and +\fBapprofiles\fR as well as \fBapsum\fR. + +\fBFlat Field Correction\fR + +Flat field corrections may be made during the basic CCD processing; i.e. +direct division by the two dimensional flat field observation. In that +case do not specify a flat field spectrum; use the null string "". The +\fBdofoe\fR task provides an alternative flat field response correction +based on division of the extracted object spectra by the extracted flat field +spectra. A discussion of the theory and merits of flat fielding directly +verses using the extracted spectra will not be made here. The +\fBdofoe\fR flat fielding algorithm is the \fIrecommended\fR method for +flat fielding since it works well and is not subject to the many problems +involved in two dimensional flat fielding. + +The first step is extraction of the flat field spectrum, if one is specified, +using the reference apertures. Only one flat field is allowed so if +multiple flat fields are required the data must be reduced in groups. When +the \fIfitflat\fR option is selected (the default) the extracted flat field +spectra are fit by smooth functions and the ratio of the flat field spectra +to the smooth functions define the response spectra. The default fitting +function and order are given by the parameters \fIf_function\fR and +\fIf_order\fR. If the parameter \fIf_interactive\fR is "yes" then the +fitting is done interactively using the \fBfit1d\fR task which uses the +\fBicfit\fR interactive fitting commands. + +If the \fIfitflat\fR option is not selected the extracted and globally +normalized flat field spectra are directly divided in the object spectra. +This removes the blaze function, thus altering the data counts, and +introduces the reciprocal of the flat field spectrum in the object +spectra. + +The final step is to normalize the flat field spectra by the mean counts over +all the fibers. This normalization step is simply to preserve the average +counts of the extracted object and arc spectra after division by the +response spectra. + +\fBDispersion Correction\fR + +If dispersion correction is not selected, \fIdispcor\fR=no, then the object +spectra are simply extracted. If it is selected the arc spectra are used +to dispersion calibrate the object spectra. There are three steps involved; +determining the dispersion functions relating pixel position to wavelength, +assigning the appropriate dispersion function to a particular observation, +and either storing the nonlinear +dispersion function in the image headers or resampling the spectra to +evenly spaced pixels in wavelength. When there are two fibers there is +also a step of applying a zero point correction to the object fiber based +on the arc fiber. + +The first arc spectrum in the arc list is used to define the reference +dispersion solution. It is extracted using the reference aperture +definitions. Note extractions of arc spectra are not background or +scattered light subtracted. The interactive task \fBecidentify\fR is used +to define the dispersion function in one fiber. The idea is to mark some +lines in a few orders whose wavelengths are known (with the line list used +to supply additional lines after the first few identifications define the +approximate wavelengths) and to fit a function giving the wavelength from +the aperture number and pixel position. The dispersion function for the +second fiber, if one is present, is then determined automatically by +reference to the first fiber using the task \fBecreidentify\fR. + +The arc dispersion function parameters are for \fBecidentify\fR and it's +related partner \fBecreidentify\fR. The parameters define a line list for +use in automatically assigning wavelengths to arc lines, a centering width +(which should match the line widths at the base of the lines), the +dispersion function type and orders, parameters to exclude bad lines from +function fits, and defining whether to refit the dispersion function as +opposed to simply determining a zero point shift. The defaults should +generally be adequate and the dispersion function fitting parameters may be +altered interactively. One should consult the help for the two tasks for +additional details of these parameters and the interactive operation of +\fBecidentify\fR. + +Once the reference dispersion functions are defined other arc spectra are +extracted as they are assign to the object spectra. The assignment of +arcs is done either explicitly with an arc assignment table (parameter +\fIarctable\fR) or based on a header parameter such as a time. +The assignments are made by the task \fBrefspectra\fR. When two arcs are +assigned to an object spectrum an interpolation is done between the two +dispersion functions. This makes an approximate correction for steady +drifts in the dispersion. + +When a second arc fiber monitors any zero point shifts in the dispersion +functions it is probably only necessary to have one or two arc spectra, one +at the beginning and/or one at the end of the night. + +The tasks \fBsetjd\fR and \fBsetairmass\fR are automatically run on all +spectra. This computes and adds the header parameters for the Julian date +(JD), the local Julian day number (LJD), the universal time (UTMIDDLE), and +the air mass at the middle of the exposure. The default arc assignment is +to use the Julian date grouped by the local Julian day number. The +grouping allows multiple nights of data to be correctly assigned at the +same time. + +Defining the dispersion function for a new arc extraction is done with +the task \fBecreidentify\fR. This is done noninteractively with log +information recorded about the line reidentifications and the fit. + +When there are two fibers there are two full dispersion function from the +single or pair of arc spectra, one for the object fiber and one for the arc +fiber. When an object spectrum is extracted so is the simultaneous arc +spectrum. A zero point shift of the arc spectrum relative to the +dispersion solution of the dual arc observation is computed using +\fBecreidentify\fR (\fIrefit\fR=no). This zero point shift is assumed to +be the same for the object fiber and it is added to the dispersion function +of the dual arc observation for the object fiber. Note that this does not +assume that the object and arc fiber dispersion functions are the same or +have the same wavelength origin, but only that the same shift in wavelength +zero point applies to both fibers. Once the dispersion function correction +is determined from the extracted arc fiber spectrum it is deleted leaving +only the object spectrum. + +The last step of dispersion correction is setting the dispersion +of the object spectrum. There are two choices here. +If the \fIlinearize\fR parameter is not set the nonlinear dispersion +function is stored in the image header. Other IRAF tasks interpret +this information when dispersion coordinates are needed for plotting +or analysis. This has the advantage of not requiring the spectra +to be interpolated and the disadvantage that the dispersion +information is only understood by IRAF tasks and cannot be readily +exported to other analysis software. + +If the \fIlinearize\fR parameter is set then the spectra are resampled to a +linear dispersion relation either in wavelength or the log of the +wavelength. For echelle spectra each order is linearized independently so +that the wavelength interval per pixel is different in different orders. +This preserves most of the resolution and avoids over or under sampling of +the highest or lowest dispersion orders. The wavelength limits are +taken from the limits determined from the arc reference spectrum and +the number of pixels is the same as the original images. The dispersion +per pixel is then derived from these constraints. + +The linearization algorithm parameters allow selecting the interpolation +function type, whether to conserve flux per pixel by integrating across the +extent of the final pixel, and whether to linearize to equal linear or +logarithmic intervals. The latter may be appropriate for radial velocity +studies. The default is to use a fifth order polynomial for interpolation, +to conserve flux, and to not use logarithmic wavelength bins. These +parameters are described fully in the help for the task \fBdispcor\fR which +performs the correction. +.ih +EXAMPLES +1. The following example uses artificial data and may be executed +at the terminal (with IRAF V2.10). This is also the sequence performed +by the test procedure "demos dofoe". Because the images are small the +dispersion solution is somewhat simplistic. + +.nf +ec> demos mkdofoe +Creating image demoobj ... +Creating image demoflat ... +Creating image demoarc ... +ec> echelle.verbose = yes +ec> dofoe demoobj apref=demoflat flat=demoflat arcs=demoarc \ +>>> norders=3 width=5. +Set reference apertures for demoflat +Searching aperture database ... +Finding apertures ... +Mar 4 9:39: FIND - 6 apertures found for demoflat +Resize apertures for demoflat? (yes): +Resizing apertures ... +Mar 4 9:39: RESIZE - 6 apertures resized for demoflat +<Review aperture assignments. Exit with 'q'> +Fit traced positions for demoflat interactively? (yes): +Tracing apertures ... +Fit curve to aperture 1 of demoflat interactively (yes): +<Review trace and fit. Exit with 'q'> +Fit curve to aperture 2 of demoflat interactively (yes): N +Mar 4 9:39: TRACE - 6 apertures traced in demoflat. +Mar 4 9:39: DATABASE - 6 apertures for demoflat written to database +Create response function demoflatnorm.ec +Extract flat field demoflat +Searching aperture database ... +Mar 4 9:39: DATABASE - 6 apertures read for demoflat from database +Extracting apertures ... +Mar 4 9:39: EXTRACT - Aperture 1 from demoflat --> demoflat.ec +Mar 4 9:39: EXTRACT - Aperture 2 from demoflat --> demoflat.ec +Mar 4 9:39: EXTRACT - Aperture 3 from demoflat --> demoflat.ec +Mar 4 9:39: EXTRACT - Aperture 4 from demoflat --> demoflat.ec +Mar 4 9:39: EXTRACT - Aperture 5 from demoflat --> demoflat.ec +Mar 4 9:40: EXTRACT - Aperture 6 from demoflat --> demoflat.ec +Fit and ratio flat field demoflat +Create the normalized response demoflatnorm.ec +demoflatnorm.ec -> demoflatnorm.ec using bzero: 0. and bscale: 1. + mean: 1. median: 0.9990048 mode: 0.9876572 + upper: INDEF lower: INDEF +Extract arc reference image demoarc +Mar 4 9:40: DATABASE - 6 apertures read for demoflat from database +Mar 4 9:40: DATABASE - 6 apertures for demoarc written to database +Mar 4 9:40: EXTRACT - Aperture 1 from demoarc --> demoarc.ec +Mar 4 9:40: EXTRACT - Aperture 2 from demoarc --> demoarc.ec +Mar 4 9:40: EXTRACT - Aperture 3 from demoarc --> demoarc.ec +Mar 4 9:40: EXTRACT - Aperture 4 from demoarc --> demoarc.ec +Mar 4 9:40: EXTRACT - Aperture 5 from demoarc --> demoarc.ec +Mar 4 9:40: EXTRACT - Aperture 6 from demoarc --> demoarc.ec +Determine dispersion solution for demoarc +<Mark lines with 'm' and change orders with 'k' +<'m' line at pixel 78 and assign 4965. +<'k' to order 2 +<'m' line at pixel 78 and assign 5009 +<'m' line at pixel 78 and assign 5020 +<'k' to order 3 +<'m' line at pixel 78 and assign 5049.8 +<'m' line at pixel 78 and assign 5050.8 +<'m' line at pixel 78 and assign 5055.3 +<'m' line at pixel 78 and assign 5062 +<'m' line at pixel 78 and assign 5064.9 +<'f' to fit +<'q' to quit fit and 'q' to quit ECIDENTIFY + +ECREIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Wed 09:54:16 04-Mar-92 + Reference image = demoarc.ec, Refit = yes + Image Found Fit Pix Shift User Shift Z Shift RMS + d...ec 8/8 8/8 1.48 7.06 2.11E-5 0.00879 +d...ec: ap = 1, w1 = 4959.1, w2 = 4978.5, dw = 0.076, nw = 256 +d...ec: ap = 2, w1 = 5003.4, w2 = 5022.1, dw = 0.073, nw = 256 +d...ec: ap = 3, w1 = 5049.0, w2 = 5067.0, dw = 0.070, nw = 256 +Extract object spectrum demoobj +Searching aperture database ... +Mar 4 9:54: DATABASE - 6 apertures read for demoflat from database +Recentering apertures ... +Mar 4 9:54: RECENTER - 6 apertures shifted by -0.03 for demoobj. +Mar 4 9:54: DATABASE - 6 apertures for demoobj written to database +Extracting apertures ... +Mar 4 9:54: EXTRACT - Aperture 1 from demoobj --> demoobj.ec +Mar 4 9:54: EXTRACT - Aperture 2 from demoobj --> demoobj.ec +Mar 4 9:54: EXTRACT - Aperture 3 from demoobj --> demoobj.ec +Mar 4 9:54: EXTRACT - Aperture 4 from demoobj --> demoobj.ec +Mar 4 9:54: EXTRACT - Aperture 5 from demoobj --> demoobj.ec +Mar 4 9:54: EXTRACT - Aperture 6 from demoobj --> demoobj.ec +Assign arc spectra for demoobj +[demoobj] refspec1='demoarc' +Reidentify arc fibers in demoobj with respect to demoarc + +ECREIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Wed 09:54:28 04-Mar-92 + Reference image = demoarcarc.ec, Refit = no + Image Found Fit Pix Shift User Shift Z Shift RMS + d...ec 8/8 8/8 0.119 0.566 1.69E-6 0.00834 +Dispersion correct demoobj +d...ec.imh: ap = 1, w1 = 4959.1, w2 = 4978.5, dw = 0.076, nw = 256 +d...ec.imh: ap = 2, w1 = 5003.4, w2 = 5022.1, dw = 0.073, nw = 256 +d...ec.imh: ap = 3, w1 = 5049.0, w2 = 5067.0, dw = 0.070, nw = 256 +.fi +.ih +REVISIONS +.ls DOFOE V2.10.3 +The image format type to be +processed is selected with the \fIimtype\fR environment parameter. The +dispersion axis parameter is now a package parameter. Images will only +be processed if the have the CCDPROC keyword. A \fIdatamax\fR parameter +has been added to help improve cosmic ray rejection. A scattered +light subtraction processing option has been added. +.le +.ih +SEE ALSO +apedit, apfind, approfiles, aprecenter, apresize, apsum, aptrace, apvariance, +ccdred, center1d, dispcor, fit1d, icfit, ecidentify, observatory, +onedspec.package, refspectra, ecreidentify, setairmass, setjd +.endhelp diff --git a/noao/imred/echelle/doc/dofoe.ms b/noao/imred/echelle/doc/dofoe.ms new file mode 100644 index 00000000..1f283f46 --- /dev/null +++ b/noao/imred/echelle/doc/dofoe.ms @@ -0,0 +1,1371 @@ +.nr PS 9 +.nr VS 11 +.de V1 +.ft CW +.nf +.. +.de V2 +.fi +.ft R +.. +.de LS +.br +.in +2 +.. +.de LE +.br +.sp .5v +.in -2 +.. +.ND February 1993 +.TL +Guide to the Fiber Optic Echelle Reduction Task DOFOE +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +.DY + +.AB +The \fBdofoe\fR reduction task is specialized for scattered light +subtraction, extraction, flat fielding, and wavelength calibration of Fiber +Optic Echelle (FOE) spectra. It is a command language script which +collects and combines the functions and parameters of many general purpose +tasks to provide a single complete data reduction path. The task provides +a degree of guidance, automation, and record keeping necessary when dealing +with the complexities of reducing this type of data. +.AE +.NH +Introductions +.LP +The \fBdofoe\fR reduction task is specialized for scattered light +subtraction, extraction, flat fielding, and wavelength calibration of Fiber +Optic Echelle (FOE) spectra. It is a command language script which +collects and combines the functions and parameters of many general purpose +tasks to provide a single complete data reduction path. The task provides +a degree of guidance, automation, and record keeping necessary when dealing +with the complexities of reducing this type of data. +.LP +The general organization of the task is to do the interactive setup steps +first using representative calibration data and then perform the majority +of the reductions automatically, possibly as a background process, with +reference to the setup data. In addition, the task determines which setup +and processing operations have been completed in previous executions of the +task and, contingent on the \f(CWredo\fR and \f(CWupdate\fR options, skip or +repeat some or all the steps. +.LP +The description is divided into a quick usage outline followed by details +of the parameters and algorithms. The usage outline is provided as a +checklist and a refresher for those familiar with this task and the +component tasks. It presents only the default or recommended usage. Since +\fBdofoe\fR combines many separate, general purpose tasks the description +given here refers to these tasks and leaves some of the details to their +help documentation. +.NH +Usage Outline +.LP +.IP [1] 6 +The images must first be processed with \fBccdproc\fR for overscan, +bias, and dark corrections. +.IP [2] +Set the \fBdofoe\fR parameters with \fBeparam\fR. Specify the object +images to be processed, the flat field image as the aperture reference and +the flat field, and one or more arc images. If there are many +object or arc spectra per setup you might want to prepare "@ files". +Verify and set the format parameters, particularly the number of orders to be +extracted and processed. The processing parameters are set +for simple extraction and dispersion correction but dispersion correction +can be turned off for quicklook or background subtraction and cleaning +may be added. +.IP [3] +Run the task. This may be repeated multiple times with different +observations and the task will generally only do the setup steps +once and only process new images. Queries presented during the +execution for various interactive operations may be answered with +"yes", "no", "YES", or "NO". The lower case responses apply just +to that query while the upper case responses apply to all further +such queries during the execution and no further queries of that +type will be made. +.IP [4] +The apertures are defined using the specified aperture reference image +which is usually a flat field in which both the object and arc fibers are +illuminated. The specified number of orders are found automatically and +sequential apertures assigned. The resize option sets the aperture size to +the widths of the profiles at a fixed fraction of the peak height. +.IP [5] +The automatic order identification and aperture assignment is based on peak +height and may be incorrect. The interactive aperture editor is entered +with a plot of the apertures. It is essential that the object and arc +fiber orders are properly paired with the arc fibers having even aperture +numbers and the object fibers having odd aperture numbers. It is also +required that no orders be skipped in the region of interest. Missing +orders are added with the 'm' key. Once all orders have been marked the +aperture numbers are resequenced with 'o'. If local background subtraction +is selected the background regions should be checked with the 'b' key. +Preceding this with the 'a' key allows any changes to the background +regions to be applied to all orders. To exit type 'q'. +.IP [6] +The order positions at a series of points along the dispersion are measured +and a function is fit to these positions. This may be done interactively to +adjust the fitting parameters. Not all orders need be examined and the "NO" +response will quit the interactive fitting. To exit the interactive +fitting type 'q'. +.IP [7] +If flat fielding is to be done the flat field spectra are extracted. A +smooth function is fit to each flat field spectrum to remove the large +scale spectral signature. The final response spectra are normalized to a +unit mean over all fibers. +.IP [8] +If scattered light subtraction is selected the scattered light parameters +are set using the aperture reference image and the task \fBapscatter\fR. +The purpose of this is to interactively define the aperture buffer distance +for the scattered light and the cross and parallel dispersion fitting +parameters. The fitting parameters are taken from and recorded in the +parameter sets \fBapscat1\fR and \fBapscat2\fR. All other scattered light +subtractions are done noninteractively with these parameters. Note that +the scattered light correction modifies the input images. +.IP [9] +If dispersion correction is selected the first arc in the arc list is +extracted. One fiber is used to identify the arc lines and define the +dispersion function using the task \fBecidentify\fR. Identify a few arc +lines in a few orders with 'm' and 'k' or 'o', use the 'l' line list +identification command to automatically add additional lines and fit the +dispersion function. Check the quality of the dispersion function fit +with 'f'. When satisfied exit with 'q'. +.IP [10] +The other fiber dispersion function is automatically determined using +the task \fBecreidentify\fR. +.IP [11] +The arc reference spectrum is dispersion corrected. +If the spectra are resampled to a linear dispersion system +(which will be the same for all spectra) the dispersion parameters +determined from the dispersion solution are printed. +.IP [12] +The object spectra are now automatically background subtracted (an +alternative to scattered light subtraction), extracted, flat fielded, +and dispersion corrected. Any new dispersion function reference arcs +assigned to the object images are automatically extracted and +dispersion functions determined. A zero point wavelength correction +is computed from the simultaneous arc fiber spectrum and applied to +the object spectrum. +.IP [13] +The final spectra will have the same name as the original 2D images +with a ".ec" extension added. +.NH +Spectra and Data Files +.LP +The basic input consists of dual fiber FOE object and calibration spectra +stored as IRAF images. +The type of image format is defined by the +environment parameter \fIimtype\fR. Only images with that extension will +be processed and created. +The raw CCD images must be processed to remove +overscan, bias, and dark count effects. This is generally done using the +\fBccdred\fR package. Flat fielding is generally not done at this stage +but as part of \fBdofoe\fR. The calibration spectra are +flat field observations in both fibers, comparison arc lamp spectra +in both fibers, and arc spectra in one fiber while the second +fiber observes the object. If for some reason the flat field or +calibration arc spectra have separate exposures for the two fibers +the separate exposures may simply be added. +.LP +The assignment of arc calibration exposures to object exposures is +generally done by selecting the nearest in time and interpolating. +However, the optional \fIarc assignment table\fR may be used to explicitly +assign arc images to specific objects. The format of this file is +described in the task \fBrefspectra\fR. +.LP +The final reduced spectra are recorded in two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ec" extension. Each line in the reduced image is a one dimensional +spectrum (an echelle order) with associated aperture and wavelength +information. When the \f(CWextras\fR parameter is set the lines in the +third dimension contain additional information (see +\fBapsum\fR for further details). These spectral formats are accepted by the +one dimensional spectroscopy tasks such as the plotting tasks \fBsplot\fR +and \fBspecplot\fR. The special task \fBscopy\fR may be used to extract +specific apertures or to change format to individual one dimensional +images. The task \fBscombine\fR is used to combine or merge orders into +a single spectrum. +.NH +Package Parameters +.LP +The \fBechelle\fR package parameters, shown in Figure 1, set parameters +affecting all the tasks in the package. Some of the parameters are not +applicable to the \fBdofoe\fR task. +.KS +.V1 + +.ce +Figure 1: Package Parameter Set for the ECHELLE Package + + I R A F + Image Reduction and Analysis Facility +PACKAGE = imred + TASK = echelle + +(extinct= onedstds$kpnoextinct.dat) Extinction file +(caldir = onedstds$spechayescal/) Standard star calibration directory +(observa= observatory) Observatory of data +(interp = poly5) Interpolation type +(dispaxi= 2) Image axis for 2D images +(nsum = 1) Number of lines/columns to sum for 2D images + +(databas= database) Database +(verbose= no) Verbose output? +(logfile= logfile) Text log file +(plotfil= ) Plot file + +(records= ) Record number extensions +(version= ECHELLE V3: July 1991) + +.KE +.V2 +The observatory parameter is only required for data +without an OBSERVAT header parameter (currently included in NOAO data). +The spectrum interpolation type might be changed to "sinc" but with the +cautions given in \fBonedspec.package\fR. The dispersion axis parameter is +only needed if a DISPAXIS image header parameter is not defined. The other +parameters define the standard I/O functions. The verbose parameter +selects whether to print everything which goes into the log file on the +terminal. It is useful for monitoring what the \fBdofoe\fR task does. The +log and plot files are useful for keeping a record of the processing. A +log file is highly recommended. A plot file provides a record of +apertures, traces, and extracted spectra but can become quite large. +The plotfile is most conveniently viewed and printed with \fBgkimosaic\fR. +.NH +Processing Parameters +.LP +The \fBdofoe\fR parameters are shown in Figure 2. +.KS +.V1 + +.ce +Figure 2: Parameters Set for DOFOE + + I R A F + Image Reduction and Analysis Facility +PACKAGE = echelle + TASK = dofoe + +objects = List of object spectra +(apref = ) Aperture reference spectrum +(flat = ) Flat field spectrum +(arcs = ) List of arc spectra +(arctabl= ) Arc assignment table (optional) + +.KE +.V1 +(readnoi= 0.) Read out noise sigma (photons) +(gain = 1.) Photon gain (photons/data number) +(datamax= INDEF) Max data value / cosmic ray threshold +(norders= 12) Number of orders +(width = 4.) Width of profiles (pixels) +(arcaps = 2x2) Arc apertures + +(fitflat= yes) Fit and ratio flat field spectrum? +(backgro= none) Background to subtract +(clean = no) Detect and replace bad pixels? +(dispcor= yes) Dispersion correct spectra? +(redo = no) Redo operations if previously done? +(update = no) Update spectra if cal data changes? +(batch = no) Extract objects in batch? +(listonl= no) List steps but don't process? + +(params = ) Algorithm parameters + +.V2 +The input images are specified by image lists. The lists may be +a list of explicit, comma separate image names, @ files, or image +templates using pattern matching against file names in the directory. +The aperture reference spectrum is used to find the orders and trace +them. Thus, this requires an image with good signal in both fibers +which usually means a flat field spectrum. It is recommended that +flat field correction be done using one dimensional extracted spectra +rather than as two dimensional images. This is done if a flat field +spectrum is specified. The arc assignment table is used to specifically +assign arc spectra to particular object spectra and the format +of the file is described in \fBrefspectra\fR. +.LP +The detector read out noise and gain are used for cleaning and variance +(optimal) extraction. The dispersion axis defines the wavelength direction +of spectra in the image if not defined in the image header by the keyword +DISPAXIS. The width parameter (in pixels) is used for the profile +centering algorithm (\fBcenter1d\fR). +.LP +The number of orders selects the number of "pairs" of object and arc +fiber profiles to be automatically found based on the strongest peaks. +Because it is important that both elements of a pair be found, +no orders be skipped, and the aperture numbers be sequential with +arc profiles having even aperture numbers and object profiles having +odd numbers in the region of interest, the automatic identification is +just a starting point for the interactive review. The even/odd +relationship between object and arc profiles is set by the \f(CWarcaps\fR +parameter and so may be reversed if desired. +.LP +The next set of parameters select the processing steps and options. The +flat fitting option allows fitting and removing the overall shape of the +flat field spectra while preserving the pixel-to-pixel response +corrections. This is useful for maintaining the approximate object count +levels, including the blaze function, and not introducing the reciprocal of +the flat field spectrum into the object spectra. If not selected the flat +field will remove the blaze function from the observations and introduce +some wavelength dependence from the flat field lamp spectrum. +.LP +The \f(CWbackground\fR option selects the type of correction for background or +scattered light. If the type is "scattered" a global scattered light is +fit to the data between the apertures and subtracted from the images. +\fINote that the input images are modified by this operation\fR. This +option is slow. Alternatively, a local background may be subtracted using +background regions defined for each aperture. The data in the regions may +be averaged, medianed, or the minimum value used. Another choice is to fit +the data in the background regions by a function and interpolate to the +object aperture. +.LP +The \f(CWclean\fR option invokes a profile fitting and deviant point rejection +algorithm as well as a variance weighting of points in the aperture. These +options require knowing the effective (i.e. accounting for any image +combining) read out noise and gain. For a discussion of cleaning and +variance weighted extraction see \fBapvariance\fR and \fBapprofiles\fR. +.LP +The dispersion correction option selects whether to extract arc spectra, +determine a dispersion function, assign them to the object spectra, and, +possibly, resample the spectra to a linear (or log-linear) wavelength +scale. +.LP +Generally once a spectrum has been processed it will not be reprocessed if +specified as an input spectrum. However, changes to the underlying +calibration data can cause such spectra to be reprocessed if the +\f(CWupdate\fR flag is set. The changes which will cause an update are a new +reference image, new flat field, adding the scattered light option, and a +new arc reference image. If all input spectra are to be processed +regardless of previous processing the \f(CWredo\fR flag may be used. Note +that reprocessing clobbers the previously processed output spectra. +.LP +The \f(CWbatch\fR processing option allows object spectra to be processed as +a background or batch job. The \f(CWlistonly\fR option prints a summary of +the processing steps which will be performed on the input spectra without +actually doing anything. This is useful for verifying which spectra will +be affected if the input list contains previously processed spectra. The +listing does not include any arc spectra which may be extracted to +dispersion calibrate an object spectrum. +.LP +The last parameter (excluding the task mode parameter) points to another +parameter set for the algorithm parameters. The way \fBdofoe\fR works +this may not have any value and the parameter set \fBparams\fR is always +used. The algorithm parameters are discussed further in the next section. +.NH +Algorithms and Algorithm Parameters +.LP +This section summarizes the various algorithms used by the \fBdofoe\fR +task and the parameters which control and modify the algorithms. The +algorithm parameters available to the user are collected in the parameter +set \fBparams\fR. These parameters are taken from the various general +purpose tasks used by the \fBdofoe\fR processing task. Additional +information about these parameters and algorithms may be found in the help +for the actual task executed. These tasks are identified in the parameter +section listing in parenthesis. The aim of this parameter set organization +is to collect all the algorithm parameters in one place separate from the +processing parameters and include only those which are relevant for +FOE data. The parameter values can be changed from the +defaults by using the parameter editor, +.V1 + + cl> epar params + +.V2 +or simple typing \f(CWparams\fR. The parameter editor can also be +entered when editing the \fBdofoe\fR parameters by typing \f(CW:e +params\fR or simply \f(CW:e\fR if positioned at the \f(CWparams\fR +parameter. Figure 3 shows the parameter set. +.KS +.V1 + +.ce +Figure 3: Algorithm Parameter Set + + I R A F + Image Reduction and Analysis Facility +PACKAGE = echelle + TASK = params + +(line = INDEF) Default dispersion line +(nsum = 10) Number of dispersion lines to sum +(extras = no) Extract sky, sigma, etc.? + + -- DEFAULT APERTURE LIMITS -- +(lower = -3.) Lower aperture limit relative to center +(upper = 3.) Upper aperture limit relative to center + + -- AUTOMATIC APERTURE RESIZING PARAMETERS -- +(ylevel = 0.05) Fraction of peak or intensity for resizing + +.KE +.KS +.V1 + -- TRACE PARAMETERS -- +(t_step = 10) Tracing step +(t_funct= spline3) Trace fitting function +(t_order= 2) Trace fitting function order +(t_niter= 1) Trace rejection iterations +(t_low = 3.) Trace lower rejection sigma +(t_high = 3.) Trace upper rejection sigma + +.KE +.KS +.V1 + -- DEFAULT BACKGROUND PARAMETERS -- +(buffer = 1.) Buffer distance from apertures +(apscat1= ) Fitting parameters across the dispersion +(apscat2= ) Fitting parameters along the dispersion +(b_funct= legendre) Background function +(b_order= 2) Background function order +(b_sampl= -10:-6,6:10) Background sample regions +(b_naver= -3) Background average or median +(b_niter= 0) Background rejection iterations +(b_low = 3.) Background lower rejection sigma +(b_high = 3.) Background upper rejection sigma +(b_grow = 0.) Background rejection growing radius +(b_smoot= 10) Background smoothing length + +.KE +.KS +.V1 + -- APERTURE EXTRACTION PARAMETERS -- +(weights= none) Extraction weights (none|variance) +(pfit = fit1d) Profile fitting algorithm (fit1d|fit2d) +(lsigma = 3.) Lower rejection threshold +(usigma = 3.) Upper rejection threshold + +.KE +.KS +.V1 + -- FLAT FIELD FUNCTION FITTING PARAMETERS -- +(f_inter= no) Fit flat field interactively? +(f_funct= spline3) Fitting function +(f_order= 20) Fitting function order + +.KE +.KS +.V1 + -- ARC DISPERSION FUNCTION PARAMETERS -- +(coordli= linelist$thar.dat) Line list +(match = 1.) Line list matching limit in Angstroms +(fwidth = 4.) Arc line widths in pixels +(cradius= 4.) Centering radius in pixels +(i_funct= chebyshev) Echelle coordinate function +(i_xorde= 3) Order of coordinate function along dispersion +(i_yorde= 3) Order of coordinate function across dispersion +(i_niter= 3) Rejection iterations +(i_low = 3.) Lower rejection sigma +(i_high = 3.) Upper rejection sigma +(refit = yes) Refit coordinate function when reidentifying? + +.KE +.KS +.V1 + -- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- +(select = interp) Selection method for reference spectra +(sort = jd) Sort key +(group = ljd) Group key +(time = no) Is sort key a time? +(timewra= 17.) Time wrap point for time sorting + +.KE +.KS +.V1 + -- DISPERSION CORRECTION PARAMETERS -- +(lineari= yes) Linearize (interpolate) spectra? +(log = no) Logarithmic wavelength scale? +(flux = yes) Conserve flux? + +.KE +.V2 +.NH 2 +Aperture Definitions +.LP +The first operation is to define the extraction apertures, which include the +aperture width, background regions, and position dependence with +wavelength, for the object and arc orders of interest. This is done +on a reference spectrum which is usually a flat field taken through +both fibers. Other spectra will inherit the reference apertures and +apply a correction for any shift of the orders across the dispersion. +The reference apertures are defined only once unless the \f(CWredo\fR +option is set. +.LP +The selected number of orders are found automatically by selecting the +highest peaks in a cut across the dispersion. Note that the specified +number of orders is multiplied by two in defining the apertures. Apertures +are assigned with a limits set by the \f(CWlower\fR and +\f(CWupper\fR parameter and numbered sequentially. A query is then +given allowing the aperture limits to be "resized" based on the profile +itself (see \fBapresize\fR). +.LP +A cut across the orders is then shown with the apertures marked and +an interactive aperture editing mode is entered (see \fBapedit\fR). +For \fBdofoe\fR the aperture identifications and numbering is particularly +critical. All "pairs" of object and arc orders in the region of +interest must be defined without skipping any orders. The orders must +also be numbered sequentially (though the direction does not matter) +so that the arc apertures are either all even or all odd as defined +by the \f(CWarcaps\fR parameter (the default is even numbers for the +arc apertures). The 'o' key will provide the necessary reordering. +If local background subtraction is used the background regions should +also be checked with the 'b' key. Typically one adjusts all +the background regions at the same time by selecting all apertures with +the 'a' key first. To exit the background and aperture editing steps type +'q'. +.LP +Next the positions of the orders at various points along the dispersion are +measured and "trace functions" are fit. The user is asked whether to fit +each trace function interactively. This is selected to adjust the fitting +parameters such as function type and order. When interactively fitting a +query is given for each aperture. After the first aperture one may skip +reviewing the other traces by responding with "NO". Queries made by +\fBdofoe\fR generally may be answered with either lower case "yes" or "no" +or with upper case "YES" or "NO". The upper case responses apply to all +further queries and so are used to eliminate further queries of that kind. +.LP +The above steps are all performed using tasks from the \fBapextract\fR +package and parameters from the \fBparams\fR parameters. As a quick +summary, the dispersion direction of the spectra are determined from the +package \fBdispaxis\fR parameter if not defined in the image header. The default +line or column for finding the orders and the number of image lines or +columns to sum are set by the \f(CWline\fR and \f(CWnsum\fR parameters. A line +of INDEF (the default) selects the middle of the image. The automatic +finding algorithm is described for the task \fBapfind\fR and basically +finds the strongest peaks. The resizing is described in the task +\fBapresize\fR and the parameters used are also described there and +identified in the PARAMETERS section. The tracing is done as described in +\fBaptrace\fR and consists of stepping along the image using the specified +\f(CWt_step\fR parameter. The function fitting uses the \fBicfit\fR commands +with the other parameters from the tracing section. +.NH 2 +Background or Scattered Light Subtraction +.LP +In addition to not subtracting any background scattered light there are two +approaches to subtracting this light. The first is to determine a smooth +global scattered light component. The second is to subtract a locally +determined background at each point along the dispersion and for each +aperture. Note that background subtraction is only done for object images +and not for arc images. +.LP +The global scattered light fitting and subtraction is done with the task +\fBapscatter\fR. The function fitting parameters are set interactively +using the aperture reference spectrum. All other subtractions are done +noninteractively with the same set of parameters. The scattered light is +subtracted from the input images, thus modifying them, and one might wish +to first make backups of the original images. +.LP +The scattered light is measured between the apertures using a specified +buffer distance from the aperture edges. The scattered light pixels are +fit by a series of one dimensional functions across the dispersion. The +independent fits are then smoothed along the dispersion by again fitting +low order functions. These fits then define the smooth scattered light +surface to be subtracted from the image. The fitting parameters are +defined and recorded in the two parameter sets \f(CWapscat1\fR and +\f(CWapscat2\fR. The scattered light algorithm is described more fully in +\fBapscatter\fR. This algorithm is relatively slow. +.LP +Local background subtraction is done during extraction based on background +regions and parameters defined by the default background parameters or +changed during interactive review of the apertures. The background +subtraction options are to 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 (\f(CWbackground\fR = +"median") or median samples during fitting (\f(CWb_naverage\fR < -1). +The background smoothing parameter \f(CWb_smooth\fR is may be used +to provide some additional local smoothing of the background light. +The background subtraction algorithm and options are described in greater +detail in \fBapsum\fR and \fBapbackground\fR. +.NH 2 +Extraction +.LP +The actual extraction of the spectra is done by summing across the fixed +width apertures at each point along the dispersion. The default is to +simply sum the pixels using partial pixels at the ends. There is an +option to weight the sum based on a Poisson noise model using the +\f(CWreadnoise\fR and \f(CWgain\fR detector parameters. Note that if the +\f(CWclean\fR option is selected the variance weighted extraction is used +regardless of the \f(CWweights\fR parameter. The sigma threshold for +cleaning are also set in the \fBparams\fR parameters. +.LP +The cleaning and variance weighting options require knowing the effective +(i.e. accounting for any image combining) read out noise and gain. These +numbers need to be adjusted if the image has been processed such that the +intensity scale has a different origin (such as a scattered light +subtraction) or scaling (such as caused by unnormalized flat fielding). +These options also require using background subtraction if the profile does +not go to zero. For optimal extraction and cleaning to work it is +recommended that any scattered light be accounted for by local background +subtraction rather than with the scattered light subtraction and the +\f(CWfitflat\fR option be used. The \f(CWb_smooth\fR parameter is also +appropriate in this application and improves the optimal extraction results +by reducing noise in the background signal. For further discussion of +cleaning and variance weighted extraction see \fBapvariance\fR and +\fBapprofiles\fR as well as \fBapsum\fR. +.NH 2 +Flat Field Correction +.LP +Flat field corrections may be made during the basic CCD processing; i.e. +direct division by the two dimensional flat field observation. In that +case do not specify a flat field spectrum; use the null string "". The +\fBdofoe\fR task provides an alternative flat field response correction +based on division of the extracted object spectra by the extracted flat field +spectra. A discussion of the theory and merits of flat fielding directly +verses using the extracted spectra will not be made here. The +\fBdofoe\fR flat fielding algorithm is the \fIrecommended\fR method for +flat fielding since it works well and is not subject to the many problems +involved in two dimensional flat fielding. +.LP +The first step is extraction of the flat field spectrum, if one is specified, +using the reference apertures. Only one flat field is allowed so if +multiple flat fields are required the data must be reduced in groups. When +the \f(CWfitflat\fR option is selected (the default) the extracted flat field +spectra are fit by smooth functions and the ratio of the flat field spectra +to the smooth functions define the response spectra. The default fitting +function and order are given by the parameters \f(CWf_function\fR and +\f(CWf_order\fR. If the parameter \f(CWf_interactive\fR is "yes" then the +fitting is done interactively using the \fBfit1d\fR task which uses the +\fBicfit\fR interactive fitting commands. +.LP +If the \f(CWfitflat\fR option is not selected the extracted and globally +normalized flat field spectra are directly divided in the object spectra. +This removes the blaze function, thus altering the data counts, and +introduces the reciprocal of the flat field spectrum in the object +spectra. +.LP +The final step is to normalize the flat field spectra by the mean counts over +all the fibers. This normalization step is simply to preserve the average +counts of the extracted object and arc spectra after division by the +response spectra. +.NH 2 +Dispersion Correction +.LP +If dispersion correction is not selected, \f(CWdispcor\fR=no, then the object +spectra are simply extracted. If it is selected the arc spectra are used +to dispersion calibrate the object spectra. There are four steps involved; +determining the dispersion functions relating pixel position to wavelength, +assigning the appropriate dispersion function to a particular observation, +determining a zero point wavelength shift from the arc fiber to be applied +to the object fiber dispersion function, and either storing the nonlinear +dispersion function in the image headers or resampling the spectra to +evenly spaced pixels in wavelength. +.LP +The first arc spectrum in the arc list is used to define the reference +dispersion solution. It is extracted using the reference aperture +definitions. Note extractions of arc spectra are not background or +scattered light subtracted. The interactive task \fBecidentify\fR is used +to define the dispersion function in one fiber. The idea is to mark some +lines in a few orders whose wavelengths are known (with the line list used +to supply additional lines after the first few identifications define the +approximate wavelengths) and to fit a function giving the wavelength from +the aperture number and pixel position. The dispersion function for +the second fiber is then determined automatically by reference to the first +fiber using the task \fBecreidentify\fR. +.LP +The arc dispersion function parameters are for \fBecidentify\fR and it's +related partner \fBecreidentify\fR. The parameters define a line list for +use in automatically assigning wavelengths to arc lines, a centering width +(which should match the line widths at the base of the lines), the +dispersion function type and orders, parameters to exclude bad lines from +function fits, and defining whether to refit the dispersion function as +opposed to simply determining a zero point shift. The defaults should +generally be adequate and the dispersion function fitting parameters may be +altered interactively. One should consult the help for the two tasks for +additional details of these parameters and the interactive operation of +\fBecidentify\fR. +.LP +Once the reference dispersion functions are defined other arc spectra are +extracted as they are assign to the object spectra. The assignment of +arcs is done either explicitly with an arc assignment table (parameter +\f(CWarctable\fR) or based on a header parameter such as a time. +The assignments are made by the task \fBrefspectra\fR. When two arcs are +assigned to an object spectrum an interpolation is done between the two +dispersion functions. This makes an approximate correction for steady +drifts in the dispersion. Because the arc fiber monitors any zero point +shifts in the dispersion functions it is probably only necessary to have +one or two arc spectra, one at the beginning and/or one at the end of the +night. +.LP +The tasks \fBsetjd\fR and \fBsetairmass\fR are automatically run on all +spectra. This computes and adds the header parameters for the Julian date +(JD), the local Julian day number (LJD), the universal time (UTMIDDLE), and +the air mass at the middle of the exposure. The default arc assignment is +to use the Julian date grouped by the local Julian day number. The +grouping allows multiple nights of data to be correctly assigned at the +same time. +.LP +Defining the dispersion function for a new arc extraction is done with +the task \fBecreidentify\fR. This is done noninteractively with log +information recorded about the line reidentifications and the fit. +.LP +From the one or two arc spectra come two full dispersion function, +one for the object fiber and one for the arc fiber. When an object +spectrum is extracted so is the simultaneous arc spectrum. A zero point +shift of the arc spectrum relative to the dispersion solution of the +dual arc observation is computed using \fBecreidentify\fR +(\f(CWrefit\fR=no). This zero point shift is assumed to be the same for the +object fiber and it is added to the dispersion function of the dual arc +observation for the object fiber. Note that this does not assume that the +object and arc fiber dispersion functions are the same or have the same +wavelength origin, but only that the same shift in wavelength zero point +applies to both fibers. Once the dispersion function correction is +determined from the extracted arc fiber spectrum it is deleted leaving only +the object spectrum. +.LP +The last step of dispersion correction is setting the dispersion +of the object spectrum. There are two choices here. +If the \f(CWlinearize\fR parameter is not set the nonlinear dispersion +function is stored in the image header. Other IRAF tasks interpret +this information when dispersion coordinates are needed for plotting +or analysis. This has the advantage of not requiring the spectra +to be interpolated and the disadvantage that the dispersion +information is only understood by IRAF tasks and cannot be readily +exported to other analysis software. +.LP +If the \f(CWlinearize\fR parameter is set then the spectra are resampled to a +linear dispersion relation either in wavelength or the log of the +wavelength. For echelle spectra each order is linearized independently so +that the wavelength interval per pixel is different in different orders. +This preserves most of the resolution and avoids over or under sampling of +the highest or lowest dispersion orders. The wavelength limits are +taken from the limits determined from the arc reference spectrum and +the number of pixels is the same as the original images. The dispersion +per pixel is then derived from these constraints. +.LP +The linearization algorithm parameters allow selecting the interpolation +function type, whether to conserve flux per pixel by integrating across the +extent of the final pixel, and whether to linearize to equal linear or +logarithmic intervals. The latter may be appropriate for radial velocity +studies. The default is to use a fifth order polynomial for interpolation, +to conserve flux, and to not use logarithmic wavelength bins. These +parameters are described fully in the help for the task \fBdispcor\fR which +performs the correction. +.NH +References +.NH 2 +IRAF Introductory References +.LP +Work is underway on a new introductory guide to IRAF. Currently, the +work below is the primary introduction. +.IP +P. Shames and D. Tody, \fIA User's Introduction to the IRAF Command +Language\fR, Central Computer Services, NOAO, 1986. +.NH 2 +CCD Reductions +.IP +F. Valdes, \fIThe IRAF CCD Reduction Package -- CCDRED\fR, Central +Computer Services, NOAO, 1987. +.IP +F. Valdes, \fIUser's Guide to the CCDRED Package\fR, Central +Computer Services, NOAO, 1988. Also on-line as \f(CWhelp ccdred.guide\fR. +.IP +P. Massey, \fIA User's Guide to CCD Reductions with IRAF\fR, Central +Computer Services, NOAO, 1989. +.NH 2 +Aperture Extraction Package +.IP +F. Valdes, \fIThe IRAF APEXTRACT Package\fR, Central Computer Services, +NOAO, 1987 (out-of-date). +.NH 2 +Task Help References +.LP +Each task in the \fBspecred\fR packages and tasks used by \fBdofibers\fR have +help pages describing the parameters and task in some detail. To get +on-line help type +.V1 + +cl> help \fItaskname\fR + +.V2 +The output of this command can be piped to \fBlprint\fR to make a printed +copy. + +.V1 + apall - Extract 1D spectra (all parameters in one task) + apdefault - Set the default aperture parameters and apidtable + 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 + + bplot - Batch plots of spectra + calibrate - Apply extinction and flux calibrations to spectra + continuum - Fit the continuum in spectra + deredden - Apply interstellar extinction corrections + dispcor - Dispersion correct spectra + dopcor - Doppler correct spectra + ecidentify - Identify features in spectrum for dispersion solution +ecreidentify - Automatically identify features in spectra + refspectra - Assign wavelength reference spectra to other spectra + sarith - Spectrum arithmetic + scombine - Combine spectra + scopy - Select and copy apertures in different spectral formats + sensfunc - Create sensitivity function + setairmass - Compute effective airmass and middle UT for an exposure + setjd - Compute and set Julian dates in images + slist - List spectrum header parameters + specplot - Stack and plot multiple spectra + splot - Preliminary spectral plot/analysis + standard - Identify standard stars to be used in sensitivity calc + + dofoe - Process Fiber Optic Echelle spectra + demos - Demonstrations and tests + + Additional help topics + + onedspec.package - Package parameters and general description of package + apextract.package - Package parameters and general description of package + approfiles - Profile determination algorithms + apvariance - Extractions, variance weighting, cleaning, and noise model + center1d - One dimensional centering algorithm + icfit - Interactive one dimensional curve fitting + +.V2 +.SH +Appendix A: DOFOE Parameters +.LP +.nr PS 8 +.nr VS 10 +objects +.LS +List of object spectra to be processed. Previously processed spectra are +ignored unless the \f(CWredo\fR flag is set or the \f(CWupdate\fR flag is set and +dependent calibration data has changed. Extracted spectra are ignored. +.LE +apref = "" +.LS +Aperture reference spectrum. This spectrum is used to define the basic +extraction apertures and is typically a flat field spectrum. +.LE +flat = "" (optional) +.LS +Flat field spectrum. If specified the one dimensional flat field spectrum +is extracted and used to make flat field calibrations. +.LE +arcs = "" (at least one if dispersion correcting) +.LS +List of arc spectra in which both fibers have arc spectra. These spectra +are used to define the dispersion functions for each fiber apart from a +zero point correction made with the arc fiber during an observation. One +fiber from the first spectrum is used to mark lines and set the dispersion +function interactively and dispersion functions for the other fiber and arc +spectra are derived from it. +.LE +arctable = "" (optional) (refspectra) +.LS +Table defining arc spectra to be assigned to object spectra (see +\fBrefspectra\fR). If not specified an assignment based on a header +parameter, \f(CWparams.sort\fR, such as the observation time is made. +.LE + +readnoise = "0." (apsum) +.LS +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 +gain = "1." (apsum) +.LS +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 +datamax = INDEF (apsum.saturation) +.LS +The maximum data value which is not a cosmic ray. +When cleaning cosmic rays and/or using variance weighted extraction +very strong cosmic rays (pixel values much larger than the data) can +cause these operations to behave poorly. If a value other than INDEF +is specified then all data pixels in excess of this value will be +excluded and the algorithms will yield improved results. +This applies only to the object spectra and not the flat field or +arc spectra. For more +on this see the discussion of the saturation parameter in the +\fBapextract\fR package. +.LE +norders = 12 (apfind) +.LS +Number of orders to be found. This number is used during the automatic +definition of the apertures from the aperture reference spectrum. Note +that the number of apertures defined is twice this number, one set for +the object fiber orders and one set for the arc fiber orders. +The interactive review of the aperture assignments allows verification +and adjustments to the automatic aperture definitions. +.LE +width = 4. (apedit) +.LS +Approximate base full width of the fiber profiles. This parameter is used +for the profile centering algorithm. +.LE +arcaps = "2x2" +.LS +List of arc fiber aperture numbers. +Since the object and arc fiber orders are paired the default setting +expects the even number apertures to be the are apertures. This should +be checked interactively. +.LE + +fitflat = yes (flat1d) +.LS +Fit and divide the extracted flat field field orders by a smooth function +in order to normalize the wavelength response? If not done the flat field +spectral shape (which includes the blaze function) will be divided +out of the object spectra, thus altering the object data values. +If done only the small scale response variations are included in the +flat field and the object spectra will retain their observed flux +levels and blaze function. +.LE +background = "none" (apsum, apscatter) +.LS +Type of background light subtraction. The choices are "none" for no +background subtraction, "scattered" for a global scattered light +subtraction, "average" to average the background within background regions, +"median" to use the median in background regions, "minimum" to use the +minimum in background regions, or "fit" to fit across the dispersion using +the background within background regions. The scattered light option fits +and subtracts a smooth global background and modifies the input images. +This is a slow operation and so is NOT performed in quicklook mode. The +other background options are local to each aperture at each point along the +dispersion. The "fit" option uses additional fitting parameters from +\fBparams\fR and the "scattered" option uses parameters from \fBapscat1\fR +and \fBapscat2\fR. +.LE +clean = yes (apsum) +.LS +Detect and correct for bad pixels during extraction? This is the same +as the clean option in the \fBapextract\fR package. If yes this also +implies variance weighted extraction and requires reasonably good values +for the readout noise and gain. In addition the datamax parameters +can be useful. +.LE +dispcor = yes +.LS +Dispersion correct spectra? Depending on the \f(CWparams.linearize\fR +parameter this may either resample the spectra or insert a dispersion +function in the image header. +.LE +redo = no +.LS +Redo operations previously done? If no then previously processed spectra +in the objects list will not be processed (unless they need to be updated). +.LE +update = no +.LS +Update processing of previously processed spectra if aperture, flat +field, or dispersion reference definitions are changed? +.LE +batch = no +.LS +Process spectra as a background or batch job. +.LE +listonly = no +.LS +List processing steps but don't process? +.LE + +params = "" (pset) +.LS +Name of parameter set containing additional processing parameters. The +default is parameter set \fBparams\fR. The parameter set may be examined +and modified in the usual ways (typically with "epar params" or ":e params" +from the parameter editor). Note that using a different parameter file +is not allowed. The parameters are described below. +.LE + +.ce +-- PACKAGE PARAMETERS + +Package parameters are those which generally apply to all task in the +package. This is also true of \fBdofoe\fR. + +observatory = "observatory" +.LS +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. For FOE data the image headers +identify the observatory as "kpno" so this parameter is not used. +For data from other observatories this parameter may be used +as describe in \fBobservatory\fR. +.LE +interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) +.LS +Spectrum interpolation type used when spectra are resampled. The choices are: + +.V1 + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.V2 +.LE +dispaxis = 2 +.LS +Default dispersion axis. The dispersion axis is 1 for dispersion +running along image lines and 2 for dispersion running along image +columns. If the image header parameter DISPAXIS is defined it has +precedence over this parameter. +.LE +database = "database" +.LS +Database (directory) used for storing aperture and dispersion information. +.LE +verbose = no +.LS +Print verbose information available with various tasks. +.LE +logfile = "logfile", plotfile = "" +.LS +Text and plot log files. If a filename is not specified then no log is +kept. The plot file contains IRAF graphics metacode which may be examined +in various ways such as with \fBgkimosaic\fR. +.LE +records = "" +.LS +Dummy parameter to be ignored. +.LE +version = "ECHELLE: ..." +.LS +Version of the package. +.LE + +.ce +PARAMS PARAMETERS + +The following parameters are part of the \fBparams\fR parameter set and +define various algorithm parameters for \fBdofoe\fR. + +.ce +-- GENERAL PARAMETERS -- + +line = INDEF, nsum = 10 +.LS +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, +editing, and tracing operations. A line of INDEF selects the middle of the +image along the dispersion axis. +.LE +extras = no (apsum) +.LS +Include extra information in the output spectra? When cleaning or using +variance weighting the cleaned and weighted spectra are recorded in the +first 2D plane of a 3D image, the raw, simple sum spectra are recorded in +the second plane, and the estimated sigmas are recorded in the third plane. +.LE + +.ce +-- DEFAULT APERTURE LIMITS -- + +lower = -3., upper = 3. (apdefault) +.LS +Default lower and upper aperture limits relative to the aperture center. +These limits are used when the apertures are first found and may be +resized automatically or interactively. +.LE + +.ce +-- AUTOMATIC APERTURE RESIZING PARAMETERS -- + +ylevel = 0.05 (apresize) +.LS +Data level at which to set aperture limits during automatic resizing. +It is a fraction of the peak relative to a local background. +.LE + +.ce +-- TRACE PARAMETERS -- + +t_step = 10 (aptrace) +.LS +Step along the dispersion axis between determination of the spectrum +positions. Note the \f(CWnsum\fR parameter is also used to enhance the +signal-to-noise at each step. +.LE +t_function = "spline3", t_order = 2 (aptrace) +.LS +Default trace fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.LE +t_niterate = 1, t_low = 3., t_high = 3. (aptrace) +.LS +Default number of rejection iterations and rejection sigma thresholds. +.LE + +.ce +-- DEFAULT BACKGROUND PARAMETERS -- + +buffer = 1. (apscatter) +.LS +Buffer distance from the edge of any aperture for data to be included +in the scattered light determination. This parameter may be modified +interactively. +.LE +apscat1 = "", apscat2 = "" (apscatter) +.LS +Parameter sets for the fitting functions across and along the dispersion. +These parameters are those used by \fBicfit\fR. These parameters are +usually set interactively. +.LE +b_function = "legendre", b_order = 1 (apsum) +.LS +Default background fitting function and order. The fitting function types are +"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and +"spline3" cubic spline. The order refers to the number of +terms in the polynomial functions or the number of spline pieces in the spline +functions. +.LE +b_naverage = -100 (apsum) +.LS +Default number of points to average or median. Positive numbers +average that number of sequential points to form a fitting point. +Negative numbers median that number, in absolute value, of sequential +points. A value of 1 does no averaging and each data point is used in the +fit. +.LE +b_niterate = 0 (apsum) +.LS +Default number of rejection iterations. If greater than zero the fit is +used to detect deviant fitting points and reject them before repeating the +fit. The number of iterations of this process is given by this parameter. +.LE +b_low_reject = 3., b_high_reject = 3. (apsum) +.LS +Default background lower and upper rejection sigmas. If greater than zero +points deviating from the fit below and above the fit by more than this +number of times the sigma of the residuals are rejected before refitting. +.LE +b_smooth = 10 (apsum) +.LS +Box car smoothing length for background when using background +subtraction. Since the background noise is often the limiting factor +for good extraction one may box car smooth the the background to improve the +statistics. +.LE + + +.ce +-- APERTURE EXTRACTION PARAMETERS -- + +weights = "none" (apsum) +.LS +Type of extraction weighting. Note that if the \f(CWclean\fR parameter is +set then the weights used are "variance" regardless of the weights +specified by this parameter. The choices are: + +"none" +.LS +The pixels are summed without weights except for partial pixels at the +ends. +.LE +"variance" +.LS +The extraction is weighted by the variance based on the data values +and a poisson/ccd model using the \f(CWgain\fR and \f(CWreadnoise\fR +parameters. +.LE +.LE +pfit = "fit1d" (apsum) (fit1d|fit2d) +.LS +Profile fitting algorithm for cleaning and variance weighted extractions. +The default is generally appropriate for FOE data but users +may try the other algorithm. See \fBapprofiles\fR for further information. +.LE +lsigma = 3., usigma = 3. (apsum) +.LS +Lower and upper rejection thresholds, given as a number of times the +estimated sigma of a pixel, for cleaning. +.LE + +.ce +-- FLAT FIELD FUNCTION FITTING PARAMETERS -- + +f_interactive = no (fit1d) +.LS +Fit the one dimensional flat field order spectra interactively? +This is used if \f(CWfitflat\fR is set and a two dimensional flat field +spectrum is specified. +.LE +f_function = "spline3", f_order = 20 (fit1d) +.LS +Function and order used to fit the composite one dimensional flat field +spectrum. The functions are "legendre", "chebyshev", "spline1", and +"spline3". The spline functions are linear and cubic splines with the +order specifying the number of pieces. +.LE + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- + +threshold = 10. (identify/reidentify) +.LS +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.LE +coordlist = "linelist$thar.dat" (ecidentify) +.LS +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelist$". +.LE +match = 1. (ecidentify) +.LS +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.LE +fwidth = 4. (ecidentify) +.LS +Approximate full base width (in pixels) of arc lines. +.LE +cradius = 4. (reidentify) +.LS +Radius from previous position to reidentify arc line. +.LE +i_function = "chebyshev", i_xorder = 3, i_yorder = 3 (ecidentify) +.LS +The default function, function order for the pixel position dependence, and +function order for the aperture number dependence to be fit to the arc +wavelengths. The functions choices are "chebyshev" or "legendre". +.LE +i_niterate = 3, i_low = 3.0, i_high = 3.0 (ecidentify) +.LS +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.LE +refit = yes (ecreidentify) +.LS +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the arc reference then a new +dispersion function of the same type as in the reference image is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised fitted coordinates without changing the +form of the dispersion function. +.LE + +.ce +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS -- + +select = "interp" (refspectra) +.LS +Selection method for assigning wavelength calibration spectra. +Note that an arc assignment table may be used to override the selection +method and explicitly assign arc spectra to object spectra. +The automatic selection methods are: + +average +.LS +Average two reference spectra without regard to any sort parameter. +If only one reference spectrum is specified then it is assigned with a +warning. If more than two reference spectra are specified then only the +first two are used and a warning is given. +This option is used to assign two reference spectra, with equal weights, +independent of any sorting parameter. +.LE +following +.LS +Select the nearest following spectrum in the reference list based on the +sorting parameter. If there is no following spectrum use the nearest preceding +spectrum. +.LE +interp +.LS +Interpolate between the preceding and following spectra in the reference +list based on the sorting parameter. If there is no preceding and following +spectrum use the nearest spectrum. The interpolation is weighted by the +relative distances of the sorting parameter. +.LE +match +.LS +Match each input spectrum with the reference spectrum list in order. +This overrides the reference aperture check. +.LE +nearest +.LS +Select the nearest spectrum in the reference list based on the sorting +parameter. +.LE +preceding +.LS +Select the nearest preceding spectrum in the reference list based on the +sorting parameter. If there is no preceding spectrum use the nearest following +spectrum. +.LE +.LE +sort = "jd", group = "ljd" (refspectra) +.LS +Image header keywords to be used as the sorting parameter for selection +based on order and to group spectra. +A null string, "", or the word "none" may be use to disable the sorting +or grouping parameters. +The sorting parameter +must be numeric but otherwise may be anything. The grouping parameter +may be a string or number and must simply be the same for all spectra within +the same group (say a single night). +Common sorting parameters are times or positions. +In \fBdofoe\fR the Julian date (JD) and the local Julian day number (LJD) +at the middle of the exposure are automatically computed from the universal +time at the beginning of the exposure and the exposure time. Also the +parameter UTMIDDLE is computed. +.LE +time = no, timewrap = 17. (refspectra) +.LS +Is the sorting parameter a 24 hour time? If so then the time origin +for the sorting is specified by the timewrap parameter. This time +should precede the first observation and follow the last observation +in a 24 hour cycle. +.LE + +.ce +-- DISPERSION CORRECTION PARAMETERS -- + +linearize = yes (dispcor) +.LS +Interpolate the spectra to a linear dispersion sampling? If yes the +spectra will be interpolated to a linear or log linear sampling +If no the nonlinear dispersion function(s) from the dispersion function +database are assigned to the input image world coordinate system +and the spectral data are not interpolated. +.LE +log = no (dispcor) +.LS +Use linear logarithmic wavelength coordinates? Linear logarithmic +wavelength coordinates have wavelength intervals which are constant +in the logarithm of the wavelength. +.LE +flux = yes (dispcor) +.LS +Conserve the total flux during interpolation? If \f(CWno\fR the output +spectrum is interpolated from the input spectrum at each output +wavelength coordinate. If \f(CWyes\fR the input spectrum is integrated +over the extent of each output pixel. This is slower than +simple interpolation. +.LE + +.ce +ENVIRONMENT PARAMETERS +.LP +The environment parameter \fIimtype\fR is used to determine the extension +of the images to be processed and created. This allows use with any +supported image extension. For STF images the extension has to be exact; +for example "d1h". diff --git a/noao/imred/echelle/doc/ecidentify.hlp b/noao/imred/echelle/doc/ecidentify.hlp new file mode 100644 index 00000000..61187a43 --- /dev/null +++ b/noao/imred/echelle/doc/ecidentify.hlp @@ -0,0 +1,770 @@ +.help ecidentify May88 noao.imred.echelle +.ih +NAME +ecidentify -- Determine the dispersion relation in echelle spectra +.ih +USAGE +ecidentify images +.ih +PARAMETERS +.ls images +List of echelle format spectra in which to identify lines and fit +dispersion functions. +.le +.ls database = "database" +Database in which the feature data and dispersion functions are recorded. +.le +.ls coordlist = "linelists$idhenear.dat" +User coordinate list consisting of an ordered list of line coordinates. A +comment line of the form "# units <units>", where <units> is one of the +understood units names, defines the units of the line list. If no units +are specified then Angstroms are assumed. Some standard line lists are +available in the directory "linelists$". The standard line lists are +described under the topic \fIlinelists\fR. +.le +.ls units = "" +The units to use if no database entry exists. The units are specified as +described in + +.nf + cl> help onedspec.package section=units +.fi + +If no units are specified and a coordinate list is used then the units of +the coordinate list are selected. If a database entry exists then the +units defined there override both this parameter and the coordinate list. +.le +.ls match = 1. +The maximum difference for a match between the feature coordinate function +value and a coordinate in the coordinate list. The unit of this parameter +is that of the user coordinates. +.le +.ls maxfeatures = 100 +Maximum number of the strongest features to be selected automatically from +the coordinate list (function 'l') or from the image data (function 'y'). +.le +.ls zwidth = 10. +Width of graphs, in user coordinates, when in zoom mode (function 'z'). +.le + +The following parameters are used in determining feature positions. +.ls ftype = "emission" +Type of features to be identified. The possibly abbreviated choices are +"emission" and "absorption". +.le +.ls fwidth = 4. +Width in pixels of features to be identified. +.le +.ls cradius = 5. +The maximum distance, in pixels, allowed between a feature position +and the initial estimate when defining a new feature. +.le +.ls threshold = 10. +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following default parameters are used when fitting a function to +the user coordinates. If a previous solution is read from the database +then the parameters from that solution override the defaults below. +.ls function = "chebyshev" +The function to be fit to the user coordinates as a function of the pixel +coordinate and aperture number. The choices are bi-dimensional +"chebyshev" and "legendre" polynomials. +.le +.ls xorder = 2 +Order of the fitting function along each echelle order. +The order is the number of polynomial terms; i.e. xorder = 2 is a linear +function. +.le +.ls yorder = 2 +Order of the fitting function with respect to the aperture number. +The order is the number of polynomial terms; i.e. yorder = 2 is a linear +function. +.le +.ls niterate = 0, lowreject = 3, highreject = 3. +Default number of rejection iterations and the sigma clipping thresholds. If +\fIniterate\fR is zero then no rejection is done. +.le + +The following parameters control the graphics input and output. +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls curosr = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le +.ih +CURSOR KEYS + +.nf + ECIDENTIFY CURSOR KEY AND COLON COMMAND SUMMARY + +? Help a Affect all features c Center feature(s) +d Delete feature(s) f Fit dispersion g Fit zero point shift +i Initialize j Go to previous order k Go to next order +l Match coordinate list m Mark feature n Next feature +o Go to specified order p Pan graph q Quit +r Redraw graph s Shift feature t Reset position +u Enter user coordinate w Window graph x Crosscorrelate peaks +y Find peaks z Zoom graph . Nearest feature ++ Next feature - Previous feature I Interrupt + +:show [file] :features [file] :coordlist [file] +:cradius [value] :threshold [value] :database [file] +:ftype [type] :fwidth [value] :image [image] +:labels [type] :match [value] :maxfeatures [value] +:minsep [value] :read [image] :write [image] +:zwidth [value] + + + ECHELLE DISPERSION FUNCTION FITTING COMMAND SUMMARY + +? Help c Print coordinates d Delete point +f Fit dispersion o Fit with fixed order offset q Quit +r Redraw graph u Undelete point w Window graph +x Set ordinate y Set abscissa I Interrupt + +:show :function [value] :highreject [value] :lowreject [value] +:niterate [value] :xorder [value] :yorder [value] + +.fi + + ECIDENTIFY CURSOR KEYS AND COLON COMMANDS +.ls ? +Clear the screen and print a menu of cursor and colon commands. +.le +.ls a +Apply next (c)enter or (d)elete operation to (a)ll features +.le +.ls c +(C)enter the feature nearest the cursor. Used when changing the position +finding parameters or when features are defined from a previous feature list. +May be used in combination with the (a)ll key. +.le +.ls d +(D)elete the feature nearest the cursor. (D)elete all features when preceded +by the (a)ll key. This does not affect the dispersion function. +.le +.ls f +(F)it a function of the pixel coordinates and aperture numbers to the user +coordinates. This enters an interactive function fitting package. +.le +.ls g +Fit a zero point shift to the user coordinates by minimizing the difference +between the user and fitted coordinates. The coordinate dispersion function +is not changed. +.le +.ls i +(I)nitialize (delete features and dispersion function fit). +.le +.ls j +Go to the next aperture in decreasing line number in the echelle format image. +Wrap around to the last line from the first line. +.le +.ls k +Go to the next aperture in increasing line number in the echelle format image. +Wrap around to the first line from the last line. +.le +.ls l +(L)ocate features in the coordinate list. A coordinate function must be +defined or at least four features in more than one aperture must have user +coordinates from which a coordinate function can be determined by an +initial automatic function fit. +.le +.ls m +(M)ark a new feature using the cursor position as the initial position +estimate. +.le +.ls n +Move the cursor or zoom to the (n)ext feature (same as +). +.le +.ls o +Go to a specific aperture (related to an echelle (o)rder). The user +is queried for the aperture number. +.le +.ls p +(P)an to the original window after (z)ooming on a feature. +.le +.ls q +(Q)uit and continue with next image. +.le +.ls r +(R)edraw the graph. +.le +.ls s +(S)hift the fit coordinates relative to the pixel coordinates. The +user specifies the desired coordinate at the position of the cursor +and a zero point shift to the fit coordinates is applied. If features +are defined then they are recentered and the shift is the average shift. +The shift in pixels, user coordinates, and z (fractional shift) is printed. +The user shift is for the fundamental order and the shift for each order +is then given by this shift divided by the order number. +.le +.ls t +Reset the current feature to the position of the cursor. The feature +is \fInot\fR recentered. This is used to mark an arbitrary position. +.le +.ls u +Enter a new (u)ser coordinate for the current feature. +When (m)arking a new feature the user coordinate is also requested. +.le +.ls w +(W)indow the graph. A window prompt is given and a number of windowing +options may be given. For more help type '?' to the window prompt or +see help under \fIgtools\fR. +.le +.ls x +Crosscorrelate features with the data peaks and reregister. This is +generally used with a feature list from a different image. +The mean shift in user coordinates, mean shift in pixels, and the fractional +shift in user coordinates is printed. The user shift is scaled to the +fundamental order. +.le +.ls y +Up to \fImaxfeatures\fR emission peaks are found automatically (in order of +peak intensity) and, if a dispersion solution is defined, the peaks are +identified from the coordinate list. +.le +.ls z +(Z)oom on the feature nearest the cursor. The width of the zoom window +is determined by the parameter \fIzwidth\fR. +.le +.ls . +Move the cursor or zoom window to the feature nearest the cursor. +.le +.ls 4 + +Move the cursor or zoom window to the (n)ext feature. +This does not automatically move to the next aperture. +.le +.ls 4 - +Move the cursor or zoom window to the previous feature. +This does not automatically move to the next aperture. +.le +.ls I +Interrupt the task immediately. The database is not updated. +.le + +Parameters are shown or set with the following "colon commands", which may be +abbreviated. To show the value of a parameter type the parameter name alone +and to set a new value follow the parameter name by the value. +.ls :show file +Show the values of all the parameters. If a file name is given then the +output is appended to that file. If no file is given then the terminal +is cleared and the output is sent to the terminal. +.le +.ls :features file +Print the feature list and the fit rms. If a file name is given then the +output is appended to that file. If no file is given then the terminal +is cleared and the output is sent to the terminal. +.le +.ls :coordlist file +Set or show the coordinate list file. +.le +.ls :cradius value +Set or show the centering radius in pixels. +.le +.ls :threshold value +Set or show the detection threshold for centering. +.le +.ls :database name +Set or show the database for recording feature records. +.le +.ls :ftype value +Set or show the feature type (emission or absorption). +.le +.ls :fwidth value +Set or show the feature width in pixels. +.le +.ls :image imagename +Set a new image or show the current image. +.le +.ls :labels value +Set or show the feature label type (none, index, pixel, or user). +.le +.ls :match value +Set or show the coordinate list matching distance. +.le +.ls :maxfeatures value +Set or show the maximum number of features automatically found. +.le +.ls :minsep value +Set or show the minimum separation allowed between features. +.le +.ls :read name +Read a record from the database. The record name defaults to the image name. +.le +.ls :threshold value +Set or show the centering threshold. +.le +.ls :write name +Write a record to the database. The record name defaults to the image name. +.le +.ls :zwidth value +Set or show the zoom width in user units. +.le + + + DISPERSION FUNCTION FITTING COMMANDS +.ls ? +Page help information. +.le +.ls c +Print input and fitted coordinates of point nearest the cursor. +.le +.ls d +Delete the nearest undeleted point to the cursor. +.le +.ls f +Fit a dispersion function including determining the order offset. +.le +.ls o +Fit a dispersion function with the order offset fixed. The user is queried +for the order offset. This is faster than the interactive fit to also +determine the order. +.le +.ls q +Quit and return to the spectrum display. +.le +.ls r +Redraw the graph. +.le +.ls u +Undelete the nearest deleted point to the cursor (which may be outside the +graph window). +.le +.ls w +Window the graph (type ? to the window prompt for more help). +.le +.ls x +Set the quantity plotted along the ordinate (x axis). +.le +.ls y +Set the quantity plotted along the abscissa (y axis). +.le +.ls I +Interrupt the task immediately. No information is saved in the database. +.le + +.ls :function [value] +Print or set the function type (chebyshev|legendre). +.le +.ls :show +Print current function and orders. +.le +.ls :niterate [value], :lowreject [value], :highreject [value] +Print or set the iterative rejection parameters. +.le +.ls :xorder [value] +Print or set the order for the dispersion dependence. +.le +.ls :yorder [value] +Print or set the order for the echelle order dependence. +.le +.ih +DESCRIPTION +Emission and absorption features in echelle format spectra (see \fIapsum\fR) +are identified interactively and from a line list and a dispersion +function is determined. The results of the line identifications and +dispersion function are stored in a database for further reference and +for use with the tasks \fBecreidentify\fR and \fBecdispcor\fR. Also +the reference spectrum keyword REFSPEC is added to the image header. +This is used by \fBrefspectra\fR and \fBecdispcor\fR. + +Each spectrum in the input list is identified in turn. Initially the +order in the first image line is graphed. The user may change the +displayed order with the 'j', 'k', and 'o' keys. The initial feature +list and dispersion function are read from the database if an entry +exists. The features are marked on the graph. The image coordinates +are in pixels unless a dispersion function is defined, in which case +they are in user coordinate units (usually wavelength in Angstroms). +The aperture number, pixel coordinate, coordinate function value, and +user coordinate for the current feature are displayed on the status +line. + +For consistency the orders are always identified by their aperture +numbers in this task and all other tasks. These are the +identifications assigned when extracting the orders using the task +\fIapsum\fR. If the user has assigned true order numbers as the +aperture numbers then there is no distinction between aperture and +order number. However, it is often the case that the aperture numbers +are simply assigned sequentially and the true order numbers may not +even be known. Initially the orders are the same as the apertures +numbers but after fitting a dispersion function the true order numbers +will be determined. This information is also recorded in the database +and indicated in the graph titles but selecting an order to be graphed +with 'o' and the status line information is always in terms of the +aperture number. + +The graphics cursor is used to select features and perform various +functions. A menu of the keystroke options and functions is printed +with the key '?'. The cursor keys and their functions are defined in +the CURSOR KEYS sections and described further below. The standard +cursor mode keys are also available to window and redraw the graph and +to produce hardcopy "snaps". + +There are two types of feature selection functions; defining new +features and selecting previously defined features. The key 'm' marks +a new feature nearest the cursor position. The feature position is +determined by the feature centering algorithm (see help for +\fBcenter1d\fR). The type of feature, emission or absorption, is set +by the \fIftype\fR parameter. If the new position is within a distance +given by the parameter \fIminsep\fR of a previous feature it is +considered to be the same feature and replaces the old feature +(normally the position of the new feature will be exactly the same as +the original feature). The coordinate list is searched for a match +between the coordinate function value (when defined) and a user +coordinate in the list. If a match is found it becomes the default +user coordinate which the user may override. The new feature is marked +on the graph and it becomes the current feature. The redefinition of a +feature which is within the minimum separation may be used to set the +user coordinate from the coordinate list. The key 't' allows setting +the position of a feature to other than that found by the centering +algorithm. + +The 'y' key applies a peak finding algorithm and up to the maximum +number of features (\fImaxfeatures\fR) are found. If there are more +peaks only the strongest are kept. The peaks are then matched against +the coordinate list to find user coordinate values. + +To select a different feature as the current feature the keys '.', 'n', +'+', and '-' are used. The '.' selects the feature nearest the cursor, +the 'n' and '+' select the next feature, and the '-' selects the +previous feature relative to the current feature in the feature list as +ordered by pixel coordinate. These keys are useful when redefining the +user coordinate with the 'u' key and when examining features in zoom +mode. To change apertures (orders) the 'j', 'k', and 'o' keys are +used. + +If four or more features are identified spanning the range of the data +(in pixel coordinates and in order number) or if a coordinate function +is defined then the 'l' key may be used to identify additional features +from a coordinate list. If a coordinate function is not defined the +default function is fit to the user coordinates of the currently +defined features. Then for each coordinate value in the coordinate +list the pixel coordinate is determined and a search for a feature at +that point is made. If a feature is found (based on the parameters +\fIftype, fwidth\fR, \fIcradius\fR, and \fBthreshold\fR) its user +coordinate value based on the coordinate function is determined. If +the coordinate function value matches the user coordinate from the +coordinate list within the error limit set by the parameter \fImatch\fR +then the new feature is entered in the feature list. Up to a maximum +number of features, set by the parameter \fImaxfeatures\fR, may be +defined in this way. A new user coordinate function is fit to all the +located features. Finally, the graph is redrawn in user coordinates +with the additional features found from the coordinate list marked. + +The 'f' key fits a two dimensional function of the pixel coordinates +and aperture number to the user coordinates. The type of function and +the orders are initially set with the parameters \fIfunction\fR, +\fIxorder\fR, and \fIyorder\fR. The value of the function for a +particular pixel coordinate is called the function coordinate and each +feature in the feature list has a function coordinate value. The +fitted function also is used to convert pixel coordinates to user +coordinates in the graph. Depending on the orders of the function +four or more features are required covering at least two orders. +A description of the dispersion function fitting is given the section +ECHELLE DISPERSION FUNCTION FITTING. + +If a zero point shift is desired without changing the coordinate function +the user may specify the coordinate of a point in the spectrum with +the 's' key from which a shift is determined. The 'g' key also +determines a shift by minimizing the difference between the user +coordinates and the fitted coordinates. This is used when a previously +determined coordinate function is applied to a new spectrum having +fewer or poorer lines and only a zero point shift can reasonably be +determined. Note that the zero point shift is in user coordinates +for the fundamental order. The shift for any particular order is then +the zero point shift divided by the order number. + +Features may be delete with the key 'd'. All features are deleted when +the 'a' key immediately precedes the delete key. Deleting the features +does not delete the coordinate function. To delete both the features +and the dispersion function the initialize key 'i' is used. Note +features deleted during dispersion function fitting also are removed +from the feature list upon exiting the fitting package. + +It is common to transfer the feature identifications and coordinate +function from one image to another. When a new image without a +database entry is examined, such as when going to the next image in the +input list or selecting a new image with the ":image" command, the +current feature list and coordinate function are kept. Alternatively, +a database record from a different image may be read with the ":read" +command. When transferring feature identifications between images the +feature coordinates will not agree exactly with the new image feature +positions and several options are available to reregister the feature +positions. The key 'c' centers the feature nearest the cursor using +the current position as the starting point. When preceded with the 'a' +key all the features are recentered (the user must refit the coordinate +function if desired). As an aside, the recentering function is also +useful when the parameters governing the feature centering algorithm +are changed. + +The (c)entering function is applicable when the shift between the +current and true feature positions is small. Larger shifts may be +determined automatically with the 'x' function which correlates +features in the image with the feature list. The features are then +recentered. A zero point shift may also be given interactively with +the 's' key by using the cursor to indicate the coordinate of a point +in the spectrum. If there are no features then the shift is exactly as +marked by the cursor but if there are features the approximate shift is +applied and then the features are recentered. The shift is then the +mean shift of the features after recentering. The shift is used as a +zero point offset added to the dispersion function. The shift is +computed in user coordinates for the fundamental order. Shifts for +each order are given by scaling of this shift. + +In addition to the single keystroke commands there are commands +initiated by the key ':' (colon commands). As with the keystroke +commands there are a number of standard graphics features available +begining with ":." (type ":.help" for these commands). The colon +commands allow the task parameter values to be listed and to be reset +within the task. A parameter is listed by typing its name. The colon +command ":show" lists all the parameters. A parameter value is reset +by typing the parameter name followed by the new value; for example +":match 10". Other colon commands display the feature list +(:features), control reading and writing records to the database (:read +and :write), and set the graph display format. + +The feature identification process for an image is completed by typing +'q' to quit. Attempting to quit an image without explicitly recording +changes in the feature database produces a warning message and an +opportunity to record the information in the database. As an immediate +exit the 'I' interrupt key may be used. This does not save the feature +information. +.ih +ECHELLE DISPERSION FUNCTION FITTING +If a minimum of four features over at least two orders, depending on +the default function orders, have been identified a dispersion function +relating the user coordinates to the extracted pixel coordinate and +aperture number may be fit. However, more features are preferable to +determine changes in the dispersion as a function of position and +order. + +The form of the function fit explicitly includes the basic order number +dependence of echelle spectra; namely the wavelength of a particular +point along the dispersion direction in different orders varies as the +reciprocal of the order number. Because of distortions, the differing +extraction paths through the two dimensional image, and rotations of +the spectra relative to the axis of constant dispersion (i.e. aligning +the orders with the image columns or lines instead of aligning the +emission and absorption features) there will be residual dependancies on +the extracted pixel positions and orders. These residual dependancies +are fit by a two dimensional polynomial of arbitrary order including +cross terms. Because the basic order number dependence has been +removed the orders should be relatively low. Currently the functions +are bi-dimensional chebyshev and legendre polynomials though other +function may be added in the future. + +Since the true order number may not be known initially a linear +relation between the aperture numbers and the order numbers is also +determined which minimizes the residuals. This relation allows an +unknown offset and possible a reversed direction of increasing order. +The fitted function is then represented as: + +.nf + y = offset +/- aperture + + wavelength = f (x, y) / y +.fi + +where y is the order number and x is the extracted pixel coordinate along the +dispersion. + +If the order offset is known initially or as a result of previous the 'o' +fit may be used. The dispersion minimization for the order offset is +then not done. This will, therefore, be faster than using the full +fit, key 'f', to also determine the order offset. + +The fitting is done interactively as a submode of \fBecidentify\fR with its +own set of cursor commands. It is entered using the 'f' key and exited using +the 'q' key. The list of commands is given the CURSOR KEY section and is +available from the fitting mode with '?'. The functionality of this fitting +is fairly simple; the function and orders may be changed, points may be deleted +and undeleted, and the results of the fit may be displayed in various formats +by selecting quantities to be plotted along either axis. Generally one +changes plotting of the pixel coordinate, order number, and wavelength +along the x axis and residuals or radial velocity errors along the y axis. +One switches between increasing the x order and the y order while switching +between plotting verses x positions and order number until the residuals +have been reduced to remove all systematic trends. +.ih +DATABASE RECORDS +The database specified by the parameter \fIdatabase\fR is a directory of +simple text files. The text files have names beginning with 'ec' followed +by the entry name, usually the name of the image. The database text files +consist of a number of records. A record begins with a line starting with the +keyword "begin". The rest of the line is the record identifier. Records +read and written by \fBecidentify\fR have "ecidentify" as the first word of the +identifier. Following this is a name which may be specified following the +":read" or ":write" commands. If no name is specified then the image name +is used. The lines following the record identifier contain +the feature information and dispersion function coefficients. +.ih +ECHELLE DISPERSION FUNCTIONS +The fitted echelle dispersion functions are evaluated as described in +this section. The basic equations are + +.nf + (1) w = (f(x,o) + shift) / o + (2) o = ap * slope + offset +.fi + +where w is the wavelength, x is the pixel coordinate along the order, o is +the order, and ap is the aperture number. The database parameter "shift" +provides a wavelength zero point shift and the parameters "slope" and +"offset" provide the transformation between aperture number and order. +Note that the function f(x,o) and the shift are in terms of first order +wavelengths. + +The database entries contain "parameter value" pairs. This includes the +parameters "shift", "offset", and "slope" defined above. The default +values for these if they are absent are 0, 0, and 1 respectively. The +"coefficients" parameter specifies the number of coefficients that follow +and define the first order wavelength dispersion function. The +coefficients and functions are described below. + +The numerical values following the "coefficients" parameter, shown in +the order in which they appear, have the following meaning. + +.nf + type Function type: 1=chebychev, 2=legendre + xpow Highest power of x + opow Highest power of o + xterms Type of cross terms: Always 1 for echelle functions + xmin Minimum x for normalization + xmax Maximum x for normalization + omin Minimum o for normalization + omax Maximum o for normalization + Cmn Coefficients: m=0-xpow, n=0-opow, m varies first +.fi + +The functions are evaluated by a sum over m and n up to the specified +highest powers. + +.nf + (3) f(x,o) = sum {Cmn * Pm * Pn} m=0-xpow, n=0-opow +.fi + +The Cmn are the coefficients of the polynomial terms Pm and Pn which +are defined as follows. + +.nf + Chebyshev: + xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin) + P0 = 1.0 + P1 = xnorm + Pm+1 = 2.0 * xnorm * Pm - Pm-1 + + onorm = (2 * o - (omax + omin)) / (omax - omin) + P0 = 1.0 + P1 = onorm + Pn+1 = 2.0 * onorm * Pn - Pn-1 + + Legendre: + xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin) + P0 = 1.0 + P1 = xnorm + Pm+1 = ((2m + 1) * xnorm * Pm - m * Pm-1)/ (m + 1) + + onorm = (2 * o - (omax + omin)) / (omax - omin) + P0 = 1.0 + P1 = onorm + Pn+1 = ((2n + 1) * onorm * Pn - n * Pn-1)/ (n + 1) +.fi + +Note that the polynomial terms are obtained by first normalizing the x and +o values to the range -1 to 1 and then iteratively evaluating them. +.ih +EXAMPLES +Because this task is interactive it is difficult to provide an actual +example. The following describes a typical usage on arc spectra. + + cl> ecidentify arc1.ec,arc2.ec + +.ls (1) +The database is searched for an entry for arc1.ec. None is found and +the first order is plotted as a function of pixel coordinate. +.le +.ls (2) +Using a line identification chart or vast experience one of the +emission lines is identified and marked with the 'm' key. Using the +cursor position a center is found by the centering algorithm. The +aperture number, pixel position, wavelength (which is currently the +same as the pixel position), and a prompt for the true value with the +default value INDEF is printed. The true wavelength is typed in and the +status line is redrawn with the information for the feature. +.le +.ls (3) +The orders are changed with the 'j', 'k', or 'o' key and further lines are +identified with the 'm' key. +.le +.ls (4) +After a number of lines have been marked spanning the full range of the orders +and pixel coordinates the key 'l' is typed. The program now fits a preliminary +dispersion solution using the current function and function orders. Using this +function it examines each line in the line list and checks to see if there is +an emission line at that point. With many orders and lots of lines this may +take some time. After additional lines have been identified (up to +\fImaxfeatures\fR lines) the function is refit. Finally the current order +is regraphed in user coordinates. +.le +.ls (5) +Again we look at some orders and see if the automatic line identifications +make sense. +.le +.ls (6) +We next enter the dispersion function fitting mode with 'f'. A plot of the +residuals vs. pixel position is drawn. Some obvious misidentifications may +be deleted with the 'd' key. One way to proceed with determining the +function orders is to start at the lowest orders (xorder = 2 for linear +and yorder = 1 for no order dependence beyond the basic dependence). We then +increase each order one at a time. The x axis is changed between order +number and pixel position using the 'x' key to see the dependence on each +dimension. The orders are increased until there are no systematic trends +apparent. Normally the y order (for the aperture or order number dependence) +is low such as 2 to 4 while the x order (for the dispersion direction) is +whatever is needed to account for distortions. Also one can prune deviant +points with the 'd' key. Note that the order offset derived from the +aperture number is given in the title block along with the RMS. When done +we exit with 'q'. +.le +.ls (7) +The new function fit is then evaluated for all orders and the current order +is redrawn based on the new dispersion. Note also that the status line +information for the current feature has both the fitted wavelength and the +user identified wavelength. We can add or delete lines and iterate with the +fitting until we are happy with the feature list and dispersion function. +.le +.ls (8) +Typing 'q' exits the graph and prints a query about saving the information +in the database. We answer yes to this query. Note that information can +also be saved while still in the graphics loop using ":write". +.le +.ls (9) +The next image in the list is then graphed but the last dispersion solution +and feature list is maintained. If the shift is small for the new arc we +type 'a' 'c' to recenter all the features. This does not refit the dispersion +automatically so we then do 'f'. Alternatively, we could use the 's' or 'x' +keys to determine a large shift and do the recentering. +.le +.ls (10) +Finally we can exit with 'q' or examine further images with the ":image" +command. +.le +.ih +REVISIONS +.ls ECIDENTIFY V2.11 +The dispersion units are now determined from a user parameter, +the coordinate list, or the database entry. +.le +.ih +SEE ALSO +apsum, center1d, gtools, ecreidentify, identify +.endhelp diff --git a/noao/imred/echelle/doc/ecreidentify.hlp b/noao/imred/echelle/doc/ecreidentify.hlp new file mode 100644 index 00000000..53ab0f8c --- /dev/null +++ b/noao/imred/echelle/doc/ecreidentify.hlp @@ -0,0 +1,117 @@ +.help ecreidentify Jun88 noao.imred.echelle +.ih +NAME +ecreidentify -- Reidentify features in echelle spectra +.ih +USAGE +ecreidentify images reference +.ih +PARAMETERS +.ls images +Echelle images in which the features in the reference image are to be +reidentified and a new dispersion function fit. +.le +.ls reference +Echelle image with previously identified features and dispersion +function. +.le +.ls shift = 0. +Shift in user coordinates to be added to the reference features before +centering. If INDEF then a shift is determined by correlating the +reference features to features automatically identified in the image to +be reidentified. +.le +.ls cradius = 5. +Centering radius in pixels. If a reidentified feature falls further +than this distance from the reference position (after shifting) it is +not reidentified. +.le +.ls threshold = 10. +In order for a feature center to be determined the range of pixel +intensities around the feature must exceed this threshold. +.le +.ls refit = yes +Refit the dispersion function? If yes and there are more than 4 +features in more than one order and a dispersion function was defined +in the reference image then a new dispersion function of the same type +and order offset +as in the reference image is fit using the new pixel positions. +Otherwise only a zero point shift is determined from the revised fitted +coordinates without changing the form of the dispersion function. +.le +.ls database = "database" +Database containing the feature data for the reference image and in +which the features for the reidentified images are recorded. +.le +.ls logfiles = "STDOUT,logfile" +List of file in which to keep a processing log. If a null file, "", is +given then no log is kept. If the log file is "STDOUT" then the log is +written to the terminal. +.le +.ih +DESCRIPTION +Emission or absorption features in a reference echelle spectrum are +reidentified in other echelle spectra. The features for the reference +image and those determined for reidentified images are recorded in the +specified database. + +The first step in transferring identifications from the reference +spectrum to another spectrum is to add a shift (in wavelength) to each +feature in the reference image. The shift is specified by the +parameter \fIshift\fR. This shift is for the fundamental order (order +number 1) which is then applied to each order by dividing by the order +number. If the shift is specified as INDEF then a shift is determined +by finding the peaks in the input spectrum and correlating these peaks +against the feature in the reference spectrum. This is the 'x' +algorithm described in \fBecidentify\fR. + +After the shift has been added to move the reference features to near +the input spectrum features these positions are adjusted by centering +on the features using the \fBcenter1d\fR algorithm. The parameters +\fIcradius\fR and \fIthreshold\fR are used in this operation. If the +centering fails to find the feature within the centering radius +(\fIcradius\fR) that feature is eliminated from the feature list. + +If the parameter \fIrefit\fR has the value "no" then the average shift +in the feature positions is recorded as a zero point wavelength offset +for the fundamental order without changing the shape of the dispersion +function. If the parameter has the value "yes" then the new feature +positions are used to refit the dispersion function (of the same function +type and orders). The order offset is also maintained. + +Log information is written to the specified log files. To log this to +the terminal, called the standard output, use STDOUT. The log +information includes reference spectrum, the spectrum being reidentified, +the number of initial features and the number actually reidentified, +the average shift in pixels, the average shift in wavelength (in terms +of the fundamental order), the average fractional shift in wavelength +(which can be scaled to a radial velocity), and the RMS of the features +wavelengths given by the dispersion function to the user specified true +wavelengths. +.ih +EXAMPLES +The features in the spectrum f033.ec were identified previously +with the task \fBecidentify\fR. The features positions in f043.ec are +are reidentified with and without refitting the dispersion function as +follows: + +.nf +ec> ecreidentify f043.ec f033.ec + +ECREIDENTIFY: NOAO/IRAF V2.7 seaman@puppis Mon 09:03:51 27-Jun-88 + Reference image = f033.ec, Refit = yes + Image Found Pix Shift User Shift Z Shift RMS + f043.ec 561/561 0.11 -1.07 -1.9E-6 0.0117 + + +ec> ecreidentify f043.ec f033.ec refit=no + +ECREIDENTIFY: NOAO/IRAF V2.7 seaman@puppis Mon 09:15:21 27-Jun-88 + Reference image = f033.ec, Refit = no + Image Found Pix Shift User Shift Z Shift RMS + f043.ec 561/561 0.11 -1.07 -1.9E-6 0.0131 +.fi +.ih +SEE ALSO +center1d, ecidentify +.endhelp |