diff options
Diffstat (limited to 'noao/imred/specred')
| -rw-r--r-- | noao/imred/specred/Revisions | 167 | ||||
| -rw-r--r-- | noao/imred/specred/doc/dofibers.hlp | 1531 | ||||
| -rw-r--r-- | noao/imred/specred/doc/dofibers.ms | 1807 | ||||
| -rw-r--r-- | noao/imred/specred/doc/doslit.hlp | 1201 | ||||
| -rw-r--r-- | noao/imred/specred/doc/doslit.ms | 1401 | ||||
| -rw-r--r-- | noao/imred/specred/doc/msresp1d.hlp | 191 | ||||
| -rw-r--r-- | noao/imred/specred/doc/skysub.hlp | 98 | ||||
| -rw-r--r-- | noao/imred/specred/dofibers.cl | 74 | ||||
| -rw-r--r-- | noao/imred/specred/dofibers.par | 42 | ||||
| -rw-r--r-- | noao/imred/specred/msresp1d.cl | 234 | ||||
| -rw-r--r-- | noao/imred/specred/msresp1d.par | 13 | ||||
| -rw-r--r-- | noao/imred/specred/params.par | 67 | ||||
| -rw-r--r-- | noao/imred/specred/sparams.par | 65 | ||||
| -rw-r--r-- | noao/imred/specred/specred.cl | 103 | ||||
| -rw-r--r-- | noao/imred/specred/specred.hd | 11 | ||||
| -rw-r--r-- | noao/imred/specred/specred.men | 51 | ||||
| -rw-r--r-- | noao/imred/specred/specred.par | 15 |
17 files changed, 7071 insertions, 0 deletions
diff --git a/noao/imred/specred/Revisions b/noao/imred/specred/Revisions new file mode 100644 index 00000000..890668dc --- /dev/null +++ b/noao/imred/specred/Revisions @@ -0,0 +1,167 @@ +.help revisions Jun88 noao.imred.msred +.nf + +======= +V2.12.3 +======= + +specred.cl +specred.men + 1. Added ODCOMBINE and LSCOMBINE to the package. + 2. Modified SCOMBINE to point to new executable. + (6/21/04, Valdes) + +===== +V2.12 +===== + +imred$specred/msresp1d.cl + Modified to use "imtype" rather than hardwired to "imh". This uses + the same code as srcfibers$fibresponse.cl. + (2/29/00, Valdes) + +========= +V2.11.3p1 +========= +======= +V2.11.3 +======= + +imred$specred/doc/msresp1d.hlp + The package was incorrect and the requirement that the unextracted + spectrum must be present even if the extracted spectrum is present + was made clearer. (9/20/99, Valdes) + +======= +V2.11.2 +======= + +imred$specred/doc/dofibers.hlp +imred$specred/doc/doslit.hlp +imred$specred/doc/dofibers.ms +imred$specred/doc/doslit.ms + Updated for change where if both crval and cdelt are INDEF then the + automatic identification is not done. (5/2/96, Valdes) + +imred$specred/specred.cl + Increased the minimum min_lenuserarea from 40000 to 100000. + (7/31/96, Valdes) + +imred$specred/doc/doslit.hlp +imred$specred/doc/doslit.ms + Updated for the addition of automatic arc line identification. (4/9/96) + +imred$specred/sparams.par + Changed match from 10 to -3. (4/5/96, Valdes) + +imred$specred/dofibers.cl +imred$specred/dofibers.par +imred$specred/params.par +imred$specred/doc/dofibers.hlp +imred$specred/doc/dofibers.ms +imred$specred/doc/doslit.hlp +imred$specred/doc/doslit.ms + Added crval/cdelt parameters used in new version with automatic arc + line identification. (4/5/96, Valdes) + +imred$specred/doc/msresp1d.hlp + Added a sentence to say that extracted throughput (sky) spectra are + flat fielded before computing the throughput values. (1/9/96, Valdes) + +imred$specred/doc/dofibers.hlp +imred$specred/doc/dofibers.ms + Describes the new header option for the aperture identification table. + (7/25/95, Valdes) + +imred$specred/specred.cl +imred$specred/dofibers.cl +imred$specred/dofibers.par +imred$specred/doc/dofibers.hlp +imred$specred/doc/dofibers.ms + Added sky alignment option. (7/19/95, Valdes) + +======= +V2.10.4 +======= + +specred/specred.cl +specred/specred.men + 1. Added background, illumination, and response. + 2. Renamed the fiber response task to "fibresponse". + (12/29/94, Valdes) + +imred$specred/dofibers.cl + There was an incorrect default value for the dispaxis parameter: + )_dispaxis --> )_.dispaxis. (8/24/92, Valdes) + +============= +V2.10-V2.10.1 +============= + +imred$msred --> imred$specred + Renamed the package to a more generic name since it is for both + multiple aperture/fiber data as well as generic slit data. + (2/20/92, Valdes) + +imred$msred/msred.cl +imred$msred/msred.hd + Added generic slit and fiber reduction tasks to make this a complete + generic package. (2/19/92, Valdes) + +imred$msred/msresp1d.cl + Improved task to include throughput file (2/18/92, Valdes) + +imred$msred/msresp1d.cl + +imred$msred/doc/msresp1d.hlp + +imred$msred/msred.cl +imred$msred/msred.hd + 1. Added new task MSRESP1D modeled after imred$src/fibers/response but + using APALL instead of APSCRIPT and all the connections to PARAMS. + 2. Added new task SKYSUB from imred$src/fibers. + +imred$msred/msbplot.cl - +imred$msred/doc/msdispcor.hlp - +imred$msred/doc/msbplot.hlp - +imred$msred/msred.hd + 1. Moved help to ONEDSPEC. + +imred$msred/* + Updated to new APEXTRACT and ONEDSPEC packages. + (7/13/90, Valdes) + +==== +V2.9 +==== + +imred$msred/msbplot.cl + +imred$msred/doc/msbplot.hlp + +imred$msred/msred.cl +imred$msred/msred.men +imred$msred/msred.hd + Added a version of ECBPLOT (written by Rob Seaman) to the package with + appropriate changes to refer to lines and apertures instead of + orders. (10/27/89, Valdes) + +imred$msred/doc/msdispcor.hlp + Tried to make the description of the global parameter clearer. Also + fixed an incorrect example. (8/29/89, Valdes) + +==== +V2.8 +==== + +imred$msred/apnormalize.par + +imred$msred/msred.cl +imred$msred/msred.men + Added APNORMALIZE to the package. (6/1/89, Valdes) + +imred$msred/standard.par + Removed ennumerated list. (4/10/89, Valdes) + +imred$msred/* + +imred$msred/doc/* + + New package specialized for reducing spectra in "multispec" format. + It includes new tasks for doing dispersion solutions in multispec + format spectra. (3/29/89, Valdes) + +.endhelp diff --git a/noao/imred/specred/doc/dofibers.hlp b/noao/imred/specred/doc/dofibers.hlp new file mode 100644 index 00000000..d5a893a7 --- /dev/null +++ b/noao/imred/specred/doc/dofibers.hlp @@ -0,0 +1,1531 @@ +.help dofibers Jul95 noao.imred.specred +.ih +NAME +dofibers -- Multifiber data reduction task +.ih +USAGE +dofibers objects +.ih +SUMMARY +The \fBdofibers\fR reduction task is specialized for scattered light +subtraction, extraction, flat +fielding, fiber throughput correction, wavelength calibration, and sky +subtraction of multifiber 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 large amount of data +generated by multifiber instruments. Variants of this task are +\fBdoargus\fR, \fBdofoe\fR, \fBdohydra\fR, and \fBdo3fiber\fR. +.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 spectra +are extracted and used to make flat field calibrations. If a separate +throughput file or image is not specified the flat field is also used +for computing a fiber throughput correction. +.le +.ls throughput = "" (optional) +Throughput file or image. If an image is specified, typically a blank +sky observation, the total flux through +each fiber is used to correct for fiber throughput. If a file consisting +of lines with the aperture number and relative throughput is specified +then the fiber throughput will be corrected by those values. If neither +is specified but a flat field image is given it is used to compute the +throughput. +.le +.ls arcs1 = "" (at least one if dispersion correcting) +List of primary arc spectra. These spectra are used to define the dispersion +functions for each fiber apart from a possible zero point correction made +with secondary shift spectra or arc calibration fibers in the object spectra. +One fiber from the first spectrum is used to mark lines and set the dispersion +function interactively and dispersion functions for all other fibers and +arc spectra are derived from it. +.le +.ls arcs2 = "" (optional) +List of optional shift arc spectra. Features in these secondary observations +are used to supply a wavelength zero point shift through the observing +sequence. One type of observation is dome lamps containing characteristic +emission lines. +.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 fibers = 97 (apfind) +Number of fibers. This number is used during the automatic definition of +the apertures from the aperture reference spectrum. It is best if this +reflects the actual number of fibers which may be found in the aperture +reference image. The interactive +review of the aperture assignments allows verification and adjustments +to the automatic aperture definitions. +.le +.ls width = 12. (apedit) +Approximate base full width of the fiber profiles. This parameter is used +for the profile centering algorithm. +.le +.ls minsep = 8. (apfind) +Minimum separation between fibers. Weaker spectra or noise within this +distance of a stronger spectrum are rejected. +.le +.ls maxsep = 15. (apfind) +Maximum separation between adjacent fibers. This parameter +is used to identify missing fibers. If two adjacent spectra exceed this +separation then it is assumed that a fiber is missing and the aperture +identification assignments will be adjusted accordingly. +.le +.ls apidtable = "" (apfind) +Aperture identification table. This may be either a text file or an +image. A text file contains the fiber number, beam number defining object +(1), sky (0), and arc (2) fibers, and a object title. An image contains +the keywords SLFIBnnn with string value consisting of the fiber number, +beam number, optional right ascension and declination, and an object +title. Unassigned and broken fibers (beam of -1) should be included in the +identification information since they will automatically be excluded. +.le +.ls crval = INDEF, cdelt = INDEF (autoidentify) +These parameters specify an approximate central wavelength and dispersion. +They may be specified as numerical values, INDEF, or image header keyword +names whose values are to be used. +If both these parameters are INDEF then the automatic identification will +not be done. +.le +.ls objaps = "", skyaps = "", arcaps = "" +List of object, sky, and arc aperture numbers. These are used to +identify arc apertures for wavelength calibration and object and sky +apertures for sky subtraction. Note sky apertures may be identified as +both object and sky if one wants to subtract the mean sky from the +individual sky spectra. Typically the different spectrum types are +identified by their beam numbers and the default, null string, +lists select all apertures. +.le +.ls objbeams = "0,1", skybeams = "0", arcbeams = 2 +List of object, sky, and arc beam numbers. The convention is that sky +fibers are given a beam number of 0, object fibers a beam number of 1, and +arc fibers a beam number of 2. The beam numbers are typically set in the +\fIapidtable\fR. Unassigned or broken fibers may be given a beam number of +-1 in the aperture identification table since apertures with negative beam +numbers are not extracted. Note it is valid to identify sky fibers as both +object and sky. +.le + +.ls scattered = no (apscatter) +Smooth and subtracted scattered light from the object and flat field +images. This operation consists of fitting independent smooth functions +across the dispersion using data outside the fiber apertures and then +smoothing the individual fits along the dispersion. The initial +flat field, or if none is given the aperture reference image, are +done interactively to allow setting the fitting parameters. All +subsequent subtractions use the same fitting parameters. +.le +.ls fitflat = yes (flat1d) +Fit the composite flat field spectrum by a smooth function and divide each +flat field spectrum by this function? This operation removes the average +spectral signature of the flat field lamp from the sensitivity correction to +avoid modifying the object fluxes. +.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 skyalign = no +Align sky lines? If yes then for the first object spectrum you are asked +to mark one or more sky lines to use for alignment. Then these lines will +be found in all spectra and an average zeropoint shift computed and applied +to the dispersion solution to align these lines. Note that this assumes +the sky lines are seen in all fibers. +.le +.ls savearcs = yes +Save any simultaneous arc apertures? If no then the arc apertures will +be deleted after use. +.le +.ls skysubtract = yes +Subtract sky from the object spectra? If yes the sky spectra are combined +and subtracted from the object spectra as defined by the object and sky +aperture/beam parameters. +.le +.ls skyedit = yes +Overplot all the sky spectra and allow contaminated sky spectra to be +deleted? +.le +.ls saveskys = yes +Save the combined sky spectrum? If no then the sky spectrum will be +deleted after sky subtraction is completed. +.le +.ls splot = no +Plot the final spectra with the task \fBsplot\fR? +.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 = yes +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 provided there are no interactive +options (\fIskyedit\fR and \fIsplot\fR) selected. +.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 \fBdofibers\fR. +.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 observatory = "observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. See \fBobservatory\fR for more +details. +.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 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 = "SPECRED: ..." +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 \fBdofibers\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 order = "decreasing" (apfind) +When assigning aperture identifications order the spectra "increasing" +or "decreasing" with increasing pixel position (left-to-right or +right-to-left in a cross-section plot of the image). +.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 = -5., upper = 5. (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 = 3 (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 +-- SCATTERED LIGHT PARAMETERS -- +.ls buffer = 1. (apscatter) +Buffer distance from the aperture edges to be excluded in selecting the +scattered light pixels to be used. +.le +.ls apscat1 = "" (apscatter) +Fitting parameters across the dispersion. This references an additional +set of parameters for the ICFIT package. The default is the "apscat1" +parameter set. +.le +.ls apscat2 = "" (apscatter) +Fitting parameters along the dispersion. This references an additional +set of parameters for the ICFIT package. The default is the "apscat2" +parameter set. +.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 multifiber 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 +.ls nsubaps = 1 (apsum) +During extraction it is possible to equally divide the apertures into +this number of subapertures. +.le + +.ce +-- FLAT FIELD FUNCTION FITTING PARAMETERS -- +.ls f_interactive = yes (fit1d) +Fit the composite one dimensional flat field spectrum 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 = 10 (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. (autoidentify/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 = "linelists$idhenear.dat" (autoidentify/identify) +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelists$". +.le +.ls match = -3. (autoidentify/identify) +The maximum difference for a match between the dispersion function prediction +value and a wavelength in the coordinate list. +.le +.ls fwidth = 4. (autoidentify/identify) +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 = "spline3", i_order = 3 (autoidentify/identify) +The default function and order to be fit to the arc wavelengths as a +function of the pixel coordinate. The functions choices are "chebyshev", +"legendre", "spline1", or "spline3". +.le +.ls i_niterate = 2, i_low = 3.0, i_high = 3.0 (autoidentify/identify) +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.le +.ls refit = yes (reidentify) +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 +.ls addfeatures = no (reidentify) +Add new features from a line list during each reidentification? +This option can be used to compensate for lost features from the +reference solution. Care should be exercised that misidentified features +are not introduced. +.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 \fBdofibers\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 + +.ce +-- SKY SUBTRACTION PARAMETERS -- +.ls combine = "average" (scombine) (average|median) +Option for combining sky pixels at the same dispersion coordinate after any +rejection operation. The options are to compute the "average" or "median" +of the pixels. The median uses the average of the two central +values when the number of pixels is even. +.le +.ls reject = "none" (scombine) (none|minmax|avsigclip) +Type of rejection operation performed on the pixels which overlap at each +dispersion coordinate. The algorithms are discussed in the +help for \fBscombine\fR. The rejection choices are: + +.nf + none - No rejection + minmax - Reject the low and high pixels + avsigclip - Reject pixels using an averaged sigma clipping algorithm +.fi + +.le +.ls scale = "none" (none|mode|median|mean) +Multiplicative scaling to be applied to each spectrum. The choices are none +or scale by the mode, median, or mean. This should not be necessary if the +flat field and throughput corrections have been properly made. +.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 \fBdofibers\fR reduction task is specialized for scattered light +subtraction, extraction, flat +fielding, fiber throughput correction, wavelength calibration, and sky +subtraction of multifiber 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 large amount of data generated by multifiber +instruments. Variants of this task are \fBdoargus\fR, \fBdofoe\fR, +\fBdohydra\fR, and \fBdo3fiber\fR. + +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, and 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 +\fBdofibers\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 are first processed with \fBccdproc\fR for overscan, +bias, and dark corrections. +The \fBdofibers\fR task will abort if the image header keyword CCDPROC, +which is added by \fBccdproc\fR, is missing. If the data processed outside +of the IRAF \fBccdred\fR package then a dummy CCDPROC keyword should be +added to the image headers; say with \fBhedit\fR. +.le +.ls [2] +Set the \fBdofibers\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. A throughput file or image, +such as a blank sky observation, may also be specified. If there are many +object or arc spectra per setup you might want to prepare "@ files". +Specify the aperture identification table for the configuration +if one has been created. If the image headers contain the SLFIB keywords +specify an image name; typically the same as the aperture reference +image. +You might wish to verify the geometry parameters, +separations, dispersion direction, etc., which may +change with different detector setups. The processing parameters are set +for complete reductions but for quicklook you might not use the clean +option or dispersion calibration and sky subtraction. + +The parameters are set for a particular configuration and different +configurations may use different flat fields, arcs, and aperture +identification tables. +.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. +The spectra are found automatically and apertures assigned based on +task parameters and the aperture identification table. Unassigned +fibers may have a negative beam number and will be ignored in subsequent +processing. The resize option sets the aperture size to the widths of +the profiles at a fixed fraction of the peak height. The interactive +review of the apertures is recommended. If the identifications are off +by a shift the 'o' key is used. To exit the aperture review type 'q'. +.le +.ls [5] +The fiber 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 fibers need be examined and the "NO" +response will quit the interactive fitting. To exit the interactive +fitting type 'q'. +.le +.ls [6] +If scattered light subtraction is to be done the flat field image is +used to define the scattered light fitting parameters interactively. +If one is not specified then the aperture reference image is used for +this purpose. + +There are two queries for the interactive fitting. A graph of the +data between the defined reference apertures separated by a specified +buffer distance is first shown. The function order and type may be +adjusted. After quiting with 'q' the user has the option of changing +the buffer value and returning to the fitting, changing the image line +or column to check if the fit parameters are satisfactory at other points, +or to quit and accept the fit parameters. After fitting all points +across the dispersion another graph showing the scattered light from +the individual fits is shown and the smoothing parameters along the +dispersion may be adjusted. Upon quiting with 'q' you have the option +of checking other cuts parallel to the dispersion or quiting and finishing +the scattered light function smoothing and subtraction. + +If there is a throughput image then this is corrected for scattered light +noninteractively using the previous fitting parameters. +.le +.ls [7] +If flat fielding is to be done the flat field spectra are extracted. The +average spectrum over all fibers is determined and a function is fit +interactively (exit with 'q'). This function is generally of sufficiently +high order that the overall shape is well fit. This function is then used +to normalize the individual flat field spectra. If a throughput image, a +sky flat, is specified then the total sky counts through each fiber are +used to correct the total flat field counts. Alternatively, a separately +derived throughput file can be used for specifying throughput corrections. +If neither type of throughput is used the flat field also provides the +throughput correction. The final response spectra are normalized to a unit +mean over all fibers. The relative average throughput for each fiber is +recorded in the log and possibly printed to the terminal. +.le +.ls [8] +If dispersion correction is selected the first arc in the arc list is +extracted. The middle fiber is used to identify the arc lines and define +the dispersion function using the task \fBautoidentify\fR. The +\fIcrval\fR and \fIcdelt\fR parameters are used in the automatic +identification. Whether or not the automatic identification is +successful you will be shown the result of the arc line identification. +If the automatic identification is not successful identify a few arc +lines with 'm' 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] +The remaining fibers are automatically reidentified. You have the option +to review the line identifications and dispersion function for each fiber +and interactively add or delete arc lines and change fitting parameters. +This can be done selectively, such as when the reported RMS increases +significantly. +.le +.ls [10] +If the spectra are to be resampled to a linear dispersion system +(which will be the same for all spectra) default dispersion parameters +are printed and you are allowed to adjust these as desired. +.le +.ls [11] +If the sky line alignment option is selected and the sky lines have not +been identified for a particular aperture identification table then you are +asked to mark one or more sky lines. You may simply accept the wavelengths +of these lines as defined by the dispersion solution for this spectrum and +fiber or you may specify knowns wavelengths for the lines. These lines will +be reidentified in all object spectra extracted and a mean zeropoint shift +will be added to the dispersion solution. This has the effect of aligning +these lines to optimize sky subtraction. +.le +.ls [12] +The object spectra are now automatically scattered light subtracted, + extracted, flat fielded, and dispersion corrected. +.le +.ls [13] +When sky subtracting, the individual sky spectra may be reviewed and some +spectra eliminated using the 'd' key. The last deleted spectrum may be +recovered with the 'e' key. After exiting the review with 'q' you are +asked for the combining option. The type of combining is dictated by the +number of sky fibers. +.le +.ls [14] +The option to examine the final spectra with \fBsplot\fR may be given. +To exit type 'q'. +.le +.ls [15] +If scattered light is subtracted from the input data a copy of the +original image is made by appending "noscat" to the image name. +If the data are reprocessed with the \fIredo\fR flag the original +image will be used again to allow modification of the scattered +light parameters. + +The final spectra will have the same name as the original 2D images +with a ".ms" extension added. The flat field and arc spectra will +also have part of the aperture identification table name added to +allow different configurations to use the same 2D flat field and arcs +but with different aperture definitions. If using the sky alignment +option an image "align" with the aperture identification table name +applied will also be created. +.le + +\fBSpectra and Data Files\fR + +The basic input consists of multifiber 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. +The \fBdofibers\fR task will abort if the image header keyword CCDPROC, +which is added by \fBccdproc\fR, is missing. If the data processed outside +of the IRAF \fBccdred\fR package then a dummy CCDPROC keyword should be +added to the image headers; say with \fBhedit\fR. +Flat fielding is +generally not done at this stage but as part of \fBdofibers\fR. +If flat fielding is done as part of the basic CCD processing then +a flattened flat field, blank sky observation, or throughput file +should still be created for applying fiber throughput corrections. + +The task \fBdofibers\fR uses several types of calibration spectra. These +are flat fields, blank sky flat fields, comparison lamp spectra, auxiliary +mercury line (from the dome lights) or sky line spectra, and simultaneous +arc spectra taken during the object observation. The flat field, +throughput image or file, auxiliary emission line spectra, and simultaneous +comparison fibers are optional. If a flat field is used then the sky flat +or throughput file is optional assuming the flat field has the same fiber +iillumination. It is legal to specify only a throughput image or file and +leave the flat field blank in order to simply apply a throughput +correction. Because only the total counts through each fiber are used from +a throughput image, sky flat exposures need not be of high signal per +pixel. + +There are three types of arc calibration methods. One is to take arc +calibration exposures through all fibers periodically and apply the +dispersion function derived from one or interpolated between pairs to the +object fibers. This is the most common method. Another method is to +use only one or two all-fiber arcs to define the shape of the dispersion +function and track zero point wavelength shifts with \fIsimultaneous arc\fR +fibers taken during the object exposure. The simultaneous arcs may or may +not be available at the instrument but \fBdofibers\fR can use this type of +observation. The arc fibers are identified by their beam or aperture +numbers. A related and mutually exclusive method is to use \fIauxiliary +line spectra\fR such as lines in the dome lights or sky lines to monitor +shifts relative to a few actual arc exposures. The main reason to do this +is if taking arc exposures through all fibers is inconvenient. + +The assignment of arc or auxiliary line calibration exposures to object +exposures is generally done by selecting the nearest in time and +interpolating. There are other options possible which are described under +the task \fBrefspectra\fR. The most general option is to define a table +giving the object image name and the one or two arc spectra to be assigned +to that object. That file is called an \fIarc assignment table\fR and it +is one of the optional setup files which can used with \fBdofibers\fR. + +The first step in the processing is identifying the spectra in the images. +The \fIaperture identification table\fR contains information about the fiber +assignments. The identification table is not mandatory, sequential numbering +will be used, but it is highly recommended for keeping track of the objects +assigned to the fibers. The aperture identification table may be +a file containing lines +specifying an aperture number, a beam number, and an object +identification. It may also be an image whose header contains the keywords +SLFIB with strings consisting of an aperture number, beam number, optional +right ascension and declination, and a tile. The file lines or keywords +must be in the same order as the fibers in the +image. The aperture number may be any unique number but it is recommended +that the fiber number be used. The beam number is used to flag object, +sky, arc, or other types of spectra. The default beam numbers used by the +task are 0 for sky, 1 for object, and 2 for arc. The object +identifications are optional but it is good practice to include them so +that the data will contain the object information independent of other +records. Figure 1 shows an example identification file called M33Sch2. +.nf + + Figure 1: Example Aperture Identification File + + cl> type m33sch2 + 1 1 143 + 2 1 254 + 3 0 sky + 4 -1 Broken + 5 2 arc + . + . + . + 44 1 s92 + 45 -1 Unassigned + 46 2 arc + 47 0 sky + 48 1 phil2 + +.fi +Note the identification of the sky fibers with beam number 0, the object +fibers with 1, and the arc fibers with 2. +The broken and unassigned fiber entries, given beam +number -1, are optional but recommended to give the automatic spectrum +finding operation the best chance to make the correct identifications. The +identification table will vary for each plugboard setup. Additional +information about the aperture identification table may be found in the +description of the task \fBapfind\fR. + +An alternative to using an aperture identification table is to give no +name, the "" empty string, and to explicitly give a range of +aperture numbers for the skys and possibly for the sky subtraction +object list in the parameters \fIobjaps, skyaps, arcaps, objbeams, +skybeams,\fR and \fIarcbeams\fR. This is reasonable if the fibers always +have a fixed typed. As an example the CTIO Argus instrument always +alternates object and sky fibers so the object apertures can be given +as 1x2 and the sky fibers as 2x2; i.e. objects are the odd numbered +apertures and skys are the even numbered apertures. + +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 +".ms" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, wavelength, and identification +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 tools 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. + +\fBPackage Parameters\fR + +The \fBspecred\fR package parameters set parameters affecting all the +tasks in the package. +The dispersion axis parameter defines the image axis along which the +dispersion runs. This is used if the image header doesn't define the +dispersion axis with the DISPAXIS keyword. +The observatory parameter is used if there is no +OBSERVAT keyword in the image header (see \fBobservatory\fR for more +details). The spectrum interpolation type might be changed to "sinc" but +with the cautions given in \fBonedspec.package\fR. +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 \fBdofibers\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 list of objects and arcs can be @ files if desired. The aperture +reference spectrum is usually the same as the flat field spectrum though it +could be any exposure with enough signal to accurately define the positions +and trace the spectra. The first list of arcs are the standard Th-Ar or +HeNeAr comparison arc spectra (they must all be of the same type). The +second list of arcs are the auxiliary emission line exposures mentioned +previously. + +The detector read out noise and gain are used for cleaning and variance +(optimal) extraction. This is specified either explicitly or by reference +to an image header keyword. +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 and separation parameters define the dimensions (in pixels) of the +spectra (fiber profile) across the dispersion. The width parameter +primarily affects the centering. The maximum separation parameter is +important if missing spectra from the aperture identification table are to +be correctly skipped. The number of fibers is either the actual number +of fibers or the number in the aperture identification table. An attempt +is made to account for unassigned or missing fibers. As a recommendation +the actual number of fibers should be specified. + +The approximate central wavelength and dispersion are used for the +automatic identification of the arc reference. They may be specified +as image header keywords or values. The INDEF values search the +entire range of the coordinate reference file but the automatic +line identification algorithm works much better and faster if +approximate values are given. + +The task needs to know which fibers are object, sky if sky subtraction is +to be done, and simultaneous arcs if used. One could explicitly give the +aperture numbers but the recommended way, provided an aperture +identification table is used, is to select the apertures based on the beam +numbers. The default values are recommended beam numbers. Sky +subtracted sky spectra are useful for evaluating the sky subtraction. +Since only the spectra identified as objects are sky subtracted one can +exclude fibers from the sky subtraction. For example, if the +\fIobjbeams\fR parameter is set to 1 then only those fibers with a beam of +1 will be sky subtracted. All other fibers will remain in the extracted +spectra but will not be sky subtracted. + +The next set of parameters select the processing steps and options. The +scattered light option allows fitting and subtracting a scattered light +surface from the input object and flat field. If there is significant +scattered light which is not subtracted the fiber throughput correction +will not be accurate. 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 and not introducing the reciprocal of the flat field spectrum into +the object spectra. 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. If simultaneous arc fibers are defined there is an option to delete +them from the final spectra when they are no longer needed. + +The sky alignment option allows applying a zeropoint dispersion shift +to all fibers based on one or more sky lines. This requires all fibers +to have the sky lines visible. When there are sky lines this will +improve the sky subtraction if there is a systematic error in the +fiber iillumination between the sky and the arc calibration. + +The sky subtraction option selects whether to combine the sky fiber spectra +and subtract this sky from the object fiber spectra. \fIDispersion +correction and sky subtraction are independent operations.\fR This means +that if dispersion correction is not done then the sky subtraction will be +done with respect to pixel coordinates. This might be desirable in some +quick look cases though it is incorrect for final reductions. + +The sky subtraction option has two additional options. The individual sky +spectra may be examined and contaminated spectra deleted interactively +before combining. This can be a useful feature in crowded regions. The +final combined sky spectrum may be saved for later inspection in an image +with the spectrum name prefixed by \fBsky\fR. + +After a spectrum has been processed it is possible to examine the results +interactively using the \fBsplot\fR tasks. This option has a query which +may be turned off with "YES" or "NO" if there are multiple spectra to be +processed. + +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 +aperture identification table, a new reference image, new flat fields, and a +new arc reference. 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. This will only occur if sky spectra editing and +\fBsplot\fR review (interactive operations) are turned off, either when the +task is run or by responding with "NO" to the queries during processing. + +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 \fBdofibers\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 \fBdofibers\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 \fBdofibers\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 +multifiber 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 \fBdofibers\fR parameters by typing \fI:e +params\fR or simply \fI:e\fR if positioned at the \fIparams\fR +parameter. + +\fBExtraction\fR + +The identification of the spectra in the two dimensional images and their +scattered light subtraction and extraction to one dimensional spectra +in multispec format is accomplished +using the tasks from the \fBapextract\fR package. The first parameters +through \fInsubaps\fR control the extractions. + +The dispersion line is that used for finding the spectra, for plotting in +the aperture editor, and as the starting point for tracing. The default +value of \fBINDEF\fR selects the middle of the image. The aperture +finding, adjusting, editing, and tracing operations also allow summing a +number of dispersion lines to improve the signal. The number of lines is +set by the \fInsum\fR parameter. + +The order parameter defines whether the order of the aperture +identifications in the aperture identification table (or the default +sequential numbers if no table is used) is in the same sense as the image +coordinates (increasing) or the opposite sense (decreasing). If the +aperture identifications turn out to be opposite to what is desired when +viewed in the aperture editing graph then simply change this parameter. + +The basic data output by the spectral extraction routines are the one +dimensional spectra. Additional information may be output when the +\fIextras\fR option is selected and the cleaning or variance weighting +options are also selected. In this case a three dimensional image is +produced with the first element of the third dimension being the cleaned +and/or weighted spectra, the second element being the uncleaned and +unweighted spectra, and the third element being an estimate of the sigma +of each pixel in the extracted spectrum. Currently the sigma data is not +used by any other tasks and is only for reference. + +The initial step of finding the fiber spectra in the aperture reference +image consists of identifying the peaks in a cut across the dispersion, +eliminating those which are closer to each other than the \fIminsep\fR +distance, and then keeping the specified \fInfibers\fR highest peaks. The +centers of the profiles are determined using the \fBcenter1d\fR algorithm +which uses the \fIwidth\fR parameter. + +Apertures are then assigned to each spectrum. The initial edges of the +aperture relative to the center are defined by the \fIlower\fR and +\fIupper\fR parameters. The trickiest part of assigning the apertures is +relating the aperture identification from the aperture identification table +to automatically selected fiber profiles. The first aperture id in the +file is assigned to the first spectrum found using the \fIorder\fR parameter to +select the assignment direction. The numbering proceeds in this way except +that if a gap greater than a multiple of the \fImaxsep\fR parameter is +encountered then assignments in the file are skipped under the assumption +that a fiber is missing (broken). If unassigned fibers are still +visible in a flat field, either by design or by scattered light, the +unassigned fibers can be included in the number of fibers to find and +then the unassigned (negative beam number) apertures are excluded from +any extraction. For more on the finding and +assignment algorithms see \fBapfind\fR. + +The initial apertures are the same for all spectra but they can each be +automatically resized. The automatic resizing sets the aperture limits +at a fraction of the peak relative to the interfiber minimum. +The default \fIylevel\fR is to resize the apertures to 5% of the peak. +See the description for the task \fBapresize\fR for further details. + +The user is given the opportunity to graphically review and adjust the +aperture definitions. This is recommended. As mentioned previously, the +correct identification of the fibers is tricky and it is fundamentally +important that this be done correctly; otherwise the spectrum +identifications will not be for the objects they say. An important command in +this regard is the 'o' key which allows reordering the identifications +based on the aperture identification table. This is required if the first +fiber is actually missing since the initial assignment begins assigning the +first spectrum found with the first entry in the aperture file. The +aperture editor is a very powerful tool and is described in detail as +\fBapedit\fR. + +The next set of parameters control the tracing and function fitting of the +aperture reference positions along the dispersion direction. The position +of a spectrum across the dispersion is determined by the centering +algorithm (see \fBcenter1d\fR) at a series of evenly spaced steps, given by +the parameter \fIt_step\fR, along the dispersion. The step size should be +fine enough to follow position changes but it is not necessary to measure +every point. The fitted points may jump around a little bit due to noise +and cosmic rays even when summing a number of lines. Thus, a smooth +function is fit. The function type, order, and iterative rejection of +deviant points is controlled by the other trace parameters. For more +discussion consult the help pages for \fBaptrace\fR and \fBicfit\fR. The +default is to fit a cubic spline of three pieces with a single iteration of +3 sigma rejection. + +The actual extraction of the spectra by summing across the aperture at each +point along the dispersion is controlled by the next set of parameters. +The default extraction simply sums the pixels using partial pixels at the +ends. The options allow selection of a weighted 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 \fBparams\fR parameters. +For more on the variance weighted extraction and cleaning see +\fBapvariance\fR and \fBapprofiles\fR as well as \fBapsum\fR. + +The last parameter, \fInsubaps\fR, is used only in special cases when it is +desired to subdivide the fiber profiles into subapertures prior to +dispersion correction. After dispersion correction the subapertures are +then added together. The purpose of this is to correct for wavelength +shifts across a fiber. + +\fBScattered Light Subtraction\fR + +Scattered light may be subtracted from the input two dimensional image as +the first step. This is done using the algorithm described in +\fBapscatter\fR. This can be important if there is significant scattered +light since the flat field/throughput correction will otherwise be +incorrect. The algorithm consists of fitting a function to the data +outside the defined apertures by a specified \fIbuffer\fR at each line or +column across the dispersion. The function fitting parameters are the same +at each line. Because the fitted functions are independent at each line or +column a second set of one dimensional functions are fit parallel to the +dispersion using the evaluated fit values from the cross-dispersion step. +This produces a smooth scattered light surface which is finally subtracted +from the input image. Again the function fitting parameters are the +same at each line or column though they may be different than the parameters +used to fit across the dispersion. + +The first time the task is run with a particular flat field (or aperture +reference image if no flat field is used) the scattered light fitting +parameters are set interactively using that image. The interactive step +selects a particular line or column upon which the fitting is done +interactively with the \fBicfit\fR commands. A query is first issued +which allows skipping this interactive stage. Note that the interactive +fitting is only for defining the fitting functions and orders. When +the graphical \fBicfit\fR fitting is exited (with 'q') there is a second prompt +allowing you to change the buffer distance (in the first cross-dispersion +stage) from the apertures, change the line/column, or finally quit. + +The initial fitting parameters and the final set parameters are recorded +in the \fBapscat1\fR and \fBapscat2\fR hidden parameter sets. These +parameters are then used automatically for every subsequent image +which is scattered light corrected. + +The scattered light subtraction modifies the input 2D images. To preserve +the original data a copy of the original image is made with the same +root name and the word "noscat" appended. The scattered light subtracted +images will have the header keyword "APSCATTE" which is how the task +avoids repeating the scattered light subtraction during any reprocessing. +However if the \fIredo\fR option is selected the scattered light subtraction +will also be redone by first restoring the "noscat" images to the original +input names. + +\fBFlat Field and Fiber Throughput Corrections\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 +\fBdofibers\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 +\fBdofibers\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. + +In addition to correcting for pixel-to-pixel response the flat field step +also corrects for differences in the fiber throughput. Thus, even if the +pixel-to-pixel flat field corrections have been made in some other way it +is desirable to use a sky or dome flat observation for determining a fiber +throughput correction. Alternatively, a separately derived throughput +file may be specified. This file consists of the aperture numbers +(the same as used for the aperture reference) and relative throughput +numbers. + +The first step is extraction of the flat field spectrum, if 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. +After extraction one or more corrections are applied. If the \fIfitflat\fR +option is selected (the default) the extracted flat field spectra are +averaged together and a smooth function is fit. 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. + +The fitted function is divided into the individual flat field spectra to +remove the basic shape of the spectrum while maintaining the relative +individual pixel responses and any fiber to fiber differences. This step +avoids introducing the flat field spectrum shape into the object spectra +and closely preserves the object counts. + +If a throughput image is available (an observation of blank sky +usually at twilight) it is extracted. If no flat field is used the average +signal through each fiber is computed and this becomes the response +normalization function. Note that a dome flat may be used in place of a +sky in the sky flat field parameter for producing throughput only +corrections. If a flat field is specified then each sky spectrum is +divided by the appropriate flat field spectrum. The total counts through +each fiber are multiplied into the flat field spectrum thus making the sky +throughput of each fiber the same. This correction is important if the +iillumination of the fibers differs between the flat field source and the +sky. Since only the total counts are required the sky or dome flat field +spectra need not be particularly strong though care must be taken to avoid +objects. + +Instead of a sky flat or other throughput image a separately derived +throughput file may be used. It may be used with or without a +flat field. + +The final step is to normalize the flat field spectra by the mean counts of +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. The final relative throughput values are recorded in the +log and possibly printed on the terminal. + +These flat field response steps and algorithm are available as a separate +task called \fBmsresp1d\fR. + +\fBDispersion Correction\fR + +Dispersion corrections are applied to the extracted spectra if the +\fBdispcor\fR parameter is set. This can be a complicated process which +the \fBdofibers\fR task tries to simplify for you. 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 resampling the spectra to evenly spaced pixels +in wavelength. + +The comparison arc spectra are used to define dispersion functions for the +fibers using the tasks \fBautoidentify\fR and \fBreidentify\fR. The +interactive \fBautoidentify\fR task is only used on the central fiber of the +first arc spectrum to define the basic reference dispersion solution from +which all other fibers and arc spectra are automatically derived using +\fBreidentify\fR. \fBAutoidentify\fR attempts to automatically identify +the arc lines using the \fIcrval\fR and \fIcdelt\fR parameters. Whether +or not it is successful the user is presented with the interactive +identification graph. The automatic identifications can be reviewed and a +new solution or corrections to the automatic solution may be performed. + +The set of arc dispersion function parameters are from \fBautoidentify\fR and +\fBreidentify\fR. The parameters define a line list for use in +automatically assigning wavelengths to arc lines, a parameter controlling +the width of the centering window (which should match the base line +widths), the dispersion function type and order, parameters to exclude bad +lines from function fits, and parameters defining whether to refit the +dispersion function, as opposed to simply determining a zero point shift, +and the addition of new lines from the line list when reidentifying +additional arc spectra. 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 operation of \fBautoidentify\fR. + +Generally, taking a number of comparison arc lamp exposures interspersed +with the program spectra is sufficient to accurately dispersion calibrate +multifiber spectra. However, there are some other calibration options +which may be of interest. These options apply additional calibration data +consisting either of auxiliary line spectra, such as from dome lights or +night sky lines, or simultaneous arc lamp spectra taken through a few +fibers during the object exposure. These options add complexity to the +dispersion calibration process. + +When only arc comparison lamp spectra are used, dispersion functions are +determined independently for each fiber of each arc image and then assigned +to the matching fibers in the program object observations. The assignment +consists of selecting one or two arc images to calibrate each object +image. When two bracketing arc spectra are used the dispersion functions +are linearly interpolated (usually based on the time of the observations). + +If taking comparison exposures is time-consuming, possibly requiring +reconfiguration to illuminate the fibers, and the spectrograph is +expected to be fairly stable apart from small shifts, there are two +mutually exclusive methods for monitoring +shifts in the dispersion zero point from the basic arc lamp spectra other +than taking many arc lamp exposures. One is to use some fibers to take a +simultaneous arc spectrum while observing the program objects. The fibers +are identified by aperture or beam numbers. The second method is to use +\fIauxiliary line spectra\fR, such as mercury lines from the dome lights. +These spectra are specified with an auxiliary shift arc list, \fIarc2\fR. + +When using auxiliary line spectra for monitoring zero point shifts one of +these spectra is plotted interactively by \fBidentify\fR with the +reference dispersion function from the reference arc spectrum. The user +marks one or more lines which will be used to compute zero point wavelength +shifts in the dispersion functions automatically. The actual wavelengths +of the lines need not be known. In this case accept the wavelength based +on the reference dispersion function. As other observations of the same +features are made the changes in the positions of the features will be +tracked as zero point wavelength changes such that wavelengths of the +features remain constant. + +When using auxiliary line spectra the only arc lamp spectrum used is the +initial arc reference spectrum (the first image in the \fIarcs1\fR list). +The master dispersion functions are then shifted based on the spectra in +the \fIarcs2\fR list (which must all be of the same type). The dispersion +function assignments made by \fBrefspectra\fR using either the arc +assignment file or based on header keywords is done in the same way as +described for the arc lamp images except using the auxiliary spectra. + +If simultaneous arcs are used the arc lines are reidentified to determine a +zero point shift relative to the comparison lamp spectra selected, by +\fBrefspectra\fR, of the same fiber. A linear function of aperture +position on the image across the dispersion verses the zero point shifts +from the arc fibers is determined and applied to the dispersion functions +from the assigned calibration arcs for the non-arc fibers. Note that if +there are two comparison lamp spectra (before and after the object +exposure) then there will be two shifts applied to two dispersion functions +which are then combined using the weights based on the header parameters +(usually the observation time). + +The arc assignments may be done either explicitly with an arc assignment +table (parameter \fIarctable\fR) or based on a header parameter. The task +used is \fBrefspectra\fR and the user should consult this task if the +default behavior is not what is desired. The default is to interpolate +linearly between the nearest arcs based on the Julian date (corrected to +the middle of the exposure). The Julian date and a local Julian day number +(the day number at local noon) are computed automatically by the task +\fBsetjd\fR and recorded in the image headers under the keywords JD and +LJD. In addition the universal time at the middle of the exposure, keyword +UTMIDDLE, is computed by the task \fBsetairmass\fR and this may also be used +for ordering the arc and object observations. + +An optional step is to use sky lines in the spectra to compute a zeropoint +dispersion shift that will align the sky lines. This may improve sky +subtraction if the iillumination is not the same between the arc calibration +and the sky. When selected the object spectrum is dispersion corrected +using a non-linear dispersion function to avoid resampling the spectrum. +The sky lines are then reidentified in wavelength space from a template +list of sky lines. The mean shift in the lines for each fiber relative to +the template in that fiber is computed to give the zeropoint shift. The +database file is created when the first object is extracted. You are asked +to mark the sky lines in one fiber and then the lines are automatically +reidentified in all other fibers. Note that this technique requires the +sky lines be found in all fibers. + +The last step of dispersion correction (resampling the spectrum to evenly +spaced pixels in wavelength) is optional and relatively straightforward. +If the \fIlinearize\fR parameter is no then the spectra are not resampled +and the nonlinear dispersion information is recorded in the image header. +Other IRAF tasks (the coordinate description is specific to IRAF) will use +this information whenever wavelengths are needed. If linearizing is +selected a linear dispersion relation, either linear in the wavelength or +the log of the wavelength, is defined once and applied to every extracted +spectrum. The resampling 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. The interpolation +function options and the nonlinear dispersion coordinate system is +described in the help topic \fBonedspec.package\fR. + +\fBSky Subtraction\fR + +Sky subtraction is selected with the \fIskysubtract\fR processing option. +The sky spectra are selected by their aperture and beam numbers and +combined into a single master sky spectrum +which is then subtracted from each object spectrum. If the \fIskyedit\fR +option is selected the sky spectra are plotted using the task +\fBspecplot\fR. By default they are superposed to allow identifying +spectra with unusually high signal due to object contamination. To +eliminate a sky spectrum from consideration point at it with the cursor and +type 'd'. The last deleted spectrum may be undeleted with 'e'. This +allows recovery of incorrect or accidental deletions. + +The sky combining algorithm parameters define how the individual sky fiber +spectra, after interactive editing, are combined before subtraction from +the object fibers. The goals of combining are to reduce noise, eliminate +cosmic-rays, and eliminate fibers with inadvertent objects. The common +methods for doing this to use a median and/or a special sigma clipping +algorithm (see \fBscombine\fR for details). The scale +parameter determines whether the individual skys are first scaled to a +common mode. The scaling should be used if the throughput is uncertain, +but in that case you probably did the wrong thing in the throughput +correction. If the sky subtraction is done interactively, i.e. with the +\fIskyedit\fR option selected, then after selecting the spectra to be +combined a query is made for the combining algorithm. This allows +modifying the default algorithm based on the number of sky spectra +selected since the "avsigclip" rejection algorithm requires at least +three spectra. + +The combined sky spectrum is subtracted from only those spectra specified +by the object aperture and beam numbers. Other spectra, such as comparison +arc spectra, are retained unchanged. One may include the sky spectra as +object spectra to produce residual sky spectra for analysis. The combined +master sky spectra may be saved if the \fIsaveskys\fR parameter is set. +The saved sky is given the name of the object spectrum with the prefix +"sky". +.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 dohydra" from the \fBhydra\fR package.. + +.nf +sp> hydra +hy> demos mkhydra +Creating image demoobj ... +Creating image demoflat ... +Creating image demoarc ... +hy> bye +sp> type demoapid +===> demoapid <=== +36 1 +37 0 +38 1 +39 1 +41 0 +42 1 +43 1 +44 0 +45 1 +46 -1 +47 0 +48 1 +sp> specred.verbose = yes +sp> dofibers demoobj apref=demoflat flat=demoflat arcs1=demoarc \ +>>> fib=12 apid=demoapid width=4. minsep=5. maxsep=7. clean- splot+ +Set reference apertures for demoflat +Resize apertures for demoflat? (yes): +Edit apertures for demoflat? (yes): +<Exit with 'q'> +Fit curve to aperture 36 of demoflat interactively (yes): +<Exit with 'q'> +Fit curve to aperture 37 of demoflat interactively (yes): N +Create response function demoflatdemoad.ms +Extract flat field demoflat +Fit and ratio flat field demoflat +<Exit with 'q'> +Create the normalized response demoflatdemoad.ms +demoflatdemoad.ms -> demoflatdemoad.ms using bzero: 0. + and bscale: 1.000001 + mean: 1.000001 median: 1.052665 mode: 1.273547 + upper: INDEF lower: INDEF +Average fiber response: +1. 1.151023 +2. 0.4519709 +3. 1.250614 +4. 1.287281 +5. 1.271358 +6. 0.6815334 +7. 1.164336 +8. 0.7499605 +9. 1.008654 +10. 1.053296 +11. 0.929967 +Extract arc reference image demoarc +Determine dispersion solution for demoarc +<A solution is found and presented.> +<Type 'f' to look at fit. Type 'q' to exit fit.> +<Exit with 'q'> + +REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Tue 16:01:07 11-Feb-92 + Reference image = d....ms.imh, New image = d....ms, Refit = yes + Image Data Found Fit Pix Shift User Shift Z Shift RMS +d....ms - Ap 41 16/20 16/16 0.00796 0.0682 8.09E-6 3.86 +Fit dispersion function interactively? (no|yes|NO|YES) (NO): y +<Exit with 'q'> +d....ms - Ap 41 16/20 16/16 0.00796 0.0682 8.09E-6 3.86 +d....ms - Ap 39 19/20 19/19 0.152 1.3 1.95E-4 3.89 +Fit dispersion function interactively? (no|yes|NO|YES) (yes): N +d....ms - Ap 39 19/20 19/19 0.152 1.3 1.95E-4 3.89 +d....ms - Ap 38 18/20 18/18 0.082 0.697 9.66E-5 3.64 +d....ms - Ap 37 19/20 19/19 0.0632 0.553 1.09E-4 6.05 +d....ms - Ap 36 18/20 18/18 0.0112 0.0954 1.35E-5 4.12 +d....ms - Ap 43 17/20 17/17 0.0259 0.221 3.00E-5 3.69 +d....ms - Ap 44 19/20 19/19 0.168 1.44 2.22E-4 4.04 +d....ms - Ap 45 20/20 20/20 0.18 1.54 2.35E-4 3.95 +d....ms - Ap 47 18/20 18/18 -2.02E-4 0.00544 9.86E-6 4.4 +d....ms - Ap 48 16/20 16/16 0.00192 0.0183 1.44E-6 3.82 + +Dispersion correct demoarc +d....ms.imh: w1 = 5748.07..., w2 = 7924.62..., dw = 8.50..., nw = 257 + Change wavelength coordinate assignments? (yes|no|NO): n +Extract object spectrum demoobj +Assign arc spectra for demoobj +[demoobj] refspec1='demoarc' +Dispersion correct demoobj +demoobj.ms.imh: w1 = 5748.078, w2 = 7924.622, dw = 8.502127, nw = 257 +Sky subtract demoobj: skybeams=0 +Edit the sky spectra? (yes): +<Exit with 'q'> +Sky rejection option (none|minmax|avsigclip) (avsigclip): +demoobj.ms.imh: +Splot spectrum? (no|yes|NO|YES) (yes): +Image line/aperture to plot (1:) (1): +<Look at spectra and change apertures with # key> +<Exit with 'q'> +.fi +.ih +REVISIONS +.ls DOFIBERS V2.11 +A sky alignment option was added. + +The aperture identification can now be taken from image header keywords. + +The initial arc line identifications is done with the automatic line +identification algorithm. +.le +.ls DOFIBERS V2.10.3 +The usual output WCS format is "equispec". 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, doargus, dohydra, dofoe, do3fiber, dispcor, +fit1d, icfit, identify, msresp1d, observatory, onedspec.package, +refspectra, reidentify, scombine, setairmass, setjd, specplot, splot +.endhelp diff --git a/noao/imred/specred/doc/dofibers.ms b/noao/imred/specred/doc/dofibers.ms new file mode 100644 index 00000000..c0196563 --- /dev/null +++ b/noao/imred/specred/doc/dofibers.ms @@ -0,0 +1,1807 @@ +.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 July 1995 +.TL +Guide to the Multifiber Reduction Task DOFIBERS +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +.DY + +.AB +The \fBdofibers\fR reduction task is specialized for scattered light +subtraction, extraction, flat +fielding, fiber throughput correction, wavelength calibration, and sky +subtraction of multifiber 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 large amount of data +generated by multifiber instruments. Variants of this task are +\fBdoargus\fR, \fBdofoe\fR, \fBdohydra\fR, and \fBdo3fiber\fR. +.AE +.NH +Introduction +.LP +The \fBdofibers\fR reduction task is specialized for scattered light +subtraction, extraction, flat +fielding, fiber throughput correction, wavelength calibration, and sky +subtraction of multifiber 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 large amount of data generated by multifiber +instruments. Variants of this task are \fBdoargus\fR, \fBdofoe\fR, +\fBdohydra\fR, and \fBdo3fiber\fR. +.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, and 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 +\fBdofibers\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 are first processed with \fBccdproc\fR for overscan, +bias, and dark corrections. +The \fBdofibers\fR task will abort if the image header keyword CCDPROC, +which is added by \fBccdproc\fR, is missing. If the data processed outside +of the IRAF \fBccdred\fR package then a dummy CCDPROC keyword should be +added to the image headers; say with \fBhedit\fR. +.IP [2] +Set the \fBdofibers\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. A throughput file or image, +such as a blank sky observation, may also be specified. If there are many +object or arc spectra per setup you might want to prepare "@ files". +Specify the aperture identification table for the configuration +if one has been created. If the image headers contain the SLFIB keywords +specify an image name; typically the same as the aperture reference +image. +You might wish to verify the geometry parameters, +separations, dispersion direction, etc., which may +change with different detector setups. The processing parameters are set +for complete reductions but for quicklook you might not use the clean +option or dispersion calibration and sky subtraction. + +The parameters are set for a particular configuration and different +configurations may use different flat fields, arcs, and aperture +identification tables. +.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. +The spectra are found automatically and apertures assigned based on +task parameters and the aperture identification table. Unassigned +fibers may have a negative beam number and will be ignored in subsequent +processing. The resize option sets the aperture size to the widths of +the profiles at a fixed fraction of the peak height. The interactive +review of the apertures is recommended. If the identifications are off +by a shift the 'o' key is used. To exit the aperture review type 'q'. +.IP [5] +The fiber 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 fibers need be examined and the "NO" +response will quit the interactive fitting. To exit the interactive +fitting type 'q'. +.IP [6] +If scattered light subtraction is to be done the flat field image is +used to define the scattered light fitting parameters interactively. +If one is not specified then the aperture reference image is used for +this purpose. + +There are two queries for the interactive fitting. A graph of the +data between the defined reference apertures separated by a specified +buffer distance is first shown. The function order and type may be +adjusted. After quiting with 'q' the user has the option of changing +the buffer value and returning to the fitting, changing the image line +or column to check if the fit parameters are satisfactory at other points, +or to quit and accept the fit parameters. After fitting all points +across the dispersion another graph showing the scattered light from +the individual fits is shown and the smoothing parameters along the +dispersion may be adjusted. Upon quiting with 'q' you have the option +of checking other cuts parallel to the dispersion or quiting and finishing +the scattered light function smoothing and subtraction. + +If there is a throughput image then this is corrected for scattered light +noninteractively using the previous fitting parameters. +.IP [7] +If flat fielding is to be done the flat field spectra are extracted. The +average spectrum over all fibers is determined and a function is fit +interactively (exit with 'q'). This function is generally of sufficiently +high order that the overall shape is well fit. This function is then used +to normalize the individual flat field spectra. If a throughput image, a +sky flat, is specified then the total sky counts through each fiber are +used to correct the total flat field counts. Alternatively, a separately +derived throughput file can be used for specifying throughput corrections. +If neither type of throughput is used the flat field also provides the +throughput correction. The final response spectra are normalized to a unit +mean over all fibers. The relative average throughput for each fiber is +recorded in the log and possibly printed to the terminal. +.IP [8] +If dispersion correction is selected the first arc in the arc list is +extracted. The middle fiber is used to identify the arc lines and define +the dispersion function using the task \fBautoidentify\fR. The +\fIcrval\fR and \fIcdelt\fR parameters are used in the automatic +identification. Whether or not the automatic identification is +successful you will be shown the result of the arc line identification. +If the automatic identification is not successful identify a few arc +lines with 'm' 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] +The remaining fibers are automatically reidentified. You have the option +to review the line identifications and dispersion function for each fiber +and interactively add or delete arc lines and change fitting parameters. +This can be done selectively, such as when the reported RMS increases +significantly. +.IP [10] +If the spectra are to be resampled to a linear dispersion system +(which will be the same for all spectra) default dispersion parameters +are printed and you are allowed to adjust these as desired. +.IP [11] +If the sky line alignment option is selected and the sky lines have not +been identified for a particular aperture identification table then you are +asked to mark one or more sky lines. You may simply accept the wavelengths +of these lines as defined by the dispersion solution for this spectrum and +fiber or you may specify knowns wavelengths for the lines. These lines will +be reidentified in all object spectra extracted and a mean zeropoint shift +will be added to the dispersion solution. This has the effect of aligning +these lines to optimize sky subtraction. +.IP [12] +The object spectra are now automatically scattered light subtracted, + extracted, flat fielded, and dispersion corrected. +.IP [13] +When sky subtracting, the individual sky spectra may be reviewed and some +spectra eliminated using the 'd' key. The last deleted spectrum may be +recovered with the 'e' key. After exiting the review with 'q' you are +asked for the combining option. The type of combining is dictated by the +number of sky fibers. +.IP [14] +The option to examine the final spectra with \fBsplot\fR may be given. +To exit type 'q'. +.IP [15] +If scattered light is subtracted from the input data a copy of the +original image is made by appending "noscat" to the image name. +If the data are reprocessed with the \fIredo\fR flag the original +image will be used again to allow modification of the scattered +light parameters. + +The final spectra will have the same name as the original 2D images +with a ".ms" extension added. The flat field and arc spectra will +also have part of the aperture identification table name added to +allow different configurations to use the same 2D flat field and arcs +but with different aperture definitions. If using the sky alignment +option an image "align" with the aperture identification table name +applied will also be created. +.NH +Spectra and Data Files +.LP +The basic input consists of multifiber 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. +The \fBdofibers\fR task will abort if the image header keyword CCDPROC, +which is added by \fBccdproc\fR, is missing. If the data processed outside +of the IRAF \fBccdred\fR package then a dummy CCDPROC keyword should be +added to the image headers; say with \fBhedit\fR. +Flat fielding is +generally not done at this stage but as part of \fBdofibers\fR. +If flat fielding is done as part of the basic CCD processing then +a flattened flat field, blank sky observation, or throughput file +should still be created for applying fiber throughput corrections. +.LP +The task \fBdofibers\fR uses several types of calibration spectra. These +are flat fields, blank sky flat fields, comparison lamp spectra, auxiliary +mercury line (from the dome lights) or sky line spectra, and simultaneous +arc spectra taken during the object observation. The flat field, +throughput image or file, auxiliary emission line spectra, and simultaneous +comparison fibers are optional. If a flat field is used then the sky flat +or throughput file is optional assuming the flat field has the same fiber +illumination. It is legal to specify only a throughput image or file and +leave the flat field blank in order to simply apply a throughput +correction. Because only the total counts through each fiber are used from +a throughput image, sky flat exposures need not be of high signal per +pixel. +.LP +There are three types of arc calibration methods. One is to take arc +calibration exposures through all fibers periodically and apply the +dispersion function derived from one or interpolated between pairs to the +object fibers. This is the most common method. Another method is to +use only one or two all-fiber arcs to define the shape of the dispersion +function and track zero point wavelength shifts with \fIsimultaneous arc\fR +fibers taken during the object exposure. The simultaneous arcs may or may +not be available at the instrument but \fBdofibers\fR can use this type of +observation. The arc fibers are identified by their beam or aperture +numbers. A related and mutually exclusive method is to use \fIauxiliary +line spectra\fR such as lines in the dome lights or sky lines to monitor +shifts relative to a few actual arc exposures. The main reason to do this +is if taking arc exposures through all fibers is inconvenient. +.LP +The assignment of arc or auxiliary line calibration exposures to object +exposures is generally done by selecting the nearest in time and +interpolating. There are other options possible which are described under +the task \fBrefspectra\fR. The most general option is to define a table +giving the object image name and the one or two arc spectra to be assigned +to that object. That file is called an \fIarc assignment table\fR and it +is one of the optional setup files which can used with \fBdofibers\fR. +.LP +The first step in the processing is identifying the spectra in the images. +The \fIaperture identification table\fR contains information about the fiber +assignments. The identification table is not mandatory, sequential numbering +will be used, but it is highly recommended for keeping track of the objects +assigned to the fibers. The aperture identification table may be +a file containing lines +specifying an aperture number, a beam number, and an object +identification. It may also be an image whose header contains the keywords +SLFIB with strings consisting of an aperture number, beam number, optional +right ascension and declination, and a tile. The file lines or keywords +must be in the same order as the fibers in the +image. The aperture number may be any unique number but it is recommended +that the fiber number be used. The beam number is used to flag object, +sky, arc, or other types of spectra. The default beam numbers used by the +task are 0 for sky, 1 for object, and 2 for arc. The object +identifications are optional but it is good practice to include them so +that the data will contain the object information independent of other +records. Figure 1 shows an example aperture identification file +called M33Sch2. +.V1 + +.ce +Figure 1: Example Aperture Identification File + + cl> type m33sch2 + 1 1 143 + 2 1 254 + 3 0 sky + 4 -1 Broken + 5 2 arc + . + . + . + 44 1 s92 + 45 -1 Unassigned + 46 2 arc + 47 0 sky + 48 1 phil2 + +.V2 +Note the identification of the sky fibers with beam number 0, the object +fibers with 1, and the arc fibers with 2. +The broken and unassigned fiber entries, given beam +number -1, are optional but recommended to give the automatic spectrum +finding operation the best chance to make the correct identifications. The +identification table will vary for each plugboard setup. Additional +information about the aperture identification table may be found in the +description of the task \fBapfind\fR. +.LP +An alternative to using an aperture identification table is to give no +name, the "" empty string, and to explicitly give a range of +aperture numbers for the skys and possibly for the sky subtraction +object list in the parameters \f(CWobjaps, skyaps, arcaps, objbeams, +skybeams,\fR and \f(CWarcbeams\fR. This is reasonable if the fibers always +have a fixed typed. As an example the CTIO Argus instrument always +alternates object and sky fibers so the object apertures can be given +as 1x2 and the sky fibers as 2x2; i.e. objects are the odd numbered +apertures and skys are the even numbered apertures. +.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 +".ms" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, wavelength, and identification +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 tools 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. +.NH +Package Parameters +.LP +The \fBspecred\fR package parameters, shown in Figure 2, set parameters +affecting all the tasks in the package. +.KS +.V1 + +.ce +Figure 2: Package Parameter Set for SPECRED + + I R A F + Image Reduction and Analysis Facility +PACKAGE = imred + TASK = specred + +(extinct= onedstds$kpnoextinct.dat) Extinction file +(caldir = onedstds$spec16redcal/) 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) Log file +(plotfil= ) Plot file + +(records= ) Record number extensions +(version= SPECRED V3: April 1992) + +.KE +.V2 +The dispersion axis parameter defines the image axis along which the +dispersion runs. This is used if the image header doesn't define the +dispersion axis with the DISPAXIS keyword. +The observatory parameter is used if there is no +OBSERVAT keyword in the image header (see \fBobservatory\fR for more +details). The spectrum interpolation type might be changed to "sinc" but +with the cautions given in \fBonedspec.package\fR. +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 \fBdofibers\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 \fBdofibers\fR parameters are shown in Figure 3. +.KS +.V1 + +.ce +Figure 3: Parameter Set for DOFIBERS + + I R A F + Image Reduction and Analysis Facility +PACKAGE = specred + TASK = dofibers + +objects = List of object spectra +(apref = ) Aperture reference spectrum +(flat = ) Flat field spectrum +(through= ) Throughput file or image (optional) +(arcs1 = ) List of arc spectra +(arcs2 = ) List of shift 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 +(fibers = 97) Number of fibers +(width = 12.) Width of profiles (pixels) +(minsep = 8.) Minimum separation between fibers (pixels) +(maxsep = 15.) Maximum separation between fibers (pixels) +(apidtab= ) Aperture identifications +(crval = INDEF) Approximate wavelength +(cdelt = INDEF) Approximate dispersion +(objaps = ) Object apertures +(skyaps = ) Sky apertures +(arcaps = ) Arc apertures +(objbeam= 0,1) Object beam numbers +(skybeam= 0) Sky beam numbers +(arcbeam= ) Arc beam numbers + +(scatter= no) Subtract scattered light? +(fitflat= yes) Fit and ratio flat field spectrum? +(clean = yes) Detect and replace bad pixels? +(dispcor= yes) Dispersion correct spectra? +(savearc= yes) Save simultaneous arc apertures? +(skysubt= yes) Subtract sky? +(skyedit= yes) Edit the sky spectra? +(savesky= yes) Save sky spectra? +(splot = no) Plot the final spectrum? +(redo = no) Redo operations if previously done? +(update = yes) 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 list of objects and arcs can be @ files if desired. The aperture +reference spectrum is usually the same as the flat field spectrum though it +could be any exposure with enough signal to accurately define the positions +and trace the spectra. The first list of arcs are the standard Th-Ar or +HeNeAr comparison arc spectra (they must all be of the same type). The +second list of arcs are the auxiliary emission line exposures mentioned +previously. +.LP +The detector read out noise and gain are used for cleaning and variance +(optimal) extraction. This is specified either explicitly or by reference +to an image header keyword. +The variance +weighting and cosmic-ray cleanning are sensitive to extremely strong +cosmic-rays; ones which are hundreds of times brighter than the +spectrum. The \fIdatamax\fR is used to set an upper limit for any +real data. Any pixels above this value will be flagged as cosmic-rays +and will not affect the extractions. +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 and separation parameters define the dimensions (in pixels) of the +spectra (fiber profile) across the dispersion. The width parameter +primarily affects the centering. The maximum separation parameter is +important if missing spectra from the aperture identification table are to +be correctly skipped. The number of fibers is either the actual number +of fibers or the number in the aperture identification table. An attempt +is made to account for unassigned or missing fibers. As a recommendation +the actual number of fibers should be specified. +.LP +The approximate central wavelength and dispersion are used for the +automatic identification of the arc reference. They may be specified +as image header keywords or values. The INDEF values search the +entire range of the coordinate reference file but the automatic +line identification algorithm works much better and faster if +approximate values are given. +.LP +The task needs to know which fibers are object, sky if sky subtraction is +to be done, and simultaneous arcs if used. One could explicitly give the +aperture numbers but the recommended way, provided an aperture +identification table is used, is to select the apertures based on the beam +numbers. The default values are recommended beam numbers. Sky +subtracted sky spectra are useful for evaluating the sky subtraction. +Since only the spectra identified as objects are sky subtracted one can +exclude fibers from the sky subtraction. For example, if the +\f(CWobjbeams\fR parameter is set to 1 then only those fibers with a beam of +1 will be sky subtracted. All other fibers will remain in the extracted +spectra but will not be sky subtracted. +.LP +The next set of parameters select the processing steps and options. The +scattered light option allows fitting and subtracting a scattered light +surface from the input object and flat field. If there is significant +scattered light which is not subtracted the fiber throughput correction +will not be accurate. 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 and not introducing the reciprocal of the flat field spectrum into +the object spectra. 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. If simultaneous arc fibers are defined there is an option to delete +them from the final spectra when they are no longer needed. +.LP +The sky alignment option allows applying a zeropoint dispersion shift +to all fibers based on one or more sky lines. This requires all fibers +to have the sky lines visible. When there are sky lines this will +improve the sky subtraction if there is a systematic error in the +fiber illumination between the sky and the arc calibration. +.LP +The sky subtraction option selects whether to combine the sky fiber spectra +and subtract this sky from the object fiber spectra. \fIDispersion +correction and sky subtraction are independent operations.\fR This means +that if dispersion correction is not done then the sky subtraction will be +done with respect to pixel coordinates. This might be desirable in some +quick look cases though it is incorrect for final reductions. +.LP +The sky subtraction option has two additional options. The individual sky +spectra may be examined and contaminated spectra deleted interactively +before combining. This can be a useful feature in crowded regions. The +final combined sky spectrum may be saved for later inspection in an image +with the spectrum name prefixed by \fBsky\fR. +.LP +After a spectrum has been processed it is possible to examine the results +interactively using the \fBsplot\fR tasks. This option has a query which +may be turned off with "YES" or "NO" if there are multiple spectra to be +processed. +.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 +aperture identification table, a new reference image, new flat fields, and a +new arc reference. 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. This will only occur if sky spectra editing and +\fBsplot\fR review (interactive operations) are turned off, either when the +task is run or by responding with "NO" to the queries during processing. +.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 way \fBdofibers\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 \fBdofibers\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 \fBdofibers\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 +multifiber 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 \fBdofibers\fR parameters by typing \f(CW:e +params\fR or simply \f(CW:e\fR if positioned at the \f(CWparams\fR +parameter. Figure 4 shows the parameter set. +.KS +.V1 + +.ce +Figure 4: Algorithm Parameter Set + + I R A F + Image Reduction and Analysis Facility +PACKAGE = specred + TASK = params + +(line = INDEF) Default dispersion line +(nsum = 10) Number of dispersion lines to sum +(order = decreasing) Order of apertures +(extras = no) Extract sky, sigma, etc.? + + -- DEFAULT APERTURE LIMITS -- +(lower = -5.) Lower aperture limit relative to center +(upper = 5.) 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= 3) 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 + -- SCATTERED LIGHT PARAMETERS -- +(buffer = 1.) Buffer distance from apertures +(apscat1= ) Fitting parameters across the dispersion +(apscat2= ) Fitting parameters along the dispersion + +.KE +.KS +.V1 + -- APERTURE EXTRACTION PARAMETERS -- +(weights= none) Extraction weights (none|variance) +(pfit = fit1d) Profile fitting algorithm (fit1d|fit2d) +(weights= none) Extraction weights (none|variance) +(pfit = fit1d) Profile fitting algorithm (fit1d|fit2d) +(lsigma = 3.) Lower rejection threshold +(usigma = 3.) Upper rejection threshold +(nsubaps= 1) Number of subapertures + +.KE +.KS +.V1 + -- FLAT FIELD FUNCTION FITTING PARAMETERS -- +(f_inter= yes) Fit flat field interactively? +(f_funct= spline3) Fitting function +(f_order= 10) Fitting function order + +.KE +.KS +.V1 + -- ARC DISPERSION FUNCTION PARAMETERS -- +(coordli=linelists$idhenear.dat) Line list +(match = -3.) Line list matching limit in Angstroms +(fwidth = 4.) Arc line widths in pixels +(cradius= 10.) Centering radius in pixels +(i_funct= spline3) Coordinate function +(i_order= 3) Order of dispersion function +(i_niter= 2) Rejection iterations +(i_low = 3.) Lower rejection sigma +(i_high = 3.) Upper rejection sigma +(refit = yes) Refit coordinate function when reidentifying? +(addfeat= no) Add features 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 +.KS +.V1 + -- SKY SUBTRACTION PARAMETERS -- +(combine= average) Type of combine operation +(reject = avsigclip) Sky rejection option +(scale = none) Sky scaling option + +.KE +.V2 +.NH 2 +Extraction +.LP +The identification of the spectra in the two dimensional images and their +scattered light subtraction and extraction to one dimensional spectra +in multispec format is accomplished +using the tasks from the \fBapextract\fR package. The first parameters +through \f(CWnsubaps\fR control the extractions. +.LP +The dispersion line is that used for finding the spectra, for plotting in +the aperture editor, and as the starting point for tracing. The default +value of \fBINDEF\fR selects the middle of the image. The aperture +finding, adjusting, editing, and tracing operations also allow summing a +number of dispersion lines to improve the signal. The number of lines is +set by the \f(CWnsum\fR parameter. +.LP +The order parameter defines whether the order of the aperture +identifications in the aperture identification table (or the default +sequential numbers if no file is used) is in the same sense as the image +coordinates (increasing) or the opposite sense (decreasing). If the +aperture identifications turn out to be opposite to what is desired when +viewed in the aperture editing graph then simply change this parameter. +.LP +The basic data output by the spectral extraction routines are the one +dimensional spectra. Additional information may be output when the +\f(CWextras\fR option is selected and the cleaning or variance weighting +options are also selected. In this case a three dimensional image is +produced with the first element of the third dimension being the cleaned +and/or weighted spectra, the second element being the uncleaned and +unweighted spectra, and the third element being an estimate of the sigma +of each pixel in the extracted spectrum. Currently the sigma data is not +used by any other tasks and is only for reference. +.LP +The initial step of finding the fiber spectra in the aperture reference +image consists of identifying the peaks in a cut across the dispersion, +eliminating those which are closer to each other than the \f(CWminsep\fR +distance, and then keeping the specified \f(CWnfibers\fR highest peaks. The +centers of the profiles are determined using the \fBcenter1d\fR algorithm +which uses the \f(CWwidth\fR parameter. +.LP +Apertures are then assigned to each spectrum. The initial edges of the +aperture relative to the center are defined by the \f(CWlower\fR and +\f(CWupper\fR parameters. The trickiest part of assigning the apertures is +relating the aperture identification from the aperture identification table +to automatically selected fiber profiles. The first aperture id in the +file is assigned to the first spectrum found using the \f(CWorder\fR +parameter to select the assignment direction. The numbering proceeds in +this way except that if a gap greater than a multiple of the \f(CWmaxsep\fR +parameter is encountered then assignments in the file are skipped under the +assumption that a fiber is missing (broken). If unassigned fibers are +still visible in a flat field, either by design or by scattered light, the +unassigned fibers can be included in the number of fibers to find and then +the unassigned (negative beam number) apertures are excluded from any +extraction. For more on the finding and assignment algorithms see +\fBapfind\fR. +.LP +The initial apertures are the same for all spectra but they can each be +automatically resized. The automatic resizing sets the aperture limits +at a fraction of the peak relative to the interfiber minimum. +The default \f(CWylevel\fR is to resize the apertures to 5% of the peak. +See the description for the task \fBapresize\fR for further details. +.LP +The user is given the opportunity to graphically review and adjust the +aperture definitions. This is recommended. As mentioned previously, the +correct identification of the fibers is tricky and it is fundamentally +important that this be done correctly; otherwise the spectrum +identifications will not be for the objects they say. An important command in +this regard is the 'o' key which allows reordering the identifications +based on the aperture identification table. This is required if the first +fiber is actually missing since the initial assignment begins assigning the +first spectrum found with the first entry in the aperture file. The +aperture editor is a very powerful tool and is described in detail as +\fBapedit\fR. +.LP +The next set of parameters control the tracing and function fitting of the +aperture reference positions along the dispersion direction. The position +of a spectrum across the dispersion is determined by the centering +algorithm (see \fBcenter1d\fR) at a series of evenly spaced steps, given by +the parameter \f(CWt_step\fR, along the dispersion. The step size should be +fine enough to follow position changes but it is not necessary to measure +every point. The fitted points may jump around a little bit due to noise +and cosmic rays even when summing a number of lines. Thus, a smooth +function is fit. The function type, order, and iterative rejection of +deviant points is controlled by the other trace parameters. For more +discussion consult the help pages for \fBaptrace\fR and \fBicfit\fR. The +default is to fit a cubic spline of three pieces with a single iteration of +3 sigma rejection. +.LP +The actual extraction of the spectra by summing across the aperture at each +point along the dispersion is controlled by the next set of parameters. +The default extraction simply sums the pixels using partial pixels at the +ends. The options allow selection of a weighted 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 \fBparams\fR parameters. +For more on the variance weighted extraction and cleaning see +\fBapvariance\fR and \fBapprofiles\fR as well as \fBapsum\fR. +.LP +The last parameter, \f(CWnsubaps\fR, is used only in special cases when it is +desired to subdivide the fiber profiles into subapertures prior to +dispersion correction. After dispersion correction the subapertures are +then added together. The purpose of this is to correct for wavelength +shifts across a fiber. +.NH 2 +Scattered Light Subtraction +.LP +Scattered light may be subtracted from the input two dimensional image as +the first step. This is done using the algorithm described in +\fBapscatter\fR. This can be important if there is significant scattered +light since the flat field/throughput correction will otherwise be +incorrect. The algorithm consists of fitting a function to the data +outside the defined apertures by a specified \fIbuffer\fR at each line or +column across the dispersion. The function fitting parameters are the same +at each line. Because the fitted functions are independent at each line or +column a second set of one dimensional functions are fit parallel to the +dispersion using the evaluated fit values from the cross-dispersion step. +This produces a smooth scattered light surface which is finally subtracted +from the input image. Again the function fitting parameters are the +same at each line or column though they may be different than the parameters +used to fit across the dispersion. +.LP +The first time the task is run with a particular flat field (or aperture +reference image if no flat field is used) the scattered light fitting +parameters are set interactively using that image. The interactive step +selects a particular line or column upon which the fitting is done +interactively with the \fBicfit\fR commands. A query is first issued +which allows skipping this interactive stage. Note that the interactive +fitting is only for defining the fitting functions and orders. When +the graphical \fBicfit\fR fitting is exited (with 'q') there is a second prompt +allowing you to change the buffer distance (in the first cross-dispersion +stage) from the apertures, change the line/column, or finally quit. +.LP +The initial fitting parameters and the final set parameters are recorded +in the \fBapscat1\fR and \fBapscat2\fR hidden parameter sets. These +parameters are then used automatically for every subsequent image +which is scattered light corrected. +.LP +The scattered light subtraction modifies the input 2D images. To preserve +the original data a copy of the original image is made with the same +root name and the word "noscat" appended. The scattered light subtracted +images will have the header keyword "APSCATTE" which is how the task +avoids repeating the scattered light subtraction during any reprocessing. +However if the \fIredo\fR option is selected the scattered light subtraction +will also be redone by first restoring the "noscat" images to the original +input names. +.NH 2 +Flat Field and Fiber Throughput Corrections +.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 +\fBdofibers\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 +\fBdofibers\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 +In addition to correcting for pixel-to-pixel response the flat field step +also corrects for differences in the fiber throughput. Thus, even if the +pixel-to-pixel flat field corrections have been made in some other way it +is desirable to use a sky or dome flat observation for determining a fiber +throughput correction. Alternatively, a separately derived throughput +file may be specified. This file consists of the aperture numbers +(the same as used for the aperture reference) and relative throughput +numbers. +.LP +The first step is extraction of the flat field spectrum, if 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. +After extraction one or more corrections are applied. If the \f(CWfitflat\fR +option is selected (the default) the extracted flat field spectra are +averaged together and a smooth function is fit. 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 +The fitted function is divided into the individual flat field spectra to +remove the basic shape of the spectrum while maintaining the relative +individual pixel responses and any fiber to fiber differences. This step +avoids introducing the flat field spectrum shape into the object spectra +and closely preserves the object counts. +.LP +If a throughput image is available (an observation of blank sky +usually at twilight) it is extracted. If no flat field is used the average +signal through each fiber is computed and this becomes the response +normalization function. Note that a dome flat may be used in place of a +sky in the sky flat field parameter for producing throughput only +corrections. If a flat field is specified then each sky spectrum is +divided by the appropriate flat field spectrum. The total counts through +each fiber are multiplied into the flat field spectrum thus making the sky +throughput of each fiber the same. This correction is important if the +illumination of the fibers differs between the flat field source and the +sky. Since only the total counts are required the sky or dome flat field +spectra need not be particularly strong though care must be taken to avoid +objects. +.LP +Instead of a sky flat or other throughput image a separately derived +throughput file may be used. It may be used with or without a +flat field. +.LP +The final step is to normalize the flat field spectra by the mean counts of +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. The final relative throughput values are recorded in the +log and possibly printed on the terminal. +.LP +These flat field response steps and algorithm are available as a separate +task called \fBmsresp1d\fR. +.NH +Dispersion Correction +.LP +Dispersion corrections are applied to the extracted spectra if the +\fBdispcor\fR parameter is set. This can be a complicated process which +the \fBdofibers\fR task tries to simplify for you. 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 resampling the spectra to evenly spaced pixels +in wavelength. +.LP +The comparison arc spectra are used to define dispersion functions for the +fibers using the tasks \fBautoidentify\fR and \fBreidentify\fR. The +interactive \fBautoidentify\fR task is only used on the central fiber of the +first arc spectrum to define the basic reference dispersion solution from +which all other fibers and arc spectra are automatically derived using +\fBreidentify\fR. \fBAutoidentify\fR attempts to automatically identify +the arc lines using the \fIcrval\fR and \fIcdelt\fR parameters. Whether +or not it is successful the user is presented with the interactive +identification graph. The automatic identifications can be reviewed and a +new solution or corrections to the automatic solution may be performed. +.LP +The set of arc dispersion function parameters are from \fBautoidentify\fR and +\fBreidentify\fR. The parameters define a line list for use in +automatically assigning wavelengths to arc lines, a parameter controlling +the width of the centering window (which should match the base line +widths), the dispersion function type and order, parameters to exclude bad +lines from function fits, and parameters defining whether to refit the +dispersion function, as opposed to simply determining a zero point shift, +and the addition of new lines from the line list when reidentifying +additional arc spectra. 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 operation of \fBautoidentify\fR. +.LP +Generally, taking a number of comparison arc lamp exposures interspersed +with the program spectra is sufficient to accurately dispersion calibrate +multifiber spectra. However, there are some other calibration options +which may be of interest. These options apply additional calibration data +consisting either of auxiliary line spectra, such as from dome lights or +night sky lines, or simultaneous arc lamp spectra taken through a few +fibers during the object exposure. These options add complexity to the +dispersion calibration process. +.LP +When only arc comparison lamp spectra are used, dispersion functions are +determined independently for each fiber of each arc image and then assigned +to the matching fibers in the program object observations. The assignment +consists of selecting one or two arc images to calibrate each object +image. When two bracketing arc spectra are used the dispersion functions +are linearly interpolated (usually based on the time of the observations). +.LP +If taking comparison exposures is time-consuming, possibly requiring +reconfiguration to illuminate the fibers, and the spectrograph is +expected to be fairly stable apart from small shifts, there are two +mutually exclusive methods for monitoring +shifts in the dispersion zero point from the basic arc lamp spectra other +than taking many arc lamp exposures. One is to use some fibers to take a +simultaneous arc spectrum while observing the program objects. The fibers +are identified by aperture or beam numbers. The second method is to use +\fIauxiliary line spectra\fR, such as mercury lines from the dome lights. +These spectra are specified with an auxiliary shift arc list, \f(CWarc2\fR. +.LP +When using auxiliary line spectra for monitoring zero point shifts one of +these spectra is plotted interactively by \fBidentify\fR with the +reference dispersion function from the reference arc spectrum. The user +marks one or more lines which will be used to compute zero point wavelength +shifts in the dispersion functions automatically. The actual wavelengths +of the lines need not be known. In this case accept the wavelength based +on the reference dispersion function. As other observations of the same +features are made the changes in the positions of the features will be +tracked as zero point wavelength changes such that wavelengths of the +features remain constant. +.LP +When using auxiliary line spectra the only arc lamp spectrum used is the +initial arc reference spectrum (the first image in the \f(CWarcs1\fR list). +The master dispersion functions are then shifted based on the spectra in +the \f(CWarcs2\fR list (which must all be of the same type). The dispersion +function assignments made by \fBrefspectra\fR using either the arc +assignment file or based on header keywords is done in the same way as +described for the arc lamp images except using the auxiliary spectra. +.LP +If simultaneous arcs are used the arc lines are reidentified to determine a +zero point shift relative to the comparison lamp spectra selected, by +\fBrefspectra\fR, of the same fiber. A linear function of aperture +position on the image across the dispersion verses the zero point shifts +from the arc fibers is determined and applied to the dispersion functions +from the assigned calibration arcs for the non-arc fibers. Note that if +there are two comparison lamp spectra (before and after the object +exposure) then there will be two shifts applied to two dispersion functions +which are then combined using the weights based on the header parameters +(usually the observation time). +.LP +The arc assignments may be done either explicitly with an arc assignment +table (parameter \f(CWarctable\fR) or based on a header parameter. The task +used is \fBrefspectra\fR and the user should consult this task if the +default behavior is not what is desired. The default is to interpolate +linearly between the nearest arcs based on the Julian date (corrected to +the middle of the exposure). The Julian date and a local Julian day number +(the day number at local noon) are computed automatically by the task +\fBsetjd\fR and recorded in the image headers under the keywords JD and +LJD. In addition the universal time at the middle of the exposure, keyword +UTMIDDLE, is computed by the task \fBsetairmass\fR and this may also be used +for ordering the arc and object observations. +.LP +.LP +An optional step is to use sky lines in the spectra to compute a zeropoint +dispersion shift that will align the sky lines. This may improve sky +subtraction if the illumination is not the same between the arc calibration +and the sky. When selected the object spectrum is dispersion corrected +using a non-linear dispersion function to avoid resampling the spectrum. +The sky lines are then reidentified in wavelength space from a template +list of sky lines. The mean shift in the lines for each fiber relative to +the template in that fiber is computed to give the zeropoint shift. The +database file is created when the first object is extracted. You are asked +to mark the sky lines in one fiber and then the lines are automatically +reidentified in all other fibers. Note that this technique requires the +sky lines be found in all fibers. +.LP +The last step of dispersion correction (resampling the spectrum to evenly +spaced pixels in wavelength) is optional and relatively straightforward. +If the \f(CWlinearize\fR parameter is no then the spectra are not resampled +and the nonlinear dispersion information is recorded in the image header. +Other IRAF tasks (the coordinate description is specific to IRAF) will use +this information whenever wavelengths are needed. If linearizing is +selected a linear dispersion relation, either linear in the wavelength or +the log of the wavelength, is defined once and applied to every extracted +spectrum. The resampling 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. The interpolation +function options and the nonlinear dispersion coordinate system is +described in the help topic \fBonedspec.package\fR. +.NH +Sky Subtraction +.LP +Sky subtraction is selected with the \f(CWskysubtract\fR processing option. +The sky spectra are selected by their aperture and beam numbers and +combined into a single master sky spectrum +which is then subtracted from each object spectrum. If the \f(CWskyedit\fR +option is selected the sky spectra are plotted using the task +\fBspecplot\fR. By default they are superposed to allow identifying +spectra with unusually high signal due to object contamination. To +eliminate a sky spectrum from consideration point at it with the cursor and +type 'd'. The last deleted spectrum may be undeleted with 'e'. This +allows recovery of incorrect or accidental deletions. +.LP +The sky combining algorithm parameters define how the individual sky fiber +spectra, after interactive editing, are combined before subtraction from +the object fibers. The goals of combining are to reduce noise, eliminate +cosmic-rays, and eliminate fibers with inadvertent objects. The common +methods for doing this to use a median and/or a special sigma clipping +algorithm (see \fBscombine\fR for details). The scale +parameter determines whether the individual skys are first scaled to a +common mode. The scaling should be used if the throughput is uncertain, +but in that case you probably did the wrong thing in the throughput +correction. If the sky subtraction is done interactively, i.e. with the +\f(CWskyedit\fR option selected, then after selecting the spectra to be +combined a query is made for the combining algorithm. This allows +modifying the default algorithm based on the number of sky spectra +selected since the "avsigclip" rejection algorithm requires at least +three spectra. +.LP +The combined sky spectrum is subtracted from only those spectra specified +by the object aperture and beam numbers. Other spectra, such as comparison +arc spectra, are retained unchanged. One may include the sky spectra as +object spectra to produce residual sky spectra for analysis. The combined +master sky spectra may be saved if the \f(CWsaveskys\fR parameter is set. +The saved sky is given the name of the object spectrum with the prefix +"sky". +.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 plot of spectra with SPLOT + calibrate - Extinction and flux calibrate spectra + continuum - Fit the continuum in spectra + deredden - Apply interstellar extinction correction + dispcor - Dispersion correct spectra + dopcor - Doppler correct spectra + fitprofs - Fit gaussian profiles + identify - Identify features in spectrum for dispersion solution + msresp1d - Create 1D response spectra from flat field and sky spectra + refspectra - Assign wavelength reference spectra to other spectra + reidentify - Automatically reidentify features in spectra + sapertures - Set or change aperture header information + sarith - Spectrum arithmetic + scombine - Combine spectra + scopy - Select and copy apertures in different spectral formats + sensfunc - Compute instrumental sensitivity from standard stars + setairmass - Compute effective airmass and middle UT for an exposure + setjd - Compute and set Julian dates in images + sfit - Fit spectra and output fit, ratio, or difference + skysub - Sky subtract extracted multispec spectra + slist - List spectrum header parameters + specplot - Scale, stack, and plot multiple spectra + splot - Preliminary spectral plot/analysis + standard - Tabulate standard star counts and fluxes + + dofibers - Process multifiber 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: DOFIBERS Parameters +.LP +.nr PS 8 +.nr VS 10 +objects +.LS +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 +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 spectra +are extracted and used to make flat field calibrations. If a separate +throughput file or image is not specified the flat field is also used +for computing a fiber throughput correction. +.LE +throughput = "" (optional) +.LS +Throughput file or image. If an image is specified, typically a blank +sky observation, the total flux through +each fiber is used to correct for fiber throughput. If a file consisting +of lines with the aperture number and relative throughput is specified +then the fiber throughput will be corrected by those values. If neither +is specified but a flat field image is given it is used to compute the +throughput. +.LE +arcs1 = "" (at least one if dispersion correcting) +.LS +List of primary arc spectra. These spectra are used to define the dispersion +functions for each fiber apart from a possible zero point correction made +with secondary shift spectra or arc calibration fibers in the object spectra. +One fiber from the first spectrum is used to mark lines and set the dispersion +function interactively and dispersion functions for all other fibers and +arc spectra are derived from it. +.LE +arcs2 = "" (optional) +.LS +List of optional shift arc spectra. Features in these secondary observations +are used to supply a wavelength zero point shift through the observing +sequence. One type of observation is dome lamps containing characteristic +emission lines. +.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, \fIparams.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 +fibers = 97 (apfind) +.LS +Number of fibers. This number is used during the automatic definition of +the apertures from the aperture reference spectrum. It is best if this +reflects the actual number of fibers which may be found in the aperture +reference image. The interactive +review of the aperture assignments allows verification and adjustments +to the automatic aperture definitions. +.LE +width = 12. (apedit) +.LS +Approximate base full width of the fiber profiles. This parameter is used +for the profile centering algorithm. +.LE +minsep = 8. (apfind) +.LS +Minimum separation between fibers. Weaker spectra or noise within this +distance of a stronger spectrum are rejected. +.LE +maxsep = 15. (apfind) +.LS +Maximum separation between adjacent fibers. This parameter +is used to identify missing fibers. If two adjacent spectra exceed this +separation then it is assumed that a fiber is missing and the aperture +identification assignments will be adjusted accordingly. +.LE +apidtable = "" (apfind) +.LS +Aperture identification table. This may be either a text file or an +image. A text file contains the fiber number, beam number defining object +(1), sky (0), and arc (2) fibers, and a object title. An image contains +the keywords SLFIBnnn with string value consisting of the fiber number, +beam number, optional right ascension and declination, and an object +title. Unassigned and broken fibers (beam of -1) should be included in the +identification information since they will automatically be excluded. +.LE +crval = INDEF, cdelt = INDEF (autoidentify) +.LS +These parameters specify an approximate central wavelength and dispersion. +They may be specified as numerical values, INDEF, or image header keyword +names whose values are to be used. +If both these parameters are INDEF then the automatic identification will +not be done. +.LE +objaps = "", skyaps = "", arcaps = "" +.LS +List of object, sky, and arc aperture numbers. These are used to +identify arc apertures for wavelength calibration and object and sky +apertures for sky subtraction. Note sky apertures may be identified as +both object and sky if one wants to subtract the mean sky from the +individual sky spectra. Typically the different spectrum types are +identified by their beam numbers and the default, null string, +lists select all apertures. +.LE +objbeams = "0,1", skybeams = "0", arcbeams = 2 +.LS +List of object, sky, and arc beam numbers. The convention is that sky +fibers are given a beam number of 0, object fibers a beam number of 1, and +arc fibers a beam number of 2. The beam numbers are typically set in the +\fIapidtable\fR. Unassigned or broken fibers may be given a beam number of +-1 in the aperture identification table since apertures with negative beam +numbers are not extracted. Note it is valid to identify sky fibers as both +object and sky. +.LE + +scattered = no (apscatter) +.LS +Smooth and subtracted scattered light from the object and flat field +images. This operation consists of fitting independent smooth functions +across the dispersion using data outside the fiber apertures and then +smoothing the individual fits along the dispersion. The initial +flat field, or if none is given the aperture reference image, are +done interactively to allow setting the fitting parameters. All +subsequent subtractions use the same fitting parameters. +.LE +fitflat = yes (flat1d) +.LS +Fit the composite flat field spectrum by a smooth function and divide each +flat field spectrum by this function? This operation removes the average +spectral signature of the flat field lamp from the sensitivity correction to +avoid modifying the object fluxes. +.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 \fIparams.linearize\fR +parameter this may either resample the spectra or insert a dispersion +function in the image header. +.LE +skyalign = no +.LS +Align sky lines? If yes then for the first object spectrum you are asked +to mark one or more sky lines to use for alignment. Then these lines will +be found in all spectra and an average zeropoint shift computed and applied +to the dispersion solution to align these lines. Note that this assumes +the sky lines are seen in all fibers. +.LE +savearcs = yes +.LS +Save any simultaneous arc apertures? If no then the arc apertures will +be deleted after use. +.LE +skysubtract = yes +.LS +Subtract sky from the object spectra? If yes the sky spectra are combined +and subtracted from the object spectra as defined by the object and sky +aperture/beam parameters. +.LE +skyedit = yes +.LS +Overplot all the sky spectra and allow contaminated sky spectra to be +deleted? +.LE +saveskys = yes +.LS +Save the combined sky spectrum? If no then the sky spectrum will be +deleted after sky subtraction is completed. +.LE +splot = no +.LS +Plot the final spectra with the task \fBsplot\fR? +.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 = yes +.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 provided there are no interactive +options (\fIskyedit\fR and \fIsplot\fR) selected. +.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 \fBdofibers\fR. + +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 +observatory = "observatory" +.LS +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. See \fBobservatory\fR for more +details. +.LE +interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) +.LS +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 +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 = "SPECRED: ..." +.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 \fBdofibers\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 +order = "decreasing" (apfind) +.LS +When assigning aperture identifications order the spectra "increasing" +or "decreasing" with increasing pixel position (left-to-right or +right-to-left in a cross-section plot of the image). +.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 = -5., upper = 5. (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 \fInsum\fR parameter is also used to enhance the +signal-to-noise at each step. +.LE +t_function = "spline3", t_order = 3 (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. + +.ce +-- SCATTERED LIGHT PARAMETERS -- + +buffer = 1. (apscatter) +.LS +Buffer distance from the aperture edges to be excluded in selecting the +scattered light pixels to be used. +.LE +apscat1 = "" (apscatter) +.LS +Fitting parameters across the dispersion. This references an additional +set of parameters for the ICFIT package. The default is the "apscat1" +parameter set. +.LE +apscat2 = "" (apscatter) +.LS +Fitting parameters along the dispersion. This references an additional +set of parameters for the ICFIT package. The default is the "apscat2" +parameter set. +.LE +.LE + +.ce +-- APERTURE EXTRACTION PARAMETERS -- + +weights = "none" (apsum) +.LS +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: + +"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 \fIgain\fR and \fIreadnoise\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 multifiber 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 +nsubaps = 1 (apsum) +.LS +During extraction it is possible to equally divide the apertures into +this number of subapertures. +.LE + +.ce +-- FLAT FIELD FUNCTION FITTING PARAMETERS -- + +f_interactive = yes (fit1d) +.LS +Fit the composite one dimensional flat field spectrum interactively? +This is used if \fIfitflat\fR is set and a two dimensional flat field +spectrum is specified. +.LE +f_function = "spline3", f_order = 10 (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. (autoidentify/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 = "linelists$idhenear.dat" (autoidentify/identify) +.LS +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelists$". +.LE +match = -3. (autoidentify/identify) +.LS +The maximum difference for a match between the dispersion function prediction +value and a wavelength in the coordinate list. +.LE +fwidth = 4. (autoidentify/identify) +.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 = "spline3", i_order = 3 (autoidentify/identify) +.LS +The default function and order to be fit to the arc wavelengths as a +function of the pixel coordinate. The functions choices are "chebyshev", +"legendre", "spline1", or "spline3". +.LE +i_niterate = 2, i_low = 3.0, i_high = 3.0 (autoidentify/identify) +.LS +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.LE +refit = yes (reidentify) +.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 +addfeatures = no (reidentify) +.LS +Add new features from a line list during each reidentification? +This option can be used to compensate for lost features from the +reference solution. Care should be exercised that misidentified features +are not introduced. +.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 \fBdofibers\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 \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 +-- SKY SUBTRACTION PARAMETERS -- + +combine = "average" (scombine) (average|median) +.LS +Option for combining sky pixels at the same dispersion coordinate after any +rejection operation. The options are to compute the "average" or "median" +of the pixels. The median uses the average of the two central +values when the number of pixels is even. +.LE +reject = "none" (scombine) (none|minmax|avsigclip) +.LS +Type of rejection operation performed on the pixels which overlap at each +dispersion coordinate. The algorithms are discussed in the +help for \fBscombine\fR. The rejection choices are: + +.nf + none - No rejection + minmax - Reject the low and high pixels + avsigclip - Reject pixels using an averaged sigma clipping algorithm +.fi + +.LE +scale = "none" (none|mode|median|mean) +.LS +Multiplicative scaling to be applied to each spectrum. The choices are none +or scale by the mode, median, or mean. This should not be necessary if the +flat field and throughput corrections have been properly made. +.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/specred/doc/doslit.hlp b/noao/imred/specred/doc/doslit.hlp new file mode 100644 index 00000000..2bcf7294 --- /dev/null +++ b/noao/imred/specred/doc/doslit.hlp @@ -0,0 +1,1201 @@ +.help doslit Feb93 noao.imred.specred +.ih +NAME +doslit -- Slit spectra data reduction task +.ih +USAGE +doslit objects +.ih +SUMMARY +\fBDoslit\fR extracts, sky subtracts, wavelength calibrates, and flux +calibrates simple two dimensional slit spectra which have been processed to +remove the detector characteristics; i.e. CCD images have been bias, dark +count, and flat field corrected. It is primarily intended for +spectrophotometry or radial velocities of stellar spectra with the spectra +aligned with one of the image axes; i.e. the assumption is that extractions +can be done by summing along image lines or columns. The alignment does +not have to be precise but only close enough that the wavelength difference +across the spectrum profiles is insignificant. The task is available +in the \fBctioslit\fR, \fBkpnoslit\fR, \fBkpnocoude\fR, and \fBspecred\fR +packages. +.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 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 \fIcaldir\fR). +.le + +.ls readnoise = "rdnoise", gain = "gain" (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 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. +.le +.ls crval = INDEF, cdelt = INDEF (autoidentify) +These parameters specify an approximate central wavelength and dispersion. +They may be specified as numerical values, INDEF, or image header keyword +names whose values are to be used. +If both these parameters are INDEF then the automatic identification will +not be done. +.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 default aperture 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 splot = no +Plot the final spectra with the task \fBsplot\fR? In quicklook mode +this is automatic and in non-quicklook mode it is queried. +.le +.ls redo = no +Redo operations previously done? If no then previously processed spectra +in the object list will not be processed unless required by the +update option. +.le +.ls update = no +Update processing of previously processed spectra if 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 the initial dispersion function solution and standard star setup are +done interactively. 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 = yes +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, 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 sigmas in a three dimensional output image format. +See the discussion in the \fBapextract\fR package for further information. +.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 defined. +.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 = 1 (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 +-- 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 +-- DEFAULT BACKGROUND PARAMETERS -- +.ls background = "fit" (apsum) (none|average|median|minimum|fit) +Type of background subtraction. The choices are "none" for no background +subtraction, "average" to average the background within the background +regions, "median" to use the median in the background regions, "minimum" to +use the minimum in the background regions, or "fit" to fit across the +dispersion using the background within the background regions. Note that +the "average" option does not do any medianing or bad pixel checking, +something which is recommended. The fitting option is slower than the +other options and requires additional fitting parameter. +.le +.ls 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_sample = "-10:-6,6:10" (apsum) +Default background sample. The sample is given by a set of colon separated +ranges each separated by either whitespace or commas. The string "*" refers +to all points. Note that the background coordinates are relative to the +aperture center and not image pixel coordinates so the endpoints need not +be integer. It is recommended that the background regions be examined +and set interactively with the 'b' key in the interactive aperture +definition mode. This requires \fIquicklook\fR to be no. +.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 = 1 (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 + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- +.ls threshold = 10. (autoidentify/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 = "linelists$idhenear.dat" (autoidentify/identify) +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelists$". +.le +.ls match = -3. (autoidentify/identify) +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.le +.ls fwidth = 4. (autoidentify/identify) +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 = "spline3", i_order = 1 (autoidentify/identify) +The default function and order to be fit to the arc wavelengths as a +function of the pixel coordinate. The functions choices are "chebyshev", +"legendre", "spline1", or "spline3". +.le +.ls i_niterate = 0, i_low = 3.0, i_high = 3.0 (autoidentify/identify) +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.le +.ls refit = yes (reidentify) +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the initial 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 +.ls addfeatures = no (reidentify) +Add new features from a line list during each reidentification? +This option can be used to compensate for lost features from the +reference solution. Care should be exercised that misidentified features +are not introduced. +.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 or group parameters. +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. There is no checking of the +group values. +.le +.ls following +Select the nearest following spectrum in the reference list based on the +sort and group parameters. 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 sort and group parameters. If there is no preceding and +following spectrum use the nearest spectrum. The interpolation is weighted +by the relative distances of the sorting parameter (see cautions in +DESCRIPTION section). +.le +.ls match +Match each input spectrum with the reference spectrum list in order. +This overrides any group values. +.le +.ls nearest +Select the nearest spectrum in the reference list based on the sort and +group parameters. +.le +.ls preceding +Select the nearest preceding spectrum in the reference list based on the +sort and group parameters. 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 (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 + +.ce +-- SENSITIVITY CALIBRATION PARAMETERS -- +.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 + +The following package parameters are used by this task. The default values +may vary depending on the package. +.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 (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 +\fBDoslit\fR extracts, sky subtracts, wavelength calibrates, and flux +calibrates simple two dimensional slit spectra which have been processed to +remove the detector characteristics; i.e. CCD images have been bias, dark +count, and flat field corrected. It is primarily intended for +spectrophotometry or radial velocities of stellar spectra with the spectra +aligned with one of the image axes; i.e. the assumption is that extractions +can be done by summing along image lines or columns. The alignment does +not have to be precise but only close enough that the wavelength difference +across the spectrum profiles is insignificant. Extended objects requiring +accurate geometric alignment over many pixels are reduced using the +\fBlongslit\fR package. + +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. \fBDoslit\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 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 \fBdoslit\fR parameters with \fBeparam\fR. Specify the object +images to be processed, +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 \fIsparams\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] +Apertures are defined for all the standard and object images. This is only +done if there are no previous aperture definitions for the image. +The highest peak is found and centered and the default aperture limits +are set. If the resize option is set the aperture is resized by finding +the level which is 5% (the default) of the peak above local background. +If not using the quicklook option you now have the option +of entering the aperture editing loop to check the aperture position, +size, and background fitting parameters, and possibly add additional +apertures. This is step is highly recommended. +It is important to check the background regions with the 'b' +key. To exit the background mode and then +to exit the review mode use 'q'. + +The spectrum positions at a series of points along the dispersion are +measured and a function is fit to these positions. If not using the +quicklook option the traced positions may be examined interactively and the +fitting parameters adjusted. To exit the interactive fitting type 'q'. +.le +.ls [5] +If dispersion correction is selected the first arc in the arc list is +extracted. The dispersion function is defined using the task +\fBautoidentify\fR. The \fIcrval\fR and \fIcdelt\fR parameters are used in +the automatic identification. Whether or not the automatic identification +is successful you will be shown the result of the arc line identification. +If the automatic identification is not successful identify a few arc lines +with with 'm' 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 [6] +If the flux calibration option is selected the standard star spectra are +processed (if not done previously). The images are +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. + +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 [7] +The object spectra are now automatically +extracted, wavelength calibrated, and flux calibrated. +.le +.ls [8] +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 \fBbplot\fR. +.le +.ls [9] +The final spectra will have the same name as the original 2D images +with a ".ms" extension added. +.le + +\fBSpectra and Data Files\fR + +The basic input consists of two dimensional 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. Lines of constant +wavelength should be closely aligned with one of the image axes though a +small amount of misalignment only causes a small loss of resolution. For +large misalignments one may use the \fBrotate\fR task. More complex +geometric problems and observations of extended objects should be handled +by the \fBlongslit\fR package. + +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 one, two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ms" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, wavelength, and identification +information. With a single aperture the image will be one dimensional +and with multiple apertures the image will be two dimensional. +When the \fIextras\fR parameter is set the images will be three +dimensional (regardless of the number of apertures) and 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. + +\fBPackage Parameters\fR + +The package parameters set parameters which change +infrequently and set 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> help onedstds + +.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 general direction in which the spectra 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 may not be exactly aligned because atmospheric +dispersion. + +The verbose parameter selects whether to print everything which goes +into the log file on the terminal. It is useful for monitoring +what the \fBdoslit\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 .ms 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. + +The arc assignment table is a file which may be used to assign +specific arc spectra to specific object and standard star spectra. +For more on this option see \fBrefspectra\fR. + +The next set of parameters describe the noise characteristics and +spectrum characteristics. 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 variance +weighting and cosmic-ray cleanning are sensitive to extremely strong +cosmic-rays; ones which are hundreds of times brighter than the +spectrum. The \fIdatamax\fR is used to set an upper limit for any +real data. Any pixels above this value will be flagged as cosmic-rays +and will not affect the extractions. + +The profile width should be approximately the full width +at the profile base. This parameter is used for centering and tracing +of the spectrum profiles. + +The approximate central wavelength and dispersion are used for the +automatic identification of the arc reference. They may be specified +as image header keywords or values. The INDEF values search the +entire range of the coordinate reference file but the automatic +line identification algorithm works much better and faster if +approximate values are given. + +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 aperture based +on the profile for each object and standard star image. 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 +adjustments made to the aperture width and background regions. + +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. + +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 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 \fBbplot\fR. + +The \fIquicklook\fR option provides a simpler, less interactive, mode. +In quicklook mode a single aperture is defined using default parameters +without interactive aperture review or trace fitting 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 \fIsparams\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 +\fBdoslit\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 \fBdoslit\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 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 \fBdoslit\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 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 a single spectrum is found and a default aperture defined +automatically. If the \fIresize\fR parameter is set the aperture width is +adjusted to a specified point on the spectrum profile (see +\fBapresize\fR). If not in "quicklook" mode (set by the \fIquicklook\fR +parameter) a query is printed to select whether to inspect and modify the +aperture and background aperture definitions using the commands described +for \fBapedit\fR. This option allows adding +apertures for other objects on the slit and adjusting +background regions to avoid contaminating objects. The query may be +answered in lower case for a single spectrum or in upper case to +permanently set the response for the duration of the task execution. This +convention for query responses is used throughout the task. 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 traces. + +The initial spectrum finding and aperture definitions are done at a specified +line or column. The positions of the spectrum at a set of other lines or +columns is done next and a smooth function is fit to define the aperture +centers at all points in the image. In non-quicklook mode the user has the +option to review and adjust the function fitting parameters and delete bad +position determinations. As with the initial aperture review there is a +query which may be answered either in lower or upper case. + +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 is basically finds the strongest peak. The default +aperture size, background parameters, and resizing are described in +the tasks \fBapdefault\fR and \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. + +\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 applying a separate +background subtraction operation) 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 +normalized flat fields (as is done in \fBccdproc\fR) and using background +subtraction if there is any appreciable sky. For further discussion of +cleaning and variance weighted extraction see \fBapvariance\fR and +\fBapprofiles\fR as well as \fBapsum\fR. + +Background sky subtraction is done during the extraction based on +background regions and parameters defined by the default parameters or +changed during the interactive setting of the apertures. The background +subtraction options are to do no background subtraction, subtract the +average, median, or minimum of the pixels in the background regions, or to +fit a function and subtract the function from under the extracted object +pixels. The background regions are specified in pixels from +the aperture center and follow changes in center of the spectrum along the +dispersion. The syntax is colon separated ranges with multiple ranges +separated by a comma or space. The background fitting uses the \fBicfit\fR +routines which include medians, iterative rejection of deviant points, and +a choice of function types and orders. Note that it is important to use a +method which rejects cosmic rays such as using either medians over all the +background regions (\fIbackground\fR = "median") or median samples during +fitting (\fIb_naverage\fR < -1). The background subtraction algorithm and +options are described in greater detail in \fBapsum\fR and +\fBapbackground\fR. + +\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 the +noninteractive \fBbplot\fR task 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 at middle of the image with no +tracing. Note extractions of arc spectra are not background subtracted. +The task \fBautoidentify\fR is attempts to define the dispersion function +automatically using the \fIcrval\fR and \fIcdelt\fR parameters. Whether or +not it is successful the user is presented with the interactive +identification graph. The automatic identifications can be reviewed and a +new solution or corrections to the automatic solution may be performed. + +The arc dispersion function parameters are for \fBautoidentify\fR and it's +related partner \fBreidentify\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 +\fBautoidentify\fR. + +The extracted reference arc spectrum is then dispersion corrected. +If the spectra are to be linearized, as set by the \fIlinearize\fR +parameter, the default linear wavelength parameters are printed and +you have the option to adjust them. The dispersion system defined at +this point will be applied automatically to all other spectra as they +are dispersion corrected. + +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. + +The assigned arc spectra are then extracted using the object aperture +definitions (but without background subtraction or cleaning) so that the +same pixels on the detector are used. The extracted arc spectra are then +reidentified automatically against the reference arc spectrum. Some +statistics of the reidentification are printed (if not in batch mode) and +the user has the option of examining the lines and fits interactively if +not in quicklook mode. The task which does the reidentification is called +\fBreidentify\fR. + +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 using the dispersion coordinate system defined previously +for the arc reference spectrum. + +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. 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. +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 \fBdoslit\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 a one +dimensional spectrum with the name \fIsens\fR. Deletion of this image +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 doslit". The output is with +the verbose package parameter set. Normally users use \fBeparam\fR +rather than the long command line. All parameters not shown +for \fBsparams\fR and \fBdoslit\fR are the default. + +.nf +cl> demos mkdoslit +Creating example longslit in image demoarc1 ... +Creating example longslit in image demoobj1 ... +Creating example longslit in image demostd1 ... +Creating example longslit in image demoarc2 ... +cl> doslit demoobj1 arcs=demoarc1,demoarc2 stand=demostd1 \ +>>> extcor=yes, fluxcal=yes resize=yes +Searching aperture database ... +Finding apertures ... +Jan 17 15:52: FIND - 1 apertures found for demoobj1 +Resizing apertures ... +Jan 17 15:52: APRESIZE - 1 apertures resized for demoobj1 (-3.50, 3.49) +Edit apertures for demostd1? (yes): +<Check aperture and background definitions ('b'). Exit with 'q'> +Fit traced positions for demostd1 interactively? (yes): +Tracing apertures ... +Fit curve to aperture 1 of demostd1 interactively (yes): +<Exit with 'q'> +Searching aperture database ... +Finding apertures ... +Jan 17 15:54: FIND - 1 apertures found for demostd1 +Resizing apertures ... +Jan 17 15:54: APRESIZE - 1 apertures resized for demostd1 (-3.35, 3.79) +Edit apertures for demostd1? (yes): +<Exit with 'q'> +Fit traced positions for demostd1 interactively? (yes): n +Tracing apertures ... +Jan 17 15:55: TRACE - 1 apertures traced in demostd1. +Jan 17 15:55: DATABASE - 1 apertures for demostd1 written to database +Extract arc reference image demoarc1 +Searching aperture database ... +Finding apertures ... +Jan 17 15:55: FIND - 1 apertures found for demoarc1 +Jan 17 15:55: DATABASE - 1 apertures for demoarc1 written to database +Extracting apertures ... +Jan 17 15:55: EXTRACT - Aperture 1 from demoarc1 --> demoarc1.ms +Determine dispersion solution for demoarc1 +<A dispersion function is automatically determined.> +<Type 'f' to see the fit residuals> +<Type 'd' to delete the two deviant lines> +<Type 'f' to refit with the bad points deleted> +<Type 'q' to quit fit and then 'q' to exit> +demoarc1.ms.imh: w1 = 4204.18..., w2 = 7355.37..., dw = 6.16..., nw = 512 + Change wavelength coordinate assignments? (yes|no|NO) (no): n +Extract standard star spectrum demostd1 +Searching aperture database ... +Jan 17 15:59: DATABASE - 1 apertures read for demostd1 from database +Extracting apertures ... +Jan 17 15:59: EXTRACT - Aperture 1 from demostd1 --> demostd1.ms +Assign arc spectra for demostd1 +[demostd1] refspec1='demoarc1 0.403' +[demostd1] refspec2='demoarc2 0.597' +Extract and reidentify arc spectrum demoarc1 +Searching aperture database ... +Jan 17 15:59: DATABASE - 1 apertures read for demostd1 from database +Jan 17 15:59: DATABASE - 1 apertures for demoarc1 written to database +Extracting apertures ... +Jan 17 15:59: EXTRACT - Aperture 1 from demoarc1 --> demostd1demoarc1.ms + +REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 15:59:21 17-Jan-92 + Reference image = demoarc1.ms, New image = demostd1..., Refit = yes +Image Data Found Fit Pix Shift User Shift Z Shift RMS +demo... 48/48 48/48 2.22E-4 0.00184 5.09E-7 0.225 +Fit dispersion function interactively? (no|yes|NO|YES) (yes): +demoarc1.ms: w1 = 4211.81, w2 = 7353.58, dw = 6.148, nw = 512, log = no + Change wavelength coordinate assignments? (yes|no|NO): N +demo... 48/48 48/48 2.22E-4 0.00184 5.09E-7 0.225 +Extract and reidentify arc spectrum demoarc2 +Searching aperture database ... +Jan 17 16:01: DATABASE - 1 apertures read for demostd1 from database +Jan 17 16:01: DATABASE - 1 apertures for demoarc2 written to database +Extracting apertures ... +Jan 17 16:01: EXTRACT - Aperture 1 from demoarc2 --> demostd1demoarc2.ms + +REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 16:01:54 17-Jan-92 + Reference image = demoarc1.ms, New image = demostd1..., Refit = yes +Image Data Found Fit Pix Shift User Shift Z Shift RMS +demo... 48/48 48/48 0.00302 0.0191 3.82E-6 0.244 +Dispersion correct demostd1 +demostd1.ms: ap = 1, w1 = 4204.181, w2 = 7355.375, dw = 6.16..., nw = 512 +Compile standard star fluxes for demostd1 +Star name in calibration list: hz2 <in kpnoslit package> +demostd1.ms.imh[1]: Example artificial long slit image +Compute sensitivity function +Fit aperture 1 interactively? (no|yes|NO|YES) (no|yes|NO|YES) (yes): +<Exit with 'q'> +Sensitivity function for all apertures --> sens +Flux and/or extinction calibrate standard stars +[demostd1.ms.imh][1]: Example artificial long slit image + Extinction correction applied + Flux calibration applied +Extract object spectrum demoobj1 +Searching aperture database ... +Jan 17 16:05: DATABASE - 1 apertures read for demoobj1 from database +Extracting apertures ... +Jan 17 16:05: EXTRACT - Aperture 1 from demoobj1 --> demoobj1.ms +Assign arc spectra for demoobj1 +[demoobj1] refspec1='demoarc1 0.403' +[demoobj1] refspec2='demoarc2 0.597' +Extract and reidentify arc spectrum demoarc1 +Searching aperture database ... +Jan 17 16:05: DATABASE - 1 apertures read for demoobj1 from database +Jan 17 16:05: DATABASE - 1 apertures for demoarc1 written to database +Extracting apertures ... +Jan 17 16:05: EXTRACT - Aperture 1 from demoarc1 --> demoobj1demoarc1.ms + +REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 16:05:39 17-Jan-92 + Reference image = demoarc1.ms, New image = demoobj1..., Refit = yes +Image Data Found Fit Pix Shift User Shift Z Shift RMS +demo... 48/48 48/48 -2.49E-4 -0.00109 -1.1E-7 0.227 +Extract and reidentify arc spectrum demoarc2 +Searching aperture database ... +Jan 17 16:05: DATABASE - 1 apertures read for demoobj1 from database +Jan 17 16:05: DATABASE - 1 apertures for demoarc2 written to database +Extracting apertures ... +Jan 17 16:05: EXTRACT - Aperture 1 from demoarc2 --> demoobj1demoarc2.ms + +REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 16:05:42 17-Jan-92 + Reference image = demoarc1.ms, New image = demoobj1..., Refit = yes +Image Data Found Fit Pix Shift User Shift Z Shift RMS +demo... 48/48 48/48 0.00266 0.0169 3.46E-6 0.24 +Dispersion correct demoobj1 +demoobj1.ms: ap = 1, w1 = 4204.181, w2 = 7355.375, dw = 6.16..., nw = 512 +Extinction correct demoobj1 +Flux calibrate demoobj1 +[demoobj1.ms.imh][1]: Example artificial long slit image + Extinction correction applied + Flux calibration applied +.fi + +2. To redo the above: + +.nf +cl> doslit demoobj1 arcs=demoarc1,demoarc2 stand=demostd1 \ +>>> extcor=yes, fluxcal=yes resize=yes redo+ +.fi +.ih +REVISIONS +.ls DOSLIT V2.11 +The initial arc line identifications is done with the automatic line +identification algorithm. +.le +.ls DOSLIT V2.10.3 +The usual output WCS format is "equispec". 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. The arc reference +is no longer taken from the center of the image but using the first object +aperture. A bug which alphabetized the arc list was fixed. +.le +.ih +SEE ALSO +apbackground, apedit, apfind, approfiles, aprecenter, apresize, apsum, +aptrace, apvariance, calibrate, ccdred, center1d, ctioslit, dispcor, +echelle.doecslit, icfit, autoidentify, identify, kpnocoude, kpnoslit, +specred, observatory, onedspec.package, refspectra, reidentify, sensfunc, +setairmass, setjd, splot, standard +.endhelp diff --git a/noao/imred/specred/doc/doslit.ms b/noao/imred/specred/doc/doslit.ms new file mode 100644 index 00000000..03ad0ab5 --- /dev/null +++ b/noao/imred/specred/doc/doslit.ms @@ -0,0 +1,1401 @@ +.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 DOSLIT +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +.DY + +.AB +\fBDoslit\fR extracts, sky subtracts, wavelength calibrates, and flux +calibrates simple two dimensional slit spectra which have been processed to +remove the detector characteristics; i.e. CCD images have been bias, dark +count, and flat field corrected. It is primarily intended for +spectrophotometry or radial velocities of stellar spectra with the spectra +aligned with one of the image axes; i.e. the assumption is that extractions +can be done by summing along image lines or columns. The alignment does +not have to be precise but only close enough that the wavelength difference +across the spectrum profiles is insignificant. The task is available +in the \fBctioslit\fR, \fBkpnoslit\fR, \fBkpnocoude\fR, and \fBspecred\fR +packages. +.AE +.NH +Introduction +.LP +\fBDoslit\fR extracts, sky subtracts, wavelength calibrates, and flux +calibrates simple two dimensional slit spectra which have been processed to +remove the detector characteristics; i.e. CCD images have been bias, dark +count, and flat field corrected. It is primarily intended for +spectrophotometry or radial velocities of stellar spectra with the spectra +aligned with one of the image axes; i.e. the assumption is that extractions +can be done by summing along image lines or columns. The alignment does +not have to be precise but only close enough that the wavelength difference +across the spectrum profiles is insignificant. Extended objects requiring +accurate geometric alignment over many pixels are reduced using the +\fBlongslit\fR package. +.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. \fBDoslit\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 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 \fBdoslit\fR parameters with \fBeparam\fR. Specify the object +images to be processed, +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 \f(CWsparams\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] +Apertures are defined for all the standard and object images. This is only +done if there are no previous aperture definitions for the image. +The highest peak is found and centered and the default aperture limits +are set. If the resize option is set the aperture is resized by finding +the level which is 5% (the default) of the peak above local background. +If not using the quicklook option you now have the option +of entering the aperture editing loop to check the aperture position, +size, and background fitting parameters, and possibly add additional +apertures. This is step is highly recommended. +It is important to check the background regions with the 'b' +key. To exit the background mode and then +to exit the review mode use 'q'. +.IP +The spectrum positions at a series of points along the dispersion are +measured and a function is fit to these positions. If not using the +quicklook option the traced positions may be examined interactively and the +fitting parameters adjusted. To exit the interactive fitting type 'q'. +.IP [5] +If dispersion correction is selected the first arc in the arc list is +extracted. The dispersion function is defined using the task +\fBautoidentify\fR. The \fIcrval\fR and \fIcdelt\fR parameters are used in +the automatic identification. Whether or not the automatic identification +is successful you will be shown the result of the arc line identification. +If the automatic identification is not successful identify a few arc lines +with with 'm' and 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 [6] +If the flux calibration option is selected the standard star spectra are +processed (if not done previously). The images are +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. +.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 [7] +The object spectra are now automatically +extracted, wavelength calibrated, and flux calibrated. +.IP [8] +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 \fBbplot\fR. +.IP [9] +The final spectra will have the same name as the original 2D images +with a ".ms" extension added. +.NH +Spectra and Data Files +.LP +The basic input consists of two dimensional 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. Lines of constant +wavelength should be closely aligned with one of the image axes though a +small amount of misalignment only causes a small loss of resolution. For +large misalignments one may use the \fBrotate\fR task. More complex +geometric problems and observations of extended objects should be handled +by the \fBlongslit\fR package. +.LP +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 one, two or three dimensional IRAF +images. The images have the same name as the original images with an added +".ms" extension. Each line in the reduced image is a one dimensional +spectrum with associated aperture, wavelength, and identification +information. With a single aperture the image will be one dimensional +and with multiple apertures the image will be two dimensional. +When the \f(CWextras\fR parameter is set the images will be three +dimensional (regardless of the number of apertures) and 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. +.NH +Package Parameters +.LP +The package parameters, shown in Figure 1 for the \fBspecred\fR package, +set parameters which change infrequently and define the standard I/O functions. +.KS +.V1 + +.ce +Figure 1: Package Parameter Set for DOSLIT Packages + + I R A F + Image Reduction and Analysis Facility +PACKAGE = imred + TASK = specred + +(extinct= onedstds$kpnoextinct.dat) Extinction file +(caldir = onedstds$spec16redcal/) 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) Log file +(plotfil= ) Plot file + +(records= ) Record number extensions +(version= SPECRED V3: April 1992) + +.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> help onedstds + +.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 general direction in which the spectra 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 may not be exactly aligned because atmospheric +dispersion. +.LP +The verbose parameter selects whether to print everything which goes +into the log file on the terminal. It is useful for monitoring +what the \fBdoslit\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. +.NH +Processing Parameters +.LP +The \fBdoslit\fR parameters are shown in Figure 2. +.KS +.V1 + +.ce +Figure 2: Parameter Set for DOSLIT + + I R A F + Image Reduction and Analysis Facility +PACKAGE = specred + TASK = doslit + +objects = List of object spectra +(arcs = ) List of arc spectra +(arctabl= ) Arc assignment table (optional) +(standar= ) List of standard star spectra + +.KE +.V1 +(readnoi= rdnoise) Read out noise sigma (photons) +(gain = gain) Photon gain (photons/data number) +(datamax= INDEF) Max data value / cosmic ray threshold +(width = 5.) Width of profiles (pixels) +(crval = INDEF) Approximate wavelength +(cdelt = INDEF) Approximate dispersion + +(dispcor= yes) Dispersion correct spectra? +(extcor = no) Extinction correct spectra? +(fluxcal= no) Flux calibrate spectra? +(resize = no) Automatically resize apertures? +(clean = no) Detect and replace bad pixels? +(splot = no) Plot the final spectrum? +(redo = no) Redo operations if previously done? +(update = no) Update spectra if cal data changes? +(quicklo= no) Minimally interactive quick-look? +(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 +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 .ms 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 +The arc assignment table is a file which may be used to assign +specific arc spectra to specific object and standard star spectra. +For more on this option see \fBrefspectra\fR. +.LP +The next set of parameters describe the noise characteristics and +spectrum characteristics. 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 variance +weighting and cosmic-ray cleanning are sensitive to extremely strong +cosmic-rays; ones which are hundreds of times brighter than the +spectrum. The \fIdatamax\fR is used to set an upper limit for any +real data. Any pixels above this value will be flagged as cosmic-rays +and will not affect the extractions. +.LP +The profile width should be approximately the full width +at the profile base. This parameter is used for centering and tracing +of the spectrum profiles. +.LP +The approximate central wavelength and dispersion are used for the +automatic identification of the arc reference. They may be specified +as image header keywords or values. The INDEF values search the +entire range of the coordinate reference file but the automatic +line identification algorithm works much better and faster if +approximate values are given. +.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 aperture based +on the profile for each object and standard star image. 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 +adjustments made to the aperture width and background regions. +.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 +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 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 \fBbplot\fR. +.LP +The \f(CWquicklook\fR option provides a simpler, less interactive, mode. +In quicklook mode a single aperture is defined using default parameters +without interactive aperture review or trace fitting 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 \f(CWsparams\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 +\fBdoslit\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 \fBdoslit\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 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 \fBdoslit\fR +parameters by typing \f(CW:e\fR when positioned at the \f(CWsparams\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 = specred + TASK = sparams + +(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= 1) 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 + -- 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 + -- BACKGROUND SUBTRACTION PARAMETERS -- +(backgro= fit) Background to subtract +(b_funct= legendre) Background function +(b_order= 1) Background function order +(b_sampl= -10:-6,6:10) Background sample regions +(b_naver= -100) Background average or median +(b_niter= 1) Background rejection iterations +(b_low = 3.) Background lower rejection sigma +(b_high = 3.) Background upper rejection sigma + +.KE +.KS +.V1 + -- ARC DISPERSION FUNCTION PARAMETERS -- +(coordli=linelists$idhenear.dat) Line list +(match = -3.) Line list matching limit in Angstroms +(fwidth = 4.) Arc line widths in pixels +(cradius= 10.) Centering radius in pixels +(i_funct= spline3) Coordinate function +(i_order= 1) Order of dispersion function +(i_niter= 0) Rejection iterations +(i_low = 3.) Lower rejection sigma +(i_high = 3.) Upper rejection sigma +(refit = yes) Refit coordinate function when reidentifying? +(addfeat= no) Add features 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 +.KS +.V1 + -- SENSITIVITY CALIBRATION PARAMETERS -- +(s_funct= spline3) Fitting function +(s_order= 1) Order of sensitivity function +(fnu = no) Create spectra having units of FNU? + +.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 input 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 a single spectrum is found and a default aperture defined +automatically. If the \f(CWresize\fR parameter is set the aperture width is +adjusted to a specified point on the spectrum profile (see +\fBapresize\fR). If not in "quicklook" mode (set by the \f(CWquicklook\fR +parameter) a query is printed to select whether to inspect and modify the +aperture and background aperture definitions using the commands described +for \fBapedit\fR. This option allows adding +apertures for other objects on the slit and adjusting +background regions to avoid contaminating objects. The query may be +answered in lower case for a single spectrum or in upper case to +permanently set the response for the duration of the task execution. This +convention for query responses is used throughout the task. 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 traces. +.LP +The initial spectrum finding and aperture definitions are done at a specified +line or column. The positions of the spectrum at a set of other lines or +columns is done next and a smooth function is fit to define the aperture +centers at all points in the image. In non-quicklook mode the user has the +option to review and adjust the function fitting parameters and delete bad +position determinations. As with the initial aperture review there is a +query which may be answered either in lower or upper case. +.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 is basically finds the strongest peak. The default +aperture size, background parameters, and resizing are described in +the tasks \fBapdefault\fR and \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 +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 applying a separate +background subtraction operation) 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 +normalized flat fields (as is done in \fBccdproc\fR) and using background +subtraction if there is any appreciable sky. For further discussion of +cleaning and variance weighted extraction see \fBapvariance\fR and +\fBapprofiles\fR as well as \fBapsum\fR. +.LP +Background sky subtraction is done during the extraction based on +background regions and parameters defined by the default parameters or +changed during the interactive setting of the apertures. The background +subtraction options are to do no background subtraction, subtract the +average, median, or minimum of the pixels in the background regions, or to +fit a function and subtract the function from under the extracted object +pixels. The background regions are specified in pixels from +the aperture center and follow changes in center of the spectrum along the +dispersion. The syntax is colon separated ranges with multiple ranges +separated by a comma or space. The background fitting uses the \fBicfit\fR +routines which include medians, iterative rejection of deviant points, and +a choice of function types and orders. Note that it is important to use a +method which rejects cosmic rays such as using either medians over all the +background regions (\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 +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 the +noninteractive \fBbplot\fR task 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 at middle of the image with no +tracing. Note extractions of arc spectra are not background subtracted. +The task \fBautoidentify\fR is attempts to define the dispersion function +automatically using the \fIcrval\fR and \fIcdelt\fR parameters. Whether or +not it is successful the user is presented with the interactive +identification graph. The automatic identifications can be reviewed and a +new solution or corrections to the automatic solution may be performed. +.LP +The arc dispersion function parameters are for \fBautoidentify\fR and it's +related partner \fBreidentify\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 +\fBautoidentify\fR. +.LP +The extracted reference arc spectrum is then dispersion corrected. +If the spectra are to be linearized, as set by the \f(CWlinearize\fR +parameter, the default linear wavelength parameters are printed and +you have the option to adjust them. The dispersion system defined at +this point will be applied automatically to all other spectra as they +are dispersion corrected. +.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 +The assigned arc spectra are then extracted using the object aperture +definitions (but without background subtraction or cleaning) so that the +same pixels on the detector are used. The extracted arc spectra are then +reidentified automatically against the reference arc spectrum. Some +statistics of the reidentification are printed (if not in batch mode) and +the user has the option of examining the lines and fits interactively if +not in quicklook mode. The task which does the reidentification is called +\fBreidentify\fR. +.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 using the dispersion coordinate system defined previously +for the arc reference spectrum. +.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. 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. +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 \fBdoslit\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 a one +dimensional spectrum with the name \f(CWsens\fR. Deletion of this image +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 +DOSLIT Task +.IP +P. Massey, \fIUser's Guide to Slit Spectra Reductions\fR, +Central Computer Services, NOAO, 1992. +.NH 2 +Task Help References +.LP +Each task in the \fBspecred\fR packages and tasks used by \fBdoslit\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 + +autoidentify - Automatically identify arc lines and a dispersion function + bplot - Batch plot of spectra with SPLOT + calibrate - Extinction and flux calibrate spectra + continuum - Fit the continuum in spectra + deredden - Apply interstellar extinction correction + dispcor - Dispersion correct spectra + dopcor - Doppler correct spectra + fitprofs - Fit gaussian profiles + identify - Identify features in spectrum for dispersion solution + msresp1d - Create 1D response spectra from flat field and sky spectra + refspectra - Assign wavelength reference spectra to other spectra + reidentify - Automatically reidentify features in spectra + sapertures - Set or change aperture header information + sarith - Spectrum arithmetic + scombine - Combine spectra + scopy - Select and copy apertures in different spectral formats + sensfunc - Compute instrumental sensitivity from standard stars + setairmass - Compute effective airmass and middle UT for an exposure + setjd - Compute and set Julian dates in images + sfit - Fit spectra and output fit, ratio, or difference + skysub - Sky subtract extracted multispec spectra + slist - List spectrum header parameters + specplot - Scale, stack, and plot multiple spectra + splot - Preliminary spectral plot/analysis + standard - Tabulate standard star counts and fluxes + + doslit - Process 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: DOSLIT 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 +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(CWcaldir\fR). +.LE + +readnoise = "rdnoise", gain = "gain" (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 +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. +.LE +crval = INDEF, cdelt = INDEF (autoidentify) +.LS +These parameters specify an approximate central wavelength and dispersion. +They may be specified as numerical values, INDEF, or image header keyword +names whose values are to be used. +If both these parameters are INDEF then the automatic identification will +not be done. +.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 aperture 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 +splot = no +.LS +Plot the final spectra with the task \fBsplot\fR? In quicklook mode +this is automatic and in non-quicklook mode it is queried. +.LE +redo = no +.LS +Redo operations previously done? If no then previously processed spectra +in the object list will not be processed unless required by the +update option. +.LE +update = no +.LS +Update processing of previously processed spectra if 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 the initial dispersion function solution and standard star setup are +done interactively. 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 = yes +.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 "eparam 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, 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 sigmas in a three dimensional output image format. +See the discussion in the \fBapextract\fR package for further information. +.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 defined. +.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 = 1 (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 +-- 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 +-- DEFAULT BACKGROUND PARAMETERS -- + +background = "fit" (apsum) (none|average|median|minimum|fit) +.LS +Type of background subtraction. The choices are "none" for no background +subtraction, "average" to average the background within the background +regions, "median" to use the median in the background regions, "minimum" to +use the minimum in the background regions, or "fit" to fit across the +dispersion using the background within the background regions. Note that +the "average" option does not do any medianing or bad pixel checking, +something which is recommended. The fitting option is slower than the +other options and requires additional fitting parameter. +.LE +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_sample = "-10:-6,6:10" (apsum) +.LS +Default background sample. The sample is given by a set of colon separated +ranges each separated by either whitespace or commas. The string "*" refers +to all points. Note that the background coordinates are relative to the +aperture center and not image pixel coordinates so the endpoints need not +be integer. It is recommended that the background regions be examined +and set interactively with the 'b' key in the interactive aperture +definition mode. This requires \f(CWquicklook\fR to be no. +.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 = 1 (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 + +.ce +-- ARC DISPERSION FUNCTION PARAMETERS -- + +threshold = 10. (autoidentify/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 = "linelists$idhenear.dat" (autoidentify) +.LS +Arc line list consisting of an ordered list of wavelengths. +Some standard line lists are available in the directory "linelists$". +.LE +match = -3. (autoidentify) +.LS +The maximum difference for a match between the dispersion function computed +value and a wavelength in the coordinate list. +.LE +fwidth = 4. (autoidentify) +.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 = "spline3", i_order = 1 (autoidentify) +.LS +The default function and order to be fit to the arc wavelengths as a +function of the pixel coordinate. The functions choices are "chebyshev", +"legendre", "spline1", or "spline3". +.LE +i_niterate = 0, i_low = 3.0, i_high = 3.0 (autoidentify) +.LS +Number of rejection iterations and sigma thresholds for rejecting arc +lines from the dispersion function fits. +.LE +refit = yes (reidentify) +.LS +Refit the dispersion function? If yes and there is more than 1 line +and a dispersion function was defined in the initial 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 +addfeatures = no (reidentify) +.LS +Add new features from a line list during each reidentification? +This option can be used to compensate for lost features from the +reference solution. Care should be exercised that misidentified features +are not introduced. +.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 or group parameters. +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. There is no checking of the +group values. +.LE +following +.LS +Select the nearest following spectrum in the reference list based on the +sort and group parameters. 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 sort and group parameters. If there is no preceding and +following spectrum use the nearest spectrum. The interpolation is weighted +by the relative distances of the sorting parameter (see cautions in +DESCRIPTION section). +.LE +match +.LS +Match each input spectrum with the reference spectrum list in order. +This overrides any group values. +.LE +nearest +.LS +Select the nearest spectrum in the reference list based on the sort and +group parameters. +.LE +preceding +.LS +Select the nearest preceding spectrum in the reference list based on the +sort and group parameters. 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 (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 +-- SENSITIVITY CALIBRATION PARAMETERS -- + +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 + +The following package parameters are used by this task. The default values +may vary depending on the package. + +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 (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/specred/doc/msresp1d.hlp b/noao/imred/specred/doc/msresp1d.hlp new file mode 100644 index 00000000..cc3dfed2 --- /dev/null +++ b/noao/imred/specred/doc/msresp1d.hlp @@ -0,0 +1,191 @@ +.help msresp1d Feb92 noao.imred.specred +.ih +NAME +msresp1d -- Create 1D aperture response from flat and throughput data +.ih +USAGE +msresp1d flat throughput apreference response +.ih +PARAMETERS +.ls flat +Flat field image to extract and normalize to create a one dimensional +aperture response image. If no flat field is specified then a throughput +image or file must be specified and only a throughput correction will be +created. Note that the two dimensional unextracted image is specified. +If an extracted image of the same name with the ".ms" extension is present +it is used without reextraction though the unextracted image must also +be present. +.le +.ls throughput +Throughput file or image. If an image is specified, typically a blank sky +observation, the total flux through each aperture is used to correct for +the aperture throughput. If a file consisting of lines with the aperture +number and relative throughput is specified then the aperture throughput +will be generated by those values. If neither is specified but a flat +field image is given the flat field is used to compute the throughput. +Note that the image is a two dimensional unextracted image. If an +extracted image of the same name with the ".ms" extension is present +it is used without reextraction though the unextracted image must also +be present. +.le +.ls apreference +Aperture reference spectrum. If not specified the apertures are defined +using the flat field or throughput images. If only a throughput file +is used then an aperture reference spectrum must be specified to define +the apertures and dimensions of the final response image. +.le +.ls response +Response spectrum to be created. +.le + +.ls recenter = no +Recenter throughput image apertures? +.le +.ls edit = yes +Edit and review apertures? +.le +.ls trace = no +Trace spectra? +.le +.ls clean = no +Detect and replace bad pixels? +.le +.ls fitflat = yes +Fit and ratio flat field spectrum? +.le +.ls interactive = yes +Interactive flat field fit? +.le +.ls function = "spline3", order = 20 +Flat field fitting function and order. The functions may be one of +"chebyshev", "legendre", "spline1" (linear spline), or "spline3" (cubic spline). +The order is either the number of polynomial terms or the number of spline +pieces. +.le +.ih +OTHER PARAMETERS +The package parameters control logging of the operations performed and +the verbose option allows printing of some progress information. The +graphics use the device defined by the STDGRAPH variable and cursor +input is with the parameter \fIcl.gcur\fR. + +Aperture extraction is done using the task \fBapall\fR and any parameters +not overridden by task parameters will be used; for example the detector +noise parameters. +.ih +DESCRIPTION +For multiaperture or multifiber spectra a throughput aperture correction +must be applied to extracted object spectra. Also it is often better to +divide by a one dimensional flat field than a two dimensional one. This +is valid provided the pixels sampled by the flat field and object are +essentially the same. The advantages are that interspectrum pixels where +there is little signal are not used and small shifts (fractions of a pixel) +can be tolerated. The task \fBmsresp1d\fR creates a multiaperture image +containing one dimensional flat field and throughput corrections which +can be directly divided into extracted object spectra. + +If a one dimensional flat field is to be determined the flat field spectra +are extracted unless an extracted image having the specified flat field +name with the ".ms" extension is present. If the \fIfitflat\fR parameter +is set then all the spectra are averaged and a smooth function is fit to +this composite flat field spectrum. The smooth fit is divided into the +individual flat field spectra. This removes the mean flat field spectrum +shape, thus avoiding introducing the inverse of the flat field spectrum +into the object spectra and changing the approximate count levels in the +object. This procedure is recommended. Note that it does not matter if +the individual fibers have differing spectral shapes (such as might happen +with a combination of fibers with differing spectral throughput) because +only a common function is used. The fitting is done using the \fBfit1d\fR +task based on the \fBicfit\fR function fitting routines. When the +\fIinteractive\fR flag is set the fitting may be done interactively +allowing iteration on the fitting function and other fitting parameters. +Note that the function fit should follow the overall shape using a fairly +high order. + +If no throughput image or file is specified the relative strengths +of the flat field spectra define a throughput correction. If a +separate throughput image or file is given then the individual +flat field spectra are normalized to unity and then scaled by the +throughput determined from the image or file. + +If a throughput image, such as a blank sky observation, is specified it is +extracted if needed. The extracted sky spectra are divided by the flat +field which is not yet corrected for throughput variations. The total flux +through each aperture is then found to define the relative throughputs of +the apertures. If a flat field was also specified the throughput values +are multiplied into the normalized flat field otherwise the response image +will consist of constant spectra with the relative throughputs derived from +the image. + +If a throughput file is specified the throughput values for each aperture +are defined from this file. The file consists of lines with two columns, +the aperture number and the relative throughput. All apertures should +be represented. If a flat field was also specified the throughput values +are multiplied into the normalized flat field. If no flat field +is given then the aperture reference image must be specified and it +will be extracted, if necessary, to provide the template for the response +image having constant values for each aperture spectrum. + +It is an error unless one or both of the flat field and throughput +are specified. + +The last stage is to normalize of the response spectra over +all apertures to a global unit mean. Because of this step the throughput +values derived from the flat field, throughput image, or throughput +file need only be relative. Log information is recorded and printed +which includes the final relative throughputs values. + +Aperture extraction is done using the task \fBapall\fR and any parameters +not overridden by task parameters will be used; for example the detector +noise parameters. Task parmeters control whether recentering, +aperture review, and tracing are done. If no aperture reference is +specified the apertures will be defined as the task is run. +The aperture reference, if defined, is often the same as the flat field. +.ih +EXAMPLES +1. To make a flat field response and apply it to an extracted object: + +.nf + ms> msred.verbose=yes + ms> msresp1d flat005 "" "" resp005.ms + Extract flat field flat005 + Searching aperture database ... + Sep 7 14:36: DATABASE - 44 apertures read for flat005. + Resize apertures for flat005? (yes): n + Edit apertures for flat005? (yes): n + Extract aperture spectra for flat005? (yes): + Review extracted spectra from flat005? (yes): n + Extracting apertures ... + Sep 7 14:37: EXTRACT - Aperture 1 from flat005 --> flat005.ms + Sep 7 14:37: EXTRACT - Aperture 2 from flat005 --> flat005.ms + Sep 7 14:37: EXTRACT - Aperture 3 from flat005 --> flat005.ms + Sep 7 14:37: EXTRACT - Aperture 4 from flat005 --> flat005.ms + Sep 7 14:37: EXTRACT - Aperture 5 from flat005 --> flat005.ms + <etc> + Fit and ratio flat field flat005 + <Interactive fitting of average extracted flat field> + Create the normalized response resp005.ms + Sep 7 14:38 BSCALE: image = resp005.ms + bzero=0. bscale=1.0 mean=1.0 median=1.02386 mode=1.07141 + Average fiber response: + 1 0.8049859 + 2 0.6428247 + 3 0.9014022 + 4 0.7955039 + 5 0.9898984 + <etc> + ms> imarith obj006.ms / resp005.ms obj006.ms +.fi + +Of course the extracted object spectra must be the same in terms of apertures, +wavelength coverage, etc. + +2. To make only a throughput correction: + +.nf + ms> msresp1d "" obj005 "" resp005 +.fi +.ih +SEE ALSO +icfit, fit1d, apflatten, apnormalize, dofibers +.endhelp diff --git a/noao/imred/specred/doc/skysub.hlp b/noao/imred/specred/doc/skysub.hlp new file mode 100644 index 00000000..75392822 --- /dev/null +++ b/noao/imred/specred/doc/skysub.hlp @@ -0,0 +1,98 @@ +.help skysub Mar94 noao.imred.specred +.ih +NAME +skysub -- Sky subtract extracted multispec spectra +.ih +USAGE +skysub input +.ih +PARAMETERS +.ls input +List of input multispec spectra to sky subtract. +.le +.ls output = "" +List of output sky subtracted spectra. If no output is specified then +the output replaces the input spectra. +.le +.ls objaps = "", objbeams = "" +Object aperture and beam numbers. An empty list selects all aperture +or beam numbers. Only the selected apertures are sky subtracted. +Other apertures are left unmodified. Note that it is valid to include +the sky apertures in the object selection which results in residual +sky spectra after subtraction by a mean sky. +.le +.ls skyaps = "", skybeams = "" +Sky aperture and beam numbers. An empty list selects all aperture or +beam numbers. +.le +.ls skyedit = yes +Edit the sky spectra? If yes the sky spectra are graphed using the +task \fBspecplot\fR and the user may delete contaminated sky spectra with +the 'd' key and exit with 'q'. +.le +.ls combine = "average" (average|median|sum) +Option for combining pixels at the same dispersion coordinate after any +rejection operation. The options are to compute the "average", "median", +or "sum" of the pixels. The median uses the average of the two central +values when the number of pixels is even. +.le +.ls reject = "none" (none|minmax|avsigclip) +Type of rejection operation performed on the pixels which overlap at each +dispersion coordinate. The algorithms are discussed in the +DESCRIPTION section. The rejection choices are: + +.nf + none - No rejection + minmax - Reject the nlow and nhigh pixels + avsigclip - Reject pixels using an averaged sigma clipping algorithm +.fi + +.le +.ls scale = no +Scale the sky spectra by the mode? +.le +.ls saveskys = yes +Save the sky spectra? If no then the mean sky spectra will be deleted after +sky subtraction is completed. Otherwise a one dimensional image with +the prefix "sky" and then the output name is created. +.le +.ls logfile = "" +Logfile for making a record of the sky subtraction operation. +.le +.ih +DESCRIPTION +This task selects a subset of aperture spectra from a multispec +format image, called sky spectra though they could be anything, +and combines them into a master spectrum which is subtracted +from another subset of spectra called the objects. Options include +saving the master sky spectrum and reviewing the selected sky spectra +graphically and deleting some of them. + +The sky apertures are selected using the aperture and beam numbers +defined during extraction (see the \fBapextract\fR package). In +some applications the beam numbers are used to code object and sky +apertures and selection by beam number is quite easy. Otherwise one +must list the aperture numbers explicitly. + +The object apertures are also selected using an aperture and beam +number list. Spectra not selected to be objects are not modified +by the sky subtraction. Note that it is perfectly valid to include +the sky spectra in the object list to produce residual sky spectra. + +When interactively editing the sky spectra the task \fBspecplot\fR +is used. To delete a spectrum type 'd'. To undelete the last deleted +spectrum type 'e'. When finished type 'e'. + +The sky spectra are combined using one of combining and rejection options from +the task \fBscombine\fR except for the option "none". +.ih +EXAMPLES +1. To median and subtract apertures 1,10,15,20 from all apertures: + +.nf + ms> skysub obj010.ms out=skysub010.ms skyaps="1,10,15,20" +.fi +.ih +SEE ALSO +specplot, scombine +.endhelp diff --git a/noao/imred/specred/dofibers.cl b/noao/imred/specred/dofibers.cl new file mode 100644 index 00000000..90a10b7e --- /dev/null +++ b/noao/imred/specred/dofibers.cl @@ -0,0 +1,74 @@ +# DOFIBERS -- Process fiber spectra from 2D to wavelength calibrated 1D. +# +# The task PROC does all of the interactive work and BATCH does the +# background work. This procedure is organized this way to minimize the +# dictionary space when the background task is submitted. + +procedure dofibers (objects) + +string objects = "" {prompt="List of object spectra"} + +file apref = "" {prompt="Aperture reference spectrum"} +file flat = "" {prompt="Flat field spectrum"} +file throughput = "" {prompt="Throughput file or image (optional)"} +string arcs1 = "" {prompt="List of arc spectra"} +string arcs2 = "" {prompt="List of shift arc spectra"} +file arctable = "" {prompt="Arc assignment table (optional)\n"} + +string readnoise = "0." {prompt="Read out noise sigma (photons)"} +string gain = "1." {prompt="Photon gain (photons/data number)"} +real datamax = INDEF {prompt="Max data value / cosmic ray threshold"} +int fibers = 97 {prompt="Number of fibers"} +real width = 12. {prompt="Width of profiles (pixels)"} +real minsep = 8. {prompt="Minimum separation between fibers (pixels)"} +real maxsep = 15. {prompt="Maximum separation between fibers (pixels)"} +file apidtable = "" {prompt="Aperture identifications"} +string crval = "INDEF" {prompt="Approximate central wavelength"} +string cdelt = "INDEF" {prompt="Approximate dispersion"} +string objaps = "" {prompt="Object apertures"} +string skyaps = "" {prompt="Sky apertures"} +string arcaps = "" {prompt="Arc apertures"} +string objbeams = "0,1" {prompt="Object beam numbers"} +string skybeams = "0" {prompt="Sky beam numbers"} +string arcbeams = "" {prompt="Arc beam numbers\n"} + +bool scattered = no {prompt="Subtract scattered light?"} +bool fitflat = yes {prompt="Fit and ratio flat field spectrum?"} +bool clean = yes {prompt="Detect and replace bad pixels?"} +bool dispcor = yes {prompt="Dispersion correct spectra?"} +bool skyalign = no {prompt="Align sky lines?"} +bool savearcs = yes {prompt="Save simultaneous arc apertures?"} +bool skysubtract = yes {prompt="Subtract sky?"} +bool skyedit = yes {prompt="Edit the sky spectra?"} +bool saveskys = yes {prompt="Save sky spectra?"} +bool splot = no {prompt="Plot the final spectrum?"} +bool redo = no {prompt="Redo operations if previously done?"} +bool update = yes {prompt="Update spectra if cal data changes?"} +bool batch = no {prompt="Extract objects in batch?"} +bool listonly = no {prompt="List steps but don't process?\n"} + +pset params = "" {prompt="Algorithm parameters"} + +begin + apscript.readnoise = readnoise + apscript.gain = gain + apscript.nfind = fibers + apscript.width = width + apscript.t_width = width + apscript.minsep = minsep + apscript.maxsep = maxsep + apscript.radius = minsep + apscript.clean = clean + proc.datamax = datamax + + proc (objects, apref, flat, throughput, arcs1, arcs2, "", + arctable, fibers, apidtable, crval, cdelt, objaps, skyaps, + arcaps, objbeams, skybeams, arcbeams, scattered, fitflat, no, + no, no, no, clean, dispcor, savearcs, skyalign, skysubtract, + skyedit, saveskys, splot, redo, update, batch, listonly) + + if (proc.dobatch) { + print ("-- Do remaining spectra as a batch job --") + print ("batch&batch") | cl + } +end diff --git a/noao/imred/specred/dofibers.par b/noao/imred/specred/dofibers.par new file mode 100644 index 00000000..cbe2e2a0 --- /dev/null +++ b/noao/imred/specred/dofibers.par @@ -0,0 +1,42 @@ +objects,s,a,"",,,"List of object spectra" +apref,f,h,"",,,"Aperture reference spectrum" +flat,f,h,"",,,"Flat field spectrum" +throughput,f,h,"",,,"Throughput file or image (optional)" +arcs1,s,h,"",,,"List of arc spectra" +arcs2,s,h,"",,,"List of shift arc spectra" +arctable,f,h,"",,,"Arc assignment table (optional) +" +readnoise,s,h,"0.",,,"Read out noise sigma (photons)" +gain,s,h,"1.",,,"Photon gain (photons/data number)" +datamax,r,h,INDEF,,,"Max data value / cosmic ray threshold" +fibers,i,h,97,,,"Number of fibers" +width,r,h,12.,,,"Width of profiles (pixels)" +minsep,r,h,8.,,,"Minimum separation between fibers (pixels)" +maxsep,r,h,15.,,,"Maximum separation between fibers (pixels)" +apidtable,f,h,"",,,"Aperture identifications" +crval,s,h,INDEF,,,"Approximate central wavelength" +cdelt,s,h,INDEF,,,"Approximate dispersion" +objaps,s,h,"",,,"Object apertures" +skyaps,s,h,"",,,"Sky apertures" +arcaps,s,h,"",,,"Arc apertures" +objbeams,s,h,"0,1",,,"Object beam numbers" +skybeams,s,h,"0",,,"Sky beam numbers" +arcbeams,s,h,"",,,"Arc beam numbers +" +scattered,b,h,no,,,"Subtract scattered light?" +fitflat,b,h,yes,,,"Fit and ratio flat field spectrum?" +clean,b,h,yes,,,"Detect and replace bad pixels?" +dispcor,b,h,yes,,,"Dispersion correct spectra?" +skyalign,b,h,no,,,"Align sky lines?" +savearcs,b,h,yes,,,"Save simultaneous arc apertures?" +skysubtract,b,h,yes,,,"Subtract sky?" +skyedit,b,h,yes,,,"Edit the sky spectra?" +saveskys,b,h,yes,,,"Save sky spectra?" +splot,b,h,no,,,"Plot the final spectrum?" +redo,b,h,no,,,"Redo operations if previously done?" +update,b,h,yes,,,"Update spectra if cal data changes?" +batch,b,h,no,,,"Extract objects in batch?" +listonly,b,h,no,,,"List steps but don\'t process? +" +params,pset,h,"",,,"Algorithm parameters" +mode,s,h,"ql",,, diff --git a/noao/imred/specred/msresp1d.cl b/noao/imred/specred/msresp1d.cl new file mode 100644 index 00000000..1083c64d --- /dev/null +++ b/noao/imred/specred/msresp1d.cl @@ -0,0 +1,234 @@ +# MSRESP1D -- Make a aperture response spectrum using a flat field +# and a throughput file or image. + +procedure msresp1d (flat, throughput, apreference, response) + +string flat {prompt="Flat field spectrum"} +string throughput {prompt="Throughput file or image"} +string apreference {prompt="Aperture reference spectrum"} +string response {prompt="Response spectrum"} + +bool recenter = no {prompt="Recenter apertures?"} +bool edit = yes {prompt="Edit/review apertures?"} +bool trace = no {prompt="Trace spectra?"} +bool clean = no {prompt="Detect and replace bad pixels?"} +bool fitflat = no {prompt="Fit and ratio flat field spectrum?"} +bool interactive = yes {prompt="Fit flat field interactively?"} +string function = "spline3" {prompt="Fitting function", + enum="spline3|legendre|chebyshev|spline1"} +int order = 20 {prompt="Fitting function order", min=1} + +begin + file flat2d, skyflat2d, apref, resp + file temp1, temp2, log1, log2 + string imtype, mstype + int i, n, ap, naxis + real respval + + flat2d = flat + skyflat2d = throughput + apref = apreference + resp = response + temp1 = mktemp ("tmp") + temp2 = mktemp ("tmp") + + imtype = "." // envget ("imtype") + i = stridx (",", imtype) + if (i > 0) + imtype = substr (imtype, 1, i-1) + mstype = ".ms" // imtype + n = strlen (imtype) + + # Check required input and output. + if (resp == "" || resp == flat2d || resp == skyflat2d) + error (1, "Bad response image name") + if (flat2d == "" && skyflat2d == "") + error (1, "No flat field or throughput specified") + + if (flat2d != "") { + i = strlen (flat2d) + if (i > n && substr (flat2d, i-n+1, i) == imtype) + flat2d = substr (flat2d, 1, i-n) + if (!access (flat2d // imtype)) + error (1, "Flat field spectrum not found - " // flat2d) + } + if (skyflat2d != "") { + i = strlen (skyflat2d) + if (i > n && substr (skyflat2d, i-n+1, i) == imtype) + skyflat2d = substr (skyflat2d, 1, i-n) + if (!access (skyflat2d // imtype)) { + if (!access (skyflat2d)) + error (1, + "Throughput file or image not found - " // skyflat2d) + + if (flat2d == "") { + i = strlen (apref) + if (i > n && substr (apref, i-n+1, i) == imtype) + apref = substr (apref, 1, i-n) + if (!access (apref // imtype)) + error (1, "Aperture reference image required") + } + } + } + + # Set logging + tee.append = yes + if (logfile == "") + log1 = "dev$null" + else + log1 = logfile + if (verbose) + log2 = "STDOUT" + else + log2 = "dev$null" + + # If using a flat field extract it if necessary and possibly fit it + # and ratio the individual apertures by an overall smooth function + + if (flat2d != "") { + if (!access (flat2d // mstype)) { + print ("Extract flat field ", flat2d) | tee (log1) + if (flat2d != apref) + apall (flat2d, output=resp, references=apref, profiles="", + interactive=yes, find=yes, recenter=recenter, + resize=no, edit=edit, trace=trace, fittrace=yes, + extract=yes, review=no, background="none", clean=clean, + extras=no) + else + apall (flat2d, output=resp, references=apref, profiles="", + interactive=no, find=yes, recenter=no, resize=no, + edit=edit, trace=no, fittrace=yes, extract=yes, + review=no, background="none", clean=clean, extras=no) + } else + imcopy (flat2d//".ms", resp, verbose=no) + + if (fitflat) { + print ("Fit and ratio flat field ", flat2d) | tee (log1) + blkavg (resp, temp1, option="average", b1=1, b2=10000) + imcopy (temp1//"[*,1]", temp1, verbose=no) + fit1d (temp1, temp1, "fit", axis=1, interactive=interactive, + sample="*", naverage=1, function=function, order=order, + low_reject=0., high_reject=0., niterate=1, grow=0., + graphics="stdgraph") + sarith (resp, "/", temp1, resp, w1=INDEF, w2=INDEF, + apertures="", beams="", apmodulus=0, reverse=no, + ignoreaps=yes, format="multispec", renumber=no, offset=0, + clobber=yes, merge=no, errval=0, verbose=no) + imdelete (temp1, verify=no) + } + } + + # If using a throughput image extract it if necessary. + # Apply it to the flat field if given and otherwise only + # compute the throughput through each aperture. + + if (skyflat2d != "") { + if (access (skyflat2d // imtype)) { + if (!access (skyflat2d // mstype)) { + print ("Extract throughput image ", skyflat2d) | tee (log1) + apall (skyflat2d, output=temp1, references=apref, + profiles="", interactive=yes, find=yes, + recenter=recenter, resize=no, edit=edit, + trace=trace, fittrace=yes, extract=yes, review=no, + background="none", clean=clean, extras=no) + temp2 = temp1 + } else + temp2 = skyflat2d // ".ms" + + if (flat2d != "") { + print ("Correct flat field to throughput image") | + tee (log1) + sarith (temp2, "/", resp, temp1, w1=INDEF, w2=INDEF, + apertures="", beams="", apmodulus=0, reverse=no, + ignoreaps=no, format="multispec", renumber=no, offset=0, + clobber=yes, merge=no, errval=0, verbose=no) + fit1d (temp1, temp1, type="fit", axis=1, + interactive=no, sample="*", naverage=1, + function="legendre", order=1, niterate=0) + sarith (resp, "*", temp1, resp, w1=INDEF, w2=INDEF, + apertures="", beams="", apmodulus=0, reverse=no, + ignoreaps=yes, format="multispec", renumber=no, + offset=0, clobber=yes, merge=no, errval=0, verbose=no) + imdelete (temp1, verify=no) + } else { + print ("Compute aperture throughput from image") | + tee (log1) + fit1d (temp2, resp, type="fit", axis=1, + interactive=no, sample="*", naverage=1, + function="legendre", order=1, niterate=0) + if (temp2 == temp1) + imdelete (temp2, verify=no) + } + + # If a flat field and throughput file are used scale the average + # flat field in each aperture to those values + + } else if (flat2d != "") { + print ("Correct flat field with throughput file ", skyflat2d) | + tee (log1) + fit1d (resp, resp, type="ratio", axis=1, + interactive=no, sample="*", naverage=1, + function="legendre", order=1, niterate=0) + + list = skyflat2d + while (fscan (list, ap, respval) != EOF) { + sarith (resp, "*", respval, resp, w1=INDEF, w2=INDEF, + apertures=ap, beams="", apmodulus=0, reverse=no, + ignoreaps=no, format="multispec", renumber=no, + offset=0, clobber=yes, merge=yes, errval=0., + verbose=no) + } + list = "" + + # If only a throughput file is given create the response from the + # aperture reference and set the aperture response to the specified + # values. + + } else { + print ("Set aperture throughput using ", skyflat2d) | tee (log1) + if (!access (apref // mstype)) { + apall (apref, output=resp, references=apref, + profiles="", interactive=no, find=yes, recenter=no, + resize=no, edit=edit, trace=no, fittrace=yes, + extract=yes, review=no, background="none", clean=no, + extras=no) + sarith (resp, "replace", "0", resp, w1=INDEF, w2=INDEF, + apertures="", beams="", apmodulus=0, reverse=no, + ignoreaps=no, format="multispec", renumber=no, + offset=0, clobber=yes, merge=yes, errval=0., verbose=no) + } else + sarith (apref//".ms", "replace", "0", resp, w1=INDEF, + w2=INDEF, apertures="", beams="", apmodulus=0, + reverse=no, ignoreaps=no, format="multispec", + renumber=no, offset=0, clobber=yes, merge=yes, + errval=0., verbose=no) + + list = skyflat2d + while (fscan (list, ap, respval) != EOF) { + sarith (resp, "replace", respval, resp, w1=INDEF, w2=INDEF, + apertures=ap, beams="", apmodulus=0, reverse=no, + ignoreaps=no, format="multispec", renumber=no, + offset=0, clobber=yes, merge=yes, errval=0., + verbose=no) + } + list = "" + } + } + + # The final response is normalized to overall unit mean and the + # average aperture response is printed. + + print ("Create the normalized response ", resp) | tee (log1) + bscale (resp, resp, bzero="0.", bscale="mean", section="", + step=1, upper=INDEF, lower=INDEF, verbose=yes) | tee (log1, >log2) + blkavg (resp, temp1, option="average", b1=10000, b2=1) + print ("Average aperture response:") | tee (log1, >log2) + hselect (temp1, "naxis", yes, > temp2) + list = temp2; ap = fscan (list, naxis) + if (naxis == 1) + listpixels (temp1) | tee (log1, >log2) + else + listpixels (temp1//"[1,*]") | tee (log1, >log2) + list = ""; delete (temp2, verify=no) + imdelete (temp1, verify=no) +end diff --git a/noao/imred/specred/msresp1d.par b/noao/imred/specred/msresp1d.par new file mode 100644 index 00000000..9a59eb46 --- /dev/null +++ b/noao/imred/specred/msresp1d.par @@ -0,0 +1,13 @@ +flat,s,a,,,,"Flat field spectrum" +throughput,s,a,,,,"Throughput file or image" +apreference,s,a,,,,"Aperture reference spectrum" +response,s,a,,,,"Response spectrum" +recenter,b,h,no,,,"Recenter apertures?" +edit,b,h,yes,,,"Edit/review apertures?" +trace,b,h,no,,,"Trace spectra?" +clean,b,h,no,,,"Detect and replace bad pixels?" +fitflat,b,h,no,,,"Fit and ratio flat field spectrum?" +interactive,b,h,yes,,,"Fit flat field interactively?" +function,s,h,"spline3",spline3|legendre|chebyshev|spline1,,"Fitting function" +order,i,h,20,1,,"Fitting function order" +mode,s,h,"ql",,, diff --git a/noao/imred/specred/params.par b/noao/imred/specred/params.par new file mode 100644 index 00000000..fab14009 --- /dev/null +++ b/noao/imred/specred/params.par @@ -0,0 +1,67 @@ +line,i,h,INDEF,,,"Default dispersion line" +nsum,i,h,10,,,"Number of dispersion lines to sum or median" +order,s,h,"decreasing","increasing|decreasing",,"Order of apertures" +extras,b,h,no,,,"Extract sky, sigma, etc.? + +-- DEFAULT APERTURE LIMITS --" +lower,r,h,-5.,,,"Lower aperture limit relative to center" +upper,r,h,5.,,,"Upper aperture limit relative to center + +-- AUTOMATIC APERTURE RESIZING PARAMETERS --" +ylevel,r,h,0.05,,,"Fraction of peak or intensity for resizing + +-- TRACE PARAMETERS --" +t_step,i,h,10,,,"Tracing step" +t_function,s,h,"spline3","chebyshev|legendre|spline1|spline3",,"Trace fitting function" +t_order,i,h,3,,,"Trace fitting function order" +t_niterate,i,h,1,0,,"Trace rejection iterations" +t_low,r,h,3.,0.,,"Trace lower rejection sigma" +t_high,r,h,3.,0.,,"Trace upper rejection sigma + +-- SCATTERED LIGHT PARAMETERS --" +buffer,r,h,1.,0.,,Buffer distance from apertures +apscat1,pset,h,"",,,Fitting parameters across the dispersion +apscat2,pset,h,"",,,"Fitting parameters along the dispersion + +-- APERTURE EXTRACTION PARAMETERS --" +weights,s,h,"none","none|variance",,Extraction weights (none|variance) +pfit,s,h,"fit1d","fit1d|fit2d",,Profile fitting algorithm (fit1d|fit2d) +lsigma,r,h,3.,,,Lower rejection threshold +usigma,r,h,3.,,,Upper rejection threshold +nsubaps,i,h,1,1,,"Number of subapertures + +-- FLAT FIELD FUNCTION FITTING PARAMETERS --" +f_interactive,b,h,yes,,,"Fit flat field interactively?" +f_function,s,h,"spline3",spline3|legendre|chebyshev|spline1,,"Fitting function" +f_order,i,h,10,1,,"Fitting function order + +-- ARC DISPERSION FUNCTION PARAMETERS --" +threshold,r,h,10.,0.,,"Minimum line contrast threshold" +coordlist,f,h,linelists$idhenear.dat,,,"Line list" +match,r,h,-3.,,,"Line list matching limit in Angstroms" +fwidth,r,h,4.,,,"Arc line widths in pixels" +cradius,r,h,10.,,,Centering radius in pixels +i_function,s,h,"spline3","legendre|chebyshev|spline1|spline3",,"Coordinate function" +i_order,i,h,3,1,,"Order of dispersion function" +i_niterate,i,h,2,0,,"Rejection iterations" +i_low,r,h,3.,0.,,"Lower rejection sigma" +i_high,r,h,3.,0.,,"Upper rejection sigma" +refit,b,h,yes,,,"Refit coordinate function when reidentifying?" +addfeatures,b,h,no,,,"Add features when reidentifying? + +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS --" +select,s,h,"interp",,,"Selection method for reference spectra" +sort,s,h,"jd",,,"Sort key" +group,s,h,"ljd",,,"Group key" +time,b,h,no,,,"Is sort key a time?" +timewrap,r,h,17.,0.,24.,"Time wrap point for time sorting + +-- DISPERSION CORRECTION PARAMETERS --" +linearize,b,h,yes,,,Linearize (interpolate) spectra? +log,b,h,no,,,"Logarithmic wavelength scale?" +flux,b,h,yes,,,"Conserve flux? + +-- SKY SUBTRACTION PARAMETERS --" +combine,s,h,"average","average|median",,Type of combine operation +reject,s,h,"avsigclip","none|minmax|avsigclip",,"Sky rejection option" +scale,s,h,"none","none|mode|median|mean",,"Sky scaling option" diff --git a/noao/imred/specred/sparams.par b/noao/imred/specred/sparams.par new file mode 100644 index 00000000..1cc001d8 --- /dev/null +++ b/noao/imred/specred/sparams.par @@ -0,0 +1,65 @@ +line,i,h,INDEF,,,"Default dispersion line" +nsum,i,h,10,,,"Number of dispersion lines to sum or median" +extras,b,h,no,,,"Extract sky, sigma, etc.? + +-- DEFAULT APERTURE PARAMETERS -- " +lower,r,h,-3.,,,Lower aperture limit relative to center +upper,r,h,3.,,,"Upper aperture limit relative to center + +-- AUTOMATIC APERTURE RESIZING PARAMETERS --" +ylevel,r,h,0.05,,,"Fraction of peak or intensity for resizing + +-- TRACE PARAMETERS --" +t_step,i,h,10,,,"Tracing step" +t_function,s,h,"spline3","chebyshev|legendre|spline1|spline3",,"Trace fitting function" +t_order,i,h,1,,,"Trace fitting function order" +t_niterate,i,h,1,0,,"Trace rejection iterations" +t_low,r,h,3.,0.,,"Trace lower rejection sigma" +t_high,r,h,3.,0.,,"Trace upper rejection sigma + +-- APERTURE EXTRACTION PARAMETERS --" +weights,s,h,"none",,,Extraction weights (none|variance) +pfit,s,h,"fit1d","fit1d|fit2d",,Profile fitting algorithm (fit1d|fit2d) +lsigma,r,h,3.,,,Lower rejection threshold +usigma,r,h,3.,,,"Upper rejection threshold + +-- BACKGROUND SUBTRACTION PARAMETERS --" +background,s,h,"fit","none|average|median|minimum|fit",,Background to subtract +b_function,s,h,"legendre","chebyshev|legendre|spline1|spline3",,"Background function" +b_order,i,h,1,,,"Background function order" +b_sample,s,h,"-10:-6,6:10",,,"Background sample regions" +b_naverage,i,h,-100,,,"Background average or median" +b_niterate,i,h,1,0,,"Background rejection iterations" +b_low,r,h,3.,0.,,"Background lower rejection sigma" +b_high,r,h,3.,0.,,"Background upper rejection sigma + +-- ARC DISPERSION FUNCTION PARAMETERS --" +threshold,r,h,10.,0.,,"Minimum line contrast threshold" +coordlist,f,h,linelists$idhenear.dat,,,"Line list" +match,r,h,-3.,,,"Line list matching limit in Angstroms" +fwidth,r,h,4.,,,"Arc line widths in pixels" +cradius,r,h,10.,,,Centering radius in pixels +i_function,s,h,"spline3","legendre|chebyshev|spline1|spline3",,"Coordinate function" +i_order,i,h,1,1,,"Order of dispersion function" +i_niterate,i,h,1,0,,"Rejection iterations" +i_low,r,h,3.,0.,,"Lower rejection sigma" +i_high,r,h,3.,0.,,"Upper rejection sigma" +refit,b,h,yes,,,"Refit coordinate function when reidentifying?" +addfeatures,b,h,no,,,"Add features when reidentifying? + +-- AUTOMATIC ARC ASSIGNMENT PARAMETERS --" +select,s,h,"interp",,,"Selection method for reference spectra" +sort,s,h,"jd",,,"Sort key" +group,s,h,"ljd",,,"Group key" +time,b,h,no,,,"Is sort key a time?" +timewrap,r,h,17.,0.,24.,"Time wrap point for time sorting + +-- DISPERSION CORRECTION PARAMETERS --" +linearize,b,h,yes,,,Linearize (interpolate) spectra? +log,b,h,no,,,"Logarithmic wavelength scale?" +flux,b,h,yes,,,"Conserve flux? + +-- SENSITIVITY CALIBRATION PARAMETERS --" +s_function,s,h,"spline3","chebyshev|legendre|spline3|spline1",,"Fitting function" +s_order,i,h,1,1,,"Order of sensitivity function" +fnu,b,h,no,,,"Create spectra having units of FNU?" diff --git a/noao/imred/specred/specred.cl b/noao/imred/specred/specred.cl new file mode 100644 index 00000000..ab859853 --- /dev/null +++ b/noao/imred/specred/specred.cl @@ -0,0 +1,103 @@ +#{ SPECRED package definition + +proto # bscale + +s1 = envget ("min_lenuserarea") +if (s1 == "") + reset min_lenuserarea = 100000 +else if (int (s1) < 100000) + reset min_lenuserarea = 100000 + +package specred + +# Slitproc +cl < doslit$doslittasks.cl +task sparams = "specred$sparams.par" + +# Dofibers +task dofibers = "specred$dofibers.cl" +task params = "specred$params.par" + +task proc = "srcfibers$proc.cl" +task fibresponse = "srcfibers$fibresponse.cl" +task arcrefs = "srcfibers$arcrefs.cl" +task doarcs = "srcfibers$doarcs.cl" +task doalign = "srcfibers$doalign.cl" +task skysub = "srcfibers$skysub.cl" +task batch = "srcfibers$batch.cl" +task getspec = "srcfibers$getspec.cl" +task listonly = "srcfibers$listonly.cl" +task apscript = "srcfibers$x_apextract.e" + +# Generic fiber reduction tasks +task msresp1d = "specred$msresp1d.cl" + +# Onedspec tasks +task autoidentify, + calibrate, + continuum, + deredden, + dispcor, + dopcor, + fitprofs, + identify, + odcombine, + refspectra, + reidentify, + sapertures, + sarith, + sensfunc, + sfit, + sflip, + slist, + skytweak, + specplot, + specshift, + splot, + standard, + telluric = "onedspec$x_onedspec.e" +task scombine = "onedspec$scombine/x_scombine.e" +task aidpars = "onedspec$aidpars.par" +task bplot = "onedspec$bplot.cl" +task scopy = "onedspec$scopy.cl" +task dispcor1 = "onedspec$dispcor1.par" + +# Apextract tasks +task apall, + apedit, + apfind, + apfit, + apflatten, + apmask, + apnormalize, + aprecenter, + apresize, + apscatter, + apsum, + aptrace = "apextract$x_apextract.e" +task apparams = "apextract$apparams.par" +task apall1 = "apextract$apall1.par" +task apfit1 = "apextract$apfit1.par" +task apflat1 = "apextract$apflat1.par" +task apnorm1 = "apextract$apnorm1.par" +task apdefault = "apextract$apdefault.par" +task apscat1 = "apextract$apscat1.par" +task apscat2 = "apextract$apscat2.par" + +# Longslit tasks +task illumination, + lscombine, + response, + transform = "twodspec$longslit/x_longslit.e" +task background = "generic$background.cl" + +# Astutil tasks +task setairmass, + setjd = "astutil$x_astutil.e" + +# Hide tasks from the user +hidetask apparams, apall1, apfit1, apflat1, apnorm1, apscat1, apscat2, dispcor1 +hidetask sparams, params, doalign +hidetask apscript, proc, batch, arcrefs, doarcs, getspec, listonly, fibresponse + +clbye diff --git a/noao/imred/specred/specred.hd b/noao/imred/specred/specred.hd new file mode 100644 index 00000000..94f4609b --- /dev/null +++ b/noao/imred/specred/specred.hd @@ -0,0 +1,11 @@ +# Help directory for the SPECRED package. + +$doc = "./doc/" +$doslit = "noao$imred/src/doslit/" + +dofibers hlp=doc$dofibers.hlp, src=dofibers.cl +doslit hlp=doc$doslit.hlp, src=doslit$doslit.cl +msresp1d hlp=doc$msresp1d.hlp, src=msresp1d.cl +skysub hlp=doc$skysub.hlp, src=srcfibers$skysub.cl + +revisions sys=Revisions diff --git a/noao/imred/specred/specred.men b/noao/imred/specred/specred.men new file mode 100644 index 00000000..3e2b0130 --- /dev/null +++ b/noao/imred/specred/specred.men @@ -0,0 +1,51 @@ + 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 + + background - Fit and subtract a line or column background + bplot - Batch plot of spectra with SPLOT + calibrate - Extinction and flux calibrate spectra + continuum - Fit the continuum in spectra + deredden - Apply interstellar extinction correction + dispcor - Dispersion correct spectra + dopcor - Doppler correct spectra + fitprofs - Fit gaussian profiles + identify - Identify features in spectrum for dispersion solution + illumination - Determine illumination calibration + lscombine - Combine longslit spectra + msresp1d - Create 1D response spectra from flat field and sky spectra + odcombine - Combine spectra (new version) + refspectra - Assign wavelength reference spectra to other spectra + reidentify - Automatically reidentify features in spectra + response - Determine response calibration + sapertures - Set or change aperture header information + sarith - Spectrum arithmetic + scombine - Combine spectra + scopy - Select and copy apertures in different spectral formats + sensfunc - Compute instrumental sensitivity from standard stars + setairmass - Compute effective airmass and middle UT for an exposure + setjd - Compute and set Julian dates in images + sfit - Fit spectra and output fit, ratio, or difference + sflip - Flip data and/or dispersion coordinates in spectra + skysub - Sky subtract extracted multispec spectra + skytweak - Sky subtract 1D spectra after tweaking sky spectra + slist - List spectrum header parameters + specplot - Scale, stack, and plot multiple spectra + specshift - Shift spectral dispersion coordinate systems + splot - Preliminary spectral plot/analysis + standard - Tabulate standard star counts and fluxes + telluric - Remove telluric features from 1D spectra + transform - Resample longslit spectra + + dofibers - Process fiber spectra + doslit - Process slit spectra diff --git a/noao/imred/specred/specred.par b/noao/imred/specred/specred.par new file mode 100644 index 00000000..15471412 --- /dev/null +++ b/noao/imred/specred/specred.par @@ -0,0 +1,15 @@ +# SPECRED parameter file +extinction,s,h,onedstds$kpnoextinct.dat,,,Extinction file +caldir,s,h,onedstds$spec16redcal/,,,Standard star calibration directory +observatory,s,h,"observatory",,,Observatory of data +interp,s,h,"poly5","nearest|linear|poly3|poly5|spline3|sinc",,Interpolation type +dispaxis,i,h,2,1,3,Image axis for 2D/3D images +nsum,s,h,"1",,,"Number of lines/columns/bands to sum for 2D/3D images +" +database,f,h,"database",,,Database +verbose,b,h,no,,,Verbose output? +logfile,s,h,"logfile",,,Log file +plotfile,s,h,"",,,"Plot file +" +records,s,h,"",,,Record number extensions +version,s,h,"SPECRED V3: April 1992" |