diff options
Diffstat (limited to 'noao/onedspec/doc')
56 files changed, 20923 insertions, 0 deletions
diff --git a/noao/onedspec/doc/aidpars.hlp b/noao/onedspec/doc/aidpars.hlp new file mode 100644 index 00000000..be846306 --- /dev/null +++ b/noao/onedspec/doc/aidpars.hlp @@ -0,0 +1,563 @@ +.help aidpars Jan04 noao.onedspec +.ih +NAME +aidpars -- Automatic line identification parameters and algorithm +.ih +SUMMARY +The automatic line identification parameters and algorithm used in +\fBautoidentify\fR, \fBidentify\fR, and \fBreidentify\fR are described. +.ih +USAGE +aidpars +.ih +PARAMETERS +.ls reflist = "" +Optional reference coordinate list to use in the pattern matching algorithm +in place of the task coordinate list. This file is a simple text list of +dispersion coordinates. It would normally be a culled and limited list of +lines for the specific data being identified. +.le +.ls refspec = "" +Optional reference dispersion calibrated spectrum. This template spectrum +is used to select the prominent lines for the pattern matching algorithm. +It need not have the same dispersion increment or dispersion coverage as +the target spectrum. +.le +.ls crpix = "INDEF" +Coordinate reference pixel for the coordinate reference value specified by +the \fIcrval\fR parameter. This may be specified as a pixel coordinate +or an image header keyword name (with or without a '!' prefix). In the +latter case the value of the keyword in the image header of the spectrum +being identified is used. A value of INDEF translates to the middle of +the target spectrum. +.le +.ls crquad = INDEF +Quadratic correction to the detected pixel positions to "linearize" the +pattern of line spacings. The corrected positions x' are derived from +the measured positions x by + +.nf + x' = x + crquad * (x - crpix)**2 +.fi + +where crpix is the pixel reference point as defined by the \fIcrpix\fR +parameter. The measured and corrected positions may be examined by +using the 't' debug flag. The value may be a number or a header +keyword (with or without a '!' prefix). The default of INDEF translates +to zero; i.e. no quadratic correction. +.le +.ls cddir = "sign" (unknown|sign|increasing|decreasing) +The sense of the dispersion increment with respect to the pixel coordinates +in the input spectrum. The possible values are "increasing" or +"decreasing" if the dispersion coordinates increase or decrease with +increasing pixel coordinates, "sign" to use the sign of the dispersion +increment (positive is increasing and negative is decreasing), and +"unknown" if the sense is unknown and to be determined by the algorithm. +.le +.ls crsearch = "INDEF" +Coordinate reference value search radius. The value may be specified +as a numerical value or as an image header keyword (with or without +a '!' prefix) whose value is to be used. The algorithm will search +for a final coordinate reference value within this amount of the value +specified by \fIcrval\fR. If the value is positive the search radius is +the specified value. If the value is negative it is the absolute value +of this parameter times \fIcdelt\fR times the number of pixels in the +input spectrum; i.e. it is the fraction of dispersion range covered by the +target spectrum assuming a dispersion increment per pixel of \fIcdelt\fR. +A value of INDEF translates to -0.1 which corresponds to a search radius +of 10% of the estimated dispersion range. +.le +.ls cdsearch = "INDEF" +Dispersion coordinate increment search radius. The value may be specified +as a numerical value or as an image header keyword (with or without +a '!' prefix) whose value is to be used. The algorithm will search +for a dispersion coordinate increment within this amount of the value +specified by \fIcdelt\fR. If the value is positive the search radius is +the specified value. If the value is negative it is the absolute value of +this parameter times \fIcdelt\fR; i.e. it is a fraction of \fIcdelt\fR. +A value of INDEF translates to -0.1 which corresponds to a search radius +of 10% of \fIcdelt\fR. +.le +.ls ntarget = 100 +Number of spectral lines from the target spectrum to use in the pattern +matching. +.le +.ls npattern = 5 +Initial number of spectral lines in patterns to be matched. There is a +minimum of 3 and a maximum of 10. The algorithm starts with the specified +number and if no solution is found with that number it is iteratively +decreased by one to the minimum of 3. A larger number yields fewer +and more likely candidate matches and so will produce a result sooner. +But in order to be thorough the algorithm will try smaller patterns to +search more possiblities. +.le +.ls nneighbors = 10 +Number of neighbors to use in making patterns of lines. This parameter +restricts patterns to include lines which are near each other. +.le +.ls nbins = 6 +Maximum number of bins to divide the reference coordinate list or spectrum +in searching for a solution. When there are no weak dispersion constraints +the algorithm subdivides the full range of the coordinate list or reference +spectrum into one bin, two bins, etc. up to this maximum. Each bin is +searched for a solution. +.le +.ls ndmax = 1000 +Maximum number of candidate dispersions to examine. The algorithm ranks +candidate dispersions by how many candidate spectral lines are fit and the +the weights assigned by the pattern matching algorithm. Starting from +the highest rank it tests each candidate dispersion to see if it is +a satisfactory solution. This parameter determines how many candidate +dispersion in the ranked list are examined. +.le +.ls aidord = 3 (minimum of 2) +The order of the dispersion function fit by the automatic identification +algorithm. This is the number of polynomial coefficients so +a value of two is a linear function and a value of three is a quadratic +function. The order should be restricted to values of two or three. +Higher orders can lead to incorrect solutions because of the increased +degrees of freedom if finding incorrect line identifications. +.le +.ls maxnl = 0.02 +Maximum non-linearity allowed in any trial dispersion function. +The definition of the non-linearity test is + +.nf + maxnl > (w(0.5) - w(0)) / (w(1) - w(0)) - 0.5 +.fi + +where w(x) is the dispersion function value (e.g. wavelength) of the fit +and x is a normalized pixel positions where the endpoints of the spectrum +are [0,1]. If the test fails on a trial dispersion fit then a linear +function is determined. +.le +.ls nfound = 6 +Minimum number of identified spectral lines required in the final solution. +If a candidate solution has fewer identified lines it is rejected. +.le +.ls sigma = 0.05 +Sigma (uncertainty) in the line center estimates specified in pixels. +This is used to propagate uncertainties in the line spacings in +the observed patterns of lines. +.le +.ls minratio = 0.1 +Minimum spacing ratio used. Patterns of lines in which the ratio of +spacings between consecutive lines is less than this amount are excluded. +.le +.ls rms = 0.1 +RMS goal for a correct dispersion solution. This is the RMS in the +measured spectral lines relative to the expected positions from the +coordinate line list based on the coordinate dispersion solution. +The parameter is specified in terms of the line centering parameter +\fIfwidth\fR since for broader lines the pixel RMS would be expected +to be larger. A pixel-based RMS criterion is used to be independent of +the dispersion. The RMS will be small for a valid solution. +.le +.ls fmatch = 0.2 +Goal for the fraction of unidentified lines in a correct dispersion +solution. This is the fraction of the strong lines seen in the spectrum +which are not identified and also the fraction of all lines in the +coordinate line list, within the range of the dispersion solution, not +identified. Both fractions will be small for a valid solution. +.le +.ls debug = "" +Print or display debugging information. This is intended for the developer +and not the user. The parameter is specified as a string of characters +where each character displays some information. The characters are: + +.nf + a: Print candidate line assignments. + b: Print search limits. + c: Print list of line ratios. +* d: Graph dispersions. +* f: Print final result. +* l: Graph lines and spectra. + r: Print list of reference lines. +* s: Print search iterations. + t: Print list of target lines. + v: Print vote array. + w: Print wavelength bin limits. +.fi + +The items with an asterisk are the most useful. The graphs are exited +with 'q' or 'Q'. +.le +.ih +DESCRIPTION +The \fBaidpars\fR parameter set contains the parameters for the automatic +spectral line identification algorithm used in the task \fBautoidentify\fR, +\fBidentify\fR, and \fBreidentify\fR. These tasks include the parameter +\fIaidpars\fR which links to this parameters set. Typing \fBaidpars\fR +allows these parameters to be edited. When editing the parameters of the +other tasks with \fBeparam\fR one can edit the \fBaidpars\fR parameters by +type ":e" when pointing to the \fIaidpars\fR task parameter. The values of +the \fBaidpars\fR parameters may also be set on the command line for the +task. The discussion which follows describes the parameters and the +algorithm. + +The goal of the automatic spectral line identification algorithm is to +automate the identification of spectral lines so that given an observed +spectrum of a spectral line source (called the target spectrum) and a file +of known dispersion coordinates for the lines, the software will identify +the spectral lines and use these identifications to determine a +dispersion function. This algorithm is quite general so that the correct +identifications and dispersion function may be found even when there is +limited or no knowledge of the dispersion coverage and resolution of the +observation. + +However, when a general line list, including a large dispersion range and +many weak lines, is used and the observation covers a much smaller portion +of the coordinate list the algorithm may take a long to time or even fail +to find a solution. Thus, it is highly desirable to provide additional +input giving approximate dispersion parameters and their uncertainties. +When available, a dispersion calibrated reference spectrum (not necessarily +of the same resolution or wavelength coverage) also aids the algorithm by +indicating the relative strengths of the lines in the coordinate file. The +line strengths need not be very similar (due to different lamps or +detectors) but will still help separate the inherently weak and strong +lines. + + +The Input + +The primary inputs to the algorithm are the observed one dimensional target +spectrum in which the spectral lines are to be identified and a dispersion +function determined and a file of reference dispersion coordinates. These +inputs are provided in the tasks using the automatic line identification +algorithm. + +One way to limit the algorithm to a specific dispersion region and to the +important spectral lines is to use a limited coordinate list. One may do +this with the task coordinate list parameter (\fIcoordlist\fR). However, +it is desirable to use a standard master line list that includes all the +lines, both strong and weak. Therefore, one may specify a limited line +list with the parameter \fIreflist\fR. The coordinates in this list will +be used by the automatic identification algorithm to search for patterns +while using the primary coordinate list for adding weaker lines during the +dispersion function fitting. + +The tasks \fBautoidentify\fR and \fBidentify\fR also provide parameters to +limit the search range. These parameters specify a reference dispersion +coordinate (\fIcrval\fR) and a dispersion increment per pixel (\fIcdelt\fR). +When these parameters are INDEF this tells the algorithm to search for a +solution over the entire range of possibilities covering the coordinate +line list or reference spectrum. + +The reference dispersion coordinate refers to an approximate coordinate at +the reference pixel coordinate specified by the parameter \fIcrpix\fR. +The default value for the reference pixel coordinate is INDEF which +translates to the central pixel of the target spectrum. + +The parameters \fIcrsearch\fR and \fIcdsearch\fR specify the expected range +or uncertainty of the reference dispersion coordinate and dispersion +increment per pixel respectively. They may be specified as an absolute +value or as a fraction. When the values are positive they are used +as an absolute value; + +.nf + crval(final) = \fIcrval\fR +/- \fIcrsearch\fR + cdelt(final) = \fIcdelt\fR +/- \fIcdsearch\fR. +.fi + +When the values are negative they are used as a fraction of the dispersion +range or fraction of the dispersion increment; + +.nf + crval(final) = \fIcrval\fR +/- abs (\fIcrsearch\fR * \fIcdelt\fR) * N_pix + cdelt(final) = \fIcdelt\fR +/- abs (\fIcdsearch\fR * \fIcdelt\fR) +.fi + +where abs is the absolute value function and N_pix is the number of pixels +in the target spectrum. When the ranges are not given explicitly, that is +they are specified as INDEF, default values of -0.1 are used. + +The parameters \fIcrval\fR, \fIcdelt\fR, \fIcrpix\fR, \fIcrsearch\fR, +and \fIcdsearch\fR may be given explicit numerical values or may +be image header keyword names. In the latter case the values of the +indicated keywords are used. This feature allows the approximate +dispersion range information to be provided by the data acquisition +system; either by the instrumentation or by user input. + +Because sometimes only the approximate magnitude of the dispersion +increment is known and not the sign (i.e. whether the dispersion +coordinates increase or decrease with increasing pixel coordinates) +the parameter \fIcdsign\fR specifies if the dispersion direction is +"increasing", "decreasing", "unknown", or defined by the "sign" of the +approximate dispersion increment parameter (sign of \fIcdelt\fR). + +The above parameters defining the approximate dispersion of the target +spectrum apply to \fIautoidentify\fR and \fIidentify\fR. The task +\fBreidentify\fR does not use these parameters except that the \fIshift\fR +parameter corresponds to \fIcrsearch\fR if it is non-zero. This task +assumes that spectra to be reidentified are the same as a reference +spectrum except for a zero point dispersion offset; i.e. the approximate +dispersion parameters are the same as the reference spectrum. The +dispersion increment search range is set to be 5% and the sign of the +dispersion increment is the same as the reference spectrum. + +An optional input is a dispersion calibrated reference spectrum (referred to +as the reference spectrum in the discussion). This is specified either in +the coordinate line list file or by the parameter \fIrefspec\fR. To +specify a spectrum in the line list file the comment "# Spectrum <image>" +is included where <image> is the image filename of the reference spectrum. +Some of the standard line lists in linelists$ may include a reference +spectrum. The reference spectrum is used to select the strongest lines for +the pattern matching algorithm. + + +The Algorithm + +First a list of the pixel positions for the strong spectral lines in the +target spectrum is created. This is accomplished by finding the local +maxima, sorting them by pixel value, and then using a centering algorithm +(\fIcenter1d\fR) to accurately find the centers of the line profiles. Note +that task parameters \fIftype\fR, \fIfwidth\fR, \fIcradius\fR, +\fIthreshold\fR, and \fIminsep\fR are used for the centering. The number +of spectral lines selected is set by the parameter \fIntarget\fR. + +In order to insure that lines are selected across the entire spectrum +when all the strong lines are concentrated in only a part of the +spectrum, the spectrum is divided into five regions and approximately +a fifth of the requested number of lines is found in each region. + +A list of reference dispersion coordinates is selected from the coordinate +file (\fIcoordlist\fR or \fIreflist\fR). The number of reference +dispersion coordinates is set at twice the number of target lines found. +The reference coordinates are either selected uniformly from the coordinate +file or by locating the strong spectral lines (in the same way as for the +target spectrum) in a reference spectrum if one is provided. The selection +is limited to the expected range of the dispersion as specified by the +user. If no approximate dispersion information is provided the range of +the coordinate file or reference spectrum is used. + +The ratios of consecutive spacings (the lists are sorted in increasing +order) for N-tuples of coordinates are computed from both lists. The size +of the N-tuple pattern is set by the \fInpattern\fR parameter. Rather than +considering all possible combinations of lines only patterns of lines with +all members within \fInneighbors\fR in the lists are used; i.e. the first +and last members of a pattern must be within \fInneighbors\fR of each other +in the lists. The default case is to find all sets of five lines which are +within ten lines of each other and compute the three spacing ratios. +Because very small spacing ratios become uncertain, the line patterns are +limited to those with ratios greater than the minimum specified by the +\fIminratio\fR parameter. Note that if the direction of the dispersion is +unknown then one computes the ratios in the reference coordinates in both +directions. + +The basic idea is that similar patterns in the pixel list and the +dispersion list will have matching spacing ratios to within a tolerance +derived by the uncertainties in the line positions (\fIsigma\fR) from the +target spectrum. The reference dispersion coordinates are assumed to have +no uncertainty. All matches in the ratio space are found between patterns +in the two lists. When matches are made then the candidate identifications +(pixel, reference dispersion coordinate) between the elements of the +patterns are recorded. After finding all the matches in ratio space a +count is made of how often each possible candidate identification is +found. When there are a sufficient number of true pairs between the lists +(of order 25% of the shorter list) then true identifications will appear in +common in many different patterns. Thus the highest counts of candidate +identifications are the most likely to be true identifications. + +Because the relationship between the pixel positions of the lines in the +target spectrum and the line positions in the reference coordinate space +is generally non-linear the line spacing ratios are distorted and may +reduce the pattern matching. The line patterns are normally restricted +to be somewhat near each other by the \fInneighbors\fR so some degree of +distortion can be tolerated. But in order to provide the ability to remove +some of this distortion when it is known the parameter \fIcrquad\fR is +provided. This parameter applies a quadratic transformation to the measured +pixel positions to another set of "linearized" positions which are used +in the line ratio pattern matching. The form of the transformation is + +.nf + x' = x + crquad * (x - crpix)**2 +.fi + +where x is the measured position, x' is the transformed position, +crquad is the value of the distortion parameter, and crpix is the value +of the coordinate reference position. + +If approximate dispersion parameters and search ranges are defined then +candidate identifications which fall outside the range of dispersion +function possibilities are rejected. From the remaining candidate +identifications the highest vote getters are selected. The number selected +is three times the number of target lines. + +All linear dispersions functions, where dispersion and pixel coordinates +are related by a zero point and slope, are found that pass within two +pixels of two or more of the candidate identifications. The dispersion +functions are ranked primarily by the number of candidate identifications +fitting the dispersion and secondarily by the total votes in the +identifications. Only the highest ranking candidate linear dispersion +are kept. The number of candidate dispersions kept is set by the +parameter \fIndmax\fR. + +The candidate dispersions are evaluated in order of their ranking. Each +line in the coordinate file (\fIcoordlist\fR) is converted to a pixel +coordinate based on the dispersion function. The centering algorithm +attempts to find a line profile near that position as defined by the +\fImatch\fR parameter. This may be specified in pixel or dispersion +coordinates. All the lines found are used to fit a polynomial dispersion +function with \fIaidord\fR coefficients. The order should be linear or +quadratic because otherwise the increased degrees of freedom allow +unrealistic dispersion functions to appear to give a good result. A +quadratic function (\fIaidord\fR = 3) is allowed since this is the +approximate form of many dispersion functions. + +However, to avoid unrealistic dispersion functions a test is made that +the maximum amplitude deviation from a linear function is less than +an amount specified by the \fImaxnl\fR parameter. The definition of +the test is + +.nf + maxnl > (w(0.5) - w(0)) / (w(1) - w(0)) - 0.5 +.fi + +where w(x) is the dispersion function value (e.g. wavelength) of the fit +and x is a normalized pixel positions where the endpoints of the spectrum +are [0,1]. What this relation means is that the wavelength interval +between one end and the center relative to the entire wavelength interval +is within maxnl of one-half. If the test fails then a linear function +is fit. The process of adding lines based on the last dispersion function +and then refitting the dispersion function is iterated twice. At the end +of this step if fewer than the number of lines specified by the parameter +\fInfound\fR have been identified the candidate dispersion is eliminated. + +The quality of the line identifications and dispersion solution is +evaluated based on three criteria. The first one is the root-mean-square +of the residuals between the pixel coordinates derived from lines found +from the dispersion coordinate file based on the dispersion function and +the observed pixel coordinates. This pixel RMS is normalized by the target +RMS set with the \fIrms\fR parameter. Note that the \fIrms\fR parameter +is specified in units of the \fIfwidth\fR parameter. This is because if +the lines are broader, requiring a larger fwidth to obtain a centroid, +then the expected uncertainty would be larger. A good solution will have +a normalized rms value less than one. A pixel RMS criterion, as opposed +to a dispersion coordinate RMS, is used since this is independent of the +actual dispersion of the spectrum. + +The other two criteria are the fraction of strong lines from the target +spectrum list which were not identified with lines in the coordinate file +and the fraction of all the lines in the coordinate file (within the +dispersion range covered by the candidate dispersion) which were not +identified. These are normalized to a target value given by \fIfmatch\fR. +The default matching goal is 0.3 which means that less than 30% of +the lines should be unidentified or greater than 70% should be identified. +As with the RMS, a value of one or less corresponds to a good solution. + +The reason the fraction identified criteria are used is that the pixel RMS +can be minimized by finding solutions with large dispersion increment per +pixel. This puts all the lines in the coordinate file into a small range +of pixels and so (incorrect) lines with very small residuals can be found. +The strong line identification criterion is clearly a requirement that +humans use in evaluating a solution. The fraction of all lines identified, +as opposed to the number of lines identified, in the coordinate file is +included to reduce the case of a large dispersion increment per pixel +mapping a large number of lines (such as the entire list) into the range of +pixels in the target spectrum. This can give the appearance of finding a +large number of lines from the coordinate file. However, an incorrect +dispersion will also find a large number which are not matched. Hence the +fraction not matched will be high. + +The three criteria, all of which are normalized so that values less +than one are good, are combined to a single figure of merit by a weighted +average. Equal weights have been found to work well; i.e. each criterion +is one-third of the figure of merit. In testing it has been found that all +correct solutions over a wide range of resolutions and dispersion coverage +have figures of merit less than one and typically of order 0.2. All +incorrect candidate dispersion have values of order two to three. + +The search for the correct dispersion function terminates immediately, +but after checking the first five most likely candidates, when +a figure of merit less than one is found. The order in which the candidate +dispersions are tested, that is by rank, was chosen to try the most promising +first so that often the correct solution is found on the first attempt. + +When the approximate dispersion is not known or is imprecise it is +often the case that the pixel and coordinate lists will not overlap +enough to have a sufficient number true coordinate pairs. Thus, at a +higher level the above steps are iterated by partitioning the dispersion +space searched into bins of various sizes. The largest size is the +maximum dispersion range including allowance for the search radii. +The smallest size bin is obtained by dividing the dispersion range by +the number specified by the \fInbins\fR parameter. The actual number +of bins searched at each bin size is actually twice the number of +bins minus one because the bins are overlapped by 50%. + +The search is done starting with bins in the middle of the size range and +in the middle of the dispersion range and working outward towards larger +and smaller bins and larger and smaller dispersion ranges. This is done to +improved the chances of finding the correction dispersion function in the +smallest number of steps. + +Another iteration performed if no solution is found after trying all the +candidate dispersion and bins is to reduce the number of lines in the +pattern. So the parameter \fInpattern\fR is an initial maximum pattern. +A larger pattern gives fewer and higher quality candidate identifications +and so converges faster. However, if no solution is found the algorithm +tries more possible matches produced by a lower number of lines in +the pattern. The pattern groups are reduced to a minimum of three lines. + +When a set of line identifications and dispersion solution satisfying the +figure of merit criterion is found a final step is performed. +Up to this point only linear dispersion functions are used since higher order +function can be stretch in unrealistic ways to give good RMS values +and fit all the lines. The final step is to use the line identifications +to fit a dispersion function using all the parameters specified by the +user (such as function type, order, and rejection parameters). This +is iterated to add new lines from the coordinate list based on the +more general dispersion function and then obtain a final dispersion +function. The line identifications and dispersion function are then +returned to the task using this automatic line identification algorithm. + +If a satisfactory solution is not found after searching all the +possibilities the algorithm will inform the task using it and the task will +report this appropriately. +.ih +EXAMPLES +1. List the parameters. + +.nf + cl> lpar aidpars +.fi + +2. Edit the parameters with \fBeparam\fR. + +.nf + cl> aidpars +.fi + +3. Edit the \fBaidpars\fR parameters from within \fBautoidentify\fR. + +.nf + cl> epar autoid + [edit the parameters] + [move to the "aidpars" parameter and type :e] + [edit the aidpars parameters and type :q or EOF character] + [finish editing the autoidentify parameters] + [type :wq or the EOF character] +.fi + +4. Set one of the parameters on the command line. + +.nf + cl> autoidentify spec002 5400 2.5 crpix=1 +.fi +.ih +REVISIONS +.ls AIDPARS V2.12.2 +There were many changes made in the paramters and algorithm. New parameters +are "crquad" and "maxnl". Changed definitions are for "rms". Default +value changes are for "cddir", "ntarget", "ndmax", and "fmatch". The most +significant changes in the algorithm are to allow for more non-linear +dispersion with the "maxnl" parameter, to decrease the "npattern" value +if no solution is found with the specified value, and to search a larger +number of candidate dispersions. +.le +.ls AIDPARS V2.11 +This parameter set is new in this version. +.le +.ih +SEE ALSO +autoidentify, identify, reidentify, center1d +.endhelp diff --git a/noao/onedspec/doc/autoidentify.hlp b/noao/onedspec/doc/autoidentify.hlp new file mode 100644 index 00000000..a344031a --- /dev/null +++ b/noao/onedspec/doc/autoidentify.hlp @@ -0,0 +1,370 @@ +.help autoidentify Jan96 noao.onedspec +.ih +NAME +autoidentify -- Automatically identify lines and fit dispersion +.ih +SUMMARY +Spectral lines are automatically identified from a list of coordinates +by pattern matching. The identified lines are then used to fit a +dispersion function which is written to a database for later use +in dispersion calibration. After a solution is found the identified +lines and dispersion function may be examined interactively. +.ih +USAGE +autoidentify images crval cdelt +.ih +PARAMETERS +.ls images +List of images containing one dimensional spectra in which to identify +spectral lines and fit dispersion functions. For two and three dimensional +spectral and spatial data one may use an image section to select a one +dimensional spectral vector or use the \fIsection\fR parameter. +.le +.ls crval, cdelt +These parameters specify an approximate coordinate value and coordinate +interval per pixel. They may be specified as numerical values, INDEF, or +image header keyword names whose values are to be used. The coordinate +reference value is for the pixel specified by the parameter +\fIaidpars.crpix\fR. The default reference pixel is INDEF which means the +middle of the spectrum. By default only the magnitude of the coordinate +interval is used and the search will include both increasing and decreasing +coordinate values with increasing pixel values. If one or both of these +parameters are specified as INDEF the search for a solution will be slower +and more likely to fail. +.le +.ls coordlist = "" +Coordinate list consisting of an list of spectral line coordinates. +A comment line of the form "# units <units>", where <units> is one of the +understood units names, defines the units of the coordinate list. If no units +are specified then Angstroms are assumed. +The line list is used for both the final identifications and for the set of +lines to use in the automatic search. A restricted search list may be +specified with the parameter \fIaidpars.reflist\fR. The line list may +contain a comment line of the form "# Spectrum <name>", where <name> is a +filename containing a reference spectrum. The reference spectrum will be +used in selecting the strong lines for the automatic search. A reference +spectrum may also be specified with the parameter \fIaidpars.refspec\fR. + +Some standard line lists are available in the directory "linelists$". +See the help topic \fIlinelists\fR for the available line lists. +.le +.ls units = "" +The units to use if no database entry exists. The units are specified as +described in + +.nf + cl> help onedspec.package section=units +.fi + +If no units are specified and a coordinate list is used then the units of +the coordinate list are selected. If a database entry exists then the +units defined there override both this parameter and the coordinate list. +.le +.ls interactive = yes (no|yes|NO|YES) +After automatically identifying the spectral lines and dispersion function +review and modify the solution interactively? If "yes" a query is given +for each spectrum providing the choice of interactive review. The +query may be turned off during execution. If "YES" the interactive review +is entered automatically without a query. The interactive, graphical +review is the same as the task \fBidentify\fR with a few restriction. +.le +.ls aidpars = "" (parameter set) +Parameter set for the automatic line identification algorithm. The +parameters are described in the help topic \fBaidpars\fR. +.le + +For two and three dimensional spectral images the following parameters are +used to select a one dimensional spectrum. +.ls section = "middle line" +If an image is not one dimensional or specified as a one dimensional image +section then the image section given by this parameter is used. The +section defines a one dimensional spectrum. The dispersion direction is +derived from the vector direction. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator which +is used with three dimensional data. Abbreviations are allowed though +beware that 'l' is not a sufficient abbreviation. +.le +.ls nsum = "1" +Number of lines, columns, or bands across the designated dispersion axis to +be summed when the image is a two or three dimensional image. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. +.le + +The following parameters are used in finding spectral lines. +.ls ftype = "emission" +Type of spectral lines to be identified. The possibly abbreviated choices are +"emission" and "absorption". +.le +.ls fwidth = 4. +Full-width at the base (in pixels) of the spectral lines to be identified. +.le +.ls cradius = 5. +The maximum distance, in pixels, allowed between a line position +and the initial estimate when defining a new line. +.le +.ls threshold = 0. +In order for a line center to be determined the range of pixel intensities +around the line must exceed this threshold. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between line positions +when defining a new line. +.le +.ls match = -3. +The maximum difference for a match between the line coordinate derived from +the dispersion function and a coordinate in the coordinate list. Positive +values are in user coordinate units and negative values are in units of +pixels. +.le + +The following parameters are used to fit a dispersion function to the user +coordinates. The \fBicfit\fR routines are used and further descriptions +about these parameters may be found under that topic. +.ls function = "spline3" +The function to be fit to user coordinates as a function of the pixel +coordinates. The choices are "chebyshev", "legendre", "spline1", or "spline3". +.le +.ls order = 1 +Order of the fitting function. The order is the number of polynomial +terms (coefficients) or the number of spline pieces. +.le +.ls sample = "*" +Sample regions for fitting specified in pixel coordinates. +.le +.ls niterate = 10 +Number of rejection iterations. +.le +.ls low_reject = 3.0, high_reject = 3.0 +Lower and upper residual rejection in terms of the RMS of the fit. +.le +.ls grow = 0 +Distance from a rejected point in which additional points are automatically +rejected regardless of their residuals. +.le + +The following parameters control the input and output. +.ls dbwrite = "yes" (no|yes|NO|YES) +Automatically write or update the database with the line identifications +and dispersion function? If "no" or "NO" then there is no database +output. If "YES" the results are automatically written to the database. +If "yes" a query is made allowing the user to reply with "no", "yes", "NO" +or "YES". The negative responses do not write to the database and the +affirmative ones do write to the database. The upper-case responses +suppress any further queries for any remaining spectra. +.le +.ls overwrite = yes +Overwrite previous solutions in the database? If there is a previous +solution for the spectrum being identified this parameter selects whether +to skip the spectrum ("no") or find a new solution ("yes"). In the later +case saving the solution to the database will overwrite the previous +solution. +.le +.ls database = "database" +Database for reading and writing the line identifications and +dispersion functions. +.le +.ls verbose = yes +Print results of the identification on the standard output? +.le +.ls logfile = "logfile" +Filename for recording log information about the identifications. +The null string, "", may be specified to skip recording the log information. +.le +.ls plotfile = "" +Filename for recording log plot information as IRAF metacode. A +null string, "", may be specified to skip recording the plot information. +(Plot output is currently not implemented.) +.le +.ls graphics = "stdgraph" +Graphics device for the interactive review. The default is the standard +graphics device which is generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file for the interactive review. If a cursor file is not +given then the standard graphics cursor is read. +.le + +.ls query +Parameter used by the program to query the user. +.le +.ih +DESCRIPTION +\fBAutoidentify\fR automatically identifies spectral lines from a list of +spectral line coordinates (\fIcoordlist\fR) and determines a dispersion +function. The identified lines and the dispersion function may be reviewed +interactively (\fIinteractive\fR) and the final results are recorded in a +\fIdatabase\fR. + +Each image in the input list (\fIimages\fR) is considered in turn. If the +image is not one dimensional or a one dimensional section of an image then +the parameter \fIsection\fR is used to select a one dimensional +spectrum. It defines the dispersion direction and central spatial +coordinate(s). If the image is not one dimensional or a set of one +dimensional spectra n multispec format then the \fInsum\fR parameter +selects the number of neighboring lines, columns, and bands to sum. + +This task is not intended to be used on all spectra in an image since in +most cases the dispersion functions will be similar though possibly with a +zero point shift. Once one spectrum is identified the others may be +reidentified with \fBreidentify\fR. + +The coordinate list of spectral lines often covers a much larger dispersion +range than the spectra being identified. This is true of the standard line +lists available in the "linelists$" directory. While the algorithm for +identifying the lines will often succeed with a large line list it is not +guaranteed nor will it find the solution quickly without additional +information. Thus it is highly desirable to provide the algorithm with +approximate information about the spectra. Generally this information is +known by the observer or recorded in the image header. + +As implied in the previous paragraph, one may use a +limited coordinate line list that matches the dispersion coverage of the +spectra reasonably well (say within 100% of the dispersion range). +This may be done with the \fIcoordlist\fR parameter or a second +coordinate list used only for the automatic search may be specified +with the parameter \fIaidpars.reflist\fR. This allows using a smaller +culled list of lines for finding the matching patterns and a large list +with weaker lines for the final dispersion function fit. + +The alternative to a limited list is to use the parameters \fIcrval\fR and +\fIcdelt\fR to specify the approximate coordinate range and dispersion +interval per pixel. These parameters may be given explicitly or by +specifying image header keywords. The pixel to which \fIcrval\fR refers is +specified by the parameter \fIaidpars.crpix\fR. By default this is INDEF +which means use the center of the spectrum. The direction in which the +dispersion coordinates increase relative to the pixel coordinates may be +specified by the \fIaidpars.cddir\fR parameter. The default is "unknown" +to search in either direction. + +The algorithm used to automatically identify the spectral lines and +find a dispersion function is described under the help topic +\fBaidpars\fR. This topic also describes the various algorithm +parameters. The default parameters are adequate for most data. + +The characteristics of the spectral lines to be found and identified are +set by several parameters. The type of spectral lines, whether "emission" +or "absorption", is set by the parameter \fIftype\fR. For arc-line +calibration spectra this parameter is set to "emission". The full-width +(in pixels) at the base of the spectral lines is set by the parameter +\fIfwidth\fR. This is used by the centering algorithm to define the extent +of the line profile to be centered. The \fIthreshold\fR parameter defines +a minimum contrast (difference) between a line peak and the neighboring +continuum. This allows noise peaks to be ignored. Finding the center of a +possible line begins with an initial position estimate. This may be an +interactive cursor position or the expected position from the coordinate +line list. The centering algorithm then searches for a line of the +specified type, width, and threshold within a given distance, specified by +the \fIcradius\fR parameter. These parameters and the centering algorithm +are described by the help topic \fBcenter1d\fR. + +To avoid finding the same line multiple times, say when there are two lines +in the line list which are blended into a single in the observation, the +\fIminsep\fR parameter rejects any new line position found within that +distance of a previously defined line. + +The automatic identification of lines includes matching a line position in +the spectrum against the list of coordinates in the coordinate line list. +The \fImatch\fR parameter defines how close the measured line position must +be to a coordinate in the line list to be considered a possible +identification. This parameter may be specified either in user coordinate +units (those used in the line list) by using a positive value or in pixels +by using a negative value. In the former case the line position is +converted to user coordinates based on a dispersion function and in the +latter the line list coordinate is converted to pixels using the inverse of +the dispersion function. + +The dispersion function is determined by fitting a set of pixel positions +and user coordinate identifications by least squares to a specified +function type. The fitting requires a function type, \fIfunction\fR, and +the order (number of coefficients or spline pieces), \fIorder\fR. +In addition the fitting can be limited to specified regions, \fIsample\fR, +and provide for the rejection of points with large residuals. These +parameters are set in advance and used during the automatic dispersion +function determination. Later the fitting may be modified interactively. +For additional discussion of these parameters see \fBicfit\fR. + +The output of this program consists of log information, plot information, +and the line identifications and dispersion function. The log information +may be appended to the file specified by the \fIlogfile\fR parameter +and printed to the standard output (normally the terminal) by +setting the \fIverbose\fR parameter to yes. This information consists +of a banner line, a line of column labels, and results for each spectrum. +For each spectrum the spectrum name, the number of spectral lines found, +the dispersion coordinate at the middle of the spectrum, the dispersion +increment per pixel, and the root-mean-square (RMS) of the residuals for +the lines used in the dispersion function fit is recorded. The units of +the RMS are those of the user (line list) coordinates. If a solution is +not found the spectrum name and a message is printed. + +The line identifications and dispersion function are written to the +specified \fIdatabase\fR. The current format of the database is described +in the help for \fIidentify\fR. If a database entry is already present for +a spectrum and the parameter \fIoverwrite\fR is "no" then the spectrum is +skipped and a message is printed to the standard output. After a solution +is found and after any interactive review (see below) the results may be +written to the database. The \fIdbwrite\fR parameter may be specified as +"no" or "NO" to disable writing to the database (and no queries will be +made), as "yes" to query whether to or not to write to the database, or as +"YES" to automatically write the results to the database with no queries. +When a query is given the responses may be "no" or "yes" for an individual +spectrum or "NO" or "YES" for all remaining spectra without further +queries. + +After a solution is found one may review and modify the line +identifications and dispersion function using the graphical functions of +the \fBidentify\fR task (with the exception that a new spectrum may not be +selected). The review mode is selected with the \fIinteractive\fR +parameter. If the parameter is "no" or "NO" then no interactive review +will be provided and there will be no queries either. If the parameter is +"YES" then the graphical review mode will be entered after each solution is +found without any query. If the parameter is "yes" then a query will be +made after a solution is found and after any log information is written to +the terminal. One may respond to the query with "no" or "yes" for an +individual spectrum or "NO" or "YES" for all remaining spectra without +further queries. For "yes" or "YES" the \fIidentify\fR review mode is +entered. To exit type 'q'. +.ih +EXAMPLES +1. The following example finds a dispersion solution for the middle column +of a long slit spectrum of a He-Ne-Ar arc spectrum using all the +interactive options. + +.nf + cl> autoid arc0022 6000 6 coord=linelists$henear.dat sec="mid col" + AUTOIDENITFY: NOAO/IRAF IRAFX valdes@puppis Thu 15:50:31 25-Jan-96 + Spectrum # Found Midpoint Dispersion RMS + arc0022[50,*] 50 5790. 6.17 0.322 + arc0022[50,*]: Examine identifications interactively? (yes): + arc0022[50,*]: Write results to database? (yes): yes +.fi + +2. The next example shows a non-interactive mode with no queries for +the middle fiber of an extracted multispec image. + +.nf + cl> autoid.coordlist="linelists$henear.dat" + cl> autoid a0003 5300 3.2 interactive- verbose- dbwrite=YES +.fi +.ih +REVISIONS +.ls AUTOIDENTIFY V2.11 +This task is new in this version. +.le +.ih +SEE ALSO +identify, reidentify, aidpars, linelists, center1d, icfit, gtools +.endhelp diff --git a/noao/onedspec/doc/bplot.hlp b/noao/onedspec/doc/bplot.hlp new file mode 100644 index 00000000..f2214b94 --- /dev/null +++ b/noao/onedspec/doc/bplot.hlp @@ -0,0 +1,201 @@ +.help bplot Mar92 noao.onedspec +.ih +NAME +bplot -- Plot spectra noninteractively using SPLOT +.ih +USAGE +bplot images [records] +.ih +PARAMETERS +.ls images +List of images to be plotted. These may be one dimensional, multiaperture, +long slit, or nonspectral images. +.le +.ls records (imred.irs and imred.iids only) +List of records to be appended to the input image root names when +using record number extension format. The syntax of this list is comma +separated record numbers or ranges of record numbers. A range consists of +two numbers separated by a hyphen. A null list may be used if no record +number extensions are desired. +.le +.ls apertures = "" +List of apertures/lines/columns to be plotted in each image. If +\fIapertures\fR is null all of the apertures/lines/columns will be plotted. +.le +.ls band = 1 +The band or plane of a three dimensional image to be plotted in each image. +.le +.ls graphics = "stdgraph" +Output graphics device. This may be one of "stdgraph", "stdplot", +"stdvdm", or the actual device name. +.le +.ls cursor = "onedspec$gcurval.dat" +File(s) containing cursor commands for the SPLOT task. +The files will be cycled sequentially. If there is more than one file +usually the number of files will agree with the number of apertures +for each image since otherwise different cursor/aperture pairings will +occur. The default is a file containing only the (q)uit command. +.le + +The following parameters are used in response to particular keystrokes. +In \fBsplot\fR they are query parameters but in \fBbplot\fR they are hidden +parameters. +.ls next_image = "" +In response to 'g' (get next image) this parameter specifies the image. +.le +.ls new_image = "" +In response to 'i' (write current spectrum) this parameter specifies the +name of a new image to create or existing image to overwrite. +.le +.ls overwrite = yes +Overwrite an existing output image? If set to yes it is possible to write +back into the input spectrum or to some other existing image. Otherwise +the user is queried again for a new image name. +.le +.ls spec2 = "" +When adding, subtracting, multiplying, or dividing by a second spectrum +('+', '-', '*', '/' keys in the 'f' mode) this parameter is used to get +the name of the second spectrum. +.le +.ls constant = 0. +When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode) +the parameter is used to get the constant. +.le +.ls wavelength = 0. +This parameter is used to get a dispersion coordinate value during deblending or +when changing the dispersion coordinates with 'u'. +.le +.ls linelist = "" +During deblending this parameter is used to get a list of line positions +and widths. +.le +.ls wstart = 0., wend = 0., dw = 0. +In response to 'p' (convert to a linear wavelength scale) these parameter +specify the starting wavelength, ending wavelength, and wavelength per pixel. +.le +.ls boxsize = 2 +In response to 's' (smooth) this parameter specifies the box size in pixels +to be used for the boxcar smooth +.le +.ih +DESCRIPTION +The spectra in the input image list are successively processed by the task +\fBsplot\fR with input supplied by the cursor parameter and the output sent +to the specified graphics device. The range of apertures and bands +specified by \fIapertures\fR and \fIbands\fR will be processed for each +image. In the \fBiids/irs\fR packages the record extension syntax is used +with input root names and a record number list. The hidden parameters from +\fBsplot\fR apply to this task. + +The cursor file(s) consists of line(s) of the form: + + [x y 1] key [command] + +where x and y are the position of the cursor (may be zero or absent if the +cursor position is irrelevant) and key is one of the keystrokes understood +by \fBsplot\fR. If the key is ":" then the \fIcolon\fR command string follows. +The default cursor file consists of the single line: + + 0 0 1 q + +If more than one cursor file is specified they are sequentially assigned to +each aperture and the list is repeated as needed. This allows the aperture +to be manipulated in differing ways. +.ih +EXAMPLES +1. To plot all of apertures of the multiaperture spectra indicated by the file +"nite1.lst" on the default plotter and run in the background: + +.nf + cl> bplot @nite1.lst graphics=stdplot & +.fi + +2. To preview the plots: + +.nf + cl> bplot @nite1.lst graphics=stdgraph +.fi + +3. To produce a histogram type plot about Balmer alpha for aperture 5 of +each spectrum with the IRAF banner suppressed: + +.nf + cl> type curfile + 6555 0 1 a + 6570 0 1 a + q + cl> splot.options="auto hist nosysid" + cl> splot.xmin=6555 + cl> splot.xmax=6570 + cl> bplot @nite1.lst apertures=5 cursor=curfile +.fi + +4. To produce plots with four spectra per page: + +.nf + cl> bplot @nite1.lst ... >G nite1.mc + cl> gkimosaic nite1.mc dev=stdplot +.fi + +The first command redirects the output of the graphics to the metacode +file nite1.mc. The task \fBgkimosaic\fR is used to make multiple plots +per page. Other tasks in the \fBplot\fR package may be used to +manipulate and redisplay the contents of the metacode file. + +5. To plot a list of apertures with a different cursor file for each aperture: + +.nf + cl> bplot @nite1.lst apertures=3,9,14 cursor=@nite1.cur +.fi + +In this case the file "nite1.cur" is assumed to be a list of +individual cursor file names, for instance: + +.nf + cur.03 + cur.09 + cur.14 +.fi + +that are in one to one correspondence with the range of apertures. +.ih +REVISIONS +.ls BPLOT V2.10.3 +The query parameters from SPLOT were added as hidden parameters in BPLOT +to allow use of those keys in a batch way. +.le +.ls BPLOT V2.10 +The \fIapertures\fR and \fIband\fR parameters been added to select +apertures from multiple spectra and long slit images, and bands from 3D +images. Since the task is a script calling \fBsplot\fR, the many revisions +to that task also apply. The version in the \fBirs/iids\fR packages +selects spectra using the record number extension syntax. +.le +.ih +BUGS +The cursor file command keystrokes cannot include any of the cursor +mode (CAPITALIZED) keys. This results from the implementation of +the cursor mode commands as external to both BPLOT and SPLOT. + +When first entered, SPLOT will always display an initial plot. BPLOT +calls SPLOT once for each aperture in each image and thus produces +N(apertures)*N(images) initial plots. The plots are not optional because +of the possible confusion a blank screen might cause an inexperienced +user. If the initial plots are unwanted they must be edited out of the +graphics stream. This can be done as follows, by directing the +graphics output of BPLOT to a metacode file and then using GKIEXTRACT +to remove only the desired plots from the metacode file: + +.nf + cl> bplot @nite1.lst cursor=curfile >G nite1.mc + cl> gkiextract nite1.mc 2x2 | gkimosaic dev=stdplot +.fi + +This assumes that curfile is designed to produce only one plot in +addition to the non-optional initial plot. In this case there will be +two plots per aperture per image and we extract every other plot starting +with the second (as encoded in the range string: "2x2"). +.ih +SEE ALSO +splot, specplot, slist, gkiextract, gkimosaic, implot, graph, ranges +.endhelp diff --git a/noao/onedspec/doc/calibrate.hlp b/noao/onedspec/doc/calibrate.hlp new file mode 100644 index 00000000..cf68ac29 --- /dev/null +++ b/noao/onedspec/doc/calibrate.hlp @@ -0,0 +1,195 @@ +.help calibrate Mar93 noao.onedspec +.ih +NAME +calibrate -- Apply extinction corrections and flux calibrations +.ih +USAGE +calibrate input output [records] +.ih +PARAMETERS +.ls input +List of input spectra to be calibrated. When using record format +extensions the root names are specified, otherwise full image names +are used. +.le +.ls output +List of calibrated spectra. If no output list is specified or if the +output name is the same as the input name then the calibrated spectra +replace the input spectra. When using record format extensions the output +names consist of root names to which the appropriate record number +extension is added. The record number extension will be the same as the +input record number extension. The output spectra are coerced to have +real datatype pixels regardless of the pixel type. +.le +.ls records (imred.irs and imred.iids only) +The set of record number extensions to be applied to each input and output +root name when using record number extension format. The syntax consists +of comma separated numbers or ranges of numbers. A range consists of +two numbers separated by a hyphen. This parameter is not queried +when record number formats are not used. +.le +.ls extinct = yes +Apply extinction correction if a spectrum has not been previously +corrected? When applying an extinction correction, an extinction file +is required. +.le +.ls flux = yes +Apply a flux calibration if a spectrum has not been previously calibrated? +When applying a flux calibration, sensitivity spectra are required. +.le +.ls extinction = <no default> +Extinction file for the observation. Standard extinction files +are available in the "onedstds$" directory. +.le +.ls observatory = ")_.observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. The default is a redirection to the +package parameter of the same name. The observatory may be one of the +observatories in the observatory database, "observatory" to select the +observatory defined by the environment variable "observatory" or the +parameter \fBobservatory.observatory\fR, or "obspars" to select the current +parameters in the \fBobservatory\fR task. See \fBobservatory\fR for +additional information. +.le +.ls ignoreaps = no +Ignore aperture numbers and apply a single flux calibration to all +apertures? Normally multiaperture instruments have separate sensitivity +functions for each aperture while long slit or Fabry-Perot data use a +single sensitivity function where the apertures are to be ignored. The +sensitivity spectra are obtained by adding the aperture number as an +extension to the sensitivity spectrum root name. When apertures are +ignored the specified sensitivity spectrum name is used without adding an +extension and applied to all input apertures. +.le +.ls sensitivity = "sens" +The root name for the sensitivity spectra produced by \fBsensfunc\fR. +Normally with multiaperture instruments, \fBsensfunc\fR will produce a +spectrum appropriate to each aperture with an aperture number extension. +If the apertures are ignored (\fIignoreaps\fR = yes) then the sensitivity +spectrum specified is used for all apertures and no aperture number is +appended automatically. +.le +.ls fnu = no +The default calibration is into units of flux per unit wavelength (F-lambda). +If \fIfnu\fR = yes then the calibrated spectrum will be in units of +flux per unit frequency (F-nu). +.le +.ls airmass, exptime +If the airmass and exposure time are not in the header nor can they be +determined from other keywords in the header then these query parameters +are used to request the airmass and exposure time. The values are updated +in the input and output images. +.le +.ih +DESCRIPTION +The input spectra are corrected for extinction and calibrated to a flux +scale using sensitivity spectra produced by the task \fBsensfunc\fR. +One or both calibrations may be performed by selecting the appropriate +parameter flags. It is an error if no calibration is specified. Normally +the spectra should be extinction corrected if also flux calibrating. +The image header keywords DC-FLAG (or the dispersion type field in the +"multispec" world coordinate system), EX-FLAG, and CA-FLAG are checked for +dispersion solution (required), previous extinction correction, and +previous flux calibration. If previously calibrated the spectrum is +skipped and a new output image is not created. + +The input spectra are specified by a list of root names (when using record +extension format) or full image names. The output calibrated spectra may +replace the input spectra if no output spectra list is specified or if the +output name is the same as the input name. When using record number +extensions the output spectra will have the same extensions applied to the +root names as those used for the input spectra. + +When applying an extinction correction the AIRMASS keyword is sought. +If the keyword is not present then the airmass at the time defined +by the other header keywords is computed using the +latitude of the observatory and observation parameters in the image +header. The observatory is first determined from the image under the +keyword OBSERVAT. If absent the observatory specified by the task +parameter "observatory" is used. See \fBobservatory\fR for further +details of the observatory database. If the air mass cannot be +determined an error results. Currently a single airmass is used +and no correction for changing extinction during the observation is +made and adjustment to the middle of the exposure. The task +\fBsetairmass\fR provides a correction for the exposure time to compute +an effective air mass. Running this task before calibration is +recommended. + +If the airmass is not in the header and cannot be computed then +the user is queried for a value. The value entered is then +recorded in both the input and output image headers. Also if +the exposure time is not found then it is also queried and +recorded in the image headers. + +The extinction correction is given by the factor + + 10. ** (0.4 * airmass * extinction) + +where the extinction is the value interpolated from the specified +extinction file for the wavelength of each pixel. After extinction +correction the EX-FLAG is set to 0. + +When applying a flux calibration the spectra are divided by the +aperture sensitivity which is represented by a spectrum produced by +the task \fBsensfunc\fR. The sensitivity spectrum is in units of: + + 2.5 * Log10 [counts/sec/Ang / ergs/cm2/sec/Ang]. + +A new spectrum is created in "F-lambda" units - ergs/cm2/sec/Angstrom +or "F-nu" units - ergs/cm2/sec/Hz. The sensitivity must span the range of +wavelengths in the spectrum and interpolation is used if the wavelength +coordinates are not identical. If some pixels in the spectrum being +calibrated fall outside the wavelength range of the sensitivity function +spectrum a warning message giving the number of pixels outside the +range. In this case the sensitivity value for the nearest wavelength +in the sensitivity function is used. + +Multiaperture instruments typically have +a separate aperture sensitivity function for each aperture. The appropriate +sensitivity function for each input spectrum is selected based on the +spectrum's aperture by appending this number to the root sensitivity function +spectrum name. If the \fIignoreaps\fR flag is set, however, the aperture +number relation is ignored and the single sensitivity spectrum (without +extension) is applied. +.ih +EXAMPLES +1. To flux calibrates a series of spectra replacing the input spectra by +the calibrated spectra: + + cl> calibrate nite1 "" + +2. To only extinction correct echelle spectra: + + cl> calibrate ccd*.ec.imh new//ccd*.ec.imh flux- + +3. To flux calibrate a long slit spectrum: + +.nf + cl> dispaxis = 2 + cl> calibrate obj.imh fcobj.imh +.fi +.ih +REVISIONS +.ls CALIBRATE V2.10.3 +This task was revised to operate on 2D and 3D spatial spectra; i.e. long +slit and Fabry-Perot data cubes. This task now includes the functionality +previously found in \fBlongslit.extinction\fR and \fBlongslit.fluxcalib\fR. + +A query for the airmass and exposure time is now made if the information +is not in the header and cannot be computed from other header keywords. +.le +.ls CALIBRATE V2.10 +This task was revised to operate on nonlinear dispersion corrected spectra +and 3D images (the \fBapextract\fR "extras"). The aperture selection +parameter was eliminated (since the header structure does not allow mixing +calibrated and uncalibrated spectra) and the latitude parameter was +replaced by the observatory parameter. The observatory mechanism insures +that if the observatory latitude is needed for computing an airmass and the +observatory is specified in the image header the correct calibration will +be applied. The record format syntax is available in the \fBirs/iids\fR +packages. The output spectra are coerced to have real pixel datatype. +.le +.ih +SEE ALSO +setairmass, standard, sensfunc, observatory, continuum +.endhelp diff --git a/noao/onedspec/doc/continuum.hlp b/noao/onedspec/doc/continuum.hlp new file mode 100644 index 00000000..6bb4e05e --- /dev/null +++ b/noao/onedspec/doc/continuum.hlp @@ -0,0 +1,263 @@ +.help continuum Mar92 noao.onedspec +.ih +NAME +continuum -- Continuum normalize spectra +.ih +USAGE +continuum input output +.ih +PARAMETERS +.ls input +Input spectra to be continuum normalized. These may be any combination +of echelle, multiaperture, one dimensional, long slit, and spectral +cube images. +.le +.ls output +Output continuum normalized spectra. The number of output spectra must +match the number of input spectra. \fBOutput\fR may be omitted if +\fBlistonly\fR is yes. +.le +.ls lines = "*", bands = "1" +A range specifications for the image lines and bands to be fit. Unspecified +lines and bands will be copied from the original. If the value is "*", all of +the currently unprocessed lines or bands will be fit. A range consists of +a first line number and a last line number separated by a hyphen. A +single line number may also be a range and multiple ranges may be +separated by commas. +.le +.ls type = "ratio" +Type of output spectra. The choices are "fit" for the fitted function, +"ratio" for the ratio of the input spectra to the fit, "difference" for +the difference between the input spectra and the fit, and "data" for +the data minus any rejected points replaced by the fit. +.le +.ls replace = no +Replace rejected points by the fit in the difference, ratio, and +data output types? +.le +.ls wavescale = yes +Wavelength scale the X axis of the plot? This option requires that the +spectra be wavelength calibrated. If \fBwavescale\fR is no, the plots +will be in "channel" (pixel) space. +.le +.ls logscale = no +Take the log (base 10) of both axes? This can be used when \fBlistonly\fR +is yes to measure the exponent of the slope of the continuum. +.le +.ls override = no +Override previously normalized spectra? If \fBoverride\fR is yes and +\fBinteractive\fR is yes, the user will be prompted before each order is +refit. If \fBoverride\fR is no, previously fit spectra are silently +skipped. +.le +.ls listonly = no +Don't modify any images? If \fBlistonly\fR is yes, the \fBoutput\fR +image list may be skipped. +.le +.ls logfiles = "logfile" +List of log files to which to write the power series coefficients. If +\fBlogfiles\fR = NULL (""), the coefficients will not be calculated. +.le +.ls interactive = yes +Perform the fit interactively using the icfit commands? This will allow +the parameters for each spectrum to be adjusted independently. A separate +set of the fit parameters (below) will be used for each spectrum and any +interactive changes to the parameters for a specific spectrum will be +remembered when that spectrum is fit in the next image. +.le +.ls sample = "*" +The ranges of X values to be used in the continuum fits. The units will vary +depending on the setting of the \fBwavescale\fR and \fBlogscale\fR +parameters. The default units are in wavelength if the spectra have +been dispersion corrected. +.le +.ls naverage = 1 +Number of sample points to combined to create a fitting point. +A positive value specifies an average and a negative value specifies +a median. +.le +.ls function = spline3 +Function to be fit to the spectra. The functions are +"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial), +"spline1" (linear spline), and "spline3" (cubic spline). The functions +may be abbreviated. The power series coefficients can only be +calculated if \fBfunction\fR is "legendre" or "chebyshev". +.le +.ls order = 1 +The order of the polynomials or the number of spline pieces. +.le +.ls low_reject = 2., high_reject = 0. +Rejection limits below and above the fit in units of the residual sigma. +.le +.ls niterate = 10 +Number of rejection iterations. +.le +.ls grow = 1. +When a pixel is rejected, pixels within this distance of the rejected pixel +are also rejected. +.le +.ls markrej = yes +Mark rejected points? If there are many rejected points it might be +desired to not mark rejected points. +.le +.ls graphics = "stdgraph" +Graphics output device for interactive graphics. +.le +.ls cursor = "" +Graphics cursor input. +.le +.ih +DESCRIPTION +A one dimensional function is fit to the continuum of spectra in a list of +echelle, multispec, or onedspec format images and then divided into the +spectrum to produce continuum normalized spectra. The first two formats +will normalize the spectra or orders (i.e. the lines) in each image. In +this description the term "spectrum" will refer to a line (in whatever +band) of an image while "image" will refer to all spectra in an image. The +parameters of the fit may vary from spectrum to spectrum within images and +between images. The fitted function may be a legendre polynomial, +chebyshev polynomial, linear spline, or cubic spline of a given order or +number of spline pieces. The output image is of pixel type real. + +The line/band numbers (for two/three dimensional images) are written to a +list of previously processed lines in the header keywords \fISFIT\fR and +\fISFITB\fR of the output image. A subsequent invocation of SFIT will only +process those requested spectra that are not in this list. This ensures +that even if the output image is the same as the input image that no +spectra will be processed twice and permits an easy exit from the task in +the midst of processing many spectra without losing any work or requiring +detailed notes. + +The points to be fit in each spectrum are determined by +selecting a sample of X values specified by the parameter \fIsample\fR +and taking either the average or median of the number of points +specified by the parameter \fInaverage\fR. The type of averaging is +selected by the sign of the parameter with positive values indicating +averaging, and the number of points is selected by the absolute value +of the parameter. The sample units will vary depending on the settings +of the \fBwavescale\fR and the \fBlogscale\fR parameters. Note that a +sample that is specified in wavelength units may be entirely outside +the domain of the data (in pixels) if some of the spectra are not +dispersion corrected. The syntax of the sample specification is a comma +separated, colon delimited list similar to the image section notation. +For example, the \fBsample\fR, "6550:6555,6570:6575" might be used to +fit the continuum near H-alpha. + +If \fIlow_reject\fR and/or \fIhigh_reject\fR are greater than zero the +sigma of the residuals between the fitted points and the fitted +function is computed and those points whose residuals are less than +\fI-low_reject\fR * sigma and greater than \fIhigh_reject\fR * sigma +are excluded from the fit. Points within a distance of \fIgrow\fR +pixels of a rejected pixel are also excluded from the fit. The +function is then refit without the rejected points. This rejection +procedure may be iterated a number of times given by the parameter +\fIniterate\fR. This is how the continuum is determined. + +If \fIreplace\fR is set then any rejected points from the fitting +are replaced by the fit in the data before outputing the difference, +ratio, or data. For example with replacing the difference will +be zero at the rejected points and the data output will be cleaned +of deviant points. + +A range specification is used to select the \fIlines\fR and \fIbands\fR to be +fit. These parameters may either be specified with the same syntax as the +\fBsample\fR parameter, or with the "hyphen" syntax used elsewhere in +IRAF. Note that a NULL range for \fBlines/bands\fR expands to \fBno\fR +lines, not to all lines. An asterisk (*) should be used to represent a +range of all of the image lines/bands. The fitting parameters (\fIsample, +naverage, function, order, low_reject, high_reject, niterate, grow\fR) +may be adjusted interactively if the parameter \fIinteractive\fR is +yes. The fitting is performed with the \fBicfit\fR package. The +cursor mode commands for this package are described in a separate help +entry under "icfit". Separate copies of the fitting parameters are +maintained for each line so that interactive changes to the parameter +defaults will be remembered from image to image. +.ih +PROMPTS +If several images or lines/bands are specified, the user is asked whether +to perform an interactive fit for each spectrum. The response +may be \fByes, no, skip, YES, NO\fR or \fBSKIP\fR. The meaning of each +response is: + +.nf + yes - Fit the next spectrum interactively. + no - Fit the next spectrum non-interactively. + skip - Skip the next spectrum in this image. + + YES - Interactively fit all of the spectra of + all of the images with no further prompts. + NO Non-interactively fit all chosen spectra of all images. + SKIP - This will produce a second prompt, "Skip what?", + with the choices: + + spectrum - skip this spectrum in all images + image - skip the rest of the current image + all - \fBexit\fR the program + This will \fBunlearn\fR the fit parameters + for all spectra! + cancel - return to the main prompt +.fi +.ih +EXAMPLES +1. To normalize all orders of the echelle spectrum for hd221170 + + cl> continuum hd221170.ec nhd221170.ec type=ratio + +Each order of the spectrum is graphed and the interactive options for +setting and fitting the continuum are available. The important +parameters are low_rejection (for an absorption spectrum), the function +type, and the order of the function; these fit parameters are +originally set to the defaults in the \fBcontinuum\fR parameter file. A +'?' will display a menu of cursor key options. Exiting with 'q' will +update the output normalized order for the current image and proceed to +the next order or image. + +The parameters of the fit for each order are initialized to the current +values the first time that the order is fit. In subsequent images, the +parameters for a order are set to the values from the previous image. +The first time an order is fit, the sample region is reset to the +entire order. Deleted points are ALWAYS forgotten from order to order +and image to image. + +2. To do several images at the same time + + cl> continuum spec*.imh c//spec*.imh + +Note how the image template concatenation operator is used to construct +the output list of spectra. Alternatively: + + cl> continuum @inlist @outlist + +where the two list files could have been created with the sections +command or by editing. + +3. To measure the power law slope of the continuum (fluxed data) + + cl> continuum uv.* type=ratio logscale+ listonly+ fun=leg order=2 +.ih +REVISIONS +.ls CONTINUUM V2.10.4 +The task was expanded to include fitting specified bands in 3D multispec +spectra. + +The task was expanded to include long slit and spectral cube data. +.le +.ls CONTINUUM V2.10 +This task was changed from a script based on \fBimages.fit1d\fR to a +task based on \fBsfit\fR. This provides for individual independent +continuum fitting in multiple spectra images and for additional +flexibility and record keeping. The parameters have been largely +changed. +.le +.ih +BUGS +The errors are not listed for the power series coefficients. + +Spectra that are updated when \fBlogscale\fR is yes are written with a +linear wavelength scale, but with a log normalized data value. + +Selection by aperture number is not supported. +.ih +SEE ALSO +sfit, fit1d, icfit, ranges +.endhelp diff --git a/noao/onedspec/doc/deredden.hlp b/noao/onedspec/doc/deredden.hlp new file mode 100644 index 00000000..862c441c --- /dev/null +++ b/noao/onedspec/doc/deredden.hlp @@ -0,0 +1,201 @@ +.help deredden Feb94 noao.onedspec +.ih +NAME +deredden -- Apply interstellar reddening correction +.ih +USAGE +deredden input output [records] value +.ih +PARAMETERS +.ls input +List of input spectra to be dereddened. When using record +format extensions the root names are specified, otherwise full +image names are used. +.le +.ls output +List of derreddened spectra. If no output list is specified then +the input spectra are modified. Also the output name may be +the same as the input name to replace the input spectra by the +calibrated spectra. When using record format extensions the +output names consist of root names to which the appropriate +record number extension is added. The record number extension +will be the same as the input record number extension. +.le +.ls records (imred.irs and imred.iids only) +The set of record number extensions to be applied to each input +and output root name when using record number extension +format. The syntax consists of comma separated numbers or +ranges of numbers. A range consists of two numbers separated +by a hyphen. This parameter is not queried when record number +formats are not used. +.le +.ls value +Extinction parameter value as selected by the type parameter. +This value may be a visual extinction, A(V), the color excess between +B and V, E(B-V), or the logarithmic H beta extinction. +These quantities are discussed further below. +.le +.ls R = 3.1 +The ratio of extinction at V, A(V), to color excess between B and V, E(B-V). +.le +.ls type = "E(B-V)" +The type of extinction parameter used. The values may be: +.ls A(V) +The absolute extinction at the V band at 5550 Angstroms. +.le +.ls E(B-V) +The color excess between the B and V bands. +.le +.ls c +The logarithmic H beta extinction. +.le +.le +.ls apertures = "" +List of apertures to be selected from input one dimensional spectra +to be calibrated. If no list is specified then all apertures are +corrected. The syntax is the same as the record number +extensions. This parameter is ignored for N-dimensional spatial +spectra such as calibrated long slit and Fabry-Perot data. +.le +.ls override = no, uncorrect = yes +If a spectrum has been previously corrected it will contain the header +parameter DEREDDEN. If this parameter is present and the override +parameter is no then a warning will be issued and no further correction +will be applied. The override parameter permits overriding this check. If +overriding a previous correction the \fIuncorrect\fR parameter determines +whether the spectra are first uncorrected to the original values before +applying the new correction. If \fIuncorrect\fR is yes then the image +header DEREDDEN parameter will refer to a correction from the original data +while if it is no then the new correction is differential and the keyword +will only reflect the last correction. When correcting individual spectra +separately in a multispectra image with different extinction parameters the +uncorrect parameter should be no. +.le +.ih +DESCRIPTION +The input spectra are corrected for interstellar extinction, or +reddening, using the empirical selective extinction function of +Cardelli, Clayton, and Mathis, \fBApJ 345:245\fR, 1989, (CCM). +The function is defined over the range 0.3-10 inverse microns +or 100-3333 nanometers. If the input data extend outside this +range an error message will be produced. + +The extinction function requires two parameters, the absolute extinction at +5550A, A(V), and the ratio, R(V), of this extinction to the color excess +between 4350A and 5550A, E(B-V). + +One of the input task parameters is R(V). If it is not known one +may use the default value of 3.1 typical of the average +interstellar extinction. The second input parameter is chosen by +the parameter \fItype\fR which may take the values "A(V)", "E(B-V)", or +"c". The value of the parameter is specified by the parameter +\fIvalue\fR. + +If A(V) is used then the CCM function can be directly evaluated. If +E(B-V) is used then A(V) is derived by: + +.nf +(1) A(V) = R(V) * E(B-V) +.fi + +For planetary nebula studies the logarithmic extinction at H beta, +denoted as c, is often determined instead of E(B-V). If this type +of input is chosen then A(V) is derived by: + +.nf +(2) A(V) = R(V) * c * (0.61 + 0.024 * c). +.fi + +This relation is based on the relation betwen E(B-V) and c computed +by Kaler and Lutz, \fBPASP 97:700\fR, 1985 to include corrections between +the monochromatic parameter c and the broadband parameter E(B-V). +In particular the function is a least squares fit to the values of +c and E(B-V) in Table III of the form: + +.nf +(3) E(B-V) = c * (A + B * c) +.fi + +The input spectra are specified by a list of root names (when using record +extension format) or full image names. They are required to be dispersion +corrected (DC-FLAG >= 0) and not previously corrected (DEREDDEN absent). +Spectra not satisfying these requirements are skipped with a warning. The +DEREDDEN flag may be overridden with the \fIoverride\fR parameter. This +may be done if different extinction parameters are required for different +spectra in the same multiple spectrum image or if a new correction is +to be applied. The \fIuncorrect\fR parameter determines whether the +previous correction is removed so that the final correction is relative +to the original data or if the new correction is differential on the +previous correction. Note that if applying separate corrections to +different spectra in a single multispectral image then override should +be yes and uncorrect should be no. + +A subset of apertures to be corrected may be selected from one dimensional +spectra with the \fIapertures\fR parameter. Long slit or other higher +dimensional spatially sampled spectra are treated as a unit. The output +calibrated spectra may replace the input spectra if no output spectra list +is specified or if the output name is the same as the input name. When +using record number extensions the output spectra will have the same +extensions applied to the root names as those used for the input spectra. + +Note that by specifying a negative extinction parameter this task may +be used to add interstellar extinction. +.ih +EXAMPLES +1. To deredden a spectrum with an extinction of 1.2 magnitudes at V: + +.nf + cl> deredden obj1.ms drobj1.ms 1.2 type=A +.fi + +2. To deredden a spectrum in place with a color excess of 0.65 and +and R(V) value of 4.5: + +.nf + cl> deredden obj2.ms obj2.ms R=4.5 + E(B-V): .65 +.fi + +3. To deredden a series of IRS planetary nebula spectra using the +H beta extinction in the irs package: + +.nf + cl> deredden pn12 drpn12 1-5,12-14 type=c + c: 1.05 +.fi + +4. To redden a spectrum: + +.nf + cl> deredden artspec artspec -1.2 type=A +.fi + +5. To deredden a long slit or Fabry-Perot spectrum either DISPAXIS +must be in the image header or be specified in the package parameters. +The summing parameters are ignored. + +.nf + cl> deredden obj1 drobj1 1.2 type=A +.fi +.ih +REVISIONS +.ls DEREDDEN V2.10.3 +Extended to operate on two and three dimensional spatial spectra such as +calibrated long slit and Fabry-Perot data. + +An option was added to allow a previous correction to be undone in order +to keep the DEREDDEN information accurate relative to the original +data. +.le +.ls DEREDDEN V2.10 +This task is new. +.le +.ih +NOTES +Since there can be only one deredding flag in multispectral images +one needs to override the flag if different spectra require different +corrections and then only the last correction will be recorded. +.ih +SEE ALSO +calibrate +.endhelp diff --git a/noao/onedspec/doc/dispcor.hlp b/noao/onedspec/doc/dispcor.hlp new file mode 100644 index 00000000..9e916e70 --- /dev/null +++ b/noao/onedspec/doc/dispcor.hlp @@ -0,0 +1,497 @@ +.help dispcor Oct92 noao.onedspec +.ih +NAME +dispcor -- Dispersion correct and resample spectra +.ih +USAGE +dispcor input output [records] +.ih +PARAMETERS +.ls input +List of input spectra or root names to be dispersion corrected. These may +be echelle or non-echelle spectra, the task will determine which from the +database dispersion functions. When using the record number extension +format, record number extensions will be appended to each root name in the +list. +.le +.ls output +List of dispersion corrected output spectra or root names. When using the +record number extension format, record number extensions will be appended +to each root name in the list. The output extension will be the same as +the input extension. If "no" output list is specified then the output +spectrum will replace the input spectrum after dispersion correction. +.le +.ls records (imred.irs and imred.iids only) +List of records or ranges of records to be appended to the input and output +root names when using record number extension format. The syntax of this +list is comma separated record numbers or ranges of record numbers. A +range consists of two numbers separated by a hyphen. A null list may be +used if no record number extensions are desired. This is a positional +query parameter only if the record format is specified. +.le +.ls linearize = yes +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 are not interpolated. +.le +.ls database = "database" +Database containing dispersion solutions created by \fBidentify\fR or +\fBecidentify\fR. If the spectra have been previous dispersion corrected +this parameter is ignored unless a new reference spectra are defined. +.le +.ls table = "" +Wavelength coordinate table or reference image. Elements in this optional +table or reference image override the wavelength coordinates given below +for specified apertures. See the DISCUSSION for additional information. +.le +.ls w1 = INDEF, w2 = INDEF, dw = INDEF, nw = INDEF +The starting wavelength, ending wavelength, wavelength interval per pixel, +and the number of pixels in the output spectra. Any combination of these +parameters may be used to restrict the wavelength coordinates of the output +spectra. If two or more have the value INDEF then suitable defaults based +on the number of input pixels and the wavelength range of the reference +dispersion solutions are used. These defaults may either come from all +spectra, all spectra of the same aperture, or individually for each +spectrum depending on the values of the \fIglobal\fR and \fIsamedisp\fR +parameters. Note that these parameters are specified in linear units even +if a logarithmic wavelength scale is selected. The conversion between +linear and logarithmic intervals between pixels is given below. These +values may be overridden for specified apertures by a wavelength table or +reference image. Otherwise these values apply to all apertures. +.le +.ls log = no +Transform to linear logarithmic wavelength coordinates? Linear logarithmic +wavelength coordinates have wavelength intervals which are constant +in the logarithm (base 10) of the wavelength. Note that if conserving flux +this will change the flux units to flux per log lambda interval. +Note that if the input spectra are in log sampling then \fIlog\fR=no will +resample back to linear sampling and \fIlog\fR=yes will resample keeping +the output spectra in log sampling. +.le +.ls flux = yes +Conserve the total flux during interpolation rather than the flux density? +If "no", the output spectrum is average of the input spectrum across each +output wavelength coordinate. This conserves flux density. If "yes" the +input spectrum is integrated over the extent of each output pixel. This +conserves the total flux. Note that in this case units of the flux will +change; for example rebinning to logarithmic wavelengths will produce flux +per log lambda. For flux calibrated data you most likely would not want to +conserve flux. +.le +.ls blank = 0. +Output value corresponding to points outside the range of the input +data. In other words, the out of bounds value. This only has an +effect when linearizing and the output spectral coordinates extend +beyond the input spectral range. +.le +.ls samedisp = no +Use the same dispersion parameters for all apertures? If yes then all +apertures in a single image will have the same dispersion parameters. +If the \fIglobal\fR parameter is all selected then all spectra in all +images will have the same dispersion paramters. This parameter +would not normally be used with echelle spectra where each order +has a different wavelength coverage. +.le +.ls global = no +Apply global wavelength defaults? Defaults for the INDEF wavelength +coordinate parameters are determined if two or less of the wavelength +parameters are specified. The defaults are based on the number of +pixels and the wavelengths of the first and last pixel as given by the +dispersion solution. If this parameter is "no" this is done +independently for each input spectrum. If this parameter is "yes" +then the maximum number of pixels and the minimum and maximum +wavelengths of all the input spectra or those of the same aperture are +used to provide defaults for the spectra. The parameter +\fIsamedisp\fR determines whether the global coordinates are over all +spectra or only those with the same aperture number. The global option +is used to have all the dispersion corrected spectra have the same +wavelength coordinates without actually specifying the wavelength +parameters. +.le +.ls ignoreaps = no +If a reference dispersion solution is not found for an aperture +use the first reference dispersion solution and ignore the aperture +number? If not ignoring the apertures all spectra must have a matching +aperture for the dispersion solution and the task aborts if this is +not the case. Ignoring the apertures avoids this abort and instead +the first dispersion solution is used. Note this parameter does not +mean ignore matches between reference and spectrum aperture numbers +but only ignore the aperture number if no matching reference is +found. + +Also if a reference table or image is given and \fIignoreaps\fR=yes +then the default dispersion parameters for any aperture not defined +by the table or image will be that of the first defined aperture. +This can still be overridden by giving explicit values for +\fIw1, w2, dw\fR and \fInw\fR. +.le +.ls confirm = no +Confirm the wavelength parameters for each spectrum? If \fIyes\fR +the wavelength parameters will be printed and the user will be asked +whether to accept them. If the parameters are not acceptable the +user will be queried for new values. The confirmation and parameter +changes are repeated until an acceptable set of parameters is obtained. +When the \fIglobal\fR parameter is \fIyes\fR changes to the wavelength +parameters will remain in effect until changed again. +.le +.ls listonly = no +List the dispersion coordinates only? If set then the dispersion coordinates +are listed but the spectra are not dispersion corrected. This may be used +to determine what the default wavelengths would be based on the dispersion +solutions. +.le +.ls verbose = yes +Print the dispersion function and coordinate assignments? +.le +.ls logfile = "" +Log file for recording the dispersion correction operations. If no file +name is given then no log information is recorded. +.le +.ih +DESCRIPTION +The dispersion coordinate systems of the input spectra are set or changed +in the output spectra. The output spectra may be the same as the input +spectra if no output spectra are specified or the output name is the +same as the input name. The input and output spectra are specified +by image templates or lists. In the \fBirs/iids\fR packages the +input and output spectra are specified as root names and the record +numbers are specified by the \fIrecord\fR parameter. The records are +given as a set of comma separate single numbers or ranges of hyphen +separated numbers. If no records are specified then the input and output +images are assumed to be full names. + +The dispersion coordinate system is defined either in the image header or +by dispersion functions in the specified database. To use reference +spectra dispersion functions they must first be assigned to the image with +\fBidentify (reidentify)\fR, \fBecidentify (ecreidentify)\fR, +\fBrefspectra\fR, or \fBhedit\fR. These tasks define the image header +keywords REFSPEC1, REFSPEC2, REFSHFT1, and REFSHFT2. The test which +determines whether to use the current dispersion coordinate system or +reference spectra dispersion solutions is the presence of the REFSPEC1 +keyword. Since it is an error to apply a dispersion function to data which +have already been dispersion corrected the any dispersion function keywords +are deleted after use and a record of them entered in sequential image +header keywords beginning with DCLOG. + +Dispersion functions are specified by one or both of the reference spectrum +image header keywords REFSPEC1 and REFSPEC2 containing the name of +calibration spectra with dispersion function solutions (either echelle +dispersion functions from \fBecidentify\fR or non-echelle dispersion +functions from \fBidentify\fR) in the database. There must be a dispersion +function for each aperture in the input spectrum unless the \fIignoreaps\fR +flag is set. If the flag is not set the task will abort if a matching +aperture is not found while if it is set spectra without a matching +aperture in the reference dispersion solutions will use the first +dispersion solution. Note that aperture number matching is done in both +cases and the \fIignoreaps\fR parameter only applies to non-matching +spectra. The common situation for using the \fIignoreaps\fR option is when +there is a single reference dispersion solution which is to be applied to a +number of spectra with different aperture numbers; hence effectively +ignoring the reference spectrum aperture number. + +If two reference spectra are specified the names may be followed by a +weighting factor (assumed to be 1 if missing). The wavelength of a pixel +is then the weighted averge of the wavelengths of the two dispersion +functions. The task \fBrefspectra\fR provides a number of ways to assign +reference spectra. Note, however, that these assignments may be made +directly using the task \fBhedit\fR or with some other task or script if +none of the methods are suitable. Also note that \fBidentify\fR and +\fBreidentify\fR add the REFSPEC1 keyword refering to the image itself +when a database entry is written. + +In addition to the one or two reference dispersion functions for each input +aperture there may also be image header keywords REFSHFT1 and REFSHFT2 +specifying reference spectra whose dispersion function zero point shifts +(the "shift" parameter in the database files) are to be applied to the +reference dispersion functions. The shifts from REFSHFT1 will be applied +to the dispersion functions from REFSPEC1 and similarly for the second +dispersion functions. The reference shifts need not be present for every +aperture in a multispectrum image. By default the mean shift from all the +reference apertures having a zero point shift is applied to all the +reference dispersion functions. If the REFSHFT keyword has the modifier +word "nearest" following the spectrum name then the shift from the nearest +aperture in spatial position (from the aperture extraction limits in the +original 2D spectrum as recorded in the 6th and 7th fields of the APNUM +keywords) is used for a particular input aperture. If the modifier word is +"interp" then the nearest two apertures are used to interpolate a zero +point shift spatially. + +The purpose of the reference shift keywords is to apply a wavelength zero +point correction to the reference dispersion functions determined from +separate arc calibration observations using a few apertures taken at the +same time as object observations. For example, consider multifiber +observations in which one or more fibers are assigned to arc lamps at the +same time the other fibers are used to observe various objects. The basic +dispersion reference, the REFSPEC keywords, will come from arc observations +taken through all the fibers. The arc fibers used during an object +observation are then calibrated against their corresponding fibers in the +arc calibration observations to determine a zero point shift. The REFSHFT +keywords will contain the name of the object spectrum itself and the shifts +from the simultaneous arc fibers will be interpolated spatially to the +nonarc object fibers and applied to the dispersion functions from the arc +calibrations for those fibers. + +The reference shift keywords are currently added with \fBhedit\fR and zero +point shifts computed with \fBidentify/reidentify\fR. The complexities of +this have been hidden in the multifiber \fBimred\fR instrument reduction +packages. The reference shift correction feature was added primarily for +use in those reduction packages. + +If the \fIlinearize\fR parameter is no the dispersion functions, weights, +and shifts are transferred from the database to the world coordinate system +keywords in the image header. Except for printing processing information +that is all that is done to the spectra. + +If the \fIlinearize\fR parameter is yes the spectra are interpolated to a +linear wavelength scale and the dispersion coordinate system in the header +is set apprpriately. A linear wavelength coordinate system is defined by a +starting wavelength, an ending wavelength, a wavelength interval per pixel, +and the number of pixels. These four parameters actually overspecify the +coordinate system and only three of these values are needed to define it. +The output coordinate system is specified by giving a set or subset of +these parameters using the parameters \fIw1\fR, \fIw2\fR, \fIdw\fR, and +\fInw\fR. + +When the \fIlog\fR option is used these parameters are still specified and +computed in non-log units but the effective interval per pixel is + +.nf + dw_log = (log10(w2) - log10(w1)) / (nw - 1) + dw_log = (log10(w1+dw*(nw-1)) - log10(w1)) / (nw - 1) +.fi + +In other words, the logarithmic interval divides the starting and ending +wavelength into the required number of pixels in log step. To avoid +confusion in this case it is best to specify the starting and ending +wavelengths (in non-log units) and the number of pixels. + +Note that if \fIlog\fR=yes the input spectra in either linear +or log sampling will be resampled to produces an output spectrum in +log sampling. Similarly, if \fIlog\fR=no the input spectra will +be resampled to linear sampling. This means that log sampled input +spectra will be resampled to linear sampling. + +Default values for any parameters which are not specified, by using the +value INDEF, are supplied based on the wavelengths of the first and last +pixel as given by the dispersion function and the number of pixels in the +input image. The defaults may either be determined separately for each +spectrum (\fIglobal\fR = \fIno\fR), from all spectra with the same aperture +(\fIglobal\fR = \fIyes\fR and \fIsamedisp\fR = \fIno\fR), or from all the +spectra (\fIglobal\fR = \fIyes\fR and \fIsamedisp\fR = \fIyes\fR). As +indicated, the parameter \fIsamedisp\fR determines whether defaults are +determined independently for each aperture or set the same for all +apertures. + +Another way to specify the wavelengths when there are many apertures is to +use a wavelength table or reference image. If an spectrum image name is +specified with the \fItable\fR parameter then the dispersion parameters for +each apertures are set to be the same as the reference spectrum. +Alternatively, a text file table consisting of lines containing an aperture +number, the starting wavelength, the ending wavelength, the wavelength +interval per pixel, and the number of output pixels may be specified. Any +of these values may be specified as INDEF (though usually the aperture +number is not). One way to view the wavelength table/reference spectrum is +that an entry in the wavelength table/reference spectrum overrides the +values of the parameters \fIw1\fR, \fIw2\fR, \fIdw\fR, and \fInw\fR, which +normally apply to all apertures, for the specified aperture. The +wavelength table is used to specify explicit independent values for +apertures. The global mechanism can supply independent values for the +INDEF parameters when the \fIsamedisp\fR parameter is no. + +If one wishes to verify and possibly change the defaults assigned, +either globally or individually, the \fIconfirm\fR flag may be set. The +user is asked whether to accept these values. By responding with no the +user is given the chance to change each parameter value. Then the new +parameters are printed and the user is again asked to confirm the +parameters. This is repeated until the desired parameters are set. When +the defaults are not global the changed parameters will not be used for the +next spectrum. When the global option is used any changes made are +retained (either for all apertures or independently for each aperture) +until changed again. + +When adjusting the wavelengths the user should specify which parameter is +free to change by entering INDEF. If none of the parameters are specified +as INDEF then those values which were not changed, i.e. by accepting the +current value, are the first to be changed. + +Once the wavelength scale has been defined the input spectrum is +interpolated for each output pixel. Output wavelengths outside the range +of the input spectrum are set to the value given by the \fIblank\fR parameter +value. The default interpolation function +is a 5th order polynomial. The choice of interpolation type is made +with the package parameter "interp". It may be set to "nearest", +"linear", "spline3", "poly5", or "sinc". Remember that this +applies to all tasks which might need to interpolate spectra in the +\fBonedspec\fR and associated packages. For a discussion of interpolation +types see \fBonedspec\fR. + +When it is desired to conserve total flux, particularly when the dispersion is +significantly reduced, the parameter \fIflux\fR is set to yes and the +output pixel value is obtained by integrating the interpolation function +across the wavelength limits of the output pixel. If it is set to no +then the flux density is conserved by averaging across the output pixel +limits. + +The input spectrum name, reference spectra, and the wavelength parameters +will be printed on the standard output if the \fIverbose\fR parameter is +set and printed to a log file if one is specified with the \fIlogfile\fR +parameter. If one wishes to only check what wavelengths will be determined +for the defaults without actually dispersion correcting the spectra the +\fIlistonly\fR flag may be set. + +Other tasks which may be used to change the dispersion coordinate system +are \fBscopy\fR, \fBspecshift\fR, and \fBsapertures\fR. +.ih +EXAMPLES +In the examples when the task is used in the IRS and IIDS packages, +shown with the "ir>" prompt the spectra have a record number extension +image name format and the records parameter must be specified. In +the other case shown with the "on>" prompt the records parameter is +not used. + +1. Dispersion correct spectra so that they have the same number of pixels +and the wavelengths limits are set by the reference spectra. + +.nf +ir> dispcor spec dcspec 9,10,447-448 +dcspec.0009: ap = 0, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 +dcspec.0010: ap = 1, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 +dcspec.0447: ap = 0, w1 = 5082.57, w2 = 6551.45, dw = 1.794, nw = 820 +dcspec.0448: ap = 1, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820 + +on> dispcor allspec.ms dcallspec.ms +dcallspec.ms: ap = 1, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 +dcallspec.ms: ap = 2, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 +dcallspec.ms: ap = 3, w1 = 5082.57, w2 = 6551.45, dw = 1.794, nw = 820 +dcallspec.ms: ap = 4, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820 +.fi + +2. Confirm and change assignments. + +.nf +on> dispcor spec* %spec%new%* confirm+ +new009: ap = 0, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 + Change wavelength coordinate assignments? (yes): + Starting wavelength (5078.8421234): 5070 + Ending wavelength (6550.535123): + Wavelength interval per pixel (1.79693812): + Number of output pixels (820): INDEF +new009: ap = 0, w1 = 5070., w2 = 6550.53, dw = 1.795, nw = 826 + Change wavelength coordinate assignments? (yes): no +new010: ap = 1, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 + Change wavelength coordinate assignments? (no): yes + Starting wavelength (5078.7071234): 5100 + Ending wavelength (6550.805123): 6500 + Wavelength interval per pixel (1.79987512): INDEF + Number of output pixels (820): INDEF +new010: ap = 1, w1 = 5100., w2 = 6500., dw = 1.797, nw = 780 + Change wavelength coordinate assignments? (yes): no +new447: ap = 0, w1 = 5082.57, w2 = 6551.45, dw = 1.793, nw = 820 + Change wavelength coordinate assignments? (yes): no +new448: ap = 1, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820 + Change wavelength coordinate assignments? (no): +.fi + +3. Confirm global assignments and do dispersion correction in place. +record format. + +.nf +ir> dispcor irs "" 9,10,447,448 confirm+ global+ samedisp+ +irs.0009: ap = 0, w1 = 5078.71, w2 = 6553.66, dw = 1.801, nw = 820 + Change wavelength coordinate assignments? (yes): + Starting wavelength (5078.7071234): 5100 + Ending wavelength (6553.664123): 6500 + Wavelength interval per pixel (1.80092412): + Number of output pixels (820): +irs.0009: ap = 0, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 + Change wavelength coordinate assignments? (yes): no +irs.0010: ap = 1, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 + Change wavelength coordinate assignments? (no): +irs.0447: ap = 0, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 + Change wavelength coordinate assignments? (no): +irs.0448: ap = 1, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 + Change wavelength coordinate assignments? (no): +.fi + +4. Make a nonlinear dispersion correction in place. + +.nf +on> dispcor spec* "" linearize=no verbose- logfile=logfile +.fi + +5. Apply a single dispersion solution to a set of record number format +images. + +ir> dispcor nite101 dcnite101 "1-10" ignore+ confirm- + +.ih +REVISIONS +.ls DISPCOR V2.12.3 +Added the blank parameter value. +.le +.ls DISPCOR V2.11.3 +Long slit and data cubes can be used with this task to either resample +using the existing WCS or to use a single dispersion function from +IDENTIFY. It uses the first one found. +.le +.ls DISPCOR V2.10.3 +Provision was added for IDENTIFY dispersion solutions consisting of +only a shift (as produced by the 'g' key in IDENTIFY or the refit=no +flag in REIDENTIFY) to be applied to previously LINEARIZED spectra. +Thus it is possible to use IDENIFY/REIDENTIFY to automatically +compute a zero point shift based on 1 or more lines and then shift +all the spectra to that zero point. + +DISPCOR will now allow multiple uses of IDENTIFY dispersion solutions +in a simple way with but with continuing protection against accidental +multiple uses of the same dispersion solutions. When a spectrum is +first dispersion corrected using one or more reference spectra keywords +the dispersion flag is set and the reference spectra keywords are moved to +DCLOGn keywords. If DISPCOR is called again without setting new +reference spectra keywords then the spectra are resampled (rebinned) +using the current coordinate system. If new reference spectra are set +then DISPCOR will apply these new dispersion functions. Thus the user +now explicitly enables multiple dispersion functions by adding +reference spectra keywords and DISPCOR eliminates accidental multiple +uses of the same dispersion function by renaming the reference +spectra. The renamed keywords also provide a history. + +The flux conservation option now computes an average across the +output pixel rather than interpolating to the middle of the output +pixel when \fIflux\fR is no. This preserves the flux density and +includes all the data; i.e. a coarse resampling will not eliminate +features which don't fall at the output pixel coordinates. + +Some additional log and verbose output was added to better inform the +user about what is done. + +Better error information is now printed if a database dispersion function +is not found. +.le +.ls DISPCOR V2.10 +This is a new version with many differences. It replaces the previous +three tasks \fBdispcor, ecdispcor\fR and \fBmsdispcor\fR. It applies both +one dimensional and echelle dispersion functions. The new parameter +\fIlinearize\fR selects whether to interpolate the spectra to a uniform +linear dispersion (the only option available previously) or to assign a +nonlinear dispersion function to the image without any interpolation. The +interpolation function parameter has been eliminated and the package +parameter \fIinterp\fR is used to select the interpolation function. The +new interpolation type "sinc" may be used but care should be exercised. +The new task supports applying a secondary zero point shift spectrum to a +master dispersion function and a spatial interpolation of the shifts when +calibration spectra are taken at the same time on a different region of the +same 2D image. The optional wavelength table may now also be an image to +match dispersion parameters. The \fIapertures\fR and \fIrebin\fR +parameters have been eliminated. If an input spectrum has been previously +dispersion corrected it will be resampled as desired. Verbose and log file +parameters have been added to log the dispersion operations as desired. +The record format syntax is available in the \fBirs/iids\fR packages. +.le +.ih +SEE ALSO +package, refspectra, scopy, specshift, sapertures +.endhelp diff --git a/noao/onedspec/doc/disptrans.hlp b/noao/onedspec/doc/disptrans.hlp new file mode 100644 index 00000000..d73a4cb4 --- /dev/null +++ b/noao/onedspec/doc/disptrans.hlp @@ -0,0 +1,193 @@ +.help disptrans Aug94 noao.onedspec +.ih +NAME +disptrans -- Transform dispersion units and apply air correction +.ih +USAGE +disptrans input output units +.ih +PARAMETERS +.ls input +List of dispersion calibrated input spectra to be dispersion transformed. +.le +.ls output +List of output dispersion transformed spectra. If given the input names +(or a null list), each input spectrum will be replaced by the transformed +output spectrum. +.le +.ls units +Output dispersion units. A wide range of dispersion units may be +specified and they are described in the UNITS section. +.le +.ls error = 0.01 +Maximum error allowed in the output dispersion transformation expressed +as a pixel error; that is, the equivalent pixel shift in the output +dispersion function corresponding to the maximum difference between +the exact transformation and the dispersion function approximation. +The smaller the allowed error the higher the order of dispersion +function used. +.le +.ls linearize = no +Resample the spectrum data to linear increments in the output dispersion +system? If no then the output dispersion function is stored in the +spectrum header and if yes the spectrum is resampled into the same +number of pixels over the same dispersion range but in even steps +of the output dispersion units. +.le +.ls verbose = yes +Print a log of each spectrum transformed to the standard output? +.le + +.ls air = "none" (none|air2vac|vac2air) +Apply an air to vacuum or vacuum to air conversion? It is the +responsibility of the user to know whether the input dispersion +is in air or vacuum units and to select the appropriate conversion. +The conversion types are "none" for no conversion, "air2vac" to +convert from air to vacuum, and "vac2air" to convert from vacuum +to air. +.le +.ls t = 15, p = 760, f = 4 +Temperature t in degrees C, pressure p in mmHg, and water vapour pressure f +in mmHg for the air index of refraction. +.le + +OTHER PARAMETERS + +.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 +.ih +DESCRIPTION +The dispersion function in the input spectra, y = f(x) where x is the +pixel coordinate and y is the input dispersion coordinate, is +transformed to y' = g(x) where y' is in the new dispersion units. This is done +by evaluating the input dispersion coordinate y at each pixel, applying an +air to vacuum or vacuum to air conversion if desired, and applying the +specified unit transformation y' = h(y). Since the transformations are +nonlinear functions and the output dispersion function must be expressed in +polynomial form, the function g(x) is determined by fitting a cubic spline +to the set of x and y' values. The lowest number of spline pieces is used +which satisfies the specified error. Note that this error is not a random +error but difference between the smooth fitted function and the smooth +dispersion function in the header. As a special case, the first +fit tried is a linear function. If this satisfies the error condition +then a simpler dispersion description is possible. Also this is +appropriate for dispersion units which are simply related by a +scale change such as Angstroms to nanometers or Hertz to Mev. + +The error condition is that the maximum difference between the exact or +analytic (the air/vacuum conversion is never exact) transformation and the +fitted function value at any pixel be less than the equivalent shift in +pixel coordinate evaluated at that point. The reason for using an error +condition in terms of pixels is that it is independent of the dispersion of +the spectra and the resolution of spectra is ultimately limited by the +pixel sampling. + +After the new dispersion function is determined the function is either +stored in the coordinate system description for the spectrum or used to +resample the pixels to linear increments in the output dispersion units. +The resampling is not done if the new dispersion function is already linear +as noted above. The sampling uses the mean value over the input spectrum +covered by an output spectrum pixel (it is flux per unit dispersion element +preserving as opposed to flux/counts preserving). The linear sampling +parameters are limited to producing the same number of output pixels as +input pixels over the same range of dispersion. If one wants to have more +control over the resampling then the \fIlinearize\fR parameter should be +set to no and the task \fBdispcor\fR used on the output spectrum. + +Note that an alternative to using this task is to do the original +dispersion calibration (based on calibration spectra) with IDENTIFY +and DISPCOR in the desired units. However, currently the standard +lines lists are in Angstroms. There are, however, linelists for +He-Ne-Ar, Th-Ar, and Th in vacuum wavelengths. +.ih +UNITS +The dispersion units are specified by strings having a unit type from the +list below along with the possible preceding modifiers, "inverse", to +select the inverse of the unit and "log" to select logarithmic units. For +example "log angstroms" to select the logarithm of wavelength in Angstroms +and "inv microns" to select inverse microns. The various identifiers may +be abbreviated as words but the syntax is not sophisticated enough to +recognized standard scientific abbreviations except for those given +explicitly below. + +.nf + angstroms - Wavelength in Angstroms + nanometers - Wavelength in nanometers + millimicrons - Wavelength in millimicrons + microns - Wavelength in microns + millimeters - Wavelength in millimeters + centimeter - Wavelength in centimeters + meters - Wavelength in meters + hertz - Frequency in hertz (cycles per second) + kilohertz - Frequency in kilohertz + megahertz - Frequency in megahertz + gigahertz - Frequency in gigahertz + m/s - Velocity in meters per second + km/s - Velocity in kilometers per second + ev - Energy in electron volts + kev - Energy in kilo electron volts + mev - Energy in mega electron volts + + nm - Wavelength in nanometers + mm - Wavelength in millimeters + cm - Wavelength in centimeters + m - Wavelength in meters + Hz - Frequency in hertz (cycles per second) + KHz - Frequency in kilohertz + MHz - Frequency in megahertz + GHz - Frequency in gigahertz + wn - Wave number (inverse centimeters) +.fi + +The velocity units require a trailing value and unit defining the +velocity zero point. For example to transform to velocity relative to +a wavelength of 1 micron the unit string would be: + +.nf + km/s 1 micron +.fi +.ih +AIR/VACUUM CONVERSION +The air to vacuum and vacuum to air conversions are obtained by multiplying +or dividing by the air index of refraction as computed from the +formulas in Allen's Astrophysical Quantities (p. 124 in 1973 edition). +These formulas include temperature, pressure, and water vapour terms +with the default values being the standard ones. +.ih +EXAMPLES +1. Convert a spectrum dispersion calibrated in Angstroms to electron +volts and resample to a linear sampling. + +.nf + cl> disptrans spec1 evspec1 ev linear+ + evspec1: Dispersion transformed to ev. +.fi + +2. Apply an air to vacuum correction to an echelle spectrum using the +default standard temperature and pressure. Don't resample but rather use +a nonlinear dispersion function. + +.nf + cl> disptrans highres.ec vac.ec angs air=air2vac + vac.ec: Dispersion transformed to angstroms in vacuum with + t = 15. C, p = 760. mmHg, f = 4. mmHg. +.fi +.ih +REVISIONS +.ls DISPTRANS V2.10.4 +New task with this release. +.le +.ih +SEE ALSO +dispcor, identify, scopy, dopcor +.endhelp diff --git a/noao/onedspec/doc/dopcor.hlp b/noao/onedspec/doc/dopcor.hlp new file mode 100644 index 00000000..6bcd0992 --- /dev/null +++ b/noao/onedspec/doc/dopcor.hlp @@ -0,0 +1,184 @@ +.help dopcor Jun94 noao.onedspec +.ih +NAME +dopcor -- Apply doppler correction +.ih +USAGE +dopcor input output redshift +.ih +PARAMETERS +.ls input +List of input spectra to be doppler corrected. +.le +.ls output +List of doppler corrected spectra. If no output list is specified then +the input spectra are modified. Also the output name may be +the same as the input name to replace the input spectra by the +calibrated spectra. +.le +.ls redshift +Redshift or radial velocity (km/s) to be removed? The spectra are corrected so +that the specified redshift is removed; i.e. spectra with a positive +velocity are shifted to shorter wavelengths and vice-versa. This parameter +may be either a number or an image header keyword with the desired redshift +or velocity value. An image header keyword may also have an initial minus +sign, '-', to specify the negative of a velocity or the redshift complement +(1/(1+z)-1) of a redshift. The choice between a redshift and a velocity is +made with the \fIisvelocity\fR parameter. +.le +.ls isvelocity = no +Is the value specified by the \fIredshift\fR parameter a velocity? If +no then the value is interpreted as a redshift and if it is yes then +it is interpreted as a physical velocity in kilometers per second. Note that +this is a relativistic velocity and not c*z! For nearby cosmological +velocities users should specify a redshift (z = v_cosmological / c). +.le +.ls add = no +Add doppler correction to existing correction in "multispec" spectra? +.le +.ls dispersion = yes +Apply a correction to the dispersion function? +.le +.ls flux = no +Apply a flux correction? +.le +.ls factor = 3 +Flux correction factor as a power of 1+z when applying a flux correction. +.le +.ls apertures = "" +List of apertures to be corrected. If none are specified then all apertures +are corrected. An aperture list consists of comma separated aperture +number or aperture number ranges. A range is hypen separated and may +include an interval step following the character 'x'. See \fBranges\fR +for further information. For N-dimensional spatial spectra such as +long slit and Fabry-Perot spectra this parameter is ignored. +.le +.ls verbose = no +Print corrections performed? The information includes the output image +name, the apertures, the redshift, and the flux correction factor. +.le +.ih +DESCRIPTION +The input spectra (as specified by the input image list and apertures) are +corrected by removing a specified doppler shift and written to the +specified output images. The correction is such that if the actual +shift of the observed object is specified then the corrected spectra +will be the rest spectra. The opposite sign for a velocity or the +redshift complement (1/(1+z)-1) may be used to add a doppler shift +to a spectrum. + +There are two common usages. One is to take spectra with high doppler +velocities, such as cosmological sources, and correct them to rest with +respect to the earth. In this case the measured redshift or velocity is +specified to "remove" this component. The other usage is to correct +spectra to heliocentric or local standard of rest. The heliocentric or LSR +velocities can be computed and entered in the image header with the task +\fBrvcorrect\fR. In this case it is tempting to again think you are +"removing" the velocity so that you specify the velocity as given in the +header. But actually what is needed is to "add" the computed standard of +rest velocity to the observed spectrum taken with respect to the telescope +to place the dispersion in the desired center of rest. Thus, in this case +you specify the opposite of the computed heliocentric or LSR velocity; i.e. +use a negative. + +The redshift or space velocity in km/s is specified either as a number or +as an image header keyword containing the velocity or redshift. If a +number is given it applies to all the input spectra while an image header +keyword may differ for each image. The latter method of specifying a +velocity is useful if velocity corrections are recorded in the image +header. See \fBrvcorrect\fR for example. + +The choice between a redshift and a space velocity for the \fIredshift\fR +parameter is made using the \fIisvelocity\fR parameter. If isvelocity=yes +then the header dispersion solution is modified according to the +relativistic Doppler correction: + + lambda_new = lamda_old * sqrt((1 + v/c)/(1 - v/c)) + +where v is the value of "redshift". If isvelocity=no, \fIredshift\fR is +interpreted as a cosmological redshift and the header dispersion solution +is modified to give: + + lambda_new = lamda_old * z + +where z is the value of "redshift" + +If the \fIadd\fR parameter is used and the image uses a "multispec" +format where the previous doppler factor is stored separately +then the new doppler factor is: + + znew = (1 + z) * (1 + zold) - 1 = z + zold + z * zold + +where z is the specified doppler factor, zold is the previous one, +and znew is the final doppler factor. If the \fIadd\fR parameter +is no then the previous correction is replaced by the new correction. +Note that for images using a linear or equispec coordinate system +the corrections are always additive since a record is not kept of +the previous correction. Also any flux correction is made based +on the specified doppler correction rather than znew. + +There are two corrections which may be made and the user selects one +or both of these. A correction to the dispersion function is selected +with the \fIdispersion\fR parameter. This correction is a term to be +applied to the dispersion coordinates defined for the image. \fIThe spectrum +is not resampled, only the dispersion coordinate function is affected\fR. +A correction to the flux, pixel values, is selected with the \fIflux\fR +parameter. This correction is only significant for cosmological redshifts. +As such the correction is dependent on a cosmological model as well as +whether a total flux or surface brightness is measured. To provide the +range of possible corrections the flux correction factor is defined by +the \fIfactor\fR parameter as the power of 1+z (where z is the +redshift) to be multiplied into the observed pixel values. + +A keyword DOPCORnn is added to the image header. The index starts from +01 and increments if multiple corrections are applied. The value of +the keywords gives the redshift applied, the flux factor if used, and +the apertures which were corrected. +.ih +EXAMPLES +1. To dispersion and flux correct a quasar spectrum with redshift of +3.2 to a rest frame: + +.nf + cl> dopcor qso001.ms qso001rest.ms 3.2 flux+ +.fi + +2. To correct a set of spectra (in place) to heliocentric rest the task +\fBrvcorrect\fR is used to set the VHELIO keyword using an observed +velocity of 0. Then: + +.nf + cl> dopcor *.imh "" -vhelio isvel+ +.fi + +3. To artificially add a redshift of 3.2 to a spectrum the complementary +redshift is computed: + +.nf + cl> = 1/(1+3.2)-1 + -0.76190476190476 + cl> dopcor artspec "" -0.762 flux+ +.fi +.ih +REVISIONS +.ls DOPCOR V2.10.3 +This task was extended to work on two and three dimensional spatial spectra +such as long slit and Fabry-Perot spectra. + +The \fIadd\fR parameter was added. +.le +.ls DOPCOR V2.10.3 +A keyword is added to log the correction applied. +.le +.ls DOPCOR V2.10.2 +A sign error in converting velocity to redshift was fixed. A validity +check on the velocities and redshifts was added. The documentation +was corrected and improved. +.le +.ls DOPCOR V2.10 +This task is new. +.le +.ih +SEE ALSO +ranges, rvcorrect +.endhelp diff --git a/noao/onedspec/doc/fitprofs.hlp b/noao/onedspec/doc/fitprofs.hlp new file mode 100644 index 00000000..ed21e7b1 --- /dev/null +++ b/noao/onedspec/doc/fitprofs.hlp @@ -0,0 +1,403 @@ +.help fitprofs Mar92 noao.onedspec +.ih +NAME +fitprofs -- Fit 1D profiles to features in image vectors +.ih +USAGE +fitprofs input +.ih +PARAMETERS +.ls input +List of input images to be fit. The images may be one dimensional +spectra (one or more spectra per image) or long slit spectra. Other +types of nonspectral images may also be used and for two dimensional +images the fitting direction will be determined from either the keyword +DISPAXIS in the image header or the \fIdispaxis\fR parameter. +.le +.ls lines = "" +List of lines, columns, or apertures to be selected from the input image +format. The default empty list, "", selects all vectors in the images. +The syntax is a list of comma separated numbers or ranges, where a range +is a pair of hyphen separated numbers. +.le +.ls bands = "" +List of bands for 3D images. The empty list, "", selects all bands. +.le +.ls dispaxis = ")_.dispaxis", nsum = ")_.nsum" +Parameters for defining vectors in 2D and 3D images. The +dispersion axis is 1 for line vectors, 2 for column vectors, and 3 for band +vectors. A DISPAXIS parameter in the image header has precedence over the +\fIdispaxis\fR parameter. The default values defer to the package +parameters of the same name. +.le + +The following are the fitting parameters. +.ls region = "" +Region of the input vectors to be fit specified as a pair of space +separated numbers. The coordinates are defined in terms of the linear +image header coordinate parameters. For dispersion corrected spectra this +is usually wavelength in Angstroms and for other data it is usually pixels. +A fitting region must be specified. +.le +.ls positions = "" +File of initial or fixed profile positions and (optional) peaks, profile +types, and widths. The +format consists of lines with one or more whitespace separated fields. +The fields are the position, peak relative to the continuum with +negative values being absorption, profile type of gaussian, lorentzian, +or voigt, and the gaussian and/or lorentzian full width at half maximum. +Trailing fields may be missing and fields to be set from default parameters +or the image data (the peak value) may be given as INDEF. +Comments and any additional columns are ignored. The positions and +widths are specified in the coordinate units of the image, usually +wavelength for dispersion corrected spectra and pixels otherwise. +.le +.ls background = "" +Background values defining the linear background. If not specified the +single pixel values nearest the fitting region endpoints are used. +Otherwise two whitespace separated values are expected. If a value is +a number then that is the background at the lower or upper end of the +fitting region (ordered in pixel space not wavelength). The special +values "avg(w1,w2,z)" or "med(w1,w2,z)" (note that there can be no +whitespace) may be specified, where w1 and w2 are dispersion values, and z +is a multiplier. This will take the average or median of pixels within the +specified range and multiply the result by the third argument. The +dispersion point used for that value in computing the linear background is +the average of the dispersion coordinates of the pixels used. +.le +.ls profile = "gaussian" (gaussian|lorentzian|voigt) +Default profile type to be fit when a profile type is not specified in +the positions file. The type are "gaussian", "lorentzian", or "voigt". +.le +.ls gfwhm = 20., lfwhm = 20. +Default gaussian and lorentzian full width at half maximum (FWHM). +These values are used for the initial and/or fixed width when they are +not specified in the position file. +.le +.ls fitbackground = yes +Fit the background? If "yes" a linear background across the fitting region +will be fit simultaneously with the profiles. If "no" the background will +be fixed. +.le +.ls fitpositions = "all" +Position fitting option. This may be "fixed" to fix all positions at their +initial values, "single" to fit a single shift to the positions while +keeping their separations fixed, or "all" to independently fit all the +positions. +.le +.ls fitgfwhm = "all", fitlfwhm = "all" +Profile width fitting options. These may be "fixed" to fix all widths +at their initial values, "single" to fit a single scale factor to the initial +widths, or "all" to independently fit all the widths. +.le + +The following parameters are used for error estimates as described +below in the ERROR ESTIMATES section. +.ls nerrsample = 0 +Number of samples for the error computation. A value less than 10 turns +off the error computation. A value of ~10 does a rough error analysis, a +value of ~50 does a reasonable error analysis, and a value >100 does a +detailed error analysis. The larger this value the longer the analysis +takes. +.le +.ls sigma0 = INDEF, invgain = INDEF +The pixel sigmas are modeled by the formula: + +.nf + sigma**2 = sigma0**2 + invgain * I +.fi + +where I is the pixel value and "**2" means the square of the quantity. If +either parameter is specified as INDEF or with a value less than zero then +no sigma estimates are made and so no error estimates for the measured +parameters is made. +.le + +The following parameters determine the output of the task. +.ls components = "" +All profiles defined by the position file are simultaneously fit but only +a subset of the fitted profiles may be selected for output. A profile +or component is identified by the order number in the position file; +i.e. the first entry in the position file is 1, the second is 2, etc. +The components to be output are specified by a range list. The empty +list, "", selects all profiles. +.le +.ls verbose = yes +Print fitting results and record of output images created on the +standard output (normally the terminal). +The fitting information is printed to the logfile so there is normally +no need to redirect this output. The output may be turned off when +the task is run as a background task. +.le +.ls logfile = "logfile" +Logfile for fitting results. If not specified the results will not be +logged. +.le +.ls plotfile = "plotfile" +File to contain plot output. The plots show the image vector with +overplots of the total fit, the individual components, and the residuals. +The plotfile may be examined and manipulated later with tools such as +\fBgkimosaic\fR. +.le +.ls output = "" +List of output images. If not specified then no output images are created. +If images are specified the list is matched with the input list. +.le +.ls option = "fit" (fit|difference) +Image output option. The choices are "fit" to output the fitted image +vector which is the sum of the fitted profiles (without a background), +or "difference" to output the data with the profiles subtracted. +.le +.ls clobber = no, merge = no +Clobber or modify any existing output images? If clobbering is not +enabled a warning is printed and any existing output images are not +modified. If clobbering is enabled then either new images are created +if merge is "no" or the new fits are merged with the existing images. +Merging is meaningful when only a subset of the input is fit such +as selected lines or apertures. +.le +.ih +DESCRIPTION +\fBFitprofs\fR fits one dimensional profile functions to image vectors +and outputs the fitting parameters, plots, and model or residual +image vectors. This is done noninteractively using a file of initial +profile positions and widths. Interactive profile fitting may be +done with the deblending option of \fBsplot\fR or +\fBstsdas.fitting.ngaussfit\fR. + +The input consists of images in a variety of formats. These include +all the spectral formats as well as standard images. For two dimensional +images (or the first 2D plane of higher dimensional images) either the +lines or columns may be fit with possible summing of adjacent lines or +columns to increase the signal-to-noise. A subset of the image apertures, +lines, or columns may be specified or all image vectors may be fit. + +The fitting parameters consist of a fitting region, a list of initial +positions, peaks, and widths, initial background endpoints, the fitting +function, and the parameters to be fit or constrained. The coordinates and +units used for the positions and widths are those defined by the standard +linear coordinate header parameters. For dispersion corrected spectra +these are generally wavelengths in Angstroms and otherwise they are +generally pixels. A fitting region must be specified by a pair of +numbers. + +The background parameter may be left empty to select the pixel values at +the endpoints of the fitting region for defining the initial linear +background. Or values at the endpoints of the fitting region may be given +explicitly in pixel space order (i.e. the first value is for the edge of +the fitting region which has smaller pixel coordinate0 Values can also be +computed from the data using the functions "avg(w1,w2)" or "med(w1,w2)" +where w1 and w2 are dispersion coordinates. The pixels in the specified +range are average or medianed and the dispersion point for the linear +background is the average of the dispersion coordinates of the pixels. + +The position list file consists of one or more columns. +The format of this file has +one or more columns. The columns are the wavelength, the peak value +(relative to the continuum with negative values being absorption), +the profile type (gaussian, lorentzian, or voigt), and the +gaussian and/or lorentzian FWHM. End columns may be missing +or INDEF values may be specified to use the default parameter +values (the profile and widths) or determine the peak from the data. +Below are examples of the file line formats + +.nf + wavelength + wavelength peak + wavelength peak (gaussian|lorenzian|voigt) + wavelength peak gaussian gfwhm + wavelength peak lorentzian lfwhm + wavelength peak voigt gfwhm + wavelength peak voigt gfwhm lfwhm + + 1234.5 <- Wavelength only + 1234.5 -100 <- Wavelength and peak + 1234.5 INDEF v <- Wavelength and profile type + 1234.5 INDEF g 12 <- Wavelength and gaussian FWHM +.fi + +where peak is the peak value, gfwhm is the gaussian FWHM, and lfwhm is +the lorentzian FWHM. This format is the same as used by \fBsplot\fR +and also by \fBartdata.mk1dspec\fR (except in the latter case the +peak is normalized to a continuum of 1). + +The profile parameters fit are the central position, the peak amplitude, +and the profile widths. The fitting may be constrained in number of ways. +The linear background may be fixed or simultaneously fit with the +profiles. The profile positions may be fixed, the relative separations +fixed but a single zero point shift fit, or all positions may be fit +simultaneously. The profile widths may also be fixed, the relative ratios +of the widths fixed while fitting a single scale factor, or all widths fit +simultaneously. The profile amplitudes are always fit. + +The fitting technique uses a nonlinear iterative Levenberg-Marquardt +algorithm to reduce the Chi-square of the fit. The execution time +increases rapidly with the number of profiles fit so there is an +effective limit to the number of profiles that can be fit at once. + +The output includes a number of formats. The fitted parameters are +recorded in a logfile (if specified) and printed on the standard +output (if the verbose flag is set). This output includes the date, +image vector, fitting parameters used, and a table of fitted or +derived quantities. The parameters included some quantities relevant to +spectral lines but others apply to any image data. The quantities are +the profile center, the background or continuum at the center of the +profile, the integral or flux of the profile (which is negative for +profiles below the background), the equivalent width, the profile peak +amplitude or core value, and the profile full width at half +maximum. Pure gaussian and lorentzian profiles will have one of +the widths set to zero while voigt profiles will have both values. + +Summary plots are recored in a plotfile (if specified). The plots +show the data with the total fit, individual profiles, and residuals +overplotted. The plotfile may be examined and printed using the +task \fBgkimosaic\fR as well as other tasks which interpret GKI metacode. + +The final output consists of images in the same format as the input. +The images may be of the total fit (sum of profiles without background) +or of the difference (residuals) of the data minus the model. +.ih +ERROR ESTIMATES +Error estimates may be computed for the fitted parameters. +This requires a model for the pixel sigmas. Currently this +model is based on a Poisson statistics model of the data. The model +parameters are a constant Gaussian sigma and an "inverse gain" as specified +by the parameters \fIsigma0\fR and \fIinvgain\fR. These parameters are +used to compute the pixel value sigma from the following formula: + +.nf + sigma**2 = sigma0**2 + invgain * I +.fi + +where I is the pixel value and "**2" means the square of the quantity. + +If either the constant sigma or the inverse gain are specified as INDEF or +with values less than zero then no noise model is applied and no error +estimates are computed. Also if the number of error samples is less than +10 then no error estimates are computed. Note that for processed spectra +this noise model will not generally be the same as the detector readout +noise and gain. These parameters would need to be estimated in some way +using the statistics of the spectrum. The use of an inverse gain rather +than a direct gain was choosed to allow a value of zero for this +parameters. This provides a model with constant uncertainties. + +The error estimates are computed by Monte-Carlo simulation. The model is +fit to the data (using the noise sigmas) and this model is used to describe +the noise-free spectrum. A number of simulations, given by the +\fInerrsample\fR, are created in which random Gaussian noise is added to +the noise-free spectrum based on the pixel sigmas from the noise model. +The model fitting is done for each simulation and the absolute deviation of +each fitted parameter to model parameter is recorded. The error estimate +for the each parameter is then the absolute deviation containing 68.3% of +the parameter estimates. This corresponds to one sigma if the distribution +of parameter estimates is Gaussian though this method does not assume +this. + +The Monte-Carlo technique automatically includes all effects of +parameter correlations and does not depend on any approximations. +However the computation of the errors does take a significant +amount of time. The amount of time and the accuracy of the +error estimates depend on how many simulations are done. A +small number of samples (of order 10) is fast but gives crude +estimates. A large number (greater than 100) is slow but gives +very good estimates. A compromise value of 50 is recommended +for many applications. + +.ih +EXAMPLES +1. The following example creates an artificial spectrum and fits it. +It requires the \fBartdata\fR and \fBproto\fR packages be loaded. + +.nf + cl> mk1dspec test slope=1 temp=0 lines=testlines nl=20 + cl> mknoise test rdnoise=10 poisson=yes + cl> fields testlines fields=1,3 > fitlines + cl> fitprofs test reg="4000 8000" pos=fitlines + # Jul 27 17:49 test - Ap 1: + # Nfit=20, background=YES, positions=all, gfwhm=all, lfwhm=all + # center cont flux eqw core gfwhm lfwhm + 6832.611 1363.188 -13461.8 9.875 -408.339 30.97 0. + 7963.674 1507.641 -8193.58 5.435 -395.207 19.48 0. + 5688.055 1217.01 -7075.11 5.814 -392.006 16.96 0. + 6831.3 1363.02 -7102.01 5.21 -456.463 14.62 0. + 7217.335 1412.323 -10110. 7.158 -427.797 22.2 0. + 6709.286 1347.437 -4985.06 3.7 -225.346 20.78 0. + 6434.317 1312.319 -7121.03 5.426 -342.849 19.51 0. + 6130.415 1273.506 -6164. 4.84 -224.146 25.83 0. + 4569.375 1074.138 -3904.6 3.635 -183.963 19.94 0. + 5656.645 1212.999 -8202.81 6.762 -303.617 25.38 0. + 4219.53 1029.458 -5161.64 5.014 -241.135 20.11 0. + 4551.424 1071.845 -3802.61 3.548 -139.39 25.63 0. + 4604.649 1078.643 -5539.15 5.135 -264.654 19.66 0. + 6966.557 1380.294 -11717.5 8.489 -600.581 18.33 0. + 4259.019 1034.501 -4280.38 4.138 -213.446 18.84 0. + 5952.958 1250.843 -8006.98 6.401 -318.313 23.63 0. + 4531.89 1069.351 -712.598 0.6664 -155.197 4.313 0. + 7814.418 1488.579 -2926.49 1.966 -164.891 16.67 0. + 5310.929 1168.846 -10132.2 8.669 -487.502 19.53 0. + 5022.948 1132.066 -7532.8 6.654 -325.594 21.73 0. + +.fi + +2. Suppose there is no obvious continuum level near the fitting +region but you want to specify a flat continuum level as the average +of pixels in a specified wavelength region. The background region +would be specified as + +.nf + background = "avg(4250,4425.3) avg(4250,4425.3)" +.fi + +Note that the value must be given twice to get a flat continuum. +.ih +REVISIONS +.ls FITPROFS V2.11.3 +Modified to allow a more general specification of the background. +.le +.ls FITPROFS V2.11 +Modified to include lorentzian and voigt profiles. The parameters and +positions file format have changed in this version. A new parameter +controls the number of Monte-Carlo samples used in the error estimates. +.le +.ls FITPROFS V2.10.3 +Error estimates based on a simple noise model are now computed. +.le +.ls FITPROFS V2.10 +This task is new. +.le +.ih +TIME REQUIREMENTS +The following CPU times were obtained with a Sun Sparcstation I. The +number of pixels in the fitting region and the number of lines fit +were varied. The worst case of fitting all parameters and a background +was considered as well as the constrained case of fitting line positions +and a single width with fixed background. + +.nf + Npixels Nprofs Fitbkg Fitpos Fitsig CPU(sec) + 100 5 yes all all 1.9 + 100 10 yes all all 3.3 + 100 15 yes all all 5.6 + 100 20 yes all all 9.0 + 512 5 yes all all 4.7 + 512 10 yes all all 10.0 + 512 15 yes all all 17.6 + 512 20 yes all all 27.8 + 1000 5 yes all all 8.0 + 1000 10 yes all all 18.0 + 1000 15 yes all all 31.8 + 1000 20 yes all all 50.2 + 1000 25 yes all all 72.8 + 1000 30 yes all all 100.2 + 512 5 no all single 2.8 + 512 10 no all single 5.3 + 512 15 no all single 8.6 + 512 20 no all single 12.8 +.fi + +Crudely this implies CPU time goes as the 1.4 power of the number of profiles +and the 0.75 power of the number of pixels. +.ih +SEE ALSO +splot, stsdas.fitting.ngaussfit +.endhelp diff --git a/noao/onedspec/doc/identify.hlp b/noao/onedspec/doc/identify.hlp new file mode 100644 index 00000000..fea7086c --- /dev/null +++ b/noao/onedspec/doc/identify.hlp @@ -0,0 +1,810 @@ +.help identify Jan96 noao.onedspec +.ih +NAME +identify -- Identify features in one dimensional image vectors +.ih +SUMMARY +Features are interactively marked in one dimensional image vectors. +The features may be spectral lines when the vector is a spectrum +or profile positions when the vector is a spatial cut. A function +may be fit to the user coordinates as a function of pixel coordinates. +This is primarily used to find dispersion functions for spectra +such as arc-line calibration spectra. The profile position measurements +are generally used for geometric calibrations. +.ih +USAGE +identify images +.ih +PARAMETERS +.ls images +List of images in which to identify features and fit coordinate functions. +.le +.ls section = "middle line" +If an image is not one dimensional or specified as a one dimensional image +section then the image section given by this parameter is used. The +section defines a one dimensional vector. The image is still considered to +be two or three dimensional. It is possible to change the data vector +within the program. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator +which is used with three dimensional data. See the example section for +examples of this syntax. Abbreviations are allowed though beware that 'l' +is not a sufficient abbreviation. +.le +.ls database = "database" +Database in which the feature data and coordinate functions are recorded. +.le +.ls coordlist = "linelists$idhenear.dat" +User coordinate list consisting of an list of line coordinates. A +comment line of the form "# units <units>", where <units> is one of the +understood units names, defines the units of the line list. If no units +are specified then Angstroms are assumed. Some standard line lists are +available in the directory "linelists$". The standard line lists are +described under the topic \fIlinelists\fR. +.le +.ls units = "" +The units to use if no database entry exists. The units are specified as +described in + +.nf + cl> help onedspec.package section=units +.fi + +If no units are specified and a coordinate list is used then the units of +the coordinate list are selected. If a database entry exists then the +units defined there override both this parameter and the coordinate list. +.le +.ls nsum = "10" +Number of lines, columns, or bands across the designated vector axis to be +summed when the image is a two or three dimensional spatial spectrum. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. +.le +.ls match = -3. +The maximum difference for a match between the feature coordinate function +value and a coordinate in the coordinate list. Positive values +are in user coordinate units and negative values are in units of pixels. +.le +.ls maxfeatures = 50 +Maximum number of the strongest features to be selected automatically from +the coordinate list (function 'l') or from the image data (function 'y'). +.le +.ls zwidth = 100. +Width of graphs, in user coordinates, when in zoom mode (function 'z'). +.le + +The following parameters are used in determining feature positions. +.ls ftype = "emission" +Type of features to be identified. The possibly abbreviated choices are +"emission" and "absorption". +.le +.ls fwidth = 4. +Full-width at the base (in pixels) of features to be identified. +.le +.ls cradius = 5. +The maximum distance, in pixels, allowed between a feature position +and the initial estimate when defining a new feature. +.le +.ls threshold = 0. +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following parameters are used to fit a function to the user coordinates. +The \fBicfit\fR package is used and further descriptions about these parameters +may be found under that package. +.ls function = "spline3" +The function to be fit to the user coordinates as a function of the pixel +coordinate. The choices are "chebyshev", "legendre", "spline1", or "spline3". +.le +.ls order = 1 +Order of the fitting function. The order is the number of polynomial terms +or number of spline pieces. +.le +.ls sample = "*" +Sample regions for fitting. This is in pixel coordinates and not the user +coordinates. +.le +.ls niterate = 0 +Number of rejection iterations. +.le +.ls low_reject = 3.0, high_reject = 3.0 +Lower and upper residual rejection in terms of the RMS of the fit. +.le +.ls grow = 0 +Distance from a rejected point in which additional points are automatically +rejected regardless of their residuals. +.le + +The following parameters control the input and output. +.ls autowrite = no +Automatically write or update the database? If "no" then when exiting the +program a query is given if the feature data and fit have been modified. +The query is answered with "yes" or "no" to save or not save the results. +If \fIautowrite\fR is "yes" exiting the program automatically updates the +database. +.le +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le + +The following parameters are queried when the 'b' key is used. +.ls crval, cdelt +These parameters specify an approximate coordinate value and coordinate +interval per pixel when the automatic line identification +algorithm ('b' key) is used. The coordinate value is for the +pixel specified by the \fIcrpix\fR parameter in the \fBaidpars\fR +parameter set. The default value of \fIcrpix\fR is INDEF which then +refers the coordinate value to the middle of the spectrum. By default +only the magnitude of the coordinate interval is used. Either value +may be given as INDEF. In this case the search for a solution will +be slower and more likely to fail. The values may also be given as +keywords in the image header whose values are to be used. +.le +.ls aidpars = "" (parameter set) +This parameter points to a parameter set for the automatic line +identification algorithm. See \fIaidpars\fR for further information. +.le +.ih +CURSOR KEYS +.ls ? +Clear the screen and print a menu of options. +.le +.ls a +Apply next (c)enter or (d)elete operation to (a)ll features +.le +.ls b +Identify features and find a dispersion function automatically using +the coordinate line list and approximate values for the dispersion. +.le +.ls c +(C)enter the feature nearest the cursor. Used when changing the position +finding parameters or when features are defined from a previous feature list. +.le +.ls d +(D)elete the feature nearest the cursor. (D)elete all features when preceded +by the (a)ll key. This does not affect the dispersion function. +.le +.ls e +Find features from a coordinate list without doing any fitting. This is +like the 'l' key without any fitting. +.le +.ls f +(F)it a function of the pixel coordinates to the user coordinates. This enters +the interactive function fitting package. +.le +.ls g +Fit a zero point shift to the user coordinates by minimizing the difference +between the user and fitted coordinates. The coordinate function is +not changed. +.le +.ls i +(I)nitialize (delete features and coordinate fit). +.le +.ls j +Go to the preceding line, column, or band in a 2D/3D or multispec image. +.le +.ls k +Go to the next line, column, or band in a 2D/3D or multispec image. +.le +.ls l +(L)ocate features in the coordinate list. A coordinate function must be +defined or at least two features must have user coordinates from which a +coordinate function can be determined. If there are features an +initial fit is done, then features are added from the coordinate list, +and then a final fit is done. +.le +.ls m +(M)ark a new feature using the cursor position as the initial position +estimate. +.le +.ls n +Move the cursor or zoom window to the (n)ext feature (same as +). +.le +.ls o +Go to the specified line, column, or band in a 2D/3D or multispec image. +For 3D images two numbers are specified. +.le +.ls p +(P)an to the original window after (z)ooming on a feature. +.le +.ls q +(Q)uit and continue with next image. +.le +.ls r +(R)edraw the graph. +.le +.ls s +(S)hift the fit coordinates relative to the pixel coordinates. The +user specifies the desired fit coordinate at the position of the cursor +and a zero point shift to the fit coordinates is applied. If features +are defined then they are recentered and the shift is the average shift. +The shift in pixels, user coordinates, and z (fractional shift) is printed. +.le +.ls t +Reset the current feature to the position of the cursor. The feature +is \fInot\fR recentered. This is used to mark an arbitrary position. +.le +.ls u +Enter a new (u)ser coordinate for the current feature. +When (m)arking a new feature the user coordinate is also requested. +.le +.ls v +Modify the fitting weight of the current feature. The weights are +integers with the lowest weight being the default of 1. +.le +.ls w +(W)indow the graph. A window prompt is given and a number of windowing +options may be given. For more help type '?' to the window prompt or +see help under \fIgtools\fR. +.le +.ls x +Find a zero point shift for the current dispersion function. This is used +by starting with the dispersion solution and features from a different +spectrum. The mean shift in user coordinates, mean shift in pixels, and +the fractional shift in user coordinates is printed. +.le +.ls y +Up to \fImaxfeatures\fR emission peaks are found automatically (in order of +peak intensity) and, if a dispersion solution is defined, the peaks are +identified from the coordinate list. +.le +.ls z +(Z)oom on the feature nearest the cursor. The width of the zoom window +is determined by the parameter \fIzwidth\fR. +.le +.ls . +Move the cursor or zoom window to the feature nearest the cursor. +.le +.ls 4 + +Move the cursor or zoom window to the (n)ext feature. +.le +.ls 4 - +Move the cursor or zoom window to the previous feature. +.le + +Parameters are shown or set with the following "colon commands", which may be +abbreviated. To show the value of a parameter type the parameter name alone +and to set a new value follow the parameter name by the value. +.ls :show file +Show the values of all the parameters. If a file name is given then the +output is appended to that file. If no file is given then the terminal +is cleared and the output is sent to the terminal. +.le +.ls :features file +Print the feature list and the fit rms. If a file name is given then the +output is appended to that file. If no file is given then the terminal +is cleared and the output is sent to the terminal. +.le +.ls :coordlist file +Set or show the coordinate list file. +.le +.ls :cradius value +Set or show the centering radius in pixels. +.le +.ls :threshold value +Set or show the detection threshold for centering. +.le +.ls :database name +Set or show the database for recording feature records. +.le +.ls :ftype value +Set or show the feature type (emission or absorption). +.le +.ls :fwidth value +Set or show the feature width in pixels. +.le +.ls :image imagename +Set a new image or show the current image. +.le +.ls :labels value +Set or show the feature label type (none, index, pixel, coord, user, or both). +None produces no labeling, index labels the features sequentially in order +of pixel position, pixel labels the features by their pixel coordinates, +coord labels the features by their user coordinates (such as wavelength), +user labels the features by the user or line list supplied string, and +both labels the features by both the user coordinates and user strings. +.le +.ls :match value +Set or show the coordinate list matching distance. +.le +.ls :maxfeatures value +Set or show the maximum number of features automatically found. +.le +.ls :minsep value +Set or show the minimum separation allowed between features. +.le +.ls :read name ap +Read a record from the database. The record name defaults to the image name +and, for 1D spectra, the aperture number defaults to aperture of +the current image. +.le +.ls :write name ap +Write a record to the database. The record name defaults to the image name +and, for 1D spectra, the aperture number defaults to aperture of +the current image. +.le +.ls :add name ap +Add features from a database record. The record name defaults to the image name +and, for 1D spectra, the aperture number defaults to aperture of +the current image. Only the features are added to any existing list +of features. The dispersion function is not read. +.le +.ls :zwidth value +Set or show the zoom width in user units. +.le +.ls :/help +Print additional help for formatting graphs. See help under "gtools". +.le +.ih +DESCRIPTION +Features in the input images are identified interactively and assigned +user coordinates. A "coordinate function" mapping pixel coordinates to +user coordinates may be determined from the identified features. A +user coordinate list may be defined to automatically identify additional +features. This task is used to measure positions of features, +determine dispersion solutions for spectra, and to identify features in +two and three dimensional images for mapping a two or three dimensional +coordinate transformation. Because of this dual use the terms vector +and feature are used rather than spectrum and spectral line. + +Each image in the input list is considered in turn. If the image is +not one dimensional or a one dimensional section of an image +then the image section given by the parameter +\fIsection\fR is used. This parameter may be specified in several ways as +described in the PARAMETERS and EXAMPLES sections. The image section is used +to select a starting vector and image axis. + +If the image is not one dimensional or in multispec format then the number +of lines, columns, or bands given by the parameter \fInsum\fR are summed. +The one dimensional image vector is graphed. The initial feature list and +coordinate function are read from the database if an entry exists. The +features are marked on the graph. The image coordinates are in pixels +unless a coordinate function is defined, in which case they are in user +coordinate units. The pixel coordinate, coordinate function value, and +user coordinate for the current feature are printed. + +The graphics cursor is used to select features and perform various +functions. A menu of the keystroke options and functions is printed +with the key '?'. The cursor keys and their functions are defined in +the CURSOR KEYS section and described further below. The standard +cursor mode keys are also available to window and redraw the graph and +to produce hardcopy "snaps". + +There are a number of ways of defining features. They fall into +two categories; interactively defining features with the cursor +and using automatic algorithms. + +The 'm' key is the principle interactive feature marking method. Typing +'m' near the position of a feature applies a feature centering algorithm +(see \fBcenter1d\fR) and, if a center is found, the feature is entered in +the feature list and marked on the spectrum. If the new position is within +a distance given by the parameter \fIminsep\fR of a previous feature it is +considered to be the same feature and replaces the old feature. Normally +the position of a new feature will be exactly the same as the original +feature. The coordinate list is searched for a match between the +coordinate function value (when defined) and a user coordinate in the +list. If a match is found it becomes the default user coordinate which the +user may override. The new feature is marked on the graph and it becomes +the current feature. The redefinition of a feature which is within the +minimum separation may be used to set the user coordinate from the +coordinate list. The 't' key allows setting the position of a feature to +other than that found by the centering algorithm. + +The principle automatic feature identification algorithm is executed +with the 'b' key. The user is queried for an approximate coordinate +value and coordinate interval per pixel. The coordinate value +is for the center of the spectrum by default though this may be changed +with the \fBaidpars\fR parameters. Only the magnitude of the +coordinate interval per pixel is used by default though this also +may be changed. Either value may be given as INDEF to do an unconstrained +search, however, this will be much slower and more likely to fail. +The algorithm searches for matches between the strong lines in the +spectrum and lines in the coordinate list. The algorithm is described +in the documentation for \fBaidpars\fR. + +The 'b' key works with no predefined dispersion solution or features. If +two or more features are identified, with 'm', spanning the range of the +data or if a coordinate function is defined, from a previous solution, then +the 'e', 'l', and 'y' keys may be used to identify additional features from +a coordinate list. The 'e' key only adds features at the coordinates of +the line lists if the centering algorithm finds a feature at that +wavelength (as described below). The 'y' key works in reverse by finding +the prominent features using a peak finding algorithm and then looking in +the coordinate list for entries near the estimated position. Up to a +maximum number of features (\fImaxfeatures\fR) will be selected. If there +are more peaks only the strongest are kept. In either of these cases there +is no automatic fitting and refitting of the dispersion function. + +The 'l' key combines automatic fits with locating lines from the coordinate +list. If two or more features are defined an initial fit is made. Then +for each coordinate value in the coordinate list the pixel coordinate is +determined and a search for a feature at that point is made. If a feature +is found (based on the parameters \fIftype, fwidth\fR, \fIcradius\fR, and +\fBthreshold\fR) its user coordinate value based on the coordinate function +is determined. If the coordinate function value matches the user +coordinate from the coordinate list within the error limit set by the +parameter \fImatch\fR then the new feature is entered in the feature list. +Up to a maximum number of features, set by the parameter \fImaxfeatures\fR, +may be defined in this way. A new user coordinate function is fit to all +the located features. Finally, the graph is redrawn in user coordinates +with the additional features found from the coordinate list marked. + +A minimum of two features must be defined for the 'l' key algorithm to +work. However, three or more features are preferable to determine changes +in the dispersion as a function of position. + +The 'f' key fits a function of the pixel coordinates to the user +coordinates. The type of function, order and other fitting parameters +are initially set with the parameters \fIfunction, order, sample, +niterate, low_reject, high_reject\fR and \fIgrow\fR.. The value of the +function for a particular pixel coordinate is called the function +coordinate and each feature in the feature list has a function +coordinate value. The fitted function also is used to convert pixel +coordinates to user coordinates in the graph. The fitting is done +within the interactive curve fitting package which has its own set of +interactive commands. For further information on this package see the +help material under \fBicfit\fR. + +If a zero point shift is desired without changing the coordinate function +the user may specify the coordinate of a point in the spectrum with +the 's' key from which a shift is determined. The 'g' key also +determines a shift by minimizing the difference between the user +coordinates and the fitted coordinates. This is used when a previously +determined coordinate function is applied to a new spectrum having +fewer or poorer lines and only a zero point shift can reasonably be +determined. Note that the zero point shift is in user coordinates. +This is only an approximate correction for shifts in the raw spectra +since these shifts are in pixels and the coordinate function should +also be appropriately shifted. + +One a set of features is defined one may select features for various +operations. To select feature as the current feature the keys '.', 'n', +'+', and '-' are used. The '.' selects the feature nearest the cursor, the +'n' and '+' select the next feature, and the '-' selects the previous +feature relative to the current feature in the feature list as ordered by +pixel coordinate. These keys are useful when redefining the user +coordinate with the 'u' key, changing the fitting weight of a feature with +'v', and when examining features in zoom mode. + +Features may be deleted with the key 'd'. All features are deleted +when the 'a' key immediately precedes the delete key. Deleting the +features does not delete the coordinate function. Features deleted in the +curve fitting package also are removed from the feature list upon +exiting the curve fitting package. + +It is common to transfer the feature identifications and coordinate function +from one image to another. When a new image without a database entry +is examined, such as when going to the next image in the input list, +changing image lines or columns with 'j', 'k' and 'o', or selecting +a new image with the ":image" command, the current feature list and coordinate +function are kept. Alternatively, a database record from a different +image may be read with the ":read" command. When transferring feature +identifications between images the feature coordinates will not agree exactly +with the new image feature positions and several options are available to +reregister the feature positions. The key 'c' centers the feature nearest +the cursor using the current position as the starting point. When preceded +with the 'a' key all the features are recentered (the user must refit +the coordinate function if desired). As an aside, the recentering +function is also useful when the parameters governing the feature +centering algorithm are changed. An additional options is the ":add" +command to add features from a database record. This does not overwrite +previous features (or the fitting functions) as does ":read". + +The (c)entering function is applicable when the shift between the current +and true feature positions is small. Larger shifts may be determined +automatically with the 's' or 'x' keys. + +A zero point shift is specified interactively with the 's' key by using the +cursor to indicate the coordinate of a point in the spectrum. If there are +no features then the shift is exactly as marked by the cursor. If there +are features the specified shift is applied, the features are recentered, +and the mean shift for all the features is determined. + +The 'x' key uses the automatic line identification algorithm (see +\fBaidpars\fR) with the constraint that the dispersion is nearly the +same and the is primarily a shift in the coordinate zero point. If +features are defined, normally by inheritance from another spectrum, then a +first pass is done to identify those features in the spectrum. Since this +only works when the shifts are significantly less than the dispersion range +of the spectrum (i.e. a significant number of features are in common) a +second pass using the full coordinate line list is performed if a shift +based on the features is not found. After a shift is found any features +remaining from the original list are recentered and a mean shift is +computed. + +In addition to the single keystroke commands there are commands initiated +by the key ':' (colon commands). As with the keystroke commands there are +a number of standard graphics features available beginning with ":." +(type ":.help" for these commands). The identify colon commands +allow the task parameter values to be listed and to be reset +within the task. A parameter is listed by typing its name. The colon command +":show" lists all the parameters. A parameter value is reset by +typing the parameter name followed by the new value; for example +":match 10". Other colon commands display the feature list (:features), +control reading and writing records to the database (:read and :write), +and set the graph display format. + +The feature identification process for an image is completed by typing +'q' to quit. Attempting to quit an image without explicitly +recording changes in the feature database produces a warning message +unless the \fIautowrite\fR parameter is set. If this parameter is +not set a prompt is given asking whether to save the results otherwise +the results are automatically saved. Also +the reference spectrum keyword REFSPEC is added to the image header at +this time. This is used by \fBrefspectra\fR and \fBdispcor\fR. +As an immediate exit the 'I' interrupt key may be used. This does not save +the feature information and may leave the graphics in a confused state. +.ih +DATABASE RECORDS +The database specified by the parameter \fIdatabase\fR is a directory of +simple text files. The text files have names beginning with 'id' followed +by the entry name, usually the name of the image. The database text files +consist of a number of records. A record begins with a line starting with the +keyword "begin". The rest of the line is the record identifier. Records +read and written by \fBidentify\fR have "identify" as the first word of the +identifier. Following this is a name which may be specified following the +":read" or ":write" commands. If no name is specified then the image name +is used. For 1D spectra the database entry includes the aperture number +and so to read a solution from a aperture different than the current image +and aperture number must be specified. For 2D/3D images the entry name +has the 1D image section which is what is specified to read the entry. +The lines following the record identifier contain +the feature information and dispersion function coefficients. + +The dispersion function is saved in the database as a series of +coefficients. The section containing the coefficients starts with the +keyword "coefficients" and the number of coefficients. + +The first four coefficients define the type of function, the order +or number of spline pieces, and the range of the independent variable +(the line or column coordinate along the dispersion). The first +coefficient is the function type code with values: + +.nf + Code Type + 1 Chebyshev polynomial + 2 Legendre polynomial + 3 Cubic spline + 4 Linear spline +.fi + +The second coefficient is the order (actually the number of terms) of +the polynomial or the number of pieces in the spline. + +The next two coefficients are the range of the independent variable over +which the function is defined. These values are used to normalize the +input variable to the range -1 to 1 in the polynomial functions. If the +independent variable is x and the normalized variable is n, then + +.nf + n = (2 * x - (xmax + xmin)) / (xmax - xmin) +.fi + +where xmin and xmax are the two coefficients. + +The spline functions divide the range into the specified number of +pieces. A spline coordinate s and the nearest integer below s, +denoted as j, are defined by + +.nf + s = (x - xmin) / (xmax - xmin) * npieces + j = integer part of s +.fi + +where npieces are the number of pieces. + +The remaining coefficients are those for the appropriate function. +The number of coefficients is either the same as the function order +for the polynomials, npieces+1 for the linear spline, or npieces + 3 +for the cubic spline. + +1. Chebyshev Polynomial + +The polynomial can be expressed as the sum + +.nf + y = sum from i=1 to order {c_i * z_i} +.fi + +where the c_i are the coefficients and the z_i are defined +interactively as: + +.nf + z_1 = 1 + z_2 = n + z_i = 2 * n * z_{i-1} - z_{i-2} +.fi + +2. Legendre Polynomial + +The polynomial can be expressed as the sum + +.nf + y = sum from i=1 to order {c_i * z_i} +.fi + +where the c_i are the coefficients and the z_i are defined +interactively as: + +.nf + z_1 = 1 + z_2 = n + z_i = ((2*i-3) * n * z_{i-1} - (i-2) * z_{i-2}) / (i-1) +.fi + +3. Linear Spline + +The linear spline is evaluated as + +.nf + y = c_j * a + c_{j+1} * b +.fi + +where j is as defined earlier and a and b are fractional difference +between s and the nearest integers above and below + +.nf + a = (j + 1) - s + b = s - j +.fi + +4. Cubic Spline + +The cubic spline is evaluated as + +.nf + y = sum from i=0 to 3 {c_{i+j} * z_i} +.fi + +where j is as defined earlier. The term z_i are computed from +a and b, as defined earlier, as follows + +.nf + z_0 = a**3 + z_1 = 1 + 3 * a * (1 + a * b) + z_2 = 1 + 3 * b * (1 + a * b) + z_3 = b**3 +.fi +.ih +EXAMPLES +1. Because this task is interactive and has many possible applications +it is difficult to provide actual examples. Instead some uses of the task +are described. + +.ls o +For defining distortions in the slit dimension as a function of +wavelength the positions of objects are marked at some wavelength. +The task \fBreidentify\fR is then used to trace the features to other +wavelengths. +.le +.ls o +For determining dispersion solutions in a one dimensional +spectrum an arc calibration is used. Three emission features are marked +and the (l)ocate key is used to find additional features from a +coordinate list of arc lines. The dispersion solution is fit interactively +and badly determined or misidentified lines are deleted. The +solution may be written to the database or transferred to the object +spectrum by reading the object image and deleting all the features. +Deleting the features does not delete the coordinate function. +.le +.ls o +For determining a two or three dimensional coordinate transformation a +dispersion solution is determined at one slit position in a long slit arc +spectrum or one spatial position in a Fabry-Perot spectrum as in the +previous example. The features are then traced to other positions with the +task \fBreidentify\fR. +.le + +2. For images which are two or three dimensional it is necessary to +specify the image axis for the data vector and the number of pixels at each +point across the vector direction to sum. One way specify a vector is to +use an image section to define a vector. For example, to select column +20: + +.nf + cl> identify obj[20,*] +.fi + +The alternative is to use the section parameter. Below are some examples +of the section parameter syntax for an image "im2d" which is 100x200 +and "im3d" which is 100x200x50. On the left is the section string syntax +and on the right is the image section + +.nf + Section parameter | Image section | Description + ------------------|---------------------|--------------------- + first line | im2d[*,1] | First image line + middle column | im2d[50,*] | Middle image column + last z | im3d[100,200,*] | Last image z vector + middle last y | im3d[50,*,50] | Image y vector + line 20 | im2d[*,20] | Line 20 + column 20 | im2d[20,*] | Column 20 + x 20 | im2d[*,20] | Line 20 + y 20 | im2d[20,*] | Column 20 + y 20 30 | im2d[20,*,30] | Column 20 + z 20 30 | im3d[20,30,*] | Image z vector + x middle | im3d[*,100,25] | Middle of image + y middle | im3d[50,*,25] | Middle of image + z middle | im3d[50,100,*] | Middle of image +.fi + +The most common usage should be "middle line", "middle column" or "middle z". + +The summing factors apply to the axes across the specified vector. For +3D images there may be one or two values. The following shows which axes +are summed, the second and third columns, when the vector axis is that shown +in the first column. + +.nf + Vector axis | Sum axis in 2D | Sum axes in 3D + ------------------|---------------------|-------------------- + 1 | 2 | 2 3 + 2 | 1 | 1 3 + 3 | - | 1 2 +.fi + +.ih +REVISIONS +.ls IDENTIFY V2.11 +The dispersion units are now determined from a user parameter, +the coordinate list, or the database entry. + +A new key, 'e', has been added to add features from a line list without +doing any fits. This is like the 'l' but without the automatic +fitting before and after adding new features. + +A new key, 'b', has been added to apply an automatic line identification +algorithm. + +The 'x' key has been changed to use the automatic line identification +algorithm. The allows finding much larger shifts. + +The match parameter may now be specified either in user coordinates or +in pixels. The default is now 3 pixels. + +The default threshold value has been changed to 0. +.le +.ls IDENTIFY V2.10.3 +The section and nsum parameter syntax was extended to apply to 3D +images. The previous values and defaults may still be used. + +The 'v' key was added to allow assigning weights to features. +.le +.ls IDENTIFY V2.10 +The principle revision is to allow multiple aperture images and long slit +spectra to be treated as a unit. New keystrokes allow jumping or scrolling +within multiple spectra in a single image. For aperture spectra the +database entries are referenced by image name and aperture number and not +with image sections. Thus, IDENTIFY solutions are not tied to specific +image lines in this case. There is a new autowrite parameter which may +be set to eliminate the save to database query upon exiting. The new +colon command "add" may be used to add features based on some other +spectrum or arc type and then apply the fit to the combined set of features. +.le +.ih +SEE ALSO +autoidentify, reidentify, aidpars, center1d, linelists, fitcoords, icfit, +gtools +.endhelp diff --git a/noao/onedspec/doc/lcalib.hlp b/noao/onedspec/doc/lcalib.hlp new file mode 100644 index 00000000..cc327217 --- /dev/null +++ b/noao/onedspec/doc/lcalib.hlp @@ -0,0 +1,125 @@ +.help lcalib Mar92 noao.onedspec +.ih +NAME +lcalib -- List information about the spectral calibration data +.ih +USAGE +lcalib option star_name +.ih +PARAMETERS +.ls option +Chooses calibration data to be listed. Option +may be: "bands" to list the bandpasses at each wavelength, "ext" to +list the extinction at each wavelength, "mags", "fnu", or "flam" +to list the magnitude, or flux of +the star (selected by the star_name parameter) at each wavelength, or +"stars" to list the star names available in the calibration directory. +.le +.ls star_name +Selects which star's magnitude list is chosen if the option parameter +is "mags", "fnu", "flam", or "bands". Also if '?' a list of available +stars in the specified calibration directory is given. +.le + +The following three queried parameters apply if the selected calibration +file is for a blackbody. See \fBstandard\fR for further details. +.ls mag +The magnitude of the observed star in the band given by the +\fImagband\fR parameter. If the magnitude is not in the same band as +the blackbody calibration file then the magnitude may be converted to +the calibration band provided the "params.dat" file containing relative +magnitudes between the two bands is in the calibration directory +.le +.ls magband +The standard band name for the input magnitude. This should generally +be the same band as the blackbody calibration file. If it is +not the magnitude will be converted to the calibration band. +.le +.ls teff +The effective temperature (deg K) or the spectral type of the star being +calibrated. If a spectral type is specified a "params.dat" file must exist +in the calibration directory. The spectral types are specified in the same +form as in the "params.dat" file. For the standard blackbody calibration +directory the spectral types are specified as A0I, A0III, or A0V, where A +can be any letter OBAFGKM, the single digit subclass is between 0 and 9, +and the luminousity class is one of I, III, or V. If no luminousity class +is given it defaults to dwarf. +.le + +.ls extinction +Extinction file. The current standard extinction files: +.nf + onedstds$kpnoextinct.dat - KPNO standard extinction + onedstds$ctioextinct.dat - CTIO standard extinction +.fi +.le +.ls caldir +Calibration directory containing standard star data. The directory name +must end with /. The current calibration directories available in the +onedstds$ may be listed with the command: + +.nf + cl> page onedstds$README +.fi +.le +.ls fnuzero = 3.68e-20 +The absolute flux per unit frequency at a magnitude of zero. This is used +to convert the calibration magnitudes to absolute flux by the formula + + Flux = fnuzero * 10. ** (-0.4 * magnitude) + +The flux units are also determined by this parameter. However, the +frequency to wavelength interval conversion assumes frequency in hertz. +The default value is based on a calibration of Vega at 5556 Angstroms of +3.52e-20 ergs/cm2/s/hz for a magnitude of 0.048. This default value +is that used in earlier versions of this task which did not allow the +user to change this calibration. +.le +.ih +DESCRIPTION +LCALIB provides a means of checking the flux calibration data. The calibration +data consists of extinction, bandpasses, and stellar magnitudes. + +The extinction is given in an extinction file consisting of lines with +wavelength and extinction. The wavelengths must be order in increasing +wavelength and the wavelengths must be in Angstroms. There are two +standard extinction files currently available, "onedstds$kpnoextinct.dat", +and "onedstds$ctioextinct.dat". + +The standard star data are in files in a calibration +directory specified with the parameter \fIcaldir\fR. A standard star +file is selected by taking the star name given, by the parameter +\fIstar_name\fR, removing blanks, +'s and -'s, appending ".dat", and converting +to lower case. This file name is appended to the specified calibration +directory. A calibration file consists of lines containing a wavelength, +a stellar magnitude, and a bandpass full width. The wavelengths are in +Angstroms. Comment lines beginning with # may be included in the file. +The star names printed by this task are just the first line of each file +in the calibration directory with the first character (#) removed. +The calibration files may be typed, copied, and printed. \fBLcalib\fR +may also be used to list data from the calibration files. +.ih +EXAMPLES + +.nf + # List the extinction table + cl> lcalib ext + # Plot the extinction table + cl> lcalib ext | graph + # Plot the energy distribution + cl> lcalib mags "bd+28 4211" | graph + # List the names of all the stars + cl> lcalib stars caldir=onedstds$irscal/ + # As above but for IIDS file + cl> lcalib stars calib_file=onedstds$iidscal/ +.fi +.ih +REVISIONS +.ls LCALIB V2.10 +This task has a more compact listing for the "stars" option and allows +paging a list of stars when the star name query is not recognized. +.le +.ih +SEE ALSO +standard, sensfunc, onedstds$README +.endhelp diff --git a/noao/onedspec/doc/mkspec.hlp b/noao/onedspec/doc/mkspec.hlp new file mode 100644 index 00000000..96efd726 --- /dev/null +++ b/noao/onedspec/doc/mkspec.hlp @@ -0,0 +1,86 @@ +.help mkspec Mar92 noao.onedspec +.ih +NAME +mkspec -- generate an artificial spectrum or image (obsolete) +.ih +USAGE +mkspec image_name image_title ncols nlines function +.ih +PARAMETERS +.ls image_name +The name to be given to the image file +.le +.ls image_title +A character string to be used to describe the image +.le +.ls ncols +The number of pixels in the spectrum (the length of the image). +.le +.ls nlines +The number or lines (rows) in the image. +.le +.ls function +An indicator specifying the form of the spectrum: 1 - a constant, +2 - a ramp running from start_level to end_level, 3 - a black body +extending in wavelength (Angstroms) from start_wave to end_wave +at a given temperature (in degrees K). +.le +.ls constant +The value to be assigned to the spectrum if function=1 (constant). +.le +.ls start_level +The starting value to be assigned to the spectrum at pixel 1 if +function=2 (ramp). +.le +.ls end_level +The ending value of the spectrum assigned at pixel=ncols if function=2. +.le +.ls start_wave +The wavelength (Angstroms) assigned to pixel 1 if function=3 (Black Body). +.le +.ls end_wave +The wavelength (Angstroms) assigned to the last pixel if function=3. +.le +.ls temperature +The black body temperature (degrees K) for which the spectrum +is to be created if function=3. +.le +.ih +DESCRIPTION +An artificial image is created with the specified name and length. +The image may have a constant value (function=1), or may be a ramp +with either positive or negative slope (function=2), or may be +a black body curve (function=3). + +Only those parameters specific to the functional form of the image +need be specified. In all cases the parameters image_name, image_title, +ncols, nlines, and function are required. If function=1, parameter constant +is required; if function=2, start_level and end_level are required; +if function=3, start_wave, end_wave, and temperature are required. + +All black body functions are normalized to 1.0 at their peak +intensity which may occur at a wavelength beyond the extent of +the generated spectrum. + +NOTE THAT THIS TASK IS OBSOLETE AND ARTDATA.MK1DSPEC SHOULD BE USED. +In particular this task does not set the header dispersion coordinate +system. +.ih +EXAMPLES + +.nf + cl> mkspec allones "Spectrum of 1.0" 1024 1 1 constant=1.0 + cl> mkspec ramp "From 100.0 to 0.0" 1024 64 2 start=100 \ + >>> end=0.0 + cl> mkspec bb5000 "5000 deg black body" 512 1 3 start=3000 \ + >>> end=8000 temp=5000 +.fi +.ih +REVISIONS +.ls MKSPEC V2.10 +This task is unchanged. +.le +.ih +SEE ALSO +artdata.mk1dspec, artdata.mk2dspec, artdata.mkechelle +.endhelp diff --git a/noao/onedspec/doc/names.hlp b/noao/onedspec/doc/names.hlp new file mode 100644 index 00000000..9004b20e --- /dev/null +++ b/noao/onedspec/doc/names.hlp @@ -0,0 +1,67 @@ +.help names Mar92 noao.onedspec +.ih +NAME +names -- Generate image names from a root and a range descriptor +.ih +USAGE +names input records +.ih +PARAMETERS +.ls input +The root file name for the input records to be calibrated. +.le +.ls records +The range of spectra to be included in the calibration operation. +Each range item will be appended to the root name to form an +image file name. +.le +.ls append = "" +If not a null string, this character string will be appended to +all the generated image names. This allows for a specification of +image sections. +.le +.ls check = no +If set to yes, a check is made that each name implied by the range +specification has at least an image header. The pixel file is not +checked. If set to no, then all possible image names are generated +even if no image exists. +.le +.ih +DESCRIPTION +A sequence of image names is generated from the input root file name +and the range description by appending the possible range values to +the root in the form "root.nnnn". At least four digits will follow the +root. + +If an append string is specified, this is added to the image name as well. + +The generated image names are written to STDOUT, but may be redirected +to a file for further use. +.ih +EXAMPLES +The following will generate names of the form nite1.0001, nite1.0002 ... +nite1.0010 and place the list in the file nite1.lst. + +.nf + cl> names nite1 1-10 >nite1.lst +.fi + +The next example uses the append option to specify that only the +first 512 pixels of each image (spectrum) are to used in the image name. + +.nf + cl> names nite1 1-10 append="[1:512]" >nite1.lst +.fi +.ih +REVISIONS +.ls NAMES V2.10 +This task is unchanged. +.le +.ih +.ih +BUGS +The append option is only useful for adding image sections since it is +added after the ONEDSPEC name is generated. Appending other strings +produces names such as root.0012str which are not recognized by +the package. +.endhelp diff --git a/noao/onedspec/doc/ndprep.hlp b/noao/onedspec/doc/ndprep.hlp new file mode 100644 index 00000000..6f59ba4b --- /dev/null +++ b/noao/onedspec/doc/ndprep.hlp @@ -0,0 +1,115 @@ +.help ndprep Mar92 noao.onedspec +.ih +NAME +ndprep -- Make a neutral density filter calibration image +.ih +USAGE +ndprep filter_curve output +.ih +PARAMETERS +.ls filter_curve +Neutral density filter curve. The directory specified by the parameter +\fIdirectory\fR is prepended to this name so if a directory is specified +then it should not be given here. If '?' a list of filter curves +in the specified directory is typed. +.le +.ls output +Output neutral density filter image. +.le +.ls w0 +Starting wavelength for the output image in Angstroms. +.le +.ls dw +Wavelength increment for the output image in Angstroms. +.le +.ls nw +Number of wavelength points for the output image (i.e. the size of the +output image). +.le +.ls nspace = 0 +Number of spatial points for a two dimensional image. If the value is +zero then a one dimensional image is created. +.le +.ls logarithm = no +Use logarithmic wavelengths and intervals? If yes then the wavelengths +will have the same starting and ending points and number of pixels but +the wavelength intervals will be logarithmic. +.le +.ls flux = yes +Conserve flux when rebinning to logarithmic wavelength intervals? +.le +.ls dispaxis = 1 +Dispersion axis for two dimensional images. Dispersion along the lines +is 1 and dispersion along the columns is 2. +.le +.ls directory = "onedstds$ctio/" +Directory containing neutral density filter curves. This directory is +prepended to the specified fiter curve file (and so must end with '/' +or '$'). +.le +.ih +DESCRIPTION +A neutral density (ND) filter curve is converted to a calibration image +with the same size and wavelength range as the images to be calibrated. +A list of standard neutral density curves is typed if the filter +curve name is given as '?'. The ND curves are text files containing +wavelength and filter transmission pairs. Comments begin with '#'. +A plot of the ND curve can be obtained using \fBgraph\fR. + +The ND curve is first interpolated to a one dimensional image of +\fInw\fR wavelength points with starting wavelength \fIwO\fR and +wavelength increment \fIdw\fR using the task \fBsinterp\fR. The +wavelength parameters must be in the same units as the filter curves +(currently Angstroms) even if the final calibration image is to be in +logarithmic wavelength intervals. If logarithmic wavelength format +is specified the image is rebinned over the same wavelength range with +the same number of points using the task \fBdispcor\fR. The rebinning +may include flux conservation to account for the changing size of +pixels or simply interpolate. Note that flux conservation will +change the apparent shape of the ND curve. + +If the number of points across the dispersion, \fInspace\fR is zero then +the final calibration image is one dimensional. If it is greater than +zero the one dimensional ND image is expanded to the specified number +of spatial points with the dispersion axis specified by the parameter +\fIdispaxis\fR (1 = dispersion along the lines, 2 = dispersion along +the columns). +.ih +EXAMPLES +To get a list of standard ND filter curves: + + cl> ndprep ? + +To graph the ND filter curve: + + cl> graph onedstds$ctio/nd1m.100mag.dat + +Naturally, if a calibration image is made then the image plotting tasks +such as \fBgraph\fR, \fBimplot\fR, and \fBsplot\fR may also be used. + +To make a one dimensional ND calibration spectrum: + +.nf + cl> ndprep w0=4000 dw=1.2 nw=512 + Input ND filter curve: onedstds$ctio/nd1m.100mag.dat + Output calibration image: NDimage +.fi + +To make a two dimensional ND calibration spectrum in logarithmic wavelength: + +.nf + cl> ndprep w0=4000 dw=1.2 nw=512 nspace=200 log+ + Input ND filter curve: onedstds$ctio/nd4m.u000mag.dat + Output calibration image: NDimage +.fi +.ih +REVISIONS +.ls NDPREP V2.10 +This task was moved from the \fBproto\fR package. It was originally +written at CTIO for CTIO data. It's functionality is largely unchanged +though it has been updated for changes in the \fBonedspec\fR package. +.le +.ih +SEE ALSO +sinterp, dispcor +.endhelp diff --git a/noao/onedspec/doc/odcombine.hlp b/noao/onedspec/doc/odcombine.hlp new file mode 100644 index 00000000..11ddffe5 --- /dev/null +++ b/noao/onedspec/doc/odcombine.hlp @@ -0,0 +1,480 @@ +.help odcombine Apr04 onedspec +.ih +NAME +odcombine -- Combine spectra using various algorithms +.ih +USAGE +odcombine input output +.ih +PARAMETERS +.ls input +List of input images containing spectra to be combined. The spectra +in the images to be combined are selected with the \fIapertures\fR and +\fIgroup\fR parameters. Only the primary spectrum is combined and +the associated band spectra are ignored. This task does not work on +higher dimensional spectra data. To apply it first use a task to +extract it to 1D spectra. The simplest method is \fBscopy\fR. +.le +.ls output +List of output images to be created containing the combined spectra. If +the grouping option is "all" then only one output image is created with the +specified name. If the grouping option is "images" then there will be one +output image for each input image and the output list must match the input +list in number. If the grouping option is "apertures" then only one output +root name is specified and there will be one output image for each selected +aperture. In this case the output images will have a name formed from the +root name and a four digit aperture number extension. In all cases the +output images contain a single 1D spectrum. Other tasks, such as +\fBscopy\fR, may be used to pack the spectra into a single file. +.le + + +There are a number of additional optional output files that may be produced. +The lists are handled in the same was as for the primary output; i.e. +depending on the grouping a single name, root name, or a matching list +is specified. +.ls headers = "" (optional) +Optional output multiextension FITS file(s). The extensions are dataless +headers from each input image. +.le +.ls bpmasks = "" (optional) +Optional output bad pixel mask(s) with good values of 0 and bad values of +1. Output pixels are marked as bad when no input pixels contributed to the +output pixel. The file name is also added to the output image header under +the keyword BPM. +.le +.ls rejmask = "" (optional) +Optional output mask file(s) identifying rejected or excluded pixels. The +pixel mask is the size of the output image but there is one extra dimension +with length equal to the number of input images. Each element of the +highest dimension is a mask corresponding to an input image with values of +1 for rejected or excluded pixels and values of 0 for pixels which were +used. The order of the masks is the order of the input images and image +header keywords, indexed by the pixel coordinate of the highest dimension +identify the input images. Note that the pixel positions are in the output +pixel coordinate system. +.le +.ls nrejmasks = "" (optional) +Optional output pixel mask(s) giving the number of input pixels rejected or +excluded from the input images. +.le +.ls expmasks = "" (optional) +Optional output exposure mask(s) giving the sum of the exposure values of +the input images with non-zero weights that contributed to that pixel. +Since masks are integer, the exposure values may be scaled to preserve +dynamic range and fractional significance. The scaling values are given in +the header under the keywords MASKSCAL and MASKZERO. Exposure values are +computed from the mask values by scale * value + zero where scale is the +value of the MASKSCAL keyword and zero is the value of the MASKZERO +keyword. +.le +.ls sigma = "" (optional) +Optional output sigma image(s). The sigma is the standard deviation, +corrected for a finite population, of the input pixel values (excluding +rejected pixels) about the output combined pixel values. +.le +.ls logfile = "STDOUT" (optional) +Optional output log file. If no file is specified then no log information is +produced. The special filename "STDOUT" prints log information to the +terminal. +.le + + +.ce +Grouping Parameters +.ls apertures = "" +List of apertures to be selected for combining. If none is specified +then all apertures are selected. The syntax is a blank or comma separated +list of aperture numbers or hypen separated aperture ranges. +.le +.ls group = "apertures" (all|images|apertures) +Option for grouping input spectra for combining (after selection by aperture) +from one or more input images. The options are: +.ls "all" +Combine all spectra from all images in the input list into a single output +spectrum. +.le +.ls "images" +Combine all spectra in each input image into a single spectrum in +separate output images. +.le +.ls "apertures" +Combine all spectra of the same aperture from all input images and put it +into an output image with specified root name and a four digit aperture +number extension. +.le +.le + + +.ce +Dispersion Matching Parameters +.ls first = no +Use the first input spectrum of each set to be combined to define the +dispersion coordinates for combining and output? If yes then all other +spectra to be combined will be interpolated to the dispersion of this +spectrum and that dispersion defines the dispersion of the +output spectrum. If no, then all the spectra are interpolated to a linear +dispersion as determined by the following parameters. The interpolation +type is set by the package parameter \fIinterp\fR. +.le +.ls w1 = INDEF, w2=INDEF, dw = INDEF, nw = INDEF, log = no +The output linear or log linear wavelength scale if the dispersion of the +first spectrum is not used. INDEF values are filled in from the maximum +wavelength range and minimum dispersion of the spectra to be combined. The +parameters are aways specified in linear wavelength even when the log +parameter is set to produce constant pixel increments in the log of the +wavelength. The dispersion is interpreted in that case as the difference +in the log of the endpoints divided by the number of pixel. +.le + + +.ce +Combining Parameters +.ls combine = "average" (average|median|sum) +Type of combining operation performed on the final set of pixels (after +offsetting, masking, thresholding, and rejection). The choices are +"average", "median", or "sum". The median uses the average of the two central +values when the number of pixels is even. For the average and sum, the +pixel values are multiplied by the weights (1 if no weighting is used) +and summed. The average is computed by dividing by the sum of the weights. +If the sum of the weights is zero then the unweighted average is used. +.le +.ls reject = "none" (none|minmax|ccdclip|crreject|sigclip|avsigclip|pclip) +Type of rejection operation performed on the pixels remaining after offsetting, +masking and thresholding. The algorithms are described in the +help page for \fBimcombine\fR. The rejection choices are: + +.nf + none - No rejection + minmax - Reject the nlow and nhigh pixels + ccdclip - Reject pixels using CCD noise parameters + crreject - Reject only positive pixels using CCD noise parameters + sigclip - Reject pixels using a sigma clipping algorithm + avsigclip - Reject pixels using an averaged sigma clipping algorithm + pclip - Reject pixels using sigma based on percentiles +.fi + +.le +.ls outtype = "real" (none|short|ushort|integer|long|real|double) +Output image pixel datatype. The pixel datatypes are "double", "real", +"long", "integer", unsigned short "ushort", and "short" with highest +precedence first. If "none" is specified then the highest precedence +datatype of the input images is used. When there is a mixture of +short and unsigned short images the highest precedence become integer. +The datatypes may be abbreviated to a single character. +.le +.ls outlimits = "" +Output region limits specified as a pair of whitespace separated pixel +values. +.le + + +.ce +Masking Parameters +.ls smaskformat = "bpmspectrum" (bpmspectrum|bpmpixel) +When a mask is applied it must be matched to the input spectrum. If the +value of this parameter is "bpmspectrum" the mask file is assumed to have a +spectral file structure with aperture and dispersion information. The mask +spectrum is matched to the input spectrum by aperture number and is +rebinned from its dispersion to match the rebinned dispersion of the input +spectrum. If the value is "bpmpixel" the mask file is assumed to have +minimal header information and the pixel information is matched to the +input image pixels. This means the mask pixels are extracted from the same +line as the input spectrum and the mask pixels are resampled in the same +way as the input spectrum pixels. +.le +.ls smasktype = "none" (none|goodvalue|badvalue|goodbits|badbit) +Type of pixel masking to use. If "none" or "" then no pixel masking is +done even if an image has an associated pixel mask. The other choices are +to select the value in the pixel mask to be treated as good (goodvalue) or +bad (badvalue) or the bits (specified as a value) to be treated as good +(goodbits) or bad (badbits). The pixel mask filename is specified by the +image header keyword "BPM". Note that if the input image contains +multiple spectra then the mask file must also contain at least the +selected apertures if the mask format is "bpmspectrum" or matching +image dimensions if the mask format is "bpmpixel". +.le +.ls maskvalue = 0 +Mask value used with the \fImasktype\fR parameter. If the mask type +selects good or bad bits the value may be specified using IRAF notation +for decimal, octal, or hexadecimal; i.e 12, 14b, 0cx to select bits 3 +and 4. +.le +.ls blank = 0. +Output value to be used when there are no pixels. +.le + + +.ce +Scaling/Weighting Parameters + +The following scaling and weighting parameters have the following behavior +and constraints, which are particularly relevant to multispec formats where +multiple spectra are contained in an image with a single image header. +When using image statistics these are calculated from the rebinned spectra +being combined as expected. When using header keywords the values will be +the same for all spectra from the same input file. + +When using a file then the list will be applied repeatedly to each +group being combined. If the grouping is by aperture then the values will +be matched in the order of the input images. Note that if an image does +not contain a specified aperture the ordering will be wrong. If the +grouping is by image then the file will be matched to the spectra in the +order of the apertures in the image. And if the grouping is "all" then the +list is matched in the order of the images and apertures within the +images with the apertures in an image varying first. + +.ls scale = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Multiplicative image scaling to be applied. The choices are none, multiply +by the reciprocal of the mode, median, or mean of the specified statistics +section, multiply by the reciprocal of the exposure time in the image header, +multiply by the values in a specified file, or multiply by a specified +image header keyword. When specified in a file the scales must be one per +line in the order of the input images. +.le +.ls zero = "none" (none|mode|median|mean|@<file>|!<keyword>) +Additive zero level image shifts to be applied. The choices are none, add +the negative of the mode, median, or mean of the specified statistics +section, add the values given in a file, or add the values given by an +image header keyword. When specified in a file the zero values must be one +per line in the order of the input images. File or keyword zero offset +values do not allow a correction to the weights. +.le +.ls weight = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Weights to be applied during the final averaging. The choices are none, +the mode, median, or mean of the specified statistics section, the exposure +time, values given in a file, or values given by an image header keyword. +When specified in a file the weights must be one per line in the order of +the input images and the only adjustment made by the task is for the number of +images previously combined. In this case the weights should be those +appropriate for the scaled images which would normally be the inverse +of the variance in the scaled image. +.le +.ls statsec = "" +Section of images to use in computing image statistics for scaling and +weighting. If no section is given then the entire region of the input is +sampled (for efficiency the images are sampled if they are big enough). +When the images are offset relative to each other one can precede the image +section with one of the modifiers "input", "output", "overlap". The first +interprets the section relative to the input image (which is equivalent to +not specifying a modifier), the second interprets the section relative to +the output image, and the last selects the common overlap and any following +section is ignored. +.le +.ls expname = "" +Image header keyword to be used with the exposure scaling and weighting +options. Also if an exposure keyword is specified that keyword will be +added to the output image using a weighted average of the input exposure +values. +.le + + +.ce +Algorithm Parameters +.ls lthreshold = INDEF, hthreshold = INDEF +Low and high thresholds to be applied to the input pixels. This is done +before any scaling, rejection, and combining. If INDEF the thresholds +are not used. +.le +.ls nlow = 1, nhigh = 1 (minmax) +The number of low and high pixels to be rejected by the "minmax" algorithm. +These numbers are converted to fractions of the total number of input images +so that if no rejections have taken place the specified number of pixels +are rejected while if pixels have been rejected by masking, thresholding, +or nonoverlap, then the fraction of the remaining pixels, truncated +to an integer, is used. +.le +.ls nkeep = 1 +The minimum number of pixels to retain or the maximum number to reject +when using the clipping algorithms (ccdclip, crreject, sigclip, +avsigclip, or pclip). When given as a positive value this is the minimum +number to keep. When given as a negative value the absolute value is +the maximum number to reject. The latter is in addition to pixels +missing due to non-overlapping offsets, bad pixel masks, or thresholds. +.le +.ls mclip = yes (ccdclip, crreject, sigclip, avsigcliip) +Use the median as the estimate for the true intensity rather than the +average with high and low values excluded in the "ccdclip", "crreject", +"sigclip", and "avsigclip" algorithms? The median is a better estimator +in the presence of data which one wants to reject than the average. +However, computing the median is slower than the average. +.le +.ls lsigma = 3., hsigma = 3. (ccdclip, crreject, sigclip, avsigclip, pclip) +Low and high sigma clipping factors for the "ccdclip", "crreject", "sigclip", +"avsigclip", and "pclip" algorithms. They multiply a "sigma" factor +produced by the algorithm to select a point below and above the average or +median value for rejecting pixels. The lower sigma is ignored for the +"crreject" algorithm. +.le +.ls rdnoise = "0.", gain = "1.", snoise = "0." (ccdclip, crreject) +CCD readout noise in electrons, gain in electrons/DN, and sensitivity noise +as a fraction. These parameters are used with the "ccdclip" and "crreject" +algorithms. The values may be either numeric or an image header keyword +which contains the value. The noise model for a pixel is: + +.nf + variance in DN = (rdnoise/gain)^2 + DN/gain + (snoise*DN)^2 + variance in e- = (rdnoise)^2 + (gain*DN) + (snoise*(gain*DN))^2 + = rdnoise^2 + Ne + (snoise * Ne)^2 +.fi + +where DN is the data number and Ne is the number of electrons. Sensitivity +noise typically comes from noise introduced during flat fielding. +.le +.ls sigscale = 0.1 (ccdclip, crreject, sigclip, avsigclip) +This parameter determines when poisson corrections are made to the +computation of a sigma for images with different scale factors. If all +relative scales are within this value of unity and all relative zero level +offsets are within this fraction of the mean then no correction is made. +The idea is that if the images are all similarly though not identically +scaled, the extra computations involved in making poisson corrections for +variations in the sigmas can be skipped. A value of zero will apply the +corrections except in the case of equal images and a large value can be +used if the sigmas of pixels in the images are independent of scale and +zero level. +.le +.ls pclip = -0.5 (pclip) +Percentile clipping algorithm parameter. If greater than +one in absolute value then it specifies a number of pixels above or +below the median to use for computing the clipping sigma. If less +than one in absolute value then it specifies the fraction of the pixels +above or below the median to use. A positive value selects a point +above the median and a negative value selects a point below the median. +The default of -0.5 selects approximately the quartile point. +See the DESCRIPTION section for further details. +.le +.ls grow = 0. +Radius in pixels for additional pixel to be rejected in an image with a +rejected pixel from one of the rejection algorithms. This applies only to +pixels rejected by one of the rejection algorithms and not the masked or +threshold rejected pixels. +.le + +The following parameters are internal to the task and not user parameters: + +.nf + offsets, masktype, maskvalue +.fi + +.ce +Environment Variables + +.ls <package>.interp +When the spectra have to be interpolated to a common pixel sampling +the "interp" parameter from the package from which ODCOMBINE is used +will be used. +.le +.ih +DESCRIPTION +\fBOdcombine\fR combines input spectra by interpolating them (if necessary) +to a common dispersion sampling, rejecting pixels exceeding specified low +and high thresholds or identified as bad in a bad pixel mask, scaling them +in various ways, applying a rejection algorithm based on known or empirical +noise statistics, and computing the sum, weighted average, or median of the +remaining pixels. Note that the "sum" option is the direct summation of +the pixels and does not perform any rejection or scaling of the data +regardless of the parameter settings. + +The input spectra are specified using an image list in which each image +may contain multiple spectra. The set of spectra may be restricted +by the \fIaperture\fR parameter to specific apertures. The set of input +spectra may then be grouped using the \fIgroup\fR parameter and each +group combined separately into final output spectra. The grouping +options are to select all the input spectra regardless of the input +image or aperture number, select all spectra of the same aperture, +or select all the spectra from the same input image. + +The output consists of one image for each combined group. The output +images and combined spectra inherit the header parameters from the first +spectrum in the combined group. There are a number of additional optional +outputs provided. The optional logfile lists parameters, the spectra +combined for each group, scaling, weights, etc., and the output names. + +The spectral combining is done using pixels at common dispersion +coordinates rather than physical or logical pixel coordinates. If the +spectra to be combined do not have identical dispersion coordinates then +the spectra are interpolated to a common dispersion sampling before +combining. The interpolation conserves pixel values rather pixel fluxes. +This means that flux calibrated data is treated correctly and that +spectra in counts are not corrected in the interpolation for changes in +pixel widths. The default interpolation function is a 5th order +polynomial. The choice of interpolation type is made with the package +parameter "interp". It may be set to "nearest", "linear", "spline3", +"poly5", or "sinc". Remember that this applies to all tasks which might +need to interpolate spectra in the \fBonedspec\fR and associated packages. +For a discussion of interpolation types see \fBonedspec\fR. + +There are two choices for the common dispersion coordinate sampling. If the +\fIfirst\fR parameter is set then the dispersion sampling of the first +spectrum is used. If this dispersion is nonlinear then the end points and +number of pixels are preserved and a linear dispersion is applied between +the endpoints. If the parameter is not set then the user specified linear +or log linear dispersion system is used. Any combination of starting +wavelength, ending wavelength, wavelength per pixel, and number of output +pixels may be specified. Unspecified values will default to reasonable +values based on the minimum or maximum wavelengths of all spectra, the +minimum dispersion, and the number of pixels needed to satisfy the other +parameters. If the parameters overspecify the linear system then the +ending wavelength is adjusted based on the other parameters. Note that for +a log linear system the wavelengths are still specified in nonlog units and +the dispersion is finally recalculated using the difference of the log +wavelength endpoints divided by the number pixel intervals (the number of +pixels minus one). + +This task is layered on top of the \fBimcombine\fR task. What happens +is that the spectra for each group to be combined is extracted from +the input, resampled to a common dispersion, and the resulting spectra +written to temporary images, one per spectrum. The temporary images +are written to the current working directory with names begining with +"tmp". The same is done with any bad pixel masks. Then the list of +images are combined using the IMCOMBINE algorithms. When the combining +is completed the temporary images are removed. If ODCOMBINE aborts +for some reason these file may be left behind and the user may delete +them. Details of what IMCOMBINE does are presented separate under the +help topic for the IMCOMBINE task. + +.ih +EXAMPLES +1. Combine orders of echelle images. + +.nf + cl> odcombine *.ec *%.ec%% group=images combine=sum +.fi + +2. Combine all spectra using range syntax and scale by the exposure times. + +.nf + cl> names irs 10-42 > irs.dat + cl> odcombine @irs.dat irscombine group=all scale=exptime +.fi + +3. Combine spectra by apertures using exposure time scaling and weighting. + +.nf + cl> odcombine *.ms comb1d \\ + >>> group=apertures scale=exptime weights=exptime + cl> scopy comb1d.* comb.ms format="multispec" + cl> imdel comb1d.* +.fi +.ih +REVISIONS +.ls ODCOMBINE V2.12.3 +This is a new version that incorporates most of the features of +IMCOMBINE. + +In addition to the many new features, including application of pixel +masks, the following functional differences from the old SCOMBINE +are noted. + +.ls 1 +The output is always a single spectrum per image. +.le +.ls 2 +The "first" option does not allow rebinning to a non-linear dispersion. +Instead, it rebins to the nearest linear dispersion matching the first +spectrum. +.le +.ih +SEE ALSO +imcombine, scombine, scopy, sarith, lscombine +.endhelp diff --git a/noao/onedspec/doc/onedspec.hlp b/noao/onedspec/doc/onedspec.hlp new file mode 100644 index 00000000..a1c06ab9 --- /dev/null +++ b/noao/onedspec/doc/onedspec.hlp @@ -0,0 +1,293 @@ +.help package Nov94 noao.onedspec +.ih +NAME +onedspec -- generic 1D spectral reduction and analysis package +.ih +USAGE +onedspec +.ih +PARAMETERS +.ls observatory = "observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. This parameter is used by several +tasks in the package through parameter redirection so this parameter may be +used to affect all these tasks at the same time. The observatory may be +one of the observatories in the observatory database, "observatory" to +select the observatory defined by the environment variable "observatory" or +the parameter \fBobservatory.observatory\fR, or "obspars" to select the +current parameters set in the \fBobservatory\fR task. See help for +\fBobservatory\fR for additional information. +.le +.ls caldir = "" +Calibration directory containing standard star data. This parameter +is used by several tasks in the package through redirection. A list of +standard calibration directories may be obtained by listing the file +"onedstds$README"; for example: + + cl> page onedstds$README + +The user may copy or create their own calibration files and specify +the directory. The directory "" refers to the current working directory. +.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 + +The following parameters apply to two and three dimensional images +such as long slit or Fabry-Perot spectra. They allow selection of +a line or column as the spectrum "aperture" and summing of neighboring +elements to form a one dimensional spectrum as the tasks in the +ONEDSPEC package expect. + +.ls dispaxis = 1 +The image axis corresponding to the dispersion. If there is an image +header keyword DISPAXIS then the value of the keyword will be used +otherwise this package parameter is used. The dispersion coordinates +are a function of column, line, or band when this parameter is 1, 2 +or 3. +.le +.ls nsum = "1" +The number of neighboring elements to sum. This is a string parameter +that can have one or two numbers. For two dimensional images only +one number is needed and specifies the number of lines or columns +to sum depending on the dispersion axis. For three dimensional +images two numbers may be given (if only one is given it defaults +to the same value for both spatial axes) to specify the summing of +the two spatial axes. The order is the lower dimensional spatial +axis first. + +For an even value the elements summed are the central specified +"aperture", nsum / 2 - 1 below, and nsum /2 above; i.e the +central value is closer to the lower element than the upper. +For example, for nsum=4 and an aperture of 10 for a dispersion +axis of 1 in a two dimensional image the spectrum used will be +the sum of lines 9 to 12. +.le + +.ls records = "" +This is a dummy parameter. It is applicable only in the \fBimred.irs\fR +and \fBimred.iids\fR packages. +.le +.ls version = "ONEDSPEC V3: November 1991" +Package version identification. +.le +.ih +DESCRIPTION +The \fBonedspec\fR package contains generic tasks for the reduction, +analysis, and display of one dimensional spectra. The specifics of +individual tasks may be found in their IRAF "help" pages. This document +describes the general and common features of the tasks. + +The functions provided in the \fBonedspec\fR package with applicable tasks +are summarized in Table 1. + +.ce +Table 1: Functions provided in the \fBonedspec\fR package + +.nf +1. Graphical display of spectra + bplot - Batch plots of spectra + identify - Identify features and fit dispersion functions + specplot - Stack and plot multiple spectra + splot - Interactive spectral plot/analysis + +2. Determining and applying dispersion calibrations + dispcor - Dispersion correct spectra + dopcor - Apply doppler corrections + identify - Identify features and fit dispersion functions + refspectra - Assign reference spectra to other spectra + reidentify - Automatically identify features in spectra + specshift - Shift spectral dispersion coordinate system + +3. Determining and applying flux calibrations + calibrate - Apply extinction and flux calibrations to spectra + deredden - Apply interstellar extinction correction + dopcor - Apply doppler corrections + lcalib - List calibration file data + sensfunc - Create sensitivity function + standard - Tabulate standard star data + +4. Fitting spectral features and continua + continuum - Fit the continuum in spectra + fitprofs - Fit gaussian profiles + sfit - Fit spectra and output fit, ratio, or difference + splot - Interactive spectral plot/analysis + +5. Arithmetic and combining of spectra + sarith - Spectrum arithmetic + scombine - Combine spectra + splot - Interactive spectral plot/analysis + +6. Miscellaneous functions + mkspec - Generate an artificial spectrum + names - Generate a list of image names from a string + sapertures - Set or change aperture header information + scopy - Select and copy spectra + sinterp - Interpolate a table of x,y to create a spectrum + slist - List spectrum header parameters + splot - Interactive spectral plot/analysis +.fi + +There are other packages which provide additional functions or specialized +tasks for spectra. Radial velocity measurements are available in the +\fBnoao.rv\fR package. The \fBnoao.imred\fR package contains a number +of packages for specific types of data or instruments. These packages +are listed in Table 2. + +.ce +Table 2: \fBImred\fR spectroscopy packages + +.nf + argus - CTIO ARGUS reduction package + ctioslit - CTIO spectrophotometric reduction package + echelle - Echelle spectral reductions (slit and FOE) + hydra - KPNO HYDRA (and NESSIE) reduction package + iids - KPNO IIDS spectral reductions + irs - KPNO IRS spectral reductions + kpnocoude - KPNO coude reduction package (slit and 3 fiber) + kpnoslit - KPNO low/moderate dispersion slits (Goldcam, RCspec, Whitecam) + specred - Generic slit and fiber spectral reduction package +.fi + +Finally, there are non-NOAO packages which may contain generally useful +software for spectra. Currently available packages are \fBstsdas\fR +and \fBxray\fR. +.ih +SPECTRUM IMAGE FORMATS AND COORDINATE SYSTEMS +See the separate help topic \fIspecwcs\fR. +.ih +INTERPOLATION +Changing the dispersion sampling of spectra, such as when converting to a +constant sampling interval per pixel or a common sampling for combining or +doing arithmetic on spectra, requires interpolation. The tasks which +reinterpolate spectra, if needed, are \fBdispcor, sarith, scombine,\fR and +\fBsplot\fR. + +The interpolation type is set by the package parameter \fIinterp\fR. +The available interpolation types are: + +.nf + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.fi + +The default interpolation type is a 5th order polynomial. + +The choice of interpolation type depends on the type of data, smooth +verses strong, sharp, undersampled features, and the requirements of +the user. The "nearest" and "linear" interpolation are somewhat +crude and simple but they avoid "ringing" near sharp features. The +polynomial interpolations are smoother but have noticible ringing +near sharp features. They are, unlike the sinc function described +below, localized. + +In V2.10 a "sinc" interpolation option is available. This function +has advantages and disadvantages. It is important to realize that +there are disadvantages! Sinc interpolation approximates applying a phase +shift to the fourier transform of the spectrum. Thus, repeated +interpolations do not accumulate errors (or nearly so) and, in particular, +a forward and reverse interpolation will recover the original spectrum +much more closely than other interpolation types. However, for +undersampled, strong features, such as cosmic rays or narrow emission or +absorption lines, the ringing can be more severe than the polynomial +interpolations. The ringing is especially a concern because it extends +a long way from the feature causing the ringing; 30 pixels with the +truncated algorithm used. Note that it is not the truncation of the +interpolation function which is at fault! + +Because of the problems seen with sinc interpolation it should be used with +care. Specifically, if there are no undersampled, narrow features it is a +good choice but when there are such features the contamination of the +spectrum by ringing is much more severe than with other interpolation +types. +.ih +UNITS +In versions of the NOAO spectroscopy packages prior to V2.10 the dispersion +units used were restricted to Angstroms. In V2.10 the first, +experimental, step of generalizing to other units was taken by +allowing the two principle spectral plotting tasks, \fBsplot\fR and +\fBspecplot\fR, to plot in various units. Dispersion functions are still +assumed to be in Angstroms but in the future the generalization will be +completed to all the NOAO spectroscopy tasks. + +The dispersion units capability of the plotting tasks allows specifying +the units with the "units" task parameter and interactively changing the +units with the ":units" command. In addition the 'v' key allows plotting +in velocity units with the zero point velocity defined by the cursor +position. + +The units are specified by strings having a unit type from the list below +along with the possible preceding modifiers, "inverse", to select the +inverse of the unit and "log" to select logarithmic units. For example "log +angstroms" to plot the logarithm of wavelength in Angstroms and "inv +microns" to plot inverse microns. The various identifiers may be +abbreviated as words but the syntax is not sophisticated enough to +recognized standard scientific abbreviations except as noted below. + +.nf + Table 1: Unit Types + + angstroms - Wavelength in Angstroms + nanometers - Wavelength in nanometers + millimicrons - Wavelength in millimicrons + microns - Wavelength in microns + millimeters - Wavelength in millimeters + centimeter - Wavelength in centimeters + meters - Wavelength in meters + hertz - Frequency in hertz (cycles per second) + kilohertz - Frequency in kilohertz + megahertz - Frequency in megahertz + gigahertz - Frequency in gigahertz + m/s - Velocity in meters per second + km/s - Velocity in kilometers per second + ev - Energy in electron volts + kev - Energy in kilo electron volts + mev - Energy in mega electron volts + z - Redshift + + nm - Wavelength in nanometers + mm - Wavelength in millimeters + cm - Wavelength in centimeters + m - Wavelength in meters + Hz - Frequency in hertz (cycles per second) + KHz - Frequency in kilohertz + MHz - Frequency in megahertz + GHz - Frequency in gigahertz + wn - Wave number (inverse centimeters) +.fi + +The velocity and redshift units require a trailing value and unit defining the +velocity zero point. For example to plot velocity relative to +a wavelength of 1 micron the unit string would be: + +.nf + km/s 1 micron +.fi + +Some additional examples of units strings are: + +.nf + milliang + megahertz + inv mic + log hertz + m/s 3 inv mic + z 5015 ang +.fi +.ih +SEE ALSO +apextract, longslit, rv, imred, specwcs +.endhelp diff --git a/noao/onedspec/doc/refspectra.hlp b/noao/onedspec/doc/refspectra.hlp new file mode 100644 index 00000000..01cfab30 --- /dev/null +++ b/noao/onedspec/doc/refspectra.hlp @@ -0,0 +1,413 @@ +.help refspectra Mar92 noao.onedspec +.ih +NAME +refspectra -- Assign reference spectra +.ih +USAGE +refspectra input [records] +.ih +PARAMETERS +.ls input +List of input spectra or root names to be assigned reference spectra. +When using the record number extension format, record number extensions +will be appended to each root name in the list. +.le +.ls records (imred.irs and imred.iids packages only) +List of records or ranges of records to be appended to the input root +names when using record number extension format. The syntax of this +list is comma separated record numbers or ranges of record numbers. A +range consists of two numbers separated by a hyphen. An example of this +syntax is "1-5,13,17-19". A null list ("") may +be used if no record number extensions are desired. This is a +positional query parameter only if the record format is specified with +the \fIrecformat\fR parameter. +.le +.ls references = "*.imh" +List of reference spectra to be assigned or a "reference spectra assignment +table" (see DESCRIPTION section). +.le +.ls apertures = "" +List of apertures to be SELECTED from the input list of spectra. If no list +is specified then all apertures are selected. The syntax is the same as the +record number extensions. +.le +.ls refaps = "" +List of reference spectra apertures to be SELECTED. If no list is specified +then all apertures are selected. The syntax is the same as the record number +extensions. +.le +.ls ignoreaps = yes +Ignore the input and reference apertures when ASSIGNING reference spectra. +If the aperture numbers are not ignored then only the reference spectra with +the same aperture number as a particular input spectra are used when assigning +reference spectra. Otherwise all the reference spectra are used. This does +not apply to the "match" and "average" options which always ignore the aperture +numbers. Note that this parameter applies to relating reference spectra to +input spectra and does not override the aperture selections on the input +spectra and reference spectra. +.le +.ls select = "interp" +Selection method for assigning reference spectra. The methods are: +.ls average +Average two reference spectra without regard to any aperture, +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 +aperture numbers or 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 aperture or 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" +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. +A null string, "", or the word "none" may be use to disable the sorting +parameter. +.le +.ls group = "ljd" +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. A null string, "", or the word "none" may be use +to disable the grouping parameter. +.le +.ls time = no, timewrap = 17. +Is the sorting parameter a 24 hour time? If so then the time orgin +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 +.ls override = no +Override previous assignments? If an input spectrum has reference +spectra assigned previously the assignment will not be changed unless +this flag is set. +.le +.ls confirm = yes +Confirm reference spectrum assignments? If \fIyes\fR then the reference +spectra assignments for each input spectrum are printed and the user may +either accept the assignment or not. Rejected assignments leave the +input spectrum unchanged. +.le +.ls assign = yes +Assign the reference spectrum by entering it in the image header? +The input spectra are only modified if this parameter is \fIyes\fR. +This parameter may be set to \fIno\fR to get a list of assignments +without actually entering the assignments in the image headers. +.le +.ls logfiles = "STDOUT,logfile" +List of log files for recording reference spectra assignments. +The file STDOUT prints to the standard output. If not specified ("") +then no logs will be recorded. +.le +.ls verbose = yes +Verbose log output? This prints additional information about the input +and reference spectra. This is useful for diagnosing why certain spectra +are ignored or not assigned as intended. +.le +.ih +DESCRIPTION +This task allows the user to define which reference spectra are to be +used in the calculation of the dispersion solution of object spectra. +The assignment of reference spectra to object spectra is often +a complex task because of the number of spectra, the use of many distinct +apertures, and different modes of observing such as interspersed arc +calibration spectra or just one calibration for a night. This task +provides a number of methods to cover many of the common cases. + +A reference spectrum is defined to be a spectrum that has been used to +calculate a wavelength solution with the tasks IDENTIFY or REIDENTIFY. +These tasks have set the keyword REFSPEC1 in the image header +equal to the spectrum's own name. + +Wavelength reference spectra are assigned to input spectra by entering +the reference spectrum name or pair of names in the image +header under the keywords REFSPEC1 and REFSPEC2. When two reference +spectra are assigned, the spectrum names may be followed by a weighting +factor (assumed to be 1 if missing). The wavelength of a pixel is +then the weighted average of the wavelengths from the reference +spectra dispersion solutions. The weighting factors are calculated +by choosing an appropriate selection method, ie average, interpolation, +etc. Note, however, that these assignments may be made directly using +the task \fBhedit\fR or with some other task or script if none of the +methods are suitable. + +The spectra to be assigned references are specified by an input list. +Optional numeric record format extensions may be appended to each name +(used as a root name) in the input list in the \fBiids/irs\fR packages. +The input spectra may be restricted to a particular set of aperture numbers +by the parameter \fIapertures\fR; the spectra not in the list of apertures +are skipped. If the aperture list is null (i.e. specified as "") then all +apertures are selected. One further selection may be made on the input +spectra. If the parameter \fIoverride\fR is no then input spectra which +have existing reference spectra assignments (which includes the reference +spectra) are skipped. + +The reference spectra parameter \fIreferences\fR may take two forms. +It may be an image list of spectra or a text file containing +a "reference spectrum assignment table". The table consists of pairs +of strings/lists with the first string being a list of object spectra +and the second string being a list of reference spectra. If this +table is used, then only those object spectra in the table that are also +listed in the input parameter list are processed. The example below +illustrates the reference spectrum assignment table: + +.nf + spec1 spec2,spec3,spec4 + spec5 + spec6,spec7 spect8,spec9 + spec10 spec11 + spec12 spec13 + spec14 spec15 +.fi + +As a convenience, if a reference list in the table is missing, the preceding +reference list is implied. This table may be used to make arbitrary assignments. + +The reference spectra in the specified list may also be restricted to a +subset of aperture numbers. However, in the case of averaging, the +reference aperture selection is ignored. In the case of matching, if +a reference spectrum is not selected then the matching input spectrum +is also skipped (in order to maintain a one-to-one correspondence). +Spectra in the reference list which are not reference spectra (as +defined earlier) are also ignored and a warning is printed. Note that +no check is made that a dispersion solution actually exists in the +dispersion solution database. + +There may be cases where there are only reference spectra for some +apertures and it is desired to apply these reference spectra to the +other apertures. The \fIignoreaps\fR flag may be used to force an +assignment between reference and object spectra with different +aperture numbers. Note that this flag is applied after the input and +reference list aperture number selections are made; in other words this +applies only to the assignments and not the input selection process. + +Once the appropriate reference spectra from the reference list have been +determined for an input spectrum they are assigned using one of the +methods selected by the parameter \fIselect\fR. The "match" method +simply pairs each element of the input spectrum list with each element +in the reference spectrum list. If a reference assignment table +is used with "match", then only the first spectrum in the reference +list for each input spectrum is assigned. + +The "average" method assigns the first two spectra in the reference list +ignoring aperture numbers or groups. The spectra are averaged by assigning +equal weights. There is no weighting based on any sort parameter. If +there are more than two spectra in the reference list then only the first +two spectra are used and the remainder are ignored. If a reference +assignment table is used only the first two reference spectra listed for +each object in the table are averaged. + +The remaining selection methods group the spectra using a header keyword +which must be constant within a group. If no group parameter is specfied +(the null string "" or the word "none") +then grouping does not occur. Only reference spectra with the same +group header value as the object are assigned to an object spectrum. +One likely group parameter is the "date-obs" keyword. This is usually +constant over a night at CTIO and KPNO. At other sites this may not +be the case. Therefore, the task \fBsetjd\fR may be used to set a +local Julian day number which is constant over a night at any +observatory. + +Within a group the spectra are ordered based on a numeric image header +parameter specified by the \fIsort\fR parameter. A null string "" or the +word "null" may be used to select no sort parameter. Parameters which are +times, as indicated by the \fItime\fR parameter, are assumed to be cyclic +with a period of 24 hours. The time wrap parameter defines the origin of a +cycle and should precede the first observation and follow the last +observation in a 24 hour period; i.e. for nighttime observations this +parameter value should bee sometime during the day. Particularly with +interpolating or choosing the nearest reference spectrum it is important +that the sorting parameter refer to the middle of the exposure. A Julian +date at the middle of an exposure may be calculated with the task +\fBsetjd\fR or a middle UT time may be computed with the task +\fBsetairmass\fR. + +The selection methods may choose the "nearest", "preceding", or "following" +reference spectrum. Alternatively, the reference wavelengths may be +interpolated between the preceding and following reference spectra with +weights given by the relative distances measured by the sorting parameter. +In the cases where a preceding or following spectrum is required and one is +not found then the nearest reference spectrum is used. These methods are +used for observing sequences where the reference spectra are taken either +nearby in time or space. + +The option "interp" should not be used without some thought as to the +nature of the interpolation. If the sorting parameter is a time (a 24 hour +cyclic parameter as opposed to a continuous parameter such as a Julian +date) then the user must be aware of when these times were recorded in the +header. For example, let us assume that the sort parameter is "ut" and +that this time was recorded in the header at the beginning of the +exposure. If the object spectrum exposure time is longer than the +reference spectra exposure times, then interpolation will weight the +preceding reference spectrum too heavily. This problem can be circumvented +by using the "average" selection method along with the reference assignment +table. Or the sort time parameter in the headers of the spectra can be +changes with \fIsetjd\fR or \fIsetairmass\fR or edited to reflect the +values at mid-exposure (see EXAMPLES). + +Once the reference spectrum or spectra for a input spectrum have been +identified the user may also chose to override any previous reference +assignments, to accept or not accept the current reference assignments +(in the case of not accepting the reference assignment the image header +is not updated), to only list the current reference assignments and not +update any image headers, as well as to record the reference assignments +to log files. These options are separately controlled by the remaining +task parameters. +.ih +KEYWORDS +This task uses the header keyword BEAM-NUM to sort the apertures. It +has an integer value. If the keyword does not exist then all apertures +are assumed to be 1. + +The keyword REFSPEC1 is used to search for reference spectra. This +keyword can be previously created by the tasks IDENTIFY and REIDENTIFY. + +The two keywords REFSPEC1 and optionally REFSPEC2 are created by the +task when the assign parameter is set to yes. They take the form: + +.nf + REFSPEC1='d1.0001' or + + REFSPEC1='d5.0001 0.756' + REFSPEC2='d5.0002 0.244' +.fi + +.ih +EXAMPLES +1. Compute a Julian date at the midpoint of the exposure for sorting +and a local Julian day number for grouping and then assign spectra +using interpolation. + +.nf + cl> setjd *.imh jd=jd ljd=ljd + cl> refspec *.imh sort=jd group=ljd select=interp +.fi + +2. Specifically assign reference spectra to input spectra. + +.nf + cl> refspectra spec1,spec3 refe=spec2,spec4 select=match +.fi + +3. Use a reference assignment table to assign reference spectra to input +spectra using the "average" option. First a table is created using an +editor. + +.nf + cl> type reftable + spec1 spec2,spec3,spec4 + spec5 + spec6,spec7 spect8,spec9 + spec10 spec11 + spec12 spec13 + spec14 spec15 + cl> refspec spec*.imh recfor- select=average refe=reftable +.fi + +4. Assign the nearest reference spectrum in zenith distance using +wildcard lists. By default the aperture numbers must match. + + cl> refspec *.imh "" sort=zd select=nearest time- + +5. Assign a specific reference spectrum to all apertures. + + cl> refspec *.imh "" refer=refnite1 ignoreaps+ + +6. Confirm assignments. + +.nf + cl> hselect irs.*.imh "$I,beam-num,ut,refspec1" yes + irs.0009.imh 0 0:22:55 irs.0009 + irs.0010.imh 1 0:22:53 irs.0010 + irs.0100.imh 0 8:22:55 + irs.0101.imh 1 8:22:53 + irs.0447.imh 0 13:00:07 irs.0447 + irs.0448.imh 1 13:00:05 irs.0448 + cl> refspec irs 100-101 refer=irs.*.imh conf+ ver+ select=nearest\ + >>> ignoreaps- + [irs.0100] Not a reference spectrum + [irs.0101] Not a reference spectrum + [irs.0100] refspec1='irs.0447' Accept assignment (yes)? + [irs.0101] refspec1='irs.0448' Accept assignment (yes)? +.fi + +Because the reference spectrum list includes all spectra the +warning messages "Not a reference spectrum" are printed with verbose +output. Remember a reference spectrum is any spectrum which has a +reference spectrum assigned which refers to itself. + +7. Assign reference spectra with weights using interpolation. In this +example we want to sort by "ut" but this keyword value was +recorded at the beginning of the integration. So we first create an +new keyword and then compute its value to be that of mid-exposure. The +new keyword is then used as the sorting parameter. + +.nf + cl> hedit *.imh utmid 0. add+ ver- show- + cl> hedit *.imh utmid "(ut)" ver- show- + cl> hedit *.imh utmid "(mod(utmid+exptime/7200.,24.))" ver- show- + cl> refspec *.imh refer=*.imh recfor- select=interp sort=utmid +.fi + +8. Assign reference spectra using the "average" option and the reference +assignment table with data with record number extensions. First edit +the file reftable: + +.nf + cl> type reftable + spec.0001 arc1.0001,arc2.0001 + spec.0002 arc1.0002,arc2.0002 + spec.0003 arc1.0003,arc2.0003 + spec.0004 arc1.0004,arc2.0004 + cl> refspec spec.*.imh recfor- refer=reftable select=average +.fi + +9. Assign a reference spectrum for aperture 1 to the object spectra +for apertures 2 thru 5. + +.nf + cl> refspec spec 2-5 recfor+ refer=arc.*.imh refaps=1 ignoreaps+ +.fi +.ih +REVISIONS +.ls REFSPECTRA V2.10.3 +If no reference spectrum is found in the interp, nearest, following, +preceding methods then a list of the reference spectra is given +showing why each was not acceptable. +.le +.ls REFSPECTRA V2.10 +A group parameter was added to allow restricting assignments by observing +period; for example by night. The record format option was removed and +the record format syntax is available in the \fBirs/iids\fR packages. +.le +.ih +SEE ALSO +identify, reidentify, dispcor, setjd, setairmass +.endhelp diff --git a/noao/onedspec/doc/reidentify.hlp b/noao/onedspec/doc/reidentify.hlp new file mode 100644 index 00000000..07eb2238 --- /dev/null +++ b/noao/onedspec/doc/reidentify.hlp @@ -0,0 +1,516 @@ +.help reidentify Jan96 noao.onedspec +.ih +NAME +reidentify -- Reidentify features +.ih +SUMMARY +Given a reference vector with identified features and (optionally) a +coordinate function find the same features in other elements of the +reference image and fit a new dispersion function or determine a +zero point shift. After all vectors of the reference image are +reidentified use the reference vectors to reidentify corresponding +vectors in other images. This task is used for transferring dispersion +solutions in arc calibration spectra and for mapping geometric and +dispersion distortion in two and three dimensional images. +.ih +USAGE +reidentify reference images +.ih +PARAMETERS +.ls reference +Image with previously identified features to be used as features reference for +other images. If there are multiple apertures, lines, or columns in the +image a master reference is defined by the \fIsection\fR parameter. +The other apertures in multispec images or other lines, or columns +(selected by \fIstep\fR) are reidentified as needed. +.le +.ls images +List of images in which the features in the reference image are to be +reidentified. In two and three dimensional images the reidentifications are +done by matching apertures, lines, columns, or bands with those in the reference +image. +.le +.ls interactive = no +Examine and fit features interactively? If the task is run interactively a +query (which may be turned off during execution) will be given for each +vector reidentified after printing the results of the automatic fit and the +user may chose to enter the interactive \fBidentify\fR task. +.le +.ls section = "middle line" +If the reference image is not one dimensional or specified as a one dimensional +image section then this parameter selects the master reference image +vector. The master reference is used when reidentifying other vectors in +the reference image or when other images contain apertures not present in +the reference image. This parameter also defines the direction +(columns, lines, or z) of the image vectors to be reidentified. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator which +is used with three dimensional data. See the example section for +\fBidentify\fR for examples of this syntax. Abbreviations are allowed +though beware that 'l' is not a sufficient abbreviation. +.le +.ls newaps = yes +Reidentify new apertures in the images which are not in the reference +image? If no, only apertures found in the reference image will be +reidentified in the other images. If yes, the master reference spectrum +is used to reidentify features in the new aperture and then the +new aperture solution will be added to the reference apertures. All +further identifications of the new aperture will then use this solution. +.le +.ls override = no +Override previous solutions? If there are previous solutions for a +particular image vector being identified, because of a previous +\fBidentify\fR or \fBreidentify\fR, this parameter selects whether +to simply skip the reidentification or do a reidentification and +overwrite the solution in the database. +.le +.ls refit = yes +Refit the coordinate function? If yes and there is more than one feature +and a coordinate function was defined in the reference image database then a new +coordinate function of the same type as in the reference is fit +using the new pixel positions. Otherwise only a zero point shift is +determined for the revised coordinates without changing the +form of the coordinate function. +.le + +The following parameters are used for selecting and reidentifying additional +lines, columns, or apertures in two dimensional formats. +.ls trace = no +There are two methods for defining additional reference lines, columns, or +bands in two and three dimensional format images as selected by the +\fIstep\fR parameter. When \fItrace\fR is no the master reference line or +column is used for each new reference vector. When this parameter is yes +then as the reidentifications step across the image the last reidentified +features are used as the reference. This "tracing" is useful if there is a +coherent shift in the features such as with long slit spectra. However, +any features lost during the tracing will be lost for all subsequent lines +or columns while not using tracing always starts with the initial set of +reference features. +.le +.ls step = "10" +The step from the reference line, column, or band used for selecting and/or +reidentifying additional lines, columns, or bands in a two or three +dimensional reference image. For three dimensional images there may be two +numbers to allow independent steps along different axes. If the step is +zero then only the reference aperture, line, column, or band is used. For +multiaperture images if the step is zero then only the requested aperture +is reidentified and if it is non-zero (the value does not matter) then all +spectra are reidentified. For long slit or Fabry-Perot images the step is +used to sample the image and the step should be large enough to map any +significant changes in the feature positions. +.le +.ls nsum = "10" +Number of lines, columns, or bands across the designated vector axis to be +summed when the image is a two or three dimensional spatial spectrum. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. This parameter is not used for +multispec type images. +.le +.ls shift = "0" +Shift in user coordinates to be added to the reference features before +centering. If the image is three dimensional then two numbers may be +specified for the two axes. Generally no shift is used by setting the +value to zero. When stepping to other lines, columns, or bands in the +reference image the shift is added to the primary reference spectrum if not +tracing. When tracing the shift is added to last spectrum when stepping to +higher lines and subtracted when stepping to lower lines. If a value +if INDEF is specified then an automatic algorithm is applied to find +a shift. +.le +.ls search = 0. +If the \fIshift\fR parameter is specified as INDEF then an automatic +search for a shift is made. There are two algorithms. If the search +value is INDEF then a cross-correlation of line peaks is done. Otherwise +if a non-zero value is given then a pattern matching algorithm (see +\fIautoidentify\fR) is used. A positive value specifies the search radius in +dispersion units and a negative value specifies a search radius as a +fraction of the reference dispersion range. +.le +.ls nlost = 0 +When reidentifying features by tracing, if the number of features not found +in the new image vector exceeds this number then the reidentification +record is not written to the database and the trace is terminated. A +warning is printed in the log and in the verbose output. +.le + +The following parameters define the finding and recentering of features. +See also \fBcenter1d\fR. +.ls cradius = 5. +Centering radius in pixels. If a reidentified feature falls further +than this distance from the previous line or column when tracing or +from the reference feature position when reidentifying a new image +then the feature is not reidentified. +.le +.ls threshold = 0. +In order for a feature center to be determined, the range of pixel +intensities around the feature must exceed this threshold. This parameter +is used to exclude noise peaks and terminate tracing when the signal +disappears. However, failure to properly set this parameter, particularly +when the data values are very small due to normalization or flux +calibration, is a common error leading to failure of the task. +.le + +The following parameters select and control the automatic addition of +new features during reidentification. +.ls addfeatures = no +Add new features from a line list during each reidentification? If +yes then the following parameters are used. This function can be used +to compensate for lost features from the reference solution, particularly +when tracing. Care should be exercised that misidentified features +are not introduced. +.le +.ls coordlist = "linelists$idhenear.dat" +User coordinate list consisting of a list of line coordinates. +Some standard line lists are available in the directory "linelists$". +The standard line lists are described under the topic \fIlinelists\fR. +.le +.ls match = -3. +The maximum difference for a match between the feature coordinate function +value and a coordinate in the coordinate list. Positive values +are in user coordinate units and negative values are in units of pixels. +.le +.ls maxfeatures = 50 +Maximum number of the strongest features to be selected automatically from +the coordinate list. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following parameters determine the input and output of the task. +.ls database = "database" +Database containing the feature data for the reference image and in which +the features for the reidentified images are recorded. +.le +.ls logfiles = "logfile" +List of files in which to keep a processing log. If a null file, "", +is given then no log is kept. +.le +.ls plotfile = "" +Optional file to contain metacode plots of the residuals. +.le +.ls verbose = no +Print reidentification information on the standard output? +.le +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le + +The following parameters are queried when the 'b' key is used in the +interactive review. +.ls crval, cdelt +These parameters specify an approximate coordinate value and coordinate +interval per pixel when the automatic line identification +algorithm ('b' key) is used. The coordinate value is for the +pixel specified by the \fIcrpix\fR parameter in the \fBaidpars\fR +parameter set. The default value of \fIcrpix\fR is INDEF which then +refers the coordinate value to the middle of the spectrum. By default +only the magnitude of the coordinate interval is used. Either value +may be given as INDEF. In this case the search for a solution will +be slower and more likely to fail. The values may also be given as +keywords in the image header whose values are to be used. +.le +.ls aidpars = "" (parameter set) +This parameter points to a parameter set for the automatic line +identification algorithm. See \fIaidpars\fR for further information. +.le +.ih +DESCRIPTION +Features (spectral lines, cross-dispersion profiles, etc.) identified in a +single reference vector (using the tasks \fBidentify\fR or +\fBautoidentify\fR) are reidentified in other reference vectors and the set +of reference vectors are reidentified in other images with the same type of +vectors. A vector may be a single one dimensional (1D) vector in a two or +three dimensional (2D or 3D) image, the sum of neighboring vectors to form +a 1D vector of higher signal, or 1D spectra in multiaperture images. The +number of vectors summed in 2D and 3D images is specified by the parameter +\fInsum\fR. This parameter does not apply to multiaperture images. + +As the previous paragraph indicates, there are two stages in this task. +The first stage is to identify the same features from a single reference +vector to a set of related reference vectors. This generally consists +of other vectors in the same reference image such as other lines or +columns in a long slit spectrum or the set of 1D aperture spectra in +a multiaperture image. In these cases the vectors are identified by +a line, column, band, or aperture number. The second stage is to +reidentify the features from the reference vectors in the matching +vectors of other images. For example the same lines in the reference +image and another image or the same apertures in several multiaperture +images. For multiaperture images the reference vector and target vector +will have the same aperture number but may be found in different image +lines. The first stage may be skipped if all the reference vectors +have been identified. + +If the images are 2D or 3D or multiaperture format and a \fIstep\fR greater +than zero is specified then additional vectors (lines/columns/bands) in the +reference image will be reidentified from the initial master reference +vector (as defined by an image section or \fIsection\fR parameter) provided +they have not been reidentified previously or the \fIoverride\fR flag is +set. For multiple aperture spectral images, called multiaperture, a step +size of zero means don't reidentify any other aperture and any other step +size reidentifies all apertures. For two and three dimensional images, +such as long slit and Fabry-Perot spectra, the step(s) should be large +enough to minimize execution time and storage requirements but small enough +to follow shifts in the features (see the discussion below on tracing). + +The reidentification of features in other reference image vectors +may be done in two ways selected by the parameter \fItrace\fR. If not +tracing, the initial reference vector is applied to the other selected +vectors. If tracing, the reidentifications are made with respect to the +last set of identifications as successive steps away from the reference +vector are made. The tracing method is appropriate for two and three +dimensional spatial images, such as long slit and Fabry-Perot spectra, in +which the positions of features traced vary smoothly. This allows +following large displacements from the initial reference by using suitably +small steps. It has the disadvantage that features lost during the +reidentifications will not propagate (unless the \fIaddfeatures\fR option +is used). By not tracing, the original set of features is used for every +other vector in the reference image. + +When tracing, the parameter \fInlost\fR is used to terminate the +tracing whenever this number of features has been lost. This parameter, +in conjunction with the other centering parameters which define +when a feature is not found, may be useful for tracing features +which disappear before reaching the limits of the image. + +When reidentifying features in other images, the reference +features are those from the same aperture, line, column, or band of the +reference image. However, if the \fInewaps\fR parameter is set +apertures in multiaperture spectra which are not in the reference +image may be reidentified against the master reference aperture and +added to the list of apertures to be reidentified in other images. +This is useful when spectra with different aperture numbers are +stored as one dimensional images. + +The reidentification of features between a reference vector and +a target vector is done as follows. First a mean shift between +the two vectors is determined. After correcting for the shift +the estimated pixel position of each reference feature in the +target vector is used as the starting point for determining +a feature center near this position. The centering fails the +feature is dropped and a check against the \fInlost\fR is made. +If it succeeds it is added to the list of features found in the +target spectrum. A zero point shift or new dispersion +function may be determined. New features may then be added from +a coordinate list. The details are given below. + +There may be a large shift between the two vectors such that the same +feature in the target vector is many pixels away from the pixel position in +the reference spectrum. A shift must then be determined. The \fIshift\fR +parameter may be used to specify a shift. The shift is in user coordinates +and is added to the reference user coordinates before trying to center +on a feature. For example if the reference spectrum has a feature at +5015A but in the new spectrum the feature is at 5025A when the reference +dispersion function is applied then the shift would be +10. Thus +a reference feature at 5015A would have the shift added to get 5025A, +then the centering would find the feature some pixel value and that +pixel value would be used with the true user coordinate of 5015A in the +new dispersion solution. + +When tracing a 2D/3D reference spectrum the shift is applied to the +previous reidentified spectrum rather than the initial reference spectrum. +The shift is added for increasing line or column values and subtracted for +decreasing line or column values. This allows "tracing" when there is a +rotation or tilt of the 2D or 3D spectrum. When not tracing the shift is +always added to the reference spectrum features as described previously. + +When reidentify other images with the reference spectrum the shift +parameter is always just added to the reference dispersion solution +matching the aperture, line, or column being reidentified. + +If the \fIshift\fR parameter is given as INDEF then an automatic +search algorithm is applied. There are two algorithms that may be +used. If the \fIsearch\fR parameter is INDEF then a cross-correlation +of the features list with the peaks found in the target spectrum is +performed. This algorithm can only find small shifts since otherwise +many lines may be missing off either end of the spectrum relative to +the reference spectrum. + +If the search parameter is non-zero then the pattern matching algorithm +described in \fIaidpars\fR is used. The search parameter specified a +search radius from the reference solution. If the value is positive the +search radius is a distance in dispersion units. If the value is negative +then the absolute value is used as a fraction of the dispersion range in +the reference solution. For example, a value of -0.1 applied to reference +dispersion solution with a range of 1000A would search for a new solution +within 100A of the reference dispersion solution. + +The pattern matching algorithm has to stages. First if there are +more than 10 features in the reference the pattern matching tries +to match the lines in the target spectrum to those features with +a dispersion per pixel having the same sign and a value within 2%. +If no solution is found then the \fIlinelist\fR is used to match +against the lines in the target spectrum, again with the dispersion +per pixel having the same sign and a value within 5%. The first +stage works when the set of features is nearly the same while the +second stage works when the shifts are large enough that many features +in the reference and target spectra are different. + +The centering algorithm is described under the topic \fIcenter1d\fR and +also in \fBidentify\fR. If a feature positions shifts by more than the +amount set by the parameter \fIcradius\fR from the starting position +(possibly after adding a shift) or the feature strength (peak to valley) is +less than the detection \fIthreshold\fR then the new feature is discarded. +The \fIcradius\fR parameter should be set large enough to find the correct +peak in the presence of any shifts but small enough to minimize incorrect +identifications. The \fIthreshold\fR parameter is used to eliminate +identifications with noise. Failure to set this parameter properly for the +data (say if data values are very small due to a calibration or +normalization operation) is the most common source of problems in using +this task. + +If a fitting function is defined for the features in the reference image, +say a dispersion function in arc lamp spectra, then the function is refit +at each reidentified line or column if the parameter \fIrefit\fR is yes. +If refitting is not selected then a zero point shift in the user +coordinates is determined without changing the form of the fitting +function. The latter may be desirable for tracking detector shifts through +a sequence of observation using low quality calibration spectra. When +refitting, the fitting parameters from the reference are used including +iterative rejection parameters to eliminate misidentifications. + +If the parameter \fIaddfeatures\fR is set additional features may be added +from a line list. If there are reference features then the new features +are added AFTER the initial reidentification and function fit. If the +reference consists only of a dispersion function, that is it has no +features, then new features will be added followed by a function fit and +then another pass of adding new features. A maximum number of added +features, a matching distance in user coordinates, and a minimum separation +from other features are additional parameters. This option is similar to +that available in \fBidentify\fR and is described more fully in the help +for that task. + +A statistics line is generated for each reidentified vector. The line +contains the name of the image being reidentified (which for two +dimensional images includes the image section and for multiaperture +spectra includes the aperture number), the number of features found +relative to the number of features in the reference, the number of +features used in the function fit relative to the number found, the +mean pixel, user coordinate, and fractional user coordinate shifts +relative to the reference coordinates, and the RMS relative to the +final coordinate system (whether refit or simply shifted) excluding any +iteratively rejected features from the calculation. + +If the task is run with the \fIinteractive\fR flag the statistics line +is printed to the standard output (the terminal) and a query is +made whether to examine and/or refit the features. A response +of yes or YES will put the user in the interactive graphical mode +of \fBidentify\fR. See the description of this task for more +information. The idea is that one can monitor the statistics information, +particularly the RMS if refitting, and select only those which may be +questionable to examine interactively. A response of no or NO will +continue on to the next reidentification. The capitalized responses +turn off the query and act as permanent response for all other +reidentifications. + +This statistics line, including headers, is written to any specified +log files. The log information includes the image being +reidentified and the reference image, and the initial shift. + +If an accessible file name is given for the plot file then a residual plot +of the reidentified lines is recorded in this file. The plot file can +be viewed with \fBgkimosaic, stdgraph\fR or reading the file +with ".read" when in cursor mode (for example with "=gcur"). + +The reidentification results for this task are recorded in a +\fIdatabase\fR. Currently the database is a directory and entries +in the database are text files with filenames formed by adding +the prefix "id" to the image name without an image extension. +.ih +EXAMPLES +1. Arc lines and a dispersion solution were defined for the middle +aperture in the multispec for arc spectrum a042.ms. To reidentify the +other apertures in the reference image and then another arc image: + +.nf + cl> reiden a042.ms a045.ms inter+ step=1 ver+ + REIDENTIFY: NOAO/IRAF V2.9 valdes@puppis Fri 29-Jun-90 + Reference image = a042.ms.imh, New image = a042.ms, Refit = yes + Image Data Found Fit Pix Shift User Shift RMS + a042.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): y + a042.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + a042.ms - Ap 23 48/48 47/48 0.216 1.32 0.754 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): n + a042.ms - Ap 22 48/48 47/48 0.0627 0.383 0.749 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): n + a042.ms - Ap 21 48/48 47/48 0.337 2.06 0.815 + <etc> + Reference image = a042.ms.imh, New image = a045.ms, Refit = yes + Image Data Found Fit Pix Shift User Shift RMS + a045.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): y + a045.ms - Ap 24 48/48 47/48 -2.38E-4 -3.75E-6 0.699 + a045.ms - Ap 23 48/48 47/48 0.216 1.32 0.754 + Fit dispersion function interactively? (no|yes|NO|YES) (yes): N + a045.ms - Ap 22 48/48 47/48 0.0627 0.383 0.749 + a042.ms - Ap 21 48/48 47/48 0.337 2.06 0.815 + a042.ms - Ap 20 48/48 47/48 -0.293 -1.79 0.726 + a042.ms - Ap 19 48/48 48/48 0.472 2.88 0.912 +.fi + +This example is verbose and includes interactive review of reidentifications. +The statistics lines have been shortened. + +2. To trace a stellar profile and arc lines in long slit images for the +purpose of making a distortion correction: + +.nf + cl> reiden rog022[135,*] "" trace+ + cl> reiden rog023 "" sec="mid line" trace+ +.fi +.ih +REVISIONS +.ls REIDENTIFY V2.11 +The \fIsearch\fR parameter and new searching algorithm has been added. + +The task will now work with only a warning if the reference image is absent; +i.e. it is possible to reidentify given only the database. + +The \fIaddfeatures\fR function will now add features before a fit if there +are no reference database features. Previously features could only be +added after an initial fit using the reference features and, so, required +the reference database to contain features for reidentification. This +new feature is useful if one wants to uses a dispersion function from one +type of calibration but wants to add features for a different kind of +calibration. +.le +.ls REIDENTIFY V2.10.3 +The section, nsum, step, and shift parameter syntax was extended to apply to 3D +images. The previous values and defaults may still be used. + +For multiaperture data a step of zero selects only the reference aperture +to be reidentified and any other step selects reidentifying all apertures. +.le +.ls REIDENTIFY V2.10 +This task is a new version with many new features. The new features +include an interactive options for reviewing identifications, iterative +rejection of features during fitting, automatic addition of new features +from a line list, and the choice of tracing or using a single master +reference when reidentifying features in other vectors of a reference +spectrum. Reidentifications from a reference image to another image is +done by matching apertures rather than tracing. New apertures not present +in the reference image may be added. +.le +.ih +SEE ALSO +autoidentify, identify, aidpars, center1d, linelists, fitcoords +.endhelp diff --git a/noao/onedspec/doc/rspectext.hlp b/noao/onedspec/doc/rspectext.hlp new file mode 100644 index 00000000..2973f552 --- /dev/null +++ b/noao/onedspec/doc/rspectext.hlp @@ -0,0 +1,138 @@ +.help rspectext Oct93 onedspec +.ih +NAME +rspectext -- convert 1D ascii text spectra to IRAF image spectra +.ih +USAGE +rspectext input output +.ih +PARAMETERS +.ls input +Input list of ascii text spectra. These may have a optional FITS header +at the beginning and then two columns of wavelength and flux. +.le +.ls output +Output list of IRAF spectra image names. The list must match the +input list. +.le + + +The following parameters are only used if there is no FITS header +with the data. +.ls title = "" +Title to be assigned to the spectra. +.le +.ls flux = no +Are the flux values flux calibrated? If so then header keywords are +inserted to identify this for the IRAF spectral software. +.le +.ls dtype = "linear" (none|linear|log|nonlinear|interp) +Type of dispersion to assign to the spectra. The options are: +.ls none +No dispersion function and nothing is added to the image header. +.le +.ls linear +Store the linear dispersion parameters \fBcrval1\fR and \fBcdelt1\fR +in the image header. The wavelength values are ignored. This may +be used if the wavelength values are known to be linear but one wants +to avoid possible roundoff and resampling errors introduced by the +"interp" option. +.le +.ls log +Store the log-linear dispersion parameters \fBcrval1\fR and \fBcdelt1\fR in +the image header. The wavelength values are ignored. This may be used if +the wavelength values are known to be linear in the log of the wavelength +but one wants to avoid possible roundoff and resampling errors introduced +by the "interp" option. +.le +.ls nonlinear +Store the wavelength values in the image header as a lookup table. +The flux values are not resampled. The wavelength values need not +be evenly sampled. +.le +.ls interp +Use the wavelength values to resample to a linear dispersion between +the first and last wavelength values. The dispersion per pixel is +determined by the number of pixels and the endpoint wavelengths. +.le +.le +.ls crval1 = 1., cdelt1 = 1. +The wavelength coordinate of the first pixel and the wavelength interval +per pixel to be used with the linear and log dispersion types. +.le +.ih +DESCRIPTION +Ascii text files consisting of an optional FITS header (usually produced +by \fBwspectext\fR) and a two column list of wavelengths and fluxes +are converted to IRAF image spectra. If a header is included then +the header information is assumed to describe the spectra including +any dispersion function. If no header is given then the minimal +information for describing spectra in IRAF is added. The dispersion +function can be set either a linear or log-linear based on two +keywords (ignoring the wavelength values) or from the wavelength +values. The latter may be stored in the header as a lookup table +allowing for nonlinear dispersions or resample to a linear dispersion. +This task is a script based on \fBrtextimage\fR for the creating +the image and entering the flux values, \fBhedit\fR to set some +of the header keywords, and \fBdispcor\fR to handle the nonlinear +or resampled dispersion functions. +.ih +EXAMPLES +1. Create spectrum from a text file originally produced by \fBwspectext\fR. + +.nf + cl> type text001 + BITPIX = 8 / 8-bit ASCII characters + NAXIS = 1 / Number of Image Dimensions + NAXIS1 = 100 / Length of axis + ORIGIN = 'NOAO-IRAF: WTEXTIMAGE' / + IRAF-MAX= 0. / Max image pixel (out of date) + IRAF-MIN= 0. / Min image pixel (out of date) + IRAF-B/P= 32 / Image bits per pixel + IRAFTYPE= 'REAL FLOATING ' / Image datatype + OBJECT = 'TITLE ' / + FILENAME= 'TEST ' / IRAF filename + FORMAT = '5G14.7 ' / Text line format + APNUM1 = '1 1 ' + DC-FLAG = 0 + WCSDIM = 1 + CTYPE1 = 'LINEAR ' + CRVAL1 = 4000. + CRPIX1 = 1. + CDELT1 = 10.1010101010101 + CD1_1 = 10.1010101010101 + LTM1_1 = 1. + WAT0_001= 'system=equispec ' + WAT1_001= 'wtype=linear label=Wavelength units=Angstroms ' + END + + 4000.00 1000. + 4010.10 1005.54 + 4020.20 1011.05 + ... + cl> rspectext text001 spec001 +.fi + +2. Create a spectrum with a nonlinear dispersion using the wavelength +values as a lookup table. + +.nf + cl> type text002 + 4000.00 1000. + 4010.10 1005.54 + 4020.20 1011.05 + ... + cl> rspectext text002 spec002 title="HH12" dtype=nonlinear +.fi +.ih +REVISIONS +.ls RSPECTEXT V2.11 +The task now automatically senses the presence of a header. +.le +.ls RSPECTEXT V2.10.3 +This is a new task with this version. +.le +.ih +SEE ALSO +wspectext, rtextimage, dispcor, mkms, imspec, sinterp +.endhelp diff --git a/noao/onedspec/doc/sapertures.hlp b/noao/onedspec/doc/sapertures.hlp new file mode 100644 index 00000000..37398d6a --- /dev/null +++ b/noao/onedspec/doc/sapertures.hlp @@ -0,0 +1,217 @@ +.help sapertures Jul95 noao.onedspec +.ih +NAME +sapertures -- Set or change aperture header information +.ih +USAGE +sapertures input +.ih +PARAMETERS +.ls input +List of spectral images to be modified. +.le +.ls apertures = "" +List of apertures to be modified. The null list +selects all apertures. A list consists of comma separated +numbers and ranges of numbers. A range is specified by a hyphen. An +optional step size may be given by using the 'x' followed by a number. +See \fBxtools.ranges\fR for more information. +.le +.ls apidtable = "" +Aperture table. This may be either a text file or an image. +A text file consisting of lines with an aperture number, +beam number, dispersion type code, coordinate of the first physical +pixel, coordinate interval per physical pixel, redshift factor, +lower extraction aperture position, upper extraction aperture position, +and aperture title or identification. An image will contain the +keywords SLFIBnnn with string value consisting of aperture number, +beam number, optional right ascension and declination, and aperture title. +Any field except the aperture number may be given the value INDEF to +indicate that the value is not to be changed from the current value. Any +apertures not in this table are assigned the values given by the task +parameters described below. + +As a special case a file having just the aperture number, beam number, and +spectrum aperture identification may be used. This file format as well as +use of an image header is the same as that in the \fBapextract\fR package. +.le +.ls wcsreset = no +Reset the world coordinate system (WCS) of the selected apertures to +uncorrected pixels. If this parameter is set the \fIapidtable\fR and task +aperture parameters are ignored. This option sets the dispersion type flag +to -1, the starting coordinate value to 1, the interval per pixel to 1, and +no redshift factor and leaves the other parameters unchanged. The option +is useful when it is desired to apply a second dispersion correction using +\fBidentify\fR and \fBdispcor\fR. +.le +.ls verbose = no +Print a record of each aperture modified? Only those apertures +in which the beam number or label are changed are printed. +.le + +If no aperture table is specified or if there is not an aperture +entry in the table for a selected aperture the following parameter +values are used. A value of INDEF will leave the corresponding +parameter unchanged. +.ls beam = INDEF +Beam number. +.le +.ls dtype = INDEF +Dispersion type. The dispersion types are: + +.nf + -1 Linear with dispersion correction flag off + 0 Linear with dispersion correction flag on + 1 Log-linear with dispersion correction flag on +.fi + +.le +.ls w1 = INDEF +Coordinate of the first physical pixel. Note that it is possible +that the physical pixels are not the same as the logical pixels if +an image section has been extracted. +.le +.ls dw = INDEF +Coordinate interval per physical pixel. Note that it is possible +that the physical pixels intervals are not the same as the logical pixels +intervals if an image section has been extracted. +.le +.ls z = INDEF +Redshift factor. This is usually set with the task \fBdopcor\fR. +Coordinates are divided by one plus the redshift factor (1+z). +.le +.ls aplow = INDEF, aphigh = INDEF +The aperture extraction limits. These are set when the \fBapextract\fR +package is used and it is unlikely that one would use this task to +change them. +.le +.ls title = INDEF +Aperture title or identification string. +.le +.ih +DESCRIPTION +This task sets or changes any of the aperture specific parameters except +the aperture number and the number of valid pixels. It is particularly +useful for images which use the "multispec" world coordinate system +attribute strings which are not readily accessible with other header +editors. A list of images and a list of apertures is used to select which +spectra are to be modified. The default empty string for the apertures +selects all apertures. The new values are specified either in an aperture +table file or with task parameters. The aperture table is used to give +different values to specific apertures. If all apertures are to have the +same values this file need not be used. + +The aperture parameters which may be modified are the beam number, the +dispersion type, the coordinate of the first physical pixel, the coordinate +interval per physical pixel, the redshift factor, the aperture extraction +limits, and the title. The task has parameters for each of these and the +aperture table consists of lines starting with an aperture number followed +by the above parameters in the list order and separated by whitespace. As +a special case the aperture table may be a file abbreviated to aperture +number, beam number, and title or an image with keywords SLFIBnnn +containing the aperture number, beam number, optional right ascension and +declination, and title. These special cases allow use of the same file +orimage used in the \fBapextract\fR package. If any of the parameters are +specified as INDEF then the value will be unchanged. + +If the \fIwcsreset\fR parameter is set then the aperture table and +task aperture parameters are ignored and the selected apertures are +reset to have a dispersion type of -1, a starting coordinate of 1, +a coordinate interval of 1, and a redshift factor of 0. This other +parameters are not changed. These choice of parameters has the effect +of resetting the spectrum to physical pixel coordinates and flagging +the spectra as not being dispersion calibrated. One use of this option +is to allow the \fBdispcor\fR task to be reapplied to previously +dispersion calibrated spectra. + +The \fIverbose\fR parameter lists the old and new values when there is +a change. If there are no changes there will be no output. +.ih +EXAMPLES +1. To add titles to a multifiber extraction and change one of the +beam numbers: + +.nf + cl> type m33aps + 36 2 Henear + 37 0 Sky + 38 1 New title + 39 1 Another title + 41 0 Sky + 42 1 Yet another title + 43 1 YAT + 44 1 Was a sky but actually has an object + 45 1 Wow + 46 1 Important new discovery + 47 0 Sky + 48 2 Henear + cl> saper m33.ms apid=m33aps v+ + demoobj1.ms: + Aperture 37: --> Sky + Aperture 38: --> New title + Aperture 39: --> Another title + Aperture 41: --> Sky + Aperture 42: --> Yet another title + Aperture 43: --> YAT + Aperture 44: beam 0 --> beam 1 + Aperture 44: --> Was a sky but actually has an object + Aperture 45: --> Wow + Aperture 46: --> Important new discovery + Aperture 47: --> Sky +.fi + +2. To reset a dispersion calibrated multifiber spectrum: + +.nf + cl> saper test.ms wcsreset+ verbose+ + test.ms: + Aperture 1: + w1 4321. --> 1. + dw 1.23 --> 1. + Aperture 2: + w1 4321. --> 1. + dw 1.23 --> 1. + <etc.> +.fi + +3. To set a constant wavelength length scale (with the default parameters): + +.nf + cl> saper test.ms dtype=0 w1=4321 dw=1.23 v+ + test.ms: + Aperture 1: + w1 1. --> 4321. + dw 1. --> 1.23 + Aperture 2: + w1 1. --> 4321. + dw 1. --> 1.23 + <etc.> +.fi + +4. To reset the wavelengths and title of only aperture 3: + +.nf + cl> saper test.ms aper=3 w1=4325 dw=1.22 title=HD12345 v+ + test.ms: + Aperture 3: + w1 4321. --> 4325. + dw 1.23 --> 1.22 + apid --> HD12345 +.fi +.ih +REVISIONS +.ls SAPERTURES V2.11 +This task has been modified to allow use of image header keywords +as done in the APEXTRACT package. +.le +.ls SAPERTURES V2.10.3 +This task has been greatly expanded to allow changing any of the WCS +parameters as well as the beam number and aperture title. +.le +.ls SAPERTURES V2.10 +This task is new. +.le +.ih +SEE ALSO +specshift, imcoords.wcsreset, hedit, ranges, onedspec.package +.endhelp diff --git a/noao/onedspec/doc/sarith.hlp b/noao/onedspec/doc/sarith.hlp new file mode 100644 index 00000000..a7e7cf87 --- /dev/null +++ b/noao/onedspec/doc/sarith.hlp @@ -0,0 +1,571 @@ +.help sarith Mar93 noao.onedspec +.ih +NAME +sarith -- Spectrum arithmetic +.ih +USAGE +sarith input1 op input2 output +.ih +PARAMETERS +.ls input1 +List of input images to be used as operands. +.le +.ls op +Operator to be applied to the first operand or to both operands. The +unary or single operand operators are: + +.nf + abs - absolute value + copy - copy (see also \fBscopy\fR) + dex - decimal exponentiation (antilog of base 10 logarithm) + exp - base e exponentiation (antilog of natural logarithm) + flam - convert F-nu to F-lambda + fnu - convert F-lambda to F-nu + inv - inverse + ln - natural logarithm + log - base 10 logarithm + lum - convert magnitude to luminosity + mag - convert luminosity to magnitude + sqrt - square root +.fi + +The binary or two operand operators are: + +.nf + replace - replace first operand values by second operand values + + - addition + - - subtraction + * - multiplication + / - division + ^ - exponentiation +.fi +.le +.ls input2 +Lists of input spectra or constants to be used as second operands for +binary operations. If a single value is specified it applies +to all the first operand input images otherwise the list must match +the first operand list in number. +.le +.ls output +List of resultant output images or root names. Image +sections are ignored and if the output format is "onedspec" then any record +extensions are stripped to form the root name. If no output list is +specified then the input list is used and the input images are replaced by +the resultant spectra. If a single output name is specified then all +resultant spectra are written to the same output image or image root +name. This allows packing or merging multiple spectra and requires +properly setting the \fIclobber\fR, \fImerge\fR, \fIrenumber\fR and +\fIoffset\fR parameters to achieve the desired output. If more than one +output image is specified then it must match the input image list in +number. +.le +.ls w1 = INDEF, w2 = INDEF +Starting and ending wavelengths to be copied. If \fIw1\fR is not specified +then the wavelength of the starting edge of the first pixel is used +(wavelength at pixel coordinate 0.5) and if \fIw2\fR is not specified then +the wavelength of the ending edge of the last pixel is used (wavelength of +the last pixel plus 0.5). If both are not specified, that is set to INDEF, +then the whole spectrum is copied and the \fIrebin\fR parameter is +ignored. Note that by specifying both endpoints the copied region can be +set to have increasing or decreasing wavelength per pixel. If the spectrum +only partially covers the specified range only that portion of the spectrum +within the range is copied. It is an error if the range is entirely +outside that of a spectrum. +.le +.ls apertures = "", beams = "" +List of apertures and beams to be selected from the input spectra. The +logical intersection of the two lists is selected. The null list +selects all apertures or beams. A list consists of comma separated +numbers and ranges of numbers. A range is specified by a hyphen. An +optional step size may be given by 'x' followed by a number. +See \fBxtools.ranges\fR for more information. If the first character +is "!" then the apertures/beams not in the list are selected. Note +that a "!" in either of the lists complements the intersection of the +two lists. +For longslit input spectra the aperture numbers +selects the lines or columns to be extracted. For 3D Fabry-Perot +spectra the aperture numbers select the first spatial axis. +.le +.ls bands = "" +List of bands in 3D multispec. +For 3D spatial spectra the band parameter applies to the second +spatial axis. +The null list selects all bands. The syntax is as described above. +.le +.ls apmodulus = 0 +Modulus to be applied to the input aperture numbers before matching against +the aperture list. If zero then no modulus is used. This is used to +select apertures which are related by the same modulus, typically a +factor of 10; for example, 10, 1010, and 2010 with a modulus of 1000 are +related. +.le +.ls reverse = no +Reverse the order of the operands in a binary operation? Because the first +operand is used as the image header template, dispersion coordinate +template, and output image in the case of a null output list it must be an +image and not a constant. To allow certain operations, for +example subtracting a spectra from a constant or using the subtractand as +the dispersion coordinate template, the reverse option is used to reverse +the order of the operands in a binary operation. +.le +.ls ignoreaps = no +Ignore aperture numbers in the second operand? Normally, spectra in +binary operations must have matching aperture numbers, otherwise an +error is printed. If this parameter is yes then the spectra are matched +by line number with the last line being used if the second operand spectrum +has fewer lines than the first operand spectrum. This is generally +used to allow using a single spectrum with multiple aperture spectra. +.le +.ls format = "multispec" (multispec|onedspec) +Output image format and name syntax. The "multispec" format consists of +one or more spectra in the same image file. The "onedspec" format consists +of a single spectrum per image with names having a root name and a four +digit aperture number extension. Note that converting to "onedspec" format +from three dimensional images where the third dimension contains associated +spectra will not include data from the extra dimension. Image sections may +be used in this case. +.le +.ls renumber = no +Renumber the output aperture numbers? If set the output aperture +numbers, including any preexisting spectra when merging, are renumbered +beginning with 1. The \fIoffset\fR parameter may be used to +change the starting number. +.le +.ls offset = 0 +Offset to be added to the input or renumbered aperture number to form +the final output aperture number. +.le +.ls clobber = no +Modify an existing output image either by overwriting or merging? +.le +.ls merge = no +Merge apertures into existing spectra? This +requires that the \fIclobber\fR parameter be set. If not merging +then the selected spectra entirely replace those in existing output images. +If merging then the input spectra replace those in the output image +with the same aperture number and new apertures are added if not present. +.le +.ls rebin = yes +Rebin the spectrum to the exact wavelength range specified by the \fIw1\fR +and \fIw2\fR parameters? If the range is given as INDEF for both endpoints +this parameter does not apply. If a range is given and this parameter is +not set then the pixels in the specified range (using the nearest pixels to +the endpoint wavelengths) are copied without rebinning. In this case the +wavelength of the first pixel may not be exactly that specified by \fIw1\fR +and the dispersion, including non-linear dispersions, is unchanged. If +this parameter is set the spectra are interpolated to have the first and +last pixels at exactly the specified endpoint wavelengths while preserving +the same number of pixels in the interval. Linear and log-linear +dispersion types are maintained while non-linear dispersions are +linearized. +.le +.ls errval = 0. +Value for resultant pixel if an arithmetic error occurs such as dividing +by zero or the square root of a negative number. +.le +.ls verbose = no +Print a record of each operation? +.le +.ih +DESCRIPTION +\fBSarith\fR performs arithmetic operations on spectra. It is +distinguished from \fBimarith\fR in that it includes unary operators, like +\fBimfunction\fR but with some specific to astronomical spectra, and binary +operations between two spectra are performed in dispersion coordinate space +(typically wavelength) rather than logical pixel space. In the latter case +the spectra are checked for matching dispersion functions (which are not +necessarily linear) and, if they don't match, the second operand is +interpolated without flux conservation. (If flux conservation is desired +then the task \fBdispcor\fR should be used first.) Thus, the spectra may +have different dispersion functions but the arithmetic is done at matching +wavelengths. The default interpolation function is a 5th order +polynomial. The choice of interpolation type is made with the package +parameter "interp". It may be set to "nearest", "linear", "spline3", +"poly5", or "sinc". Remember that this applies to all tasks which might +need to interpolate spectra in the \fBonedspec\fR and associated packages. +For a discussion of interpolation types see \fBonedspec\fR. + +The unary operators operate on the spectra in the first operand list to +produce the specified output spectra, which may be the same as the +input spectra. The operators include: + +.nf + abs - absolute value + copy - copy (see also \fBscopy\fR) + dex - decimal exponentiation (antilog of base 10 logarithm) + exp - base e exponentiation (antilog of natural logarithm) + flam - convert F-nu to F-lambda + fnu - convert F-lambda to F-nu + inv - inverse + ln - natural logarithm + log - base 10 logarithm + lum - convert magnitude to luminosity + mag - convert luminosity to magnitude + sqrt - square root +.fi + +The luminosity to magnitude and magnitude to luminosity operators are +based on the standard relation: + +.nf + mag = -2.5 * log (lum) +.fi + +where the log is base 10. The F-nu to F-lambda and F-lambda to F-nu +operators are based on the relation: + +.nf + F-nu = F-lambda * lambda / nu +.fi + +where lambda is wavelength and nu is frequency (currently the wavelength +is assumed to be Angstroms and so F-lambda is in units of per Angstrom +and F-nu is in units of per Hertz). In all the operators it is the +responsibility of user as to the appropriateness of the operator to +the input. + +The binary operators operate on the spectra in the first operand list +and the spectra or numerical constants in the second operand. Numeric +constants are equivalent to spectra having the specified value at all +pixels. The binary operators are the standard arithmetic ones plus +exponentiation and replacement: + +.nf + replace - replace first operand values by second operand values + + - addition + - - subtraction + * - multiplication + / - division + ^ - exponentiation +.fi + +If the second operand is a spectrum, as mentioned previously, it is +interpolated, without flux conservation, to the dispersion +function of the first operand spectrum if necessary. + +There is a distinctions between the first operand and the second operand. +The first operand must always be a spectrum. It supplies the dispersion +function to be matched by the second operand spectrum. It also supplies +a copy of it's image header when a new output spectrum is created. +In cases where it is desired to have the second operand be the +dispersion/header reference and/or the first operand be a constant +the \fIreverse\fR parameter is used. For example to subtract a +spectrum from the constant 1: + +.nf + cl> sarith 1 - spec invspec reverse+ +.fi + +or to subtract two spectra using the subtractand as the dispersion +reference: + +.nf + cl> sarith spec1 - spec2 diff reverse+ +.fi + +When a binary operation on a pair of spectra is performed the aperture +numbers may be required to be the same if \fIignoreaps\fR is no. For +images containing multiple spectra the apertures need not be in the +same order but only that matching apertures exist. If this parameter +is set to yes then aperture numbers are ignored when the operation is +performed. For multiple spectra images the second operand spectra +are matched by image line number rather than by aperture. If the +second operand image has fewer lines, often just one line, then the +last line is used repeatedly. This feature allows multiple spectra +in the primary operand list to be operated upon by a single spectrum; +for example to subtract one spectrum from all spectra in the +in a multiple spectrum image. + +If it is an error to perform an operation on certain data values, for +example division by zero or the square root of a negative number, +then the output value is given the value specified by the parameter +\fIerrval\fR. + +A log of the operations performed may be printed to the standard +output, which may then be redirected if desired, if the \fIverbose\fR +parameter is set. In the output the last bracketed number is the +aperture number of the spectrum. + +INPUT/OUTPUT + +The arithmetic part of \fBsarith\fR is fairly straightforward and +intuitive. The selection of input spectra from input images and +the placing of output spectra in output images can be more confusing +because there are many possibilities. This section concentrates +on the topics of the input and output. Since the concepts apply to all +of the operators it simplifies things to think in terms of copying +input spectra to output spectra; the "copy" operator. Note that the +task \fBscopy\fR is actually just this case of \fBsarith\fR with +parameters set for copying. While the discussion here is similar +to that in the help for \fBscopy\fR, the examples for that task +are more focused for illustrating this topic than the \fBsarith\fR +examples which concentrate more on the arithmetic aspects of +the task. + +Input spectra are specified by an image list which may include explicit +image names, wildcard templates and @files containing image names. +The image names may also include image sections such as to select portions of +the wavelength coverage. The input images may be either one or two +dimensional spectra. One dimensional spectra may be stored in +individual one dimensional images or as lines in two (or three) +dimensional images. The one dimensional spectra are identified by +an aperture number, which must be unique within an image, and a beam number. +Two dimensional long slit and three dimensional Fabry-Perot spectra are +treated, for the purpose of this +task, as a collection of spectra with dispersion either along any axis +specified by the DISPAXIS image header parameter +or the \fIdispaxis\fR package parameter. The aperture and band +parameters specify a spatial position. A number of adjacent +lines, columns, and bands, specified by the \fInsum\fR package parameter, +will be summed to form an aperture spectrum. If number is odd then the +aperture/band number refers to the middle and if it is even it refers to the +lower of the two middle lines or columns. + +In the case of many spectra each stored in separate one dimensional +images, the image names may be such that they have a common root name +and a four digit aperture number extension. This name syntax is +called "onedspec" format. Including such spectra in an +input list may be accomplished either with wildcard templates such as + +.nf + name* + name.????.imh +.fi + +where the image type extension ".imh" must be given to complete the +template but the actual extension could also be that for an STF type +image, or using an @file prepared with the task \fBnames\fR. +To generate this syntax for output images the \fIformat\fR parameter +is set to "onedspec" (this will be discussed further later). + +From the input images one may select a range of wavelengths with the +\fIw1\fR and \fIw2\fR parameters and a subset of spectra based on aperture and +beam numbers using the \fIaperture\fR and \fIbeam\fR parameters. +If the wavelength range is specified as INDEF the full spectra are +used without any resampling. If the aperture and beam lists are not +specified, an empty list, then all apertures and beams are selected. The +lists may be those spectra desired or the complement obtained by prefixing +the list with '!'. Only the selected wavelength range and spectra will +be operated upon and passed on to the output images. + +Specifying a wavelength range is fairly obvious except for the question +of pixel sampling. Either the pixels in the specified range are used +without resampling or the pixels are resampled to correspond eactly +to the requested range. The choice is made with the \fIrebin\fR parameter. +In the first case the nearest pixels to the specified wavelength +endpoints are determined and those pixels and all those in between +are used. The dispersion relation is unchanged. In the second case +the spectra are reinterpolated to have the specified starting and +ending wavelengths with the same number of pixels between those points +as in the original spectrum. The reinterpolation is done in either +linear or log-linear dispersion. The non-linear dispersion functions +are interpolated to a linear dispersion. + +Using \fBsarith\fR with long slit and Fabry-Perot images provides a quick +and simple type of extraction as opposed to using the \fBapextract\fR +package. When summing it is often desired to start each aperture after the +number of lines summed. To do this specify a step size in the aperture/band +list. For example to extract columns 3 to 23 summing every 5 columns you +would use an aperture list of "3-23x5" and an \fInsum\fR of 5. If you do +not use the step in the aperture list you would extract the sum of columns +1 to 5, then columns 2 to 6, and so on. + +In the special case of subapertures extracted by \fBapextract\fR, related +apertures are numbered using a modulus; for example apertures +5, 1005, 2005. To allow selecting all related apertures using a single +aperture number the \fIapmodulus\fR parameter is used to specify the +modulus factor; 1000 in the above example. This is a very specialized +feature which should be ignored by most users. + +The output list of images may consist of an empty list, a single image, +or a list of images matching the input list in number. Note that it +is the number of image names that matters and not the number of spectra +since there may be any number of spectra in an image. The empty list +converts to the same list as the input and is shorthand for replacing +the input image with the output image upon completion; therefore it +is equivalent to the case of a matching list. If the input +consists of just one image then the distinction between a single +output and a matching list is moot. The interesting distinction is +when there is an input list of two or more images. The two cases +are then a mapping of many-to-many or many-to-one. Note that it is +possible to have more complex mappings by repeating the same output +name in a matching list provided clobbering, merging, and possibly +renumbering is enabled. + +In the case of a matching list, spectra from different input images +will go to different output images. In the case of a single output +image all spectra will go to the same output image. Note that in +this discussion an output image when "onedspec" format is specified +is actually a root name for possibly many images. However, +it should be thought of as a single image from the point of view +of image lists. + +When mapping many spectra to a single output image, which may have existing +spectra if merging, there may be a conflict with repeated aperture +numbers. One option is to consecutively renumber the aperture numbers, +including any previous spectra in the output image when merging and then +continuing with the input spectra in the order in which they are selected. +This is specified with the \fIrenumber\fR parameter which renumbers +beginning with 1. + +Another options which may be used independently of renumbering or in +conjunction with it is to add an offset as specified by the \fIoffset\fR +parameter. This is last step in determining the output aperture +numbers so that if used with the renumber option the final aperture +numbers begin with one plus the offset. + +It has been mentioned that it is possible to write and add to +existing images. If an output image exists an error will be +printed unless the \fIclobber\fR parameter is set. If clobbering +is allowed then the existing output image will be replaced by the +new output. Rather than replacing an output image sometimes one +wants to replace certain spectra or add new spectra. This is +done by selecting the \fImerge\fR option. In this case if the output +has a spectrum with the same aperture number as the input spectrum +it is replaced by the input spectrum. If the input spectrum aperture +number is not in the output then the spectrum is added to the output +image. To add spectra with the same aperture number and not +replace the one in the output use the \fIrenumber\fR or +\fIoffset\fR options. +.ih +EXAMPLES +In addition to the examples in this section there are many examples +in the help for \fBscopy\fR which illustrate aspects of selecting +input spectra and producing various types of output. Those examples +are equivalent to using the "copy" operator. The same examples will +also apply with other operators where the input spectra are modified +arithmetically before being copied to the output images. + +I. SIMPLE EXAMPLES + +The simple examples use only a single input image and create a new +output image. + +1. Examples of unary operations: + +.nf + cl> sarith example1 mag "" magexample + cl> sarith magexample lum "" example2 + cl> sarith example1 log "" logexample +.fi + +Note that a place holder for the second operand is required on the command +line which will be ignored. + +2. Examples of binary operations using constants: + +.nf + cl> sarith example1 + 1000 example2 + cl> sarith example1 - 1000 example2 reverse+ + cl> sarith example1 / 1000 example2 + cl> sarith example1 ** 2 example2 +.fi + +3. Examples of binary operations between spectra with matching apertures: + +.nf + cl> sarith example1 + example2 example3 + cl> sarith example1 - example2 example3 +.fi + +4. Example of binary operations between spectra with the second image +consisting of a single spectrum: + +.nf + cl> sarith example1 / flatspec flatexample1 ignore+ errval=1 +.fi + +II. MORE COMPLEX EXAMPLES + +5. Unary and constant operations on a list of images: + +.nf + cl> sarith example* fnu "" %example%fnu% + cl> sarith example* + 1000 %example%fnu% +.fi + +6. Binary operations on a list of images using a single second operand +with matching apertures: + +.nf + cl> sarith example* - skyspec %example%skysub%* +.fi + +7. Selecting apertures to operate upon: + +.nf + cl> sarith example* - skyspec %example%skysub%* aper=1,5,9 +.fi + +8. Extract the sum of each 10 columns in a long slit spectrum and normalize +by the central spectrum: + +.nf + cl> nsum = "10" + cl> sarith longslit copy "" longslit.ms aper=5-500x10 + longslit[5] --> longslit.ms[5] + longslit[15] --> longslit.ms[15] + longslit[25] --> longslit.ms[25] + ... + cl> sarith longslit.ms / longslit.ms[*,25] norm ignore+ + longslit.ms[5] / longslit.ms[*,25][245] --> norm[5] + longslit.ms[15] / longslit.ms[*,25][245] --> norm[15] + longslit.ms[25] / longslit.ms[*,25][245] --> norm[25] + ... +.fi + +9. In place operations: + +.nf + cl> sarith example* + 1000 example* clobber+ + example1[1] + 1000. --> example1[1] + example1[2] + 1000. --> example1[2] + ... + example2[1] + 1000. --> example2[1] + example2[2] + 1000. --> example2[2] + ... + cl> sarith example* flam "" example* clobber+ + example1[1] -- flam --> example1[1] + example1[2] -- flam --> example1[2] + ... + example2[1] -- flam --> example2[1] + example2[2] -- flam --> example2[2] + ... + cl> sarith example* - skyspec "" clobber+ ignore+ + example1[1] + skyspec[1] --> example1[1] + example1[2] + skyspec[1] --> example1[2] + ... + example2[1] + skyspec[1] --> example2[1] + example2[2] + skyspec[1] --> example2[2] + ... +.fi + +10. Merging existing spectra with the results of operations: + +.nf + cl> sarith example* / flat "" clobber+ merge+ renum+ ignor+ +.fi +.ih +REVISIONS +.ls SARITH V2.11 +Previously both w1 and w2 had to be specified to select a range to +be used. Now if only one is specified the second endpoint defaults +to the first or last pixel. + +The noise band in multispec data is only copied from the primary +spectrum and not modified. This is a kludge until the noise is +handled properly. +.le +.ls SARITH V2.10.3 +Additional support for 3D multispec/equispec or spatial spectra has been +added. The "bands" parameter allows selecting specific bands and +the onedspec output format creates separate images for each selected +aperture and band. +.le +.ls SARITH V2.10 +This task is new. +.le +.ih +SEE ALSO +scopy, splot, imarith, imfunction +.endhelp diff --git a/noao/onedspec/doc/sbands.hlp b/noao/onedspec/doc/sbands.hlp new file mode 100644 index 00000000..0bde52ac --- /dev/null +++ b/noao/onedspec/doc/sbands.hlp @@ -0,0 +1,209 @@ +.help sbands Nov93 onedspec +.ih +NAME +sbands -- bandpass spectrophotometry of spectra +.ih +USAGE +sbands input output bands +.ih +PARAMETERS +.ls input +Input list of spectra to be measured. These may be one dimensional +spectra in individual or "multispec" format or calibrated spatial spectra such +as long slit or Fabry-Perot images. The dispersion axis and summing +parameters are specified by package parameters for the spatial spectra. +.le +.ls output +Output file for the results. This may be a filename or "STDOUT" to +write to the terminal. +.le +.ls bands +Bandpass file consisting of lines with one, two, or three bandpasses per +line. A bandpass is specified by an identification string (quoted if it is +null or contains whitespace), the central wavelength, the width of the +bandpass in wavelength, and a filter filename with the special value "none" +if there is no filter (a flat unit response). This format is described +further in the description section. +.le +.ls apertures = "" +List of apertures to select from the input spectra. For one dimensional +spectra this is the aperture number and for spatial spectra it is +the column or line. If the null string is specified all apertures are +selected. The aperture list syntax is a range list which includes +intervals and steps (see \fBranges\fR). +.le +.ls normalize = yes +Normalize the bandpass fluxes by the bandpass response? If no then +the results will depend on the bandpass widths and filter function +values. If yes then fluxes will be comparable to an average pixel +value. When computing indices and equivalent widths the flux must +either be normalized or the bandpasses and filter response functions +must be the same. +.le +.ls mag = no, magzero = 0. +Output the bandpass fluxes as magnitudes with specified magnitude +zero point? +.le +.ls verbose = yes +Include a verbose header giving a banner, the parameters used, +the bandpasses, and column headings? +.le +.ih +DESCRIPTION +\fBSbands\fR performs bandpass spectrophotometry with one or more bandpasses +on one or more spectra. A list of input spectra is specified. The spectra +may be of any type acceptable in the \fBnoao.onedspec\fR package including +multispec format with nonlinear dispersion, long slit spectra, and even +3D cubes with one dispersion axis. The \fIapertures\fR parameter allows +selecting a subset of the spectra by aperture number. + +The bandpasses are specified in a text file. A bandpass consists of four +fields; an identification name, the wavelength of the bandpass center, a +bandpass width, and a filename for a filter. The identification is a +string which must be quoted if a null name or a name with whitespace is +desired. The identification could be given as the central wavelength if +nothing else is appropriate. The filter field is a filename for a text +file containing the filter values. A filter file consists of a wavelength +ordered list of wavelength and relative response. Extrapolation uses the +end point values and interpolation is linear. The special name "none" is +used if there is no filter. This is equivalent to unit response at all +wavelengths. + +In the bandpass file there may be one, two, or three bandpasses on +a line. Below are some examples of the three cases: + +.nf + alpha 5000 10 myalpha.dat + beta1 4000 100 none beta2 4100 100 none + line 4500 100 none red 4000 200 none blue 5000 200 none +.fi + +The flux in each bandpass is measured by summing each pixel in the interval +multiplied by the interpolated filter response at that pixel. At the edges +of the bandpass the fraction of the pixel in the bandpass is used. If the +bandpass goes outside the range of the data an INDEF value will be reported. +If the \fInormalize\fR option is yes then the total flux is divided by +the sum of the filter response values. If the \fImag\fR option is +yes the flux will be converted to a magnitude (provided it is positive) +using the formula + +.nf + magnitude = magzero - 2.5 * log10 (flux) +.fi + +where \fImagzero\fR is a parameter for the zero point magnitude and log10 +is the base 10 logarithm. Note that there is no attempt to deal with the +pixel flux units. This is the responsibility of the user. + +If there is only one bandpass (on one line of the band file) then only +the band flux or magnitude is reported. If there are two bandpasses +the fluxes or magnitudes for the two bands are reported as well as a +band index, the flux ratio or magnitude difference (depending on the \fImag\fR) +flag, and an equivalent width using the second band as the continuum. +If there are three bandpasses then a continuum bandpass flux is computed +as the interpolation between the bandpass centers to the center of the +first bandpass. The special bandpass identification "cont" will +be reported. + +The equivalent width is obtained from the two bandpasses by the +formula + +.nf + eq. width = (1 - flux1 / flux2) * width1 +.fi + +where flux1 and flux2 are the two bandpass fluxes and width1 is the +width of the first bandpass. Note that for this to be meaningful +the bandpasses should be normalized or have the same width/response. + +The results of measuring each bandpass in each spectrum are written +to the specified output file. This file may be given as "STDOUT" to +write the results to the terminal. The output file contains lines +with the spectrum name and aperture, the band identifications and +fluxes or magnitudes, and the band index and equivalent width (if +appropriate). The \fIverbose\fR option allows creating a more +documented output by including a commented header with the task +name and parameters, the bandpass definitions, and column labels. +The examples below show the form of the output. +.ih +EXAMPLES +The following examples use artificial data and arbitrary bands. + +1. Show example results with one, two, and three bandpass entries in +the bandpass file. + +.nf + cl> type bands + test 6125 50 none red 6025 100 none blue 6225 100 none + test 6125 50 none red 6025 100 none + test 6125 50 none blue 6225 100 none + test 6125 50 none + cl> sbands oned STDOUT bands + + # SBANDS: NOAO/IRAF IRAFX valdes@puppis Mon 15:31:45 01-Nov-93 + # bands = bands, norm = yes, mag = no + # band filter wavelength width + # test none 6125. 50. + # red none 6025. 100. + # blue none 6225. 100. + # test none 6125. 50. + # red none 6025. 100. + # test none 6125. 50. + # blue none 6225. 100. + # test none 6125. 50. + # + # spectrum band flux band flux index eqwidth + oned(1) test 44.33 cont 97.97 0.45 27.37 + oned(1) test 44.33 red 95.89 0.46 26.89 + oned(1) test 44.33 blue 100.04 0.44 27.84 + oned(1) test 44.33 +.fi + +2. This example shows measurements on a long slit spectrum with an +aperture selection and magnitude output. + +.nf + cl> type lsbands.dat + band1 4500 40 none + band2 4600 40 none + band3 4700 40 none + cl> nsum=5 + cl> sbands ls STDOUT lsbands.dat apertures=40-60x5 mag+ magzero=10.1 + + # SBANDS: NOAO/IRAF IRAFX valdes@puppis Mon 15:37:18 01-Nov-93 + # bands = lsbands.dat, norm = yes, mag = yes, magzero = 10.10 + # band filter wavelength width + # band1 none 4500. 40. + # band2 none 4600. 40. + # band3 none 4700. 40. + # + # spectrum band mag + ls[38:42,*](40) band1 3.14 + ls[38:42,*](40) band2 3.19 + ls[38:42,*](40) band3 3.15 + ls[43:47,*](45) band1 3.13 + ls[43:47,*](45) band2 3.15 + ls[43:47,*](45) band3 3.14 + ls[48:52,*](50) band1 2.34 + ls[48:52,*](50) band2 2.43 + ls[48:52,*](50) band3 2.43 + ls[53:57,*](55) band1 3.10 + ls[53:57,*](55) band2 3.15 + ls[53:57,*](55) band3 3.12 + ls[58:62,*](60) band1 3.14 + ls[58:62,*](60) band2 3.19 + ls[58:62,*](60) band3 3.15 +.fi +.ih +REVISIONS +.ls SBANDS V2.10.4 +The flux column is now printed to 6 digits of precision with possible +exponential format to permit flux calibrated spectra to print properly. +.le +.ls SBANDS V2.10.3 +The task is new in this release +.le +.ih +SEE ALSO +splot +.endhelp diff --git a/noao/onedspec/doc/scombine.hlp b/noao/onedspec/doc/scombine.hlp new file mode 100644 index 00000000..06e63003 --- /dev/null +++ b/noao/onedspec/doc/scombine.hlp @@ -0,0 +1,765 @@ +.help scombine Sep97 noao.onedspec +.ih +NAME +scombine -- Combine spectra +.ih +USAGE +scombine input output +.ih +PARAMETERS +.ls input +List of input images containing spectra to be combined. The spectra +in the images to be combined are selected with the \fIapertures\fR and +\fIgroup\fR parameters. Only the primary spectrum is combined and +the associated band spectra are ignored. +.le +.ls output +List of output images to be created containing the combined spectra. +If the grouping option is "all" +or "apertures" then only one output image will be created. In the +first case the image will contain only one spectrum and in the latter case +there will be a spectrum for each selected aperture. +If the grouping option is "images" then there will be one +output spectrum per input spectrum. +.le +.ls noutput = "" +List of output images to be created containing the number of spectra combined. +The number of images required is the same as the \fIoutput\fR list. +Any or all image names may be given as a null string, i.e. "", in which +case no output image is created. +.le +.ls logfile = "STDOUT" +File name for recording log information about the combining operation. +The file name "STDOUT" is used to write the information to the terminal. +If the null string is specified then no log information is printed or +recorded. +.le + +.ls apertures = "" +List of apertures to be selected for combining. If none is specified +then all apertures are selected. The syntax is a blank or comma separated +list of aperture numbers or aperture ranges separated by a hyphen. +.le +.ls group = "apertures" (all|images|apertures) +Option for grouping input spectra for combining (after selection by aperture) +from one or more input images. The options are: +.ls "all" +Combine all spectra from all images in the input list into a single output +spectrum. +.le +.ls "images" +Combine all spectra in each input image into a single spectrum in +separate output images. +.le +.ls "apertures" +Combine all spectra of the same aperture from all input images and put it +into a single output image with the other selected apertures. +.le +.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 first two are applied after any pixel +rejection. The sum option ignores the rejection and scaling parameters and +no rejection is performed. In other words, the "sum" option is simply the +direct summation 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|ccdclip|crreject|sigclip|avsigclip|pclip) +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 + sigclip - Reject pixels using a sigma clipping algorithm + avsigclip - Reject pixels using an averaged sigma clipping algorithm + ccdclip - Reject pixels using CCD noise parameters + crreject - Reject only positive pixels using CCD noise parameters + pclip - Reject pixels using sigma based on percentiles +.fi + +.le + +.ls first = no +Use the first input spectrum of each set to be combined to define the +dispersion coordinates for combining and output? If yes then all other +spectra to be combined will be interpolated to the dispersion of this +reference spectrum and that dispersion defines the dispersion of the +output spectrum. If no, then all the spectra are interpolated to a linear +dispersion as determined by the following parameters. The interpolation +type is set by the package parameter \fIinterp\fR. +.le +.ls w1 = INDEF, w2=INDEF, dw = INDEF, nw = INDEF, log = no +The output linear or log linear wavelength scale if the dispersion of the +first spectrum is not used. INDEF values are filled in from the maximum +wavelength range and minimum dispersion of the spectra to be combined. The +parameters are aways specified in linear wavelength even when the log +parameter is set to produce constant pixel increments in the log of the +wavelength. The dispersion is interpreted in that case as the difference +in the log of the endpoints divided by the number of pixel increments. +.le + +.ls scale = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Multiplicative image scaling to be applied. The choices are none, +multiply by the reciprocal of the mode , median, or mean of the specified +statistics section, scale by the exposure time in the image header, multiply +by the values in a specified file, or multiply by a specified image header +keyword. When specified in a file the scales must be one per line in the +order of the input spectra. +.le +.ls zero = "none" (none|mode|median|mean|@<file>|!<keyword>) +Additive zero level image shifts to be applied. The choices are none, +add the negative of the mode, median, or mean of the specified statistics +section, add the values given in a file, or add values given by an +image header keyword. When specified in a file the zero values must be one +per line in the order of the input spectra. File or keyword zero offset +values do not allow a correction to the weights. +.le +.ls weight = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Weights to be applied during the final averaging. The choices are none, +the mode, median, or mean of the specified statistics section, the exposure +time, values given in a file, or values given by an image header keyword. +When specified in a file the weights must be one per line in the order of +the input spectra. +.le +.ls sample = "" +Wavelength sample regions to use in computing spectrum statistics for +scaling and weighting. If no sample regions are given then the entire +input spectrum is used. The syntax is colon separated wavelengths +or a file containing colon separated wavelengths preceded by the +@ character; i.e. @<file>. +.le + +.ce +Algorithm Parameters +.ls lthreshold = INDEF, hthreshold = INDEF +Low and high thresholds to be applied to the input pixels. This is done +before any scaling, rejection, and combining. If INDEF the thresholds +are not used. +.le +.ls nlow = 1, nhigh = 1 (minmax) +The number of low and high pixels to be rejected by the "minmax" algorithm. +These numbers are converted to fractions of the total number of input spectra +so that if no rejections have taken place the specified number of pixels +are rejected while if pixels have been rejected by thresholding +or nonoverlap, then the fraction of the remaining pixels, truncated +to an integer, is used. +.le +.ls nkeep = 1 +The minimum number of pixels to retain or the maximum number to reject +when using the clipping algorithms (ccdclip, crreject, sigclip, +avsigclip, or pclip). When given as a positive value this is the minimum +number to keep. When given as a negative value the absolute value is +the maximum number to reject. This is actually converted to a number +to keep by adding it to the number of images. +.le +.ls mclip = yes (ccdclip, crreject, sigclip, avsigcliip) +Use the median as the estimate for the true intensity rather than the +average with high and low values excluded in the "ccdclip", "crreject", +"sigclip", and "avsigclip" algorithms? The median is a better estimator +in the presence of data which one wants to reject than the average. +However, computing the median is slower than the average. +.le +.ls lsigma = 3., hsigma = 3. (ccdclip, crreject, sigclip, avsigclip, pclip) +Low and high sigma clipping factors for the "ccdclip", "crreject", "sigclip", +"avsigclip", and "pclip" algorithms. They multiply a "sigma" factor +produced by the algorithm to select a point below and above the average or +median value for rejecting pixels. The lower sigma is ignored for the +"crreject" algorithm. +.le +.ls rdnoise = "0.", gain = "1.", snoise = "0." (ccdclip, crreject) +Effective CCD readout noise in electrons, gain in electrons/DN, and +sensitivity noise as a fraction. These parameters are used with the +"ccdclip" and "crreject" algorithms. The values may be either numeric or +an image header keyword which contains the value. Note that if the spectra +have been extracted from a 2D CCD image then the noise parameters must be +adjusted for background and the aperture summing. +.le +.ls sigscale = 0.1 (ccdclip, crreject, sigclip, avsigclip) +This parameter determines when poisson corrections are made to the +computation of a sigma for images with different scale factors. If all +relative scales are within this value of unity and all relative zero level +offsets are within this fraction of the mean then no correction is made. +The idea is that if the images are all similarly though not identically +scaled, the extra computations involved in making poisson corrections for +variations in the sigmas can be skipped. A value of zero will apply the +corrections except in the case of equal images and a large value can be +used if the sigmas of pixels in the images are independent of scale and +zero level. +.le +.ls pclip = -0.5 (pclip) +Percentile clipping algorithm parameter. If greater than +one in absolute value then it specifies a number of pixels above or +below the median to use for computing the clipping sigma. If less +than one in absolute value then it specifies the fraction of the pixels +above or below the median to use. A positive value selects a point +above the median and a negative value selects a point below the median. +The default of -0.5 selects approximately the quartile point. +See the DESCRIPTION section for further details. +.le +.ls grow = 0 +Number of pixels to either side of a rejected pixel +to also be rejected. This applies only to pixels rejected by one of +the rejection algorithms and not the threshold rejected pixels. +.le +.ls blank = 0. +Value to use when there are no input pixels to combine for an output pixel. +.le +.ih +DESCRIPTION +\fBScombine\fR combines input spectra by interpolating them (if necessary) +to a common dispersion sampling, rejecting pixels exceeding specified low +and high thresholds, scaling them in various ways, applying a rejection +algorithm based on known or empirical noise statistics, and computing the +sum, weighted average, or median of the remaining pixels. Note that +the "sum" option is the direct summation of the pixels and does not +perform any rejection or scaling of the data regardless of the parameter +settings. + +The input spectra are specified using an image list in which each image +may contain multiple spectra. The set of spectra may be restricted +by the \fIaperture\fR parameter to specific apertures. The set of input +spectra may then be grouped using the \fIgroup\fR parameter and each +group combined separately into a final output spectrum. The grouping +options are to select all the input spectra regardless of the input +image or aperture number, select all spectra of the same aperture, +or select all the spectra from the same input image. + +The output consists of either a single image with one spectrum for each +combined group or, when grouping by image, an image with the single +combined spectra from each input image. The output images and +combined spectra inherit the header parameters from the first spectrum +of the combined group. In addition to the combined spectrum an associated +integer spectrum containing the number of pixels combined +and logfile listing the combined spectra, scaling, weights, etc, may +be produced. + +The spectral combining is done using pixels at common dispersion +coordinates rather than physical or logical pixel coordinates. If the +spectra to be combined do not have identical dispersion coordinates then +the spectra are interpolated to a common dispersion sampling before +combining. The interpolation conserves pixel values rather pixel fluxes. +This means that flux calibrated data is treated correctly and that +spectra in counts are not corrected in the interpolation for changes +in pixel widths. +The default interpolation function is a 5th order polynomial. The +choice of interpolation type is made with the package parameter "interp". +It may be set to "nearest", "linear", "spline3", "poly5", or "sinc". +Remember that this applies to all tasks which might need to interpolate +spectra in the \fBonedspec\fR and associated packages. For a discussion of +interpolation types see \fBonedspec\fR. + +There are two choices for the common dispersion coordinate sampling. If the +\fIfirst\fR parameter is set then the dispersion sampling of the first +spectrum is used. This dispersion system may be nonlinear. If the +parameter is not set then the user specified linear or log linear +dispersion system is used. Any combination of starting wavelength, ending +wavelength, wavelength per pixel, and number of output pixels may be +specified. Unspecified values will default to reasonable values based on +the minimum or maximum wavelengths of all spectra, the minimum dispersion, +and the number of pixels needed to satisfy the other parameters. If the +parameters overspecify the linear system then the ending wavelength is +adjusted based on the other parameters. Note that for a log linear system +the wavelengths are still specified in nonlog units and the dispersion is +finally recalculated using the difference of the log wavelength endpoints +divided by the number pixel intervals (the number of pixels minus one). + +There are several stages to combining a selected group of spectra. The +first is interpolation to a common dispersion sampling as discussed +above. The second stage is to eliminate any pixels outside the specified +thresholds. Note that the thresholds apply to the interpolated +spectra. Scaling and zero offset factors are computed and applied to the +spectra if desire. The computation of these factors as well as weights is +discussed in the following section. Next there is a choice of rejection +algorithms to identify and eliminate deviant pixels. Some of these are +based on order statistics and some relative to the distance from an initial +median or average using a noise model cutoff. A growing factor may be +applied to neighbors of rejected pixels to reject additional pixels. The +various algorithms are described in detail in a following section. +Finally, the remaining pixels are combined by summing (which may not be +appropriate when pixels are rejected), computing a median, or computing a +weighted or unweighted average. The combined spectrum is written to an +output image as well the number of pixels used in the final combining. + +SCALES AND WEIGHTS + +In order to combine spectra with rejection of pixels based on deviations +from some average or median they must be scaled to a common level. There +are two types of scaling available, a multiplicative intensity scale and an +additive zero point shift. The intensity scaling is defined by the +\fIscale\fR parameter and the zero point shift by the \fIzero\fR +parameter. These parameters may take the values "none" for no scaling, +"mode", "median", or "mean" to scale by statistics of the spectrum pixels, +"exposure" (for intensity scaling only) to scale by the exposure time +keyword in the image header, any other image header keyword specified by +the keyword name prefixed by the character '!', and the name of a file +containing the scale factors for the input image prefixed by the +character '@'. + +Examples of the possible parameter values are shown below where +"myval" is the name of an image header keyword and "scales.dat" is +a text file containing a list of scale factors. + +.nf + scale = none No scaling + zero = mean Intensity offset by the mean + scale = exposure Scale by the exposure time + zero = !myval Intensity offset by an image keyword + scale = @scales.dat Scales specified in a file +.fi + +The spectrum statistics factors are computed within specified sample +regions given as a series of colon separated wavelengths. If no +regions are specified then all pixels are used. If the +wavelength sample list is too long the regions can be defined in a file and +specified in the \fIsample\fR parameter using the syntax @<file> where file +is the filename. + +The statistics are as indicated by their names. In particular, the +mode is a true mode using a bin size which is a fraction of the +range of the pixels and is not based on a relationship between the +mode, median, and mean. Also thresholded pixels are excluded from the +computations as well as during the rejection and combining operations. + +The "exposure" option in the intensity scaling uses the value of the image +header keyword (EXPTIME, EXPOSURE, or ITIME). Note that the exposure +keyword is also updated in the final image as the weighted average of the +input values. If one wants to use a nonexposure time keyword and keep the +exposure time updating feature the image header keyword syntax is +available; i.e. !<keyword>. + +Scaling values may be defined as a list of values in a text file. The file +name is specified by the standard @file syntax. The list consists of one +value per line. The order of the list is assumed to be the same as the +order of the input spectra. It is a fatal error if the list is incomplete +and a warning if the list appears longer than the number of input spectra. +Consideration of the grouping parameter must be included in +generating this list since spectra may come from different images, +some apertures may be missing, and, when there are multiple output spectra +or images, the same list will be repeatedly used. + +If both an intensity scaling and zero point shift are selected the +multiplicative scaling is done first. Use of both makes sense for images +if the intensity scaling is the exposure time to correct for +different exposure times and with the zero point shift allowing for +sky brightness changes. This is less relevant for spectra but the option +is available. + +The spectrum statistics and scale factors are recorded in the log file +unless they are all equal, which is equivalent to no scaling. The +intensity scale factors are normalized to a unit mean and the zero +point shifts are adjusted to a zero mean. When scal factors +or zero point shifts are specified by the user in an @file or by an +image header keyword, no normalization is done. + +Scaling affects not only the mean values between spectra but also the +relative pixel uncertainties. For example scaling an spectrum by a +factor of 0.5 will reduce the effective noise sigma of the spectrum +at each pixel by the square root of 0.5. Changes in the zero +point also changes the noise sigma if the spectrum noise characteristics +are Poissonian. In the various rejection algorithms based on +identifying a noise sigma and clipping large deviations relative to +the scaled median or mean, one may need to account for the scaling induced +changes in the spectrum noise characteristics. + +In those algorithms it is possible to eliminate the "sigma correction" +while still using scaling. The reasons this might be desirable are 1) if +the scalings are similar the corrections in computing the mean or median +are important but the sigma corrections may not be important and 2) the +spectrum statistics may not be Poissonian, either inherently or because the +spectra have been processed in some way that changes the statistics. In the +first case because computing square roots and making corrections to every +pixel during the iterative rejection operation may be a significant +computational speed limit the parameter \fIsigscale\fR selects how +dissimilar the scalings must be to require the sigma corrections. This +parameter is a fractional deviation which, since the scale factors are +normalized to unity, is the actual minimum deviation in the scale factors. +For the zero point shifts the shifts are normalized by the mean shift +before adjusting the shifts to a zero mean. To always use sigma scaling +corrections the parameter is set to zero and to eliminate the correction in +all cases it is set to a very large number. + +If the final combining operation is "average" then the spectra may be +weighted during the averaging. The weights are specified in the same way +as the scale factors. The weights, scaled to a unit sum, are printed in +the log output. + +The weights are only used for the final weighted average and sigma image +output. They are not used to form averages in the various rejection +algorithms. For weights in the case of no scaling or only multiplicative +scaling the weights are used as given or determined so that images +with lower signal levels will have lower weights. However, for +cases in which zero level scaling is used the weights are computed +from the initial weights (the exposure time, image statistics, or +input values) using the formula: + +.nf + weight_final = weight_initial / (scale * zero) +.fi + +where the zero values are those before adjustment to zero mean over +all images. The reasoning is that if the zero level is high the sky +brightness is high and so the S/N is lower and the weight should be lower. + + +THRESHOLD REJECTION + +There is an initial threshold rejection step which may be applied. The +thresholds are given by the parameters \fIlthreshold\fR and +\fIhthreshold\fR. Values of INDEF mean that no threshold value is +applied. Threshold rejection may be used to exclude very bad pixel values +or as a way of masking images. The former case is useful to exclude very +bright cosmic rays. Some of the rejection algorithms, such as "avsigclip", +can perform poorly if very strong cosmic rays are present. For masking one +can use a task like \fBimedit\fR or \fBimreplace\fR to set parts of the +spectra to be excluded to some very low or high magic value. + + +REJECTION ALGORITHMS + +The \fIreject\fR parameter selects a type of rejection operation to +be applied to pixels not thresholded. If no rejection +operation is desired the value "none" is specified. This task is +closely related to the image combining task \fBimcombine\fR and, in +particular, has the same rejection algorithms. +Some the algorithms are more appropriate to images but are available +in this task also for completeness. + +MINMAX +.in 4 +A specified fraction of the highest and lowest pixels are rejected. +The fraction is specified as the number of high and low pixels, the +\fInhigh\fR and \fInlow\fR parameters, when data from all the input spectra +are used. If pixels are missing where there is no overlap or have been +rejected by thresholding then a matching fraction of the remaining pixels, +truncated to an integer, are used. Thus, + +.nf + nl = n * nlow/nspectra + 0.001 + nh = n * nhigh/nspectra + 0.001 +.fi + +where n is the number of pixels to be combined, nspectra is the number +of input spectra, nlow and nhigh +are task parameters and nl and nh are the final number of low and +high pixels rejected by the algorithm. The factor of 0.001 is to +adjust for rounding of the ratio. + +As an example with 10 input spectra and specifying one low and two high +pixels to be rejected the fractions to be rejected are 0.1 and 0.2 +and the number rejected as a function of n is: + +.nf + n 0 1 2 3 4 5 6 7 8 9 10 + nl 0 0 0 0 0 1 1 1 1 1 2 + nh 0 0 0 0 0 0 0 0 0 0 1 +.fi +.in -4 +CCDCLIP +.in 4 +If the noise characteristics of the spectra can be described by fixed +gaussian noise, a poissonian noise which scales with the square root of +the intensity, and a sensitivity noise which scales with the intensity, +the sigma in data values at a pixel with true value <I>, +as approximated by the median or average with the lowest and highest value +excluded, is given as: + +.nf + sigma = ((rn / g) ** 2 + <I> / g + (s * <I>) ** 2) ** 1/2 +.fi + +where rn is the read out noise in electrons, g is the gain in +electrons per data value, s is a sensitivity noise given as a fraction, +and ** is the exponentiation operator. Often the sensitivity noise, +due to uncertainties in the pixel sensitivities (for example from the +flat field), is not known in which case a value of zero can be used. + +This model is typically valid for CCD images. During extraction of +spectra from CCD images the noise parameters of the spectrum pixels +will be changed from those of the CCD pixels. Currently it is up to +the user to determine the proper modifications of the CCD read noise +gain, and sensitivity noise. + +The read out noise is specified by the \fIrdnoise\fR parameter. The value +may be a numeric value to be applied to all the input spectra or an image +header keyword containing the value for spectra from each image. +Similarly, the parameter \fIgain\fR specifies the gain as either a value or +image header keyword and the parameter \fIsnoise\fR specifies the +sensitivity noise parameter as either a value or image header keyword. + +The algorithm operates on each output pixel independently. It starts by +taking the median or unweighted average (excluding the minimum and maximum) +of the unrejected pixels provided there are at least two input pixels. The +expected sigma is computed from the CCD noise parameters and pixels more +that \fIlsigma\fR times this sigma below or \fIhsigma\fR times this sigma +above the median or average are rejected. The process is then iterated +until no further pixels are rejected. If the average is used as the +estimator of the true value then after the first round of rejections the +highest and lowest values are no longer excluded. Note that it is possible +to reject all pixels if the average is used and is sufficiently skewed by +bad pixels such as cosmic rays. + +If there are different CCD noise parameters for the input images +(as might occur using the image header keyword specification) then +the sigmas are computed for each pixel from each image using the +same estimated true value. + +If the images are scaled and shifted and the \fIsigscale\fR threshold +is exceedd then a sigma is computed for each pixel based on the +spectrum scale parameters; i.e. the median or average is scaled to that of the +original image before computing the sigma and residuals. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +This is the best clipping algorithm to use if the CCD noise parameters are +adequately known. The parameters affecting this algorithm are \fIreject\fR +to select this algorithm, \fImclip\fR to select the median or average for +the center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, the CCD noise parameters \fIrdnoise, gain\fR and \fIsnoise\fR, +\fIlsigma\fR and \fIhsigma\fR to select the clipping thresholds, +and \fIsigscale\fR to set the threshold for making corrections to the sigma +calculation for different image scale factors. + +.in -4 +CRREJECT +.in 4 +This algorithm is identical to "ccdclip" except that only pixels above +the average are rejected based on the \fIhsigma\fR parameter. This +is appropriate for rejecting cosmic ray events and works even with +two spectra. + +.in -4 +SIGCLIP +.in 4 +The sigma clipping algorithm computes at each output pixel the median or +average excluding the high and low values and the sigma about this +estimate. There must be at least three input pixels, though for this method +to work well there should be at least 10 pixels. Values deviating by more +than the specified sigma threshold factors are rejected. These steps are +repeated, except that after the first time the average includes all values, +until no further pixels are rejected or there are fewer than three pixels. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +rejection. + +The parameters affecting this algorithm are \fIreject\fR to select +this algorithm, \fImclip\fR to select the median or average for the +center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, \fIlsigma\fR and \fIhsigma\fR to select the +clipping thresholds, and \fIsigscale\fR to set the threshold for +making corrections to the sigma calculation for different spectrum scale +factors. + +.in -4 +AVSIGCLIP +.in 4 +The averaged sigma clipping algorithm assumes that the sigma about the +median or mean (average excluding the low and high values) is proportional +to the square root of the median or mean at each point. This is +described by the equation: + +.nf + sigma(column,line) = sqrt (gain(line) * signal(column,line)) +.fi + +where the \fIestimated\fR signal is the mean or median (hopefully excluding +any bad pixels) and the gain is the \fIestimated\fR proportionality +constant having units of photons/data number. + +This noise model is valid for spectra whose values are proportional to the +number of photons recorded. In effect this algorithm estimates a +photon per data value gain for each spectrum. +The gain proportionality factor is computed +independently for each output spectrum by averaging the square of the residuals +(at points having three or more input values) scaled by the median or +mean. + +Once the proportionality factor is determined, deviant pixels exceeding the +specified thresholds are rejected at each point by estimating the sigma +from the median or mean. If any values are rejected the median or mean +(this time not excluding the extreme values) is recomputed and further +values rejected. This is repeated until there are no further pixels +rejected or the number of remaining input values falls below three. Note +that the proportionality factor is not recomputed after rejections. + +If the spectra are scaled differently and the sigma scaling correction +threshold is exceedd then a correction is made in the sigma +calculations for these differences, again under the assumption that +the noise in an spectra scales as the square root of the mean intensity. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +rejection. + +This algorithm works well for even a few input spectra. It works better if +the median is used though this is slower than using the average. Note that +if the spectra have a known read out noise and gain (the proportionality +factor above) then the "ccdclip" algorithm is superior. However, currently +the CCD noise characteristics are not well propagated during extraction so +this empirical algorithm is the one most likely to be useful. The two +algorithms are related in that the average sigma proportionality factor is +an estimate of the gain. + +The parameters affecting this algorithm are \fIreject\fR to select +this algorithm, \fImclip\fR to select the median or average for the +center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, \fIlsigma\fR and \fIhsigma\fR to select the +clipping thresholds, and \fIsigscale\fR to set the threshold for +making corrections to the sigma calculation for different image scale +factors. + +.in -4 +PCLIP +.in 4 +The percentile clipping algorithm is similar to sigma clipping using the +median as the center of the distribution except that, instead of computing +the sigma of the pixels from the CCD noise parameters or from the data +values, the width of the distribution is characterized by the difference +between the median value and a specified "percentile" pixel value. This +width is then multipled by the scale factors \fIlsigma\fR and \fIhsigma\fR +to define the clipping thresholds above and below the median. The clipping +is not iterated. + +The pixel values at each output point are ordered in magnitude and the +median is determined. In the case of an even number of pixels the average +of the two middle values is used as the median value and the lower or upper +of the two is the median pixel when counting from the median pixel to +selecting the percentile pixel. The parameter \fIpclip\fR selects the +percentile pixel as the number (if the absolute value is greater +than unity) or fraction of the pixels from the median in the ordered set. +The direction of the percentile pixel from the median is set by the sign of +the \fIpclip\fR parameter with a negative value signifying pixels with +values less than the median. Fractional values are internally converted to +the appropriate number of pixels for the number of input spectra. A minimum +of one pixel and a maximum corresponding to the extreme pixels from the +median are enforced. The value used is reported in the log output. Note +that the same percentile pixel is used even if pixels have been rejected by +nonoverlap or thresholding; for example, if the 3nd pixel below +the median is specified then the 3rd pixel will be used whether there are +10 pixels or 5 pixels remaining after the preliminary steps. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +Some examples help clarify the definition of the percentile pixel. In the +examples assume 10 pixels. The median is then the average of the +5th and 6th pixels. A \fIpclip\fR value of 2 selects the 2nd pixel +above the median (6th) pixel which is the 8th pixel. A \fIpclip\fR +value of -0.5 selects the point halfway between the median and the +lowest pixel. In this case there are 4 pixels below the median, +half of that is 2 pixels which makes the percentile pixel the 3rd pixel. + +The percentile clipping algorithm is most useful for clipping small +excursions, such as the wings of bright lines when combining +disregistered observations, that are missed when using +the pixel values to compute a sigma. It is not as powerful, however, as +using the CCD noise parameters (provided they are accurately known) to clip +about the median. This algorithm is primarily used with direct images +but remains available for spectra. + +The parameters affecting this algorithm are \fIreject\fR to select this +algorithm, \fIpclip\fR to select the percentile pixel, \fInkeep\fR to limit +the number of pixels rejected, and \fIlsigma\fR and \fIhsigma\fR to select +the clipping thresholds. + + +.in -4 +GROW REJECTION + +Neighbors of pixels rejected by the rejection algorithms +may also be rejected. The number of neighbors to be rejected on either +side is specified by the \fIgrow\fR parameter. + +This rejection step is also checked against the \fInkeep\fR parameter +and only as many pixels as would not violate this parameter are +rejected. Unlike it's application in the rejection algorithms at +this stage there is no checking on the magnitude of the residuals +and the pixels retained which would otherwise be rejected are randomly +selected. + + +COMBINING + +After all the steps of offsetting the input images, masking pixels, +threshold rejection, scaling, and applying a rejection algorithms the +remaining pixels are combined and output. The pixels may be combined +by computing the median or by computing a weighted average. +.ih +EXAMPLES +1. Combine orders of echelle images. + +.nf + cl> scombine *.ec *%.ec%% group=images combine=sum +.fi + +2. Combine all spectra using range syntax and scale by the exposure times. + +.nf + cl> names irs 10-42 > irs.dat + cl> scombine @irs.dat irscombine group=all scale=exptime +.fi + +3. Combine spectra by apertures using exposure time scaling and weighting. + +.nf + cl> scombine *.ms combine.ms nout=ncombine.ms \\ + >>> group=apertures scale=exptime weights=exptime +.fi +.ih +REVISIONS +.ls SCOMBINE V2.10.3 +The weighting was changed from using the square root of the exposure time +or spectrum statistics to using the values directly. This corresponds +to variance weighting. Other options for specifying the scaling and +weighting factors were added; namely from a file or from a different +image header keyword. The \fInkeep\fR parameter was added to allow +controlling the maximum number of pixels to be rejected by the clipping +algorithms. The \fIsnoise\fR parameter was added to include a sensitivity +or scale noise component to the noise model. +.le +.ls SCOMBINE V2.10 +This task is new. +.le +.ih +NOTES +The pixel uncertainties and CCD noise model are not well propagated. In +particular it would be desirable to propagate the pixel uncertainties +and CCD noise parameters from the initial CCD images. +.ih +SEE ALSO +imcombine, odcombine, lscombine +.endhelp diff --git a/noao/onedspec/doc/scoords.hlp b/noao/onedspec/doc/scoords.hlp new file mode 100644 index 00000000..9a529ffa --- /dev/null +++ b/noao/onedspec/doc/scoords.hlp @@ -0,0 +1,83 @@ +.help scoords May97 onedspec +.ih +NAME +scoords -- set spectrum coordinates from a pixel array (1D only) +.ih +USAGE +scoords images coords +.ih +PARAMETERS +.ls images +List of one dimensional spectrum image names. +.le +.ls coords +List of file names containing the coordinate values. There may be +one file which applies to all input images or a matching list +of one coordinate file for each input image. The coordinate files +are a list of coordinate values with one coordinate per line. +The coordinates must be ordered in increasing or decreasing value. +The number of coordinates must match the number of pixels in the image. +.le +.ls label = "" +Optional coordinate axis label. A typical value is "Wavelength" +for wavelength coordinates. +.le +.ls units = "" +Optional coordinate axis units. A typical value is "Angstroms". In +order to allow coordinate conversions by other IRAF spectra tasks +the value should be specified as one of the known units +(see units description in \fBonedspec.package\fR). +.le +.ls verbose = yes +Print a line as each spectrum is processed? +.le +.ih +DESCRIPTION +\fBScoords\fR sets spectral coordinates in one dimensional spectral +images as a list of coordinates in the image header. The +coordinate file(s) consists of coordinate values given one per line. +Each coordinate value is assigned to an image pixel in the order given +and so the number of coordinate values must match the number of pixels +in the spectrum. Also the coordinates must be monotonically increasing +or decreasing. + +When multiple spectra are to be set a matching list of coordinates can +be specified or a single coordinate file for all images may be used. + +The coordinate system set in the header is an example of the "multispec" +world coordinate system. This is understood by all the standard +IRAF tasks. It is described under the help topic "onedspec.specwcs". +Once the coordinates are set one may resample the spectrum to a +more compact linear description using the task \fBdispcor\fR. + +Since the coordinate values are stored in the header (double +precision numbers) the header can become quite large if the spectrum +is long. Be sure the environment variable "min_lenuserarea" which +defines the maximum size of the image header in number of characters +is large enough to hold all the coordinates. +.ih +EXAMPLES +1. Set the coordinates for a spectrum. + +.nf + cl> type coords.dat + 4000. + 4010.123 + 4020.246 + 4031.7 + <etc> + cl> scoords spec coords.dat label=Wavelength units=Angstroms + cl> listpix spec wcs=world + 4000. 124. + 4010.123 543 + <etc> +.fi +.ih +REVISIONS +.ls SCOORDS V2.11 +This is a new task with this version. +.le +.ih +SEE ALSO +rtextimage, dispcor, specwcs, onedspec.package +.endhelp diff --git a/noao/onedspec/doc/scopy.hlp b/noao/onedspec/doc/scopy.hlp new file mode 100644 index 00000000..d0863687 --- /dev/null +++ b/noao/onedspec/doc/scopy.hlp @@ -0,0 +1,541 @@ +.help scopy Mar93 noao.onedspec +.ih +NAME +scopy -- Select and copy spectra +.ih +USAGE +scopy input output +.ih +PARAMETERS +.ls input +List of input images containing spectra to be copied. +.le +.ls output +List of output image names or root names. Image +sections are ignored and if the output format is "onedspec" then any record +extensions are stripped to form the root name. If no output list is +specified then the input list is used and the input images are replaced by +the copied output spectra. If a single output name is specified then all +copied spectra are written to the same output image or image root +name. This allows packing or merging multiple spectra and requires +properly setting the \fIclobber\fR, \fImerge\fR, \fIrenumber\fR and +\fIoffset\fR parameters to achieve the desired output. If more than one +output image is specified then it must match the input image list in +number. +.le +.ls w1 = INDEF, w2 = INDEF +Starting and ending wavelengths to be copied. If \fIw1\fR is not specified +then the wavelength of the starting edge of the first pixel is used +(wavelength at pixel coordinate 0.5) and if \fIw2\fR is not specified then +the wavelength of the ending edge of the last pixel is used (wavelength of +the last pixel plus 0.5). If both are not specified, that is set to INDEF, +then the whole spectrum is copied and the \fIrebin\fR parameter is +ignored. Note that by specifying both endpoints the copied region can be +set to have increasing or decreasing wavelength per pixel. If the spectrum +only partially covers the specified range only that portion of the spectrum +within the range is copied. It is an error if the range is entirely +outside that of a spectrum. +.le +.ls apertures = "", beams = "" +List of apertures and beams to be selected from the input spectra. The +logical intersection of the two lists is selected. The null list +selects all apertures or beams. A list consists of comma separated +numbers and ranges of numbers. A range is specified by a hyphen. An +optional step size may be given by 'x' followed by a number. +See \fBxtools.ranges\fR for more information. If the first character +is "!" then the apertures/beams not in the list are selected. Note +that a "!" in either of the lists complements the intersection of the +two lists. For longslit input spectra the aperture numbers +selects the lines or columns to be extracted. For 3D Fabry-Perot +spectra the aperture numbers select the first spatial axis. +.le +.ls bands = "" +List of bands in 3D multispec. +For 3D spatial spectra the band parameter applies to the second +spatial axis. +The null list selects all bands. The syntax is as described above. +.le +.ls apmodulus = 0 +Modulus to be applied to the input aperture numbers before matching against +the aperture list. If zero then no modulus is used. This is allows +selecting apertures which are related by the same modulus, typically a +factor of 10; for example, 10, 1010 and 2010 with a modulus of 1000 are +related. +.le +.ls format = "multispec" (multispec|onedspec) +Output image format and name syntax. The "multispec" format consists of +one or more spectra in the same image file. The "onedspec" format consists +of a single spectrum per image with names having a root name and a four +digit aperture number extension. Note that converting to "onedspec" format +from three dimensional images where the third dimension contains associated +spectra will not include data from the extra dimension. Image sections may +be used in that case. +.le +.ls renumber = no +Renumber the output aperture numbers? If set the output aperture +numbers, including any preexisting spectra when merging, are renumbered +beginning with 1. The \fIoffset\fR parameter may be used to +change the starting number. +.le +.ls offset = 0 +Offset to be added to the input or renumbered aperture number to form +the final output aperture number. +.le +.ls clobber = no +Modify an existing output image either by overwriting or merging? +.le +.ls merge = no +Merge apertures into existing spectra? This +requires that the \fIclobber\fR parameter be set. If not merging +then the selected spectra entirely replace those in existing output images. +If merging then the input spectra replace those in the output image +with the same aperture number and new apertures are added if not present. +.le +.ls rebin = yes +Rebin the spectrum to the exact wavelength range specified by the \fIw1\fR +and \fIw2\fR parameters? If the range is given as INDEF for both endpoints +this parameter does not apply. If a range is given and this parameter is +not set then the pixels in the specified range (using the nearest pixels to +the endpoint wavelengths) are copied without rebinning. In this case the +wavelength of the first pixel may not be exactly that specified by \fIw1\fR +and the dispersion, including non-linear dispersions, is unchanged. If +this parameter is set the spectra are interpolated to have the first and +last pixels at exactly the specified endpoint wavelengths while preserving +the same number of pixels in the interval. Linear and log-linear +dispersion types are maintained while non-linear dispersions are +linearized. +.le +.ls verbose = no +Print a record of each aperture copied? +.le +.ih +DESCRIPTION +\fBScopy\fR selects regions of spectra from an input list of spectral +images and copies them to output images. This task can be used to extract +aperture spectra from long slit and Fabry-Perot images and to select, +reorganize, merge, renumber, pack, and unpack spectra in many ways. Below +is a list of some of the uses and many examples are given in the EXAMPLES +section. + +.nf + o Pack many spectra into individual images into a single image + o Unpack images with multiple spectra into separate images + o Extract a set of lines or columns from long slit spectra + o Extract a set of spatial positions from Fabry-Perot spectra + o Extract specific wavelength regions + o Select a subset of spectra to create a new image + o Merge a subset of spectra into an existing image + o Combine spectra from different images into one image + o Renumber apertures +.fi + +Input spectra are specified by an image list which may include explicit +image names, wildcard templates and @files containing image names. +The image names may also include image sections such as to select portions of +the wavelength coverage. The input images may be either one or two +dimensional spectra. One dimensional spectra may be stored in +individual one dimensional images or as lines in two (or three) +dimensional images. The one dimensional spectra are identified by +an aperture number, which must be unique within an image, and a beam number. +Two dimensional long slit and three dimensional Fabry-Perot spectra are +treated, for the purpose of this +task, as a collection of spectra with dispersion either along any axis +specified by the DISPAXIS image header parameter +or the \fIdispaxis\fR package parameter. The aperture and band +parameters specify a spatial position. A number of adjacent +lines, columns, and bands, specified by the \fInsum\fR package parameter, +will be summed to form an aperture spectrum. If number is odd then the +aperture/band number refers to the middle and if it is even it refers to the +lower of the two middle lines or columns. + +In the case of many spectra each stored in separate one dimensional +images, the image names may be such that they have a common root name +and a four digit aperture number extension. This name syntax is +called "onedspec" format. Including such spectra in an +input list may be accomplished either with wildcard templates such as + +.nf + name* + name.????.imh +.fi + +where the image type extension ".imh" must be given to complete the +template but the actual extension could also be that for an STF type +image, or using an @file prepared with the task \fBnames\fR. +To generate this syntax for output images the \fIformat\fR parameter +is set to "onedspec" (this will be discussed further later). + +From the input images one may select a range of wavelengths with the +\fIw1\fR and \fIw2\fR parameters and a subset of spectra based on aperture and +beam numbers using the \fIaperture\fR and \fIbeam\fR parameters. +If the wavelength range is specified as INDEF the full spectra are +copied without any resampling. If the aperture and beam lists are not +specified, an empty list, then all apertures and beams are selected. The +lists may be those spectra desired or the complement obtained by prefixing +the list with '!'. Only the selected wavelength range and spectra will +be operated upon and passed on to the output images. + +Specifying a wavelength range is fairly obvious except for the question +of pixel sampling. Either the pixels in the specified range are copied +without resampling or the pixels are resampled to correspond eactly +to the requested range. The choice is made with the \fIrebin\fR parameter. +In the first case the nearest pixels to the specified wavelength +endpoints are determined and those pixels and all those in between +are copied. The dispersion relation is unchanged. In the second case +the spectra are reinterpolated to have the specified starting and +ending wavelengths with the same number of pixels between those points +as in the original spectrum. The reinterpolation is done in either +linear or log-linear dispersion. The non-linear dispersion functions +are interpolated to a linear dispersion. + +Using \fBscopy\fR with long slit or Fabry-Perot images provides a quick and +simple type of extraction as opposed to using the \fBapextract\fR package. +When summing it is often desired to start each aperture after the number of +lines summed. To do this specify a step size in the aperture/band list. For +example to extract columns 3 to 23 summing every 5 columns you would use an +aperture list of "3-23x5" and an \fInsum\fR of 5. If you do not use the +step in the aperture list you would extract the sum of columns 1 to 5, then +columns 2 to 6, and so on. + +In the special case of subapertures extracted by \fBapextract\fR, related +apertures are numbered using a modulus; for example apertures +5, 1005, 2005. To allow selecting all related apertures using a single +aperture number the \fIapmodulus\fR parameter is used to specify the +modulus factor; 1000 in the above example. This is a very specialized +feature which should be ignored by most users. + +The output list of images may consist of an empty list, a single image, +or a list of images matching the input list in number. Note that it +is the number of image names that matters and not the number of spectra +since there may be any number of spectra in an image. The empty list +converts to the same list as the input and is shorthand for replacing +the input image with the output image upon completion; therefore it +is equivalent to the case of a matching list. If the input +consists of just one image then the distinction between a single +output and a matching list is moot. The interesting distinction is +when there is an input list of two or more images. The two cases +are then a mapping of many-to-many or many-to-one. Note that it is +possible to have more complex mappings by repeating the same output +name in a matching list provided clobbering, merging, and possibly +renumbering is enabled. + +In the case of a matching list, spectra from different input images +will go to different output images. In the case of a single output +image all spectra will go to the same output image. Note that in +this discussion an output image when "onedspec" format is specified +is actually a root name for possibly many images. However, +it should be thought of as a single image from the point of view +of image lists. + +When mapping many spectra to a single output image, which may have existing +spectra if merging, there may be a conflict with repeated aperture +numbers. One option is to consecutively renumber the aperture numbers, +including any previous spectra in the output image when merging and then +continuing with the input spectra in the order in which they are selected. +This is specified with the \fIrenumber\fR parameter which renumbers +beginning with 1. + +Another options which may be used independently of renumbering or in +conjunction with it is to add an offset as specified by the \fIoffset\fR +parameter. This is last step in determining the output aperture +numbers so that if used with the renumber option the final aperture +numbers begin with one plus the offset. + +It has been mentioned that it is possible to write and add to +existing images. If an output image exists an error will be +printed unless the \fIclobber\fR parameter is set. If clobbering +is allowed then the existing output image will be replaced by the +new output. Rather than replacing an output image sometimes one +wants to replace certain spectra or add new spectra. This is +done by selecting the \fImerge\fR option. In this case if the output +has a spectrum with the same aperture number as the input spectrum +it is replaced by the input spectrum. If the input spectrum aperture +number is not in the output then the spectrum is added to the output +image. To add spectra with the same aperture number and not +replace the one in the output use the \fIrenumber\fR or +\fIoffset\fR options. + +To print a record as each input spectrum is copied the \fIverbose\fR +parameter may be set. The syntax is the input image name followed +by the aperture number in []. An arrow then points to the output +image name with the final aperture number also in [], except for +"onedspec" format where the image name extension gives the aperture +number. It is important to remember that it is the aperture numbers +which are shown and not the image lines; there is not necessarily any +relation between image lines and aperture numbers though often they +are the same. +.ih +EXAMPLES +Because there are so many possiblities there are many examples. To +help find examples close to those of interest they are divided into +three sections; examples involving standard multispec images only, examples +with onedspec format images, and examples with long slit and Fabry-Perot +images. In the examples the verbose flag is set to yes and the output is +shown. + +I. MULTISPEC IMAGES + +The examples in this section deal with the default spectral format of +one or more spectra in an image. Note that the difference between +a "onedspec" image and a "multispec" image with one spectrum is purely +the image naming syntax. + +1. Select a single spectrum (aperture 3): + +.nf + cl> scopy example1 ap3 aperture=3 + example1[3] --> ap3[3] +.fi + +2. Select a wavelength region from a single spectrum: + +.nf + cl> scopy example1 ap3 aperture=3 w1=5500 w2=6500 + example1[3] --> ap3[3] +.fi + +3. Select a subset of spectra (apertures 1, 2, 4, 6, and 9): + +.nf + cl> scopy example1 subset apertures="1-2,4,6-9x3" + example1[1] --> subset[1] + example1[2] --> subset[2] + example1[4] --> subset[4] + example1[6] --> subset[6] + example1[9] --> subset[9] +.fi + +This example shows various features of the aperture list syntax. + +4. Select the same apertures (1 and 3) from multiple spectra and in the +same wavelength region: + +.nf + cl> scopy example* %example%subset%* apertures=1,3 w1=5500 w2=6500 + example1[1] --> subset1[1] + example1[3] --> subset1[3] + example2[1] --> subset2[1] + example2[3] --> subset2[3] + ... +.fi + +The output list uses the pattern substitution feature of image templates. + +5. Select the same aperture from multiple spectra and pack them in a +a single image: + +.nf + cl> scopy example* ap2 aperture=2 renumber+ + example1[2] --> ap2[1] + example2[2] --> ap2[2] + example3[2] --> ap2[3] + ... +.fi + +6. To renumber the apertures sequentially starting with 11: + +.nf + cl> scopy example1 renum renumber+ + example1[1] --> renum[11] + example1[5] --> renum[12] + example1[9] --> renum[13] + ... +.fi + +7. To replace apertures (2) in one image with that from another: + +.nf + cl> scopy example1 example2 aperture=2 clobber+ merge+ + example1[2] --> example2[2] +.fi + +8. To merge two sets of spectra with different aperture numbers into + one image: + +.nf + cl> scopy example![12]* merge + example1[1] -> merge[1] + example1[3] -> merge[3] + ... + example2[2] -> merge[2] + example2[4] -> merge[4] + ... +.fi + +The input list uses the ![] character substitution syntax of image templates. + +9. To merge a set of spectra with the same aperture numbers into another +existing image: + +.nf + cl> scopy example2 example1 clobber+ merge+ renumber+ + example1[5] --> example1[2] + example1[9] --> example1[3] + example2[1] --> example1[4] + example2[5] --> example1[5] + example2[9] --> example1[6] +.fi + +Both images contained apertures 1, 5, and 9. The listing does not show +the renumbering of the aperture 1 from example1 since the aperture number +was not changed. + +10. Select parts of a 3D image where the first band is the +variance weighted extraction, band 2 is nonweighted extraction, +band 3 is the sky, and band 4 is the sigma: + +.nf + cl> scopy example3d.ms[*,*,1] var1.ms + example3d.ms[*,*,1][1] --> var1.ms[1] + example3d.ms[*,*,1][2] --> var1.ms[2] + ... + cl> scopy example3d.ms[10:400,3,3] skyap3 + example3d.ms[10:400,3,3][3] --> skyap3[3] + cl> scopy example3d.ms[*,*,1] "" clobber+ + example3d.ms[*,*,1][1] --> example3d.ms[1] + example3d.ms[*,*,1][2] --> example3d.ms[2] + ... +.fi + +Note that this could also be done with \fBimcopy\fR. The last example +is done in place; i.e. replacing the input image by the output image +with the other bands eliminatated; i.e. the output image is two dimensional. + +II. ONEDSPEC IMAGES + +1. Expand a multi-spectrum image to individual single spectrum images: + +.nf + cl> scopy example1 record format=onedspec + example1[1] --> record.0001 + example1[5] --> record.0005 + example1[9] --> record.0009 + ... +.fi + +2. Pack a set of individual 1D spectra into a single image: + +.nf + cl> scopy record.????.imh record.ms + record.0001[1] --> record.ms[1] + record.0005[5] --> record.ms[5] + record.0009[9] --> record.ms[9] + ... +.fi + +3. Copy a set of record syntax spectra to a different rootname and renumber: + +.nf + cl> scopy record.????.imh newroot format=onedspec + record.0001[1] --> newroot.0001 + record.0005[5] --> newroot.0002 + record.0009[9] --> newroot.0003 + ... +.fi + +III. LONG SLIT IMAGES + +To define the dispersion axis either the image header parameter DISPAXIS +must be set (using HEDIT for example) or a the package \fIdispaxis\fR +parameter must be set. In these examples the output is the default +multispec format. + +1. To extract column 250 into a spectrum: + +.nf + cl> scopy longslit1 c250 aperture=250 + longslit1[250] --> c250[250] +.fi + +2. To sum and extract every set of 10 columns: + +.nf + cl> nsum = 10 (or epar the package parameters) + cl> scopy longslit1 sum10 apertures=5-500x10 + longslit1[5] --> sum10[5] + longslit1[15] --> sum10[15] + longslit1[25] --> sum10[25] + ... +.fi + +3. To extract the sum of 10 columns centered on column 250 from a set +of 2D images: + +.nf + cl> nsum = 10 (or epar the package parameters) + cl> scopy longslit* %longslit%c250.%* aperture=250 + longslit1[250] --> c250.1[250] + longslit2[250] --> c250.2[250] + longslit3[250] --> c250.3[250] + ... +.fi + +4. To extract the sum of 10 columns centered on column 250 from a set of +2D images and merge them into a single, renumbered output image: + +.nf + cl> nsum = 10 (or epar the package parameters) + cl> scopy longslit* c250 aperture=250 renum+ + longslit1[250] --> c250[1] + longslit2[250] --> c250[2] + longslit3[250] --> c250[3] + ... +.fi + +IV. FABRY-PEROT IMAGES + +To define the dispersion axis either the image header parameter DISPAXIS +must be set (using HEDIT for example) or a the package \fIdispaxis\fR +parameter must be set. In these examples the output is the default +multispec format. + +1. To extract a spectrum from the spatial position (250,250) where +dispaxis=3: + +.nf + cl> scopy fp1 a250 aperture=250 band=250 + longslit1[250] --> a250[250] +.fi + +2. To sum and extract every set of 10 lines and bands (dispaxis=1): + +.nf + cl> nsum = "10" + cl> scopy fp1 sum10 apertures=5-500x10 bands=5-500x10 + longslit1[5] --> sum10[5] + longslit1[15] --> sum10[15] + longslit1[25] --> sum10[25] + ... +.fi + +3. To extract the sum of 10 columns and 20 lines centered on column 250 and +line 100 from a set of 3D images with dispaxis=3: + +.nf + cl> nsum = "10 20" + cl> scopy longslit* %longslit%c250.%* aperture=250 band=100 + longslit1[250] --> c250.1[250] + longslit2[250] --> c250.2[250] + longslit3[250] --> c250.3[250] + ... +.fi +.ih +REVISIONS +.ls SCOPY V2.11 +Previously both w1 and w2 had to be specified to select a range to +copy. Now if only one is specified the second endpoint defaults +to the first or last pixel. +.le +.ls SCOPY V2.10.3 +Additional support for 3D multispec/equispec or spatial spectra has been +added. The "bands" parameter allows selecting specific bands and +the onedspec output format creates separate images for each selected +aperture and band. +.le +.ls SCOPY V2.10 +This task is new. +.le +.ih +SEE ALSO +ranges, sarith, imcopy, dispcor, specshift +.endhelp diff --git a/noao/onedspec/doc/sensfunc.hlp b/noao/onedspec/doc/sensfunc.hlp new file mode 100644 index 00000000..1ebd7e24 --- /dev/null +++ b/noao/onedspec/doc/sensfunc.hlp @@ -0,0 +1,447 @@ +.help sensfunc Mar93 noao.onedspec +.ih +NAME +sensfunc -- Determine sensitivity and extinction functions +.ih +USAGE +sensfunc standards sensitivity +.ih +PARAMETERS +.ls standards = "std" +Input standard star data file created by the task \fBstandard\fR. +.le +.ls sensitivity = "sens" +Output sensitivity function image name or rootname. Generally each +aperture results in an independent sensitivity function with the +aperture number appended to the rootname. If the parameter \fIignoreaps\fR +is set, however, the aperture numbers are ignored and a single sensitivity +function is determined with the output image having the specified name +with no extension. +.le +.ls apertures = "" +List of apertures to be selected from the input file. All other apertures +are ignored. If no list is specified then all apertures are selected. +See \fBranges\fR for the syntax. +.le +.ls ignoreaps = no +Ignore aperture numbers and create a single sensitivity function? Normally +each aperture produces an independent sensitivity function. If the +apertures are ignored then all the observations are combined into +a single sensitivity function. +.le +.ls logfile = "logfile" +Output log filename for statistical information about the stars used +and the sensitivity function and extinction function. +If no filename is given then no file is written. +.le +.ls extinction = <no default> +Input extinction file. Any extinction determination made will be +relative to this extinction. If no file is given then no extinction +correction is applied and any extinction determination from the +standard star data will be an absolute determination of the +extinction. The default value is redirected to the package parameter +of the same name. The extinction file is generally one of the standard +extinctions in the calibration directory "onedstds$". + +If extinction corrected spectra were used as input to \fBstandard\fR +then it is important that the same extinction file be used here. +This includes using no extinction file in both tasks. +.le +.ls newextinction = "extinct.dat" +Output revised extinction file. If the extinction is revised and an +output filename is given then a revised extinction file is written. It +has the same format as the standard extinction files. +.le +.ls observatory = ")_.observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. The default is a redirection to look +in the parameters for the parent package for a value. This is only used +when graphing flux calibrated data of spectra which do not include the +airmass in the image header. The observatory may be one of the +observatories in the observatory database, "observatory" to select the +observatory defined by the environment variable "observatory" or the +parameter \fBobservatory.observatory\fR, or "obspars" to select the current +parameters set in the \fBobservatory\fR task. See help for +\fBobservatory\fR for additional information. +.le +.ls function = "spline3" +Function used to fit the sensitivity data. The function types are +"chebyshev" polynomial, "legendre" polynomial, "spline3" cubic spline, +and "spline1" linear spline. The default value may be changed interactively. +.le +.ls order = 6 +Order of the sensitivity fitting function. The value corresponds to the +number of polynomial terms or the number of spline pieces. The default +value may be changed interactively. +.le +.ls interactive = yes +Determine the sensitivity function interactively? If yes the user +graphically interacts with the data, modifies data and parameters +affecting the sensitivity function, and determines a residual extinction. +.le +.ls graphs = "sr" +Graphs to be displayed per frame. From one to four graphs may be displayed +per frame. The graph types are selected by single characters and are: + +.nf +a - residual sensitivity vs airmass +c - composite residual sensitivity and error bars vs wavelength +e - input extinction and revised extinction vs wavelength +i - Flux calibrated spectrum vs wavelength +r - residual sensitivity vs wavelength +s - sensitivity vs wavelength +.fi + +All other characters including whitespace and commas are ignored. The order +and number of graphs determines the positions of the graphs. +.le +.ls marks = "plus cross box" +Symbols used to mark included, deleted, and added data respectively. +The available mark types are point, box, plus, cross, diamond, hline +(horizontal line), vline (vertical line), hebar (horizontal error bar), +vebar (vertical error bar), and circle. +.le +.ls colors = "2 1 3 4" +Colors to use for "lines", "marks", "deleted" data, and "added" data. +The colors associated with the numbers is graphics device dependent. +For example in XGTERM they are defined by resources while on other +devices that don't support colors only one color will appear. +.le +.ls cursor = "" +Graphics cursor input list. If not specified as a file then standard +graphics cursor is read. +.le +.ls device = "stdgraph" +Graphics output device. +.le +.ls answer +Query parameter for selecting whether to fit apertures interactively. +.le +.ih +CURSOR COMMANDS + +.nf +? Print help +a Add a point at the cursor position +c Toggle use of composite points +d Delete point, star, or wavelength nearest the cursor +e Toggle residual extinction correction +f Fit data with a sensitivity function and overplot +g Fit data with a sensitivity function and redraw the graph(s) +i Print information about point nearest the cursor +m Move point, star, wavelength nearest the cursor to new sensitivity +o Reset to original data +q Quit and write sensitivity function for current aperture +r Redraw graph(s) +s Toggle shift of standard stars to eliminate mean deviations +u Undelete point, star, or wavelength nearest the cursor +w Change weights of point, star, or wavelength nearest the cursor + +:flux [min] [max] Limits for flux calibrated graphs (INDEF for autoscale) +:function [type] Function to be fit to sensitivity data: + chebyshev - Chebyshev polynomial + legendre - Legendre polynomial + spline1 - Linear spline + spline3 - Cubic spline +:graphs [types] Graphs to be displayed (up to four): + a - Residual sensitivity vs airmass + c - Composite residuals and error bars vs wavelength + e - Extinction (and revised extinction) vs wavelength + i - Flux calibrated image vs wavelength + l - Log of flux calibrated image vs wavelength + r - Residual sensitivity vs wavelength + s - Sensitivity vs wavelength +:images [images] Images to flux calibrate and plot (up to four) +:marks marks Mark types to use for included, delete, and added points: + point, box, plus, cross, diamond, hline, + vline, hebar, vebar, circle +:order [order] Order of function +:skys [images] Sky images for flux calibration (up to four) +:stats [file] Statistics about stars and sensitivity fit +:vstats [file] Verbose statistics about sensitivity fit +.fi +.ih +DESCRIPTION +Standard star calibration measurements are used to determine the system +sensitivity as a function of wavelength for each independent aperture. +If the parameter \fIignoreaps\fR is set then the aperture numbers are +ignored and a single sensitivity function is determined from all the +observations. Using measurements spanning a range of airmass it is +also possible to derive an adjustment to the standard extinction curve +or even an absolute determination. Extinction determination requires +that the observations span a good range of airmass during photometric +conditions. When conditions are poor and standard star observations +are obtained during periods of variable transparency, the entire +sensitivity curve may vary by a constant factor, assuming that the +cause of the variations has no color effect. This is often the case +during periods of thin clouds. In this case the mean sensitivity of +each observation may be shifted to match the observation of greatest +sensitivity. This allows for the possibility of deriving correct +absolute fluxes if one observation of a standard was obtained during a +clear period. + +The input data is a file of calibration information produced by the +task \fBstandard\fR. The data consists of a spectrum identification +line containing the spectrum image name, the sky image name if beam +switching, the aperture number, the length of the spectrum, the +exposure time, airmass, wavelength range, and title. Following the +identification line are calibration lines consisting of the central +bandpass wavelengths, the tabulated fluxes in the bandpasses, the +bandpass widths, and the observed counts in the bandpasses. The +spectrum identification and calibration lines repeat for each standard +star observation. The parameter \fIapertures\fR may be used to select +only specific apertures from the input data. This parameter is in the +form of a range list (see help for \fBranges\fR) and if no list is +given (specified by the null string "") then all apertures are selected. + +An input extinction file may also be specified. Any extinction +determinations are then residuals to this input extinction table. +The format of this table is described in \fBlcalib\fR. + +The calibration factor at each point is computed as + + (1) C = 2.5 log (O / (T B F)) + A E + +where O is the observed counts in a bandpass of an observation, +T is the exposure time of the observation, B is the bandpass width, +F is the flux per Angstrom at the bandpass for the standard star, +A is the airmass of the observation, and E is the extinction +at the bandpass. Thus, C is the ratio of the observed count rate per +Angstrom corrected to some extinction curve to the expected flux +expressed in magnitudes. The goal of the task is to fit the observations +to the relation + + (2) C = S(W) + AE(W) + +where W is wavelength, S(W) is the sensitivity function, and E(W) is +a residual extinction function relative to the extinction used in (1). +In later discussion we will also refer to the residual sensitivity which +is defined by + + (3) R = C - S(W) - AE(W) + +The sensitivity function S(W) is output as an one dimensional image +much like the spectra. The sensitivities are in magnitude units to +better judge the variations and because the interpolation is smoother +in the logarithmic space (mags = 2.5 log10[sensitivity]). There is one +sensitivity function for each aperture unless the parameter +\fIignoreaps\fR is set. In the first case the image names are formed +from the specified rootname with the aperture number as a four digit +numerical extension. In the latter case a single sensitivity function +is determined from all data, ignoring the aperture numbers, and the +specified output image is created without an extension. These images +are used by \fBcalibrate\fR to correct observations to a relative of +absolute flux scale. If no sensitivity function image rootname is +specified then the sensitivity curves are not output. + +If a revised extinction function E(W) has been determined for one or +more of the apertures then the functions are averaged over all +apertures, added to the original extinction, and written to the +specified extinction table. The format of this table is the same as +the standard extinction tables and are, thus, interchangeable. If no +new extinction filename is specified then no extinction table is +recorded. + +If a log filename is given then statistical information about the +sensitivity function determinations are recorded. This includes the +names of the input standard star observations and the tabulated +sensitivity, extinction, and error information. + +Some points to note are that if no input extinction is given then the +E in (1) are zero and the E determined in (2) is the absolute extinction. +If the data are not good enough to determine extinction then using one +of the standard extinction curves the problem reduces to fitting + + (4) C = S(W) + +The sensitivity and extinction functions are determined as fitted +curves. The curves are defined by a function type and order. There +are four function types and the order specifies either the number of +terms in the polynomial or the number of pieces in the spline. The +order is automatically reduced to the largest +value which produces a nonsingular result. In this case the function +will attempt to pass through every calibration point. Lower orders +provide for a smoother representation of the function. The latter +is generally more appropriate for a detector. The initial function +type and order for the sensitivity function is specified by the +parameters \fIfunction\fR and \fIorder\fR. + +If the \fIinteractive\fR flag is no then the default function and order +is fit to equation (4) (i.e. there is no residual extinction determination +or manipulation of the data). The sensitivity functions are output +if an image rootname is given and the log information is output if a +log filename is given. + +When the sensitivity is determined interactively a query is given for +each aperture. The responses "no" and "yes" select fitting the sensitivity +interactively or not for the specified aperture. The responses "NO" and +"YES" apply to all apertures and no further queries will be given. +When interactive fitting is selected the data are graphed +on the specified graphics device and input is through the specified +cursor list. The graphics output consists of from one to four graphs. +The user selects how many and which types of graphs to display. The +graph types and their single character code used to select them are: + +.nf + a - residual sensitivity vs airmass + c - composite residual sensitivity and error bars vs wavelength + e - input extinction and revised extinction vs wavelength + i - Flux calibrated spectrum vs wavelength + r - residual sensitivity vs wavelength + s - sensitivity vs wavelength +.fi + +The initial graphs are selected with the parameter \fBgraphs\fR and changed +interactively with the colon command ':graphs \fItypes\fR'. The ability +to view a variety of graphs allows evaluating the effects of the +sensitivity curve and extinction in various ways. The flux calibrated +spectrum graph uses the current sensitivity function and checks for +possible wiggles in the sensitivity curve which affect the shape of the +continuum. The choice of graphs also allows the +user to trade off plotting speed and resolution against the amount of +information available simultaneously. Thus, with some graphics devices +or over a slow line one can reduce the number of graphs for greater speed +while on very fast devices with large screens one can look at more +data. The parameter \fImarks\fR and the associated colon command +':marks \fItypes\fR' also let the user define the symbols used to mark +included, deleted, and added data points. + +The list of interactive commands in given in the section on CURSOR COMMANDS. +The commands include deleting, undeleting, adding, moving, and identifying +individual data points, whole stars, or all points at the same wavelength. +Some other commands include 'c' to create composite points by averaging +all points at the same wavelength (this requires exact overlap in the +bandpasses) which then replace the individual data points in the fit. +This is different than the composite point graph which displays the +residual in the mean sensitivity +and error \fIin the mean\fR but uses the input data in the fitting. +The 's' command shifts the data so that the mean sensitivity of each +star is the same as the star with the greatest mean sensitivity. +This compensates for variable grey extinction due to clouds. Note +that delete points are excluded from the shift calculation and a +deleted star will not be used as the star of greatest sensitivity. +Another useful command is 'o' to recover the original data. This cancels +all changes made due to shifting, extinction corrections, deleting points, +creating composite points, etc. + +The 'e' command attempts to compute a residual extinction by finding +correlations between the sensitivity points at different airmass. +Note that this is not iterative so that repeating this after having +added an extinction correction simply redetermines the correction. +At each wavelength or wavelength regions having multiple observations at +different airmass a slope with airmass is determined. This slope is +the residual extinction at that wavelength. A plot of the residual +extinctions at each wavelength is made using the ICFIT procedure. +The user may then examine and fit a curve through the residual extinction +estimates as a function of wavelength (see \fBicfit\fR for a description +of the commands). The user must decide how much wavelength dependence +is derivable from the data. In many cases only a constant fit +to a "gray extinction" or possibly a linear fit is realistic. +The fitting is exited by the key 'q'. + +To help evaluate how important the residual extinction determination +is a t-statistic significance is computed. This statistic is defined by + + (5) t = sqrt (r**2 * (N - 2) / (1 - r**2)) + +where the correlation coefficient + + (6) r = RMS with correction / RMS without correction + +is the fractional improvement in the RMS due to the added extinction +correction and N is the number of wavelength points. For large +N this approaches a gaussian sigma but a more precise significance +requires the t-distribution for N-2 degrees of freedom. Basically this +asks, was the improvement in the RMS significantly more than would +occur with random errors? A value greater than 3 is good while +a value less than 1 is not significant. The user may then accept the +revised extinction and apply it to the data. + +Note that when there are multiple apertures used each aperture has an +independent system sensitivity but the residual extinction is the same. +Therefore, the residual extinctions from each aperture are averaged at +the end. If one determines a new extinction then one may replace the +original input extinction by the new extinction and rederive the +sensitivity. +.ih +EXAMPLES +1. The following command generates sensitivity spectra + + cl> sensfunc std sens + +This command uses the data from the \fBstandard\fR output +file "std" to create sensitivity functions with rootname "sens". +If not interactive the task will produce the output with some +progress messages being printed. If it is interactive the graphics +device will be used to display the data and the fit and user can +change the function and order of the fit, delete bad points, shift +data to correct for clouds or bandpass errors, and possibly determine +a revised extinction function. The statistics of the +sensitivity determination are written to the logfile ("logfile" by +default). + +2. The following examples illustrate the colon command syntax. Generally +if no argument is given the current value is displayed. For the statistics +commands an optional output file may be given to record the information. + +.nf +:flux 1e-12 INDEF Set lower limit for flux plots +:flux INDEF INDEF Restore autoscaling in flux plots +:func spline3 Select cubic spline function +:g srae Graph sensitivity, residuals, airmass, + and extinction +:g sii Graph sensitivity and two images +:i n1.0004 n1.0008 Set first two images to graph (the defaults + are taken from the standard star list) +:skys n1.0005 Subtract this sky image from first image + for flux calibrated spectrum +:m plus Change the mark type for included points and + don't change the deleted or added point mark type +:stats Print statistics to terminal +:vstats stdstats Print verbose statistics to file +.fi +.ih +REVISIONS +.ls SENSFUNC V2.10.3+ +Deleted points and stars are now ignored from the grey shift calculation. +.le +.ls SENSFUNC V2.10.3 +A color parameter was added for graphics terminals supporting color. +.le +.ls SENSFUNC V2.10 +The latitude parameter has been replaced by the observatory parameter. +The 'i' flux calibrated graph type now shows flux in linear scaling +while the new graph type 'l' shows flux in log scaling. A new colon +command allows fixing the flux limits for the flux calibrated graphs. +.le +.ls SENSFUNC V2.8 +This task has been completely rewritten from that of versions 2.5 and +earlier. + +.nf +1. The input standard data format is different. +2. Extinction corrections beyond a grey term are now supported. +3. Weighting by the counts is not supported. +4. Tabular input is not supported. +5. The data which can be displayed is greatly improved. +6. The fitting options have been greatly enhanced. +7. The fitting function types available have been extended. +8. One or more flux calibrated images may be displayed using the + current sensitivity function. +9. Additional flexibility is provided for treating apertures. +.fi +.le +.ih +BUGS +If the flux points do not span the wavelength range, set by the +standard star observations, then the fitting may fail at some maximum +order. When it fails there is no message but the highest order which +can be successfully fit is used. To work around this one can either +add fake points, truncate the wavelength range in the first line of each +tabulated object in the file produced by \fBstandard\fR, or exclude the +part of the image data which cannot be uncalibrated (using +\fBscopy\fR or \fBdispcor\fR). +.ih +SEE ALSO +standard, lcalib, calibrate, observatory, icfit, ranges, scopy, dispcor +.endhelp diff --git a/noao/onedspec/doc/sfit.hlp b/noao/onedspec/doc/sfit.hlp new file mode 100644 index 00000000..0416c622 --- /dev/null +++ b/noao/onedspec/doc/sfit.hlp @@ -0,0 +1,262 @@ +.help sfit Mar92 noao.onedspec +.ih +NAME +sfit -- Fit spectra +.ih +USAGE +sfit input output +.ih +PARAMETERS +.ls input +Input spectra to be fit. These may be any combination of echelle, +multispec, onedspec, long slit, and spectral cube format images. +.le +.ls output +Output fitted spectra. The number of output spectra must +match the number of input spectra. \fBOutput\fR may be omitted if +\fBlistonly\fR is yes. +.le +.ls lines = "*", bands = "1" +A range specifications for the image lines and bands to be fit. Unspecified +lines and bands will be copied from the original. If the value is "*", all of +the currently unprocessed lines or bands will be fit. A range consists of +a first line number and a last line number separated by a hyphen. A +single line number may also be a range and multiple ranges may be +separated by commas. +.le +.ls type = "fit" +Type of output spectra. The choices are "fit" for the fitted function, +"ratio" for the ratio of the input spectra to the fit, "difference" for +the difference between the input spectra and the fit, and "data" for +the data minus any rejected points replaced by the fit. +.le +.ls replace = no +Replace rejected points by the fit in the difference, ratio, and +data output types? +.le +.ls wavescale = yes +Wavelength scale the X axis of the plot? This option requires that the +spectra be wavelength calibrated. If \fBwavescale\fR is no, the plots +will be in "channel" (pixel) space. +.le +.ls logscale = no +Take the log (base 10) of both axes? This can be used when \fBlistonly\fR +is yes to measure the exponent of the slope of the continuum. +.le +.ls override = no +Override previously fit spectra? If \fBoverride\fR is yes and +\fBinteractive\fR is yes, the user will be prompted before each order is +refit. If \fBoverride\fR is no, previously fit spectra are silently +skipped. +.le +.ls listonly = no +Don't modify any images? If \fBlistonly\fR is yes, the \fBoutput\fR +image list may be skipped. +.le +.ls logfiles = "logfile" +List of log files to which to write the power series coefficients. If +\fBlogfiles\fR = NULL (""), the coefficients will not be calculated. +.le +.ls interactive = yes +Perform the fit interactively using the icfit commands? This will allow +the parameters for each spectrum to be adjusted independently. A separate +set of the fit parameters (below) will be used for each spectrum and any +interactive changes to the parameters for a specific spectrum will be +remembered when that spectrum is fit in the next image. +.le +.ls sample = "*" +The ranges of X values to be used in the fits. The units will vary +depending on the setting of the \fBwavescale\fR and \fBlogscale\fR +parameters. The default units are in wavelength if the spectra have +been dispersion corrected. The sample range syntax consists of +pairs of values separated by colons and multiple ranges can be +given separated by commas. +.le +.ls naverage = 1 +Number of sample points to combined to create a fitting point. +A positive value specifies an average and a negative value specifies +a median. +.le +.ls function = spline3 +Function to be fit to the spectra. The functions are +"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial), +"spline1" (linear spline), and "spline3" (cubic spline). The functions +may be abbreviated. The power series coefficients can only be +calculated if \fBfunction\fR is "legendre" or "chebyshev". +.le +.ls order = 1 +The order of the polynomials or the number of spline pieces. +.le +.ls low_reject = 3., high_reject = 3. +Rejection limits below and above the fit in units of the residual sigma. +.le +.ls niterate = 0 +Number of rejection iterations. +.le +.ls grow = 1. +When a pixel is rejected, pixels within this distance of the rejected pixel +are also rejected. +.le +.ls markrej = yes +Mark rejected points? If there are many rejected points it might be +desired to not mark rejected points. +.le +.ls graphics = "stdgraph" +Graphics output device for interactive graphics. +.le +.ls cursor = "" +Graphics cursor input. +.le +.ih +DESCRIPTION +A one dimensional function is fit to spectra in a list of echelle, +multispec, or onedspec format images. The first two formats will +fit the spectra or orders (i.e. the lines) in each image. +In this description the term "spectrum" will refer to a line of +an image while "image" will refer to all spectra in an image. +The parameters of the fit may vary from spectrum to spectrum within +images and between images. The fitted function may +be a legendre polynomial, chebyshev polynomial, linear spline, or cubic +spline of a given order or number of spline pieces. The output spectra +are formed from the fit, the ratio between the pixel values and the fit, +the difference of the spectra to the fit, and the original data with +rejected points possibly replaced. The output image is of pixel type real. + +The line/band numbers (for two/three dimensional images) are written to a +list of previously processed lines in the header keywords \fISFIT\fR and +\fISFITB\fR of the output image. A subsequent invocation of SFIT will only +process those requested spectra that are not in this list. This ensures +that even if the output image is the same as the input image that no +spectra will be processed twice and permits an easy exit from the task in +the midst of processing many spectra without losing any work or requiring +detailed notes. + +The points to be fit in each spectrum are determined by +selecting a sample of X values specified by the parameter \fIsample\fR +and taking either the average or median of the number of points +specified by the parameter \fInaverage\fR. The type of averaging is +selected by the sign of the parameter with positive values indicating +averaging, and the number of points is selected by the absolute value +of the parameter. The sample units will vary depending on the settings +of the \fBwavescale\fR and the \fBlogscale\fR parameters. Note that a +sample that is specified in wavelength units may be entirely outside +the domain of the data (in pixels) if some of the spectra are not +dispersion corrected. The syntax of the sample specification is a comma +separated, colon delimited list similar to the image section notation. +For example, the \fBsample\fR, "6550:6555,6570:6575" might be used to +fit the continuum near H-alpha. + +If \fIlow_reject\fR and/or \fIhigh_reject\fR are greater than zero the +sigma of the residuals between the fitted points and the fitted +function is computed and those points whose residuals are less than +\fI-low_reject\fR * sigma and greater than \fIhigh_reject\fR * sigma +are excluded from the fit. Points within a distance of \fIgrow\fR +pixels of a rejected pixel are also excluded from the fit. The +function is then refit without the rejected points. This rejection +procedure may be iterated a number of times given by the parameter +\fIniterate\fR. + +If \fIreplace\fR is set then any rejected points from the fitting +are replaced by the fit in the data before outputing the difference, +ratio, or data. For example with replacing the difference will +be zero at the rejected points and the data output will be cleaned +of deviant points. + +A range specification is used to select the \fIlines\fR and \fIbands\fR to be +fit. These parameters may either be specified with the same syntax as the +\fBsample\fR parameter, or with the "hyphen" syntax used elsewhere in +IRAF. Note that a NULL range for \fBlines/bands\fR expands to \fBno\fR +lines, not to all lines. An asterisk (*) should be used to represent a +range of all of the image lines/bands. The fitting parameters (\fIsample, +naverage, function, order, low_reject, high_reject, niterate, grow\fR) +may be adjusted interactively if the parameter \fIinteractive\fR is +yes. The fitting is performed with the \fBicfit\fR package. The +cursor mode commands for this package are described in a separate help +entry under "icfit". Separate copies of the fitting parameters are +maintained for each line so that interactive changes to the parameter +defaults will be remembered from image to image. +.ih +PROMPTS +If several images or lines are specified, the user is asked whether +to perform an interactive fit for each spectrum. The response +may be \fByes, no, skip, YES, NO\fR or \fBSKIP\fR. The meaning of each +response is: + +.nf + yes - Fit the next spectrum interactively. + no - Fit the next spectrum non-interactively. + skip - Skip the next spectrum in this image. + + YES - Interactively fit all of the spectra of + all of the images with no further prompts. + NO Non-interactively fit all chosen spectra of all images. + SKIP - This will produce a second prompt, "Skip what?", + with the choices: + + spectrum - skip this spectrum in all images + image - skip the rest of the current image + all - \fBexit\fR the program + This will \fBunlearn\fR the fit parameters + for all spectra! + cancel - return to the main prompt +.fi +.ih +EXAMPLES +1. To normalize all orders of the echelle spectrum for hd221170 + + cl> sfit hd221170.ec nhd221170.ec type=ratio + +Each order of the spectrum is graphed and the interactive options for +setting and fitting the continuum are available. The important +parameters are low_rejection (for an absorption spectrum), the function +type, and the order of the function; these fit parameters are +originally set to the defaults in the SFIT parameter file. A +'?' will display a menu of cursor key options. Exiting with 'q' will +update the output normalized order for the current image and proceed to +the next order or image. + +The parameters of the fit for each order are initialized to the current +values the first time that the order is fit. In subsequent images, the +parameters for a order are set to the values from the previous image. +The first time an order is fit, the sample region is reset to the +entire order. Deleted points are ALWAYS forgotten from order to order +and image to image. + +2. To do several images at the same time + + cl> sfit spec*.imh c//spec*.imh + +Note how the image template concatenation operator is used to construct +the output list of spectra. Alternatively: + + cl> sfit @inlist @outlist + +where the two list files could have been created with the sections +command or by editing. + +3. To measure the power law slope of the continuum (fluxed data) + + cl> sfit uv.* type=ratio logscale+ listonly+ fun=leg order=2 +.ih +REVISIONS +.ls SFIT V2.10.4 +The task was expanded to include fitting specified bands in 3D multispec +spectra. + +The task was expanded to include long slit and spectral cube data. +.le +.ls SFIT V2.10 +This task is new. +.le +.ih +BUGS +The errors are not listed for the power series coefficients. + +Spectra that are updated when \fBlogscale\fR is yes are written with a +linear wavelength scale, but with a log normalized data value. + +Selection by aperture number is not supported. +.ih +SEE ALSO +continuum, fit1d, icfit, ranges +.endhelp diff --git a/noao/onedspec/doc/sflip.hlp b/noao/onedspec/doc/sflip.hlp new file mode 100644 index 00000000..66790e4e --- /dev/null +++ b/noao/onedspec/doc/sflip.hlp @@ -0,0 +1,114 @@ +.help sflip Jul94 noao.onedspec +.ih +NAME +sflip -- Flip data and/or dispersion coordinates in spectra +.ih +USAGE +sflip input output +.ih +PARAMETERS +.ls input +List of input images containing spectra to be flipped. +.le +.ls output +Matching list of output image names for flipped spectra. +If no list is specified then the flipped spectra will replace the input +spectra. If the output image name matching an input image name is the +same then the flipped spectrum will replace the original spectrum. +.le +.ls coord_flip = no +Flip the dispersion coordinates? If yes then the relationship between the +logical pixel coordinates and the dispersion coordinates will be reversed so +that the dispersion coordinate of the first pixel of the output image will +correspond to the coordinate of the last pixel in the input image and +vice-versa for the other endpoint pixel. The physical coordinates +will also be flipped. Only the coordinate system along the dispersion +axis is flipped. +.le +.ls data_flip = yes +Flip the order of the data pixels as they are stored in the image along +the dispersion axis? If yes then the first pixel in the input spectrum +becomes the last pixel in the output spectrum along the dispersion +axis of the image. +.le +.ih +DESCRIPTION +The dispersion coordinate system and/or the data in the spectra specified +by the input list of images are flipped and stored in the matching output +image given in the output list of images. If the output image list is left +blank or an output image name is the same as an input image name then the +operation is done so that the flipped spectra in the image replace the +original spectra. All of the supported spectrum types are allowed; one +dimensional images, collections of spectra in multispec format, and two and +three dimensional spatial spectra in which one axis is dispersion. In all +cases the flipping affects only the dispersion axis of the image as +specified by the DISPAXIS header keyword or the "dispaxis" parameter. The +parameters \fIcoord_flip\fR and \fIdata_flip\fR select whether the +coordinate system and data are flipped. If neither operation is selected +then the output spectra will simply be copies of the input spectra. + +Flipping of the coordinate system means that the relation between +"logical" pixel coordinates (the index system of the image array) +and the dispersion and physical coordinate systems is reversed. +The dispersion coordinate of the first pixel in the flipped spectrum +will be the same as the dispersion coordinate of the last pixel +in the original spectrum and vice-versa for the other endpoint. + +Flipping of the data means that the order in which the pixels are stored +in the image file is reversed along the image axis corresponding to +the dispersion. + +While flipping spectra seems simple there are some subtleties. If +both the coordinate system and the data are flipped then plots of +the spectra in which the dispersion coordinates are shown will appear +the same as in the original spectra. In particular the coordinate +of a feature in the spectrum will remain unchanged. In contrast +flipping either the coordinate system or the data will cause features +in the spectrum to move to opposite ends of the spectrum relative +to the dispersion coordinates. + +Since plotting programs often plot the dispersion axis in some standard way +such as increasing from left to right, flipping both the dispersion +coordinates and the data will produce plots that look identical even though +the order of the points plotted will be reversed. Only if the spectra are +plotted against logical pixel coordinates will a change be evident. Note +also that the plotting programs themselves have options to reverse the +displayed graph. So if all one wants is to reverse the direction of +increasing dispersion in a plot then physically flipping of the spectra is +not generally necessary. + +Flipping of both the coordinate system and the data is also equivalent +to using an image section with a reversed axis. For example +a one dimensional spectrum can be flipped in both dispersion coordinates +and data pixel order by + +.nf + cl> imcopy spec1[-*] spec2 +.fi + +Higher dimensional spectra need appropriate dimensions in the image +sections. One advantage of \fBsflip\fR is that it will determine the +appropriate dispersion axis itself. +.ih +EXAMPLES +In the following the spectra can be one dimensional, multispec, +long slit, or spectral data cubes. + +.nf + cl> sflip spec1 spec1f # Flip data to new image + cl> sflip spec1 spec1 # Flip data to same image + cl> sflip spec1 spec1f coord+ data- # Flip coordinates and not data + cl> sflip spec1 spec1f coord+ # Flip both coordinates and data + cl> sflip spec* f//spec* # Flip a list of images +.fi +.ih +REVISIONS +.ls SFLIP V2.10.4 +New in this release. Note that the V2.9 SFLIP was different in that +it was script which simply flipped the data. Coordinate systems were +not handled in the same way. +.le +.ih +SEE ALSO +imcopy, scopy, dispcor, sapertures +.endhelp diff --git a/noao/onedspec/doc/sinterp.hlp b/noao/onedspec/doc/sinterp.hlp new file mode 100644 index 00000000..b983beba --- /dev/null +++ b/noao/onedspec/doc/sinterp.hlp @@ -0,0 +1,146 @@ +.help sinterp Mar92 noao.onedspec +.ih +NAME +sinterp -- Interpolate a tables of x,y pairs to produce a spectrum +.ih +USAGE +sinterp tbl_file +.ih +PARAMETERS +.ls tbl_file +The name of a file which contains the x,y pairs to be used as +the basis for interpolation. The pairs must be in order of +increasing x. +.le + +The following parameters may or may not be necessary, depending +on the options selected. + +.ls input +If a few single elements are desired, rather than a full +array of elements, the user may enter a sequence of x values +from the terminal or a file to be used to interpolate into +the x,y table (parameter curve_gen=no). +.le +.ls image +If parameter make_image=yes, then an image file name is needed +.le +.ls order = 5 +If the interpolator is a polynomial fit or spline (interp_mode= +chebyshev, legnedre, spline3, spline1), the order of the fit +is required. +.le +.ls x1 +If parameter curve_gen=yes, this is the starting x value to +begin the curve generation. +.le + +Of the following three parameters, two must be specified, and the +third will be derived. + +.ls x2 = 0.0 +As above, but x2 determines the endpoint of the curve. +.le +.ls dx = 0.0 +As above, but dx determines the pixel-to-pixel increment +to be used during the curves generation. +.le +.ls npts = 0 +As above, but this determines the number of pixels to be generated. +.le + +.ls curve_gen = no +If this parameter is set to yes, then parameters x1, and two of +the three x2, dx, npts are required. The output is in the form +of new x,y pairs and may be redirected to a text file. +But if parameter make_image is also yes, the output is +in the form of an IRAF image file having the name given by +the parameter image. If curve_gen=no, the user must supply +a set of x values and interpolation is performed on those values. +.le +.ls make_image = no +If set to yes, then curve_gen=yes is implied and an image file name +is requied. A one dimensional IRAF image is created. +.le +.ls tbl_size = 1024 +This parameter defines the maximum size to be set aside for +memory storage of the input x,y pairs. +.le +.ls interp_mode = "chebyshev" +This parameter controls the method of interpolation. The linear +and curve options are true interpolators, while chebyshev, +legendre, spline3, and splin1 are fits to the data. +.le +.ih +DESCRIPTION +The specified file is read assuming it is a text file containing +pairs of x,y values in the form: xxx yyy. The table is used +to define the function y(x). The pairs must be entered in the file +in increasing order of x. + +The user specifies either specific x values for which the function +is to be evaluated, or specifies that a sequence of values beginning +with x1 are to be generated. In the former case, the explicit x values +may come either from the keyboard or from a file. In the latter case +the user must also specify the sequence by defining the increment, dx, +the endpoint, x2, and the number of points to generate in the sequence. +Then y(x) is evaluated at x1, x1+dx, x1+2*dx, ... , x1+(n-2)*dx, x2. +Only 2 of the 3 parameters (x2, dx, npts) are needed to fully +specify the sequence. + +The output of the function evaluation is either new x,y pairs written +to STDOUT, or an IRAF image. + +The function used to evaluated the tabular data may be any of the following +forms: + +.ls (1) +Linear interpolation between points. +.le +.ls (2) +Smooth interpolation between points. +.le +.ls (3) +A polynomial fit of either Legendre or Chebyshev types. +.le +.ls (4) +A cubic or linear spline. +.le + +If the table of x,y pairs is very large, the parameter tbl_size +should be set to the number of pairs. For example, if a spectrum +is available as a text file of x,y pairs (such as might be +obtained from IUE), and the number of pairs is 4096, then tbl_size +should be set to 4096. This provides for sufficient memory to +contain the table. + +.ih +EXAMPLES +The following shows how a text file may be used to generate a spectrum: + +.nf + cl> sinterp textfile make+ x1=4000 x2=5000 npts=1024 \ + >>> image=testimage interp_mode=curve +.fi + +The following sequence shows how to generate a spectrum of an IRS +standard star using the calibration file data as the source. + +.nf + cl> lcalib flam feige34 caldir=onedstds$irscal/ >textfile + cl> sinterp textfile make+ x1=3550 dx=1.242 npts=1024 \ + >>> interp_mode=linear image=feige34 +.fi +.ih +REVISIONS +.ls SINTERP V2.10.3+ +The image header dispersion coordinate system has been updated to the +current system. +.le +.ls SINTERP V2.10 +This task is unchanged. +.le +.ih +SEE ALSO +lcalib +.endhelp diff --git a/noao/onedspec/doc/skytweak.hlp b/noao/onedspec/doc/skytweak.hlp new file mode 100644 index 00000000..857e4380 --- /dev/null +++ b/noao/onedspec/doc/skytweak.hlp @@ -0,0 +1,311 @@ +.help skytweak Mar97 noao.onedspec +.ih +NAME +skytweak -- sky subtract 1D spectra after tweaking sky spectra +.ih +SUMMARY +Sky spectra are shifted and scaled to best subtract sky features from data +spectra. This may be done non-interactively to minimize the RMS in some +region or regions of the data spectra and interactively with a graphically +search. +.ih +USAGE +skytweak input output cal +.ih +PARAMETERS +.ls input +List of input data images containing one dimensional spectra to be +corrected. All spectra in each image are corrected. The spectra need not +be wavelength calibrated. +.le +.ls output +List of output corrected images. The list must either match the input list +or be an empty list. If an empty list is specified the input spectra will +be replaced by the corrected spectra. The input spectra will also be +replaced if the input and output image names are the same. Any other image +name must be for a new image otherwise a warning message will be given and +the task will proceed to the next input image. +.le +.ls cal +List of sky calibration images. If a single image is specified it +will apply to all the input images. Otherwise the list of calibration +images must match the list of input images. +.le +.ls ignoreaps = no +Ignore aperture numbers between the input spectra and the calibration +spectra? If "no" then the calibration image must contain a spectrum +with the same aperture number as each spectrum in the input image. +Otherwise the first spectrum in the calibration image will be used +for all spectra in the input image. +.le +.ls xcorr = yes +Cross-correlate each input spectrum with the calibration spectrum to +determine an shift for the calibration spectrum? Only regions specified by +the sample regions parameter will be used in the cross-correlation. +.le +.ls tweakrms = yes +Search for the minimum RMS in the corrected spectrum by adjusting the +shifts and scales between the input spectrum and the calibration spectrum? +The RMS is minimized in the specified sample regions. +.le +.ls interactive = yes +Enter an interactive graphical mode to search for the best shift +and scale between the input spectra and calibration spectra? This +is done after the optional automatic cross-correlation and RMS minimization +step. A query is made for each input spectrum so that the interactive +step may be skipped during the execution of the task. +.le +.ls sample = "*" +Sample regions to use for cross-correlation, automatic RMS minimization, +and RMS values. The sample regions are specified by a list of comma +separated ranges. The ranges are colon separate coordinate values. +For dispersion calibrated spectra the coordinate values are in the +dispersion units otherwise they are in pixel coordinates. The string "*" +selects the entire spectrum. The sample regions may be changed +interactively either with the cursor or with a colon command. +.le +.ls lag = 10 +The cross-correlation lag to use when \fIxcorr\fR = yes. The lag +is given in pixels. This is the distance to either side of the +initial shift over which the cross-correlation profile is computed. +If a value of zero is given then the cross-correlation step is not done. +.le +.ls shift = 0., dshift = 1. +The initial shift and shift step in pixels. This initializes the shift +search parameters for the first spectrum. If \fIdshift\fR is zero then +there will be no search for a new shift and the 'x' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls scale = 1., dscale = 0.2 +The initial scale and scale step. This initializes the scale +search parameters for the first spectrum. If \fIdscale\fR is zero then +there will be no search for a new scale and the 'y' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls offset = 1. +The interactive search displays three candidate corrected spectra which +have been normalized to a mean of one. The offset is added and subtracted +to separate the three candidates. The value may be changed interactively. +.le +.ls smooth = 1 +The displayed candidate corrected spectra are smoothed by a moving +boxcar average with a box size specified by this parameter. The smoothing +only applies to the displayed spectra and does not affect the measured +RMS or the output corrected spectra. The value may be changed interactively. +.le +.ls cursor = "" +Input cursor for the interactive graphics. A null value selects the +graphics cursor otherwise a file of cursor values may be specified. +.le +.ls answer +Query parameter for responding to the interactive question. This parameter +should not be specified on the command line. +.le +.ls interp = poly5 +The \fBpackage\fR parameter specifying the interpolation function for shifting +the calibration spectra to match the input spectra. +.le +.ih +DESCRIPTION +Input one dimensional spectra are corrected to remove sky features by +subtracting a shifted and scaled sky calibration spectra. +The shifting +allows for possible small shifts or errors in the dispersion zeropoints. + +The following describes the correction. Let J(x_i) be the calibration +spectrum at a set of pixels x_i. An interpolation function is fit to this +spectrum to give J(x). The shifted and scaled calibration function +is then + +.nf + (1) J'(x) = J(x+dx) *scale +.fi + +where dx is the pixel shift parameter and +scale is the scale parameter. +The output corrected spectrum is then computed as + +.nf + (2) I'(x_i) = I(x_i) - J'(x_i) +.fi + +where I' is the corrected spectrum and I is the input spectrum. If the +spectra are dispersion calibrated, possibly with different dispersion +parameters, then the x values in (2) from the input spectrum are converted +to matching pixels in the calibration spectrum using the dispersion +functions of the two spectra. + +The purpose of this task is to determine the best values of the +shift and scale parameters dx and scale. There +are automatic and interactive methods provided. The automatic +methods are cross-correlation of the calibration and input spectra +to find a shift and an iterative search for the in both +shift and scale that minimizes the RMS of I' in some region. +The automatic methods are performed first, if selected, followed +by the interactive, graphical step. The following describes +the steps in the order in which they occur. + +The initial values of the shift and scale are set by the parameters +\fIshift\fR and \fIscale\fR for the first spectrum. After that the values +determined for the previous spectrum, those actually applied to correcting +that spectrum, are used as the initial values for the next spectrum. The +search steps and sample regions are also initialized by task parameters but +may be modified during the interactive step and the modified values apply +to subsequent spectra. + +If the \fIxcorr\fR parameter is yes and the \fIlag\fR parameter is +not zero the calibration spectrum is cross-correlated against the input +spectrum. Each spectrum is prepared as follows. A large scale continuum +is fit by a quadratic chebyshev using 5 iterations of sigma clipping with a +clipping factor of 3 sigma below the fit and 1 sigma above the fit and +rejecting the deviant points along with one pixel on either side. This +attempts to eliminate the effects of absorption lines. The continuum fit +is subtracted from the spectrum and the spectrum is extended and tapered by +a cosine function of length given by the \fIlag\fR parameter. + +The prepared spectra are then cross-correlated by shifting the calibration +spectrum plus and minus the specified \fIlag\fR amount about the current +shift value. Only the regions in the input spectrum specified by the +sample regions parameter are used in the correlation. This produces a +correlation profile whose peak defines the relative shift between the two +spectra. The current shift value is updated. This method assumes the +common telluric features dominate within the specified sample regions. The +lag size should be roughly the profile widths of the telluric features. + +If the \fItweakrms\fR parameter is yes and \fIdshift\fR is greater than +zero trial corrections at the current shift value and plus and minus one +shift step with the scale value fixed at its current value are made and the +RMS in the sample regions computed. If the RMS is smallest at the current +shift value the shift step is divided in half otherwise the current shift +value is set to the shift with the lowest RMS. The process is then +repeated with the new shift and shift step values. This continues until +either the shift step is less than 0.01 pixels or the shift is more than +two pixels from the initial shift. In the latter case the final shift is +reset to the original shift. + +The scale factor is then varied if \fIdscale\fR is greater than zero by the +scale step at a fixed shift in the same way as above to search for a +smaller RMS in the sample regions. This search terminates when the scale +step is less than 0.01 or if the scale value has departed by 100% of the +initial value. In the latter case the scale value is left unchanged. + +The search over the shifts and scales is repeated a second time after which +the tweak algorithm terminates. + +After the optional cross-correlation and tweak steps the interactive search +mode may be entered. This occurs if \fIinteractive\fR = yes. A query is +asking whether to search interactively. The answers may be "no", "yes", +"NO", or "YES". The lower case answers apply to the current spectrum and +the upper case answers apply to all subsequent spectra. This means that if +an answer of "NO" or "YES" is given then there will be no further queries +for the remaining input spectra. + +If the interactive step is selected a graph of three candidate corrections +for the input spectrum is displayed. There also may be a graph of the +calibration or input spectrum shown for reference. Initially the +calibration spectrum is displayed. The additional graph may be toggled off +and on and between the input and calibration spectra with the 'c' and 'd' +keys. The three candidate corrected spectra will be with the current shift +and scale in the middle and plus or minus one step in either the shift or +scale. Initially the spectra will be at different scale values. +Information about the current shift and scale and the step used is given in +the graph title. + +One may toggle between shift steps and scale steps with the 'x' (for shift) +or 'y' (for scale) keys. The RMS in the title is the RMS within the +currently defined sample regions. If one of the step values is zero then a +display of different values of that parameter will not be selected. The +step size will need to be set with a colon command to search in that +parameter. + +If 'x' is typed when the three spectra are at different shifts then the +nearest spectrum to the y cursor at the x cursor position will be +selected. If the central spectrum is selected the step size is divided in +half otherwise the current shift is changed and the selected spectrum +becomes the middle spectrum. Three new spectra are then shown. The same +applies if 'y' is typed when the three spectra are at different scales. +This allows an interactive search similar to the iterative tweakrms method +described previously except the user can use whatever criteria is desired +to search for the best scale and shift. + +There are additional keystrokes and colon commands to set or change sample +regions, reset the current shift, scale, and step sizes, expand the step +size in the current mode, adjust the offsets between the spectra, and +get help. The 'w' key and GTOOLS colon commands are available to window +the graphs. Any changes in the x limits apply to both graphs while y limit +adjustments apply to the graph pointed to by the cursor. + +Two other commands require a short explanation. The 'a' key may +be used to run the tweakrms algorithm starting from the current +shift, scale, and steps and the current sample regions. This allows +one to graphically set or reset the sample regions before doing +the RMS minimization. The ":smooth" command and associated +\fIsmooth\fR task parameter allow the corrected spectra to be +displayed with a boxcar smoothing to better see faint features in +noise. It is important to realize that the smoothing is only +done on the displayed spectra. The telluric correction and computed RMS +are done in the unsmoothed data. + +After the interactive step is quit with 'q' or if the interactive +step is not done then the final output spectrum is computed and +written to the output image. A brief log output is printed for +each spectrum. +.ih +CURSOR KEYS AND COLON COMMANDS +.nf +? - print help +a - automatic RMS minimization within sample regions +c - toggle calibration spectrum display +d - toggle data spectrum display +e - expand (double) the step for the current selection +q - quit +r - redraw the graphs +s - add or reset sample regions +w - window commands (see :/help for additional information) +x - graph and select from corrected shifted candidates +y - graph and select from corrected scaled candidates + +:help - print help +:shift [value] - print or reset the current shift +:scale [value] - print or reset the current scale +:dshift [value] - print or reset the current shift step +:dscale [value] - print or reset the current scale step +:offset [value] - print or reset the current offset between spectra +:sample [value] - print or reset the sample regions +:smooth [value] - print or reset the smoothing box size +.fi +.ih +EXAMPLES +1. To interactively search for a best correction with the default +cross-correlation and tweak steps: + +.nf + cl> skytweak spec001.ms skyspec001.ms spec005.ms +.fi + +2. To search only for a scale factor: + +.nf + cl> skytweak spec001.ms skyspec001.ms spec005.ms xcorr- dshift=0. +.fi + +3. To processes a set of spectra non-interactively with the same calibration +spectrum and to replace the input spectra with the corrected spectra and +log the processing: + +.nf + cl> skytweak spec* "" skyspec inter- > log +.fi +.ih +REVISIONS +.ls SKYTWEAK V2.11 +This task is new in this version. +.le +.ih +SEE ALSO +telluric +.endhelp diff --git a/noao/onedspec/doc/skytweak.key b/noao/onedspec/doc/skytweak.key new file mode 100644 index 00000000..a694ba36 --- /dev/null +++ b/noao/onedspec/doc/skytweak.key @@ -0,0 +1,35 @@ + SKYTWEAK COMMAND SUMMARY + +? - print help +a - automatic RMS minimization within sample regions +c - toggle calibration spectrum display +d - toggle data spectrum display +e - expand (double) the step for the current selection +q - quit +r - redraw the graphs +s - add or reset sample regions +w - window commands (see :/help for additional information) +x - graph and select from corrected shifted candidates +y - graph and select from corrected scaled candidates + +:help - print help +:shift [value] - print or reset the current shift +:scale [value] - print or reset the current scale +:dshift [value] - print or reset the current shift step +:dscale [value] - print or reset the current scale step +:offset [value] - print or reset the current offset between spectra +:sample [value] - print or reset the sample regions +:smooth [value] - print or reset the smoothing box size + + +The stacked display shows three corrected candidate spectra. The center +one is for the current shift and scale and the other two are one step +higher or lower in the shift or scale. The current values and the +step is shown in the title. Toggle between the shift and scale candidates +with 'x' or 'y'. Select the best spectrum with the cursor and typing +'x' or 'y'. Selecting the middle spectrum with 'x' in the shift display +divides the shift step in half. Selecting one of the other spectra +changes the current shift. Selecting the middle spectrum with 'y' +in the scale display divides the scale step in half. Selecting one of +the other spectra changes the current scale. When 'q' is typed the +final shift and scale will be that of the middle spectrum. diff --git a/noao/onedspec/doc/slist.hlp b/noao/onedspec/doc/slist.hlp new file mode 100644 index 00000000..322914b0 --- /dev/null +++ b/noao/onedspec/doc/slist.hlp @@ -0,0 +1,142 @@ +.help slist Mar92 noao.onedspec +.ih +NAME +slist -- List spectral header information +.ih +USAGE +slist images +.ih +PARAMETERS +.ls images +List of images to be listed. +.le +.ls apertures = "" +List of apertures to be selected from the images for listing. A null +list selects all apertures. See \fBranges\fR for the syntax of +this list. +.le +.ls long_header = no +If set to yes, then a multiline listing of the header elements is given. +If set to no, then a single line per spectrum is given. The contents +of the listing depend on the format. +.le +.ih +DESCRIPTION +This task lists header information from apertures in a list of input +images. There is a short one line per spectrum listing and a more +extended listing selected by the \fIlong_header\fR parameter. + +In both short and long outputs the aperture information consists of +lines with the following whitespace separated fields: the image line, +the aperture number, the beam number, the dispersion type, the +wavelength of the first pixel, the wavelength interval per pixel, +the number of valid pixels, and the aperture title. The dispersion +type is an integer with a value of -1 if not dispersion corrected, +0 if dispersion corrected to a linear wavelength sampling, 1 if +dispersion corrected to a log wavelength sampling, and 2 if dispersion +corrected to a nonlinear sampling. The wavelength per pixel is +an approximation based on the wavelength endpoints divided by the +number of pixels in the case of a nonlinear dispersion function. +Also the wavelengths refer to the actual pixels taking any image sections +into account and so may differ from the coordinate system information in +the header which is defined for the original physical coordinates. +The aperture titles may be identical with the image title if individual +aperture titles are not defined. + +In the short output format the image title is given first followed +by the above described information. This format is compact and +suitable for easy use in other programs (see the example below). +The long output format is blocked by image and gives the image name +and title on the first line, the exposure time, universal time, +and siderial time on the second line, the right ascention, declination, +hour angle, and airmass on the third line, and then the individual +aperture information on the remaining lines. If some of the header +information is missing a value of INDEF is printed. The keywords used +are EXPTIME/ITIME/EXPOSURE (in that order) for the exposure time, +and UT, ST, RA, DEC, HA, and AIRMASS for the remaining values. + + demoobj.ms: Hydra artificial image + EXPTIME = 2133.33 UT = 9:10:09.0 ST = 20:09:34.0 + RA = 1:34:02.00 DEC = 30:37:03.0 HA = INDEF AIRMASS = 2.3 +.ih +EXAMPLES +1. List short header for an object and arc from a Hydra multifiber reduction +for fibers 36 to 39. + +.nf + cl> slist demoobj.ms,demoarc1.ms ap=36-39 + demoobj.ms 1 37 0 0 5785.85 6.140271 256 Sky fiber + demoobj.ms 2 38 1 0 5785.85 6.140271 256 SS313 + demoobj.ms 3 39 1 0 5785.85 6.140271 256 SS444 + demoarc1.ms 1 36 2 0 5785.85 6.140271 256 Arc fiber + demoarc1.ms 2 37 0 0 5785.85 6.140271 256 Sky fiber + demoarc1.ms 3 38 1 0 5785.85 6.140271 256 SS313 + demoarc1.ms 4 39 1 0 5785.85 6.140271 256 SS444 +.fi + +Note that fiber 37 is the first image line in demoobj.ms and teh second image +line in demoarc.ms. The dispersion is the same in all fibers by design. + +2. List long headers for the two images of example 1 but restricted to +apertures 38 and 39. + +.nf + cl> slist demoobj.ms,demoarc1.ms ap=38,39 l+ + demoobj.ms: Hydra artificial image + EXPTIME = 2133.33 UT = 9:10:09.0 ST = 20:09:34.0 + RA = 1:34:02.00 DEC = 30:37:03.0 HA = INDEF AIRMASS = 2.3 + 2 38 1 0 5785.85 6.140271 256 SS313 + 3 39 1 0 5785.85 6.140271 256 SS444 + demoarc1.ms: Hydra artificial image + EXPTIME = 2133.33 UT = 9:10:09.0 ST = 20:09:34.0 + RA = 1:34:02.00 DEC = 30:37:03.0 HA = INDEF AIRMASS = 2.3 + 3 38 1 0 5785.85 6.140271 256 SS313 + 4 39 1 0 5785.85 6.140271 256 SS444 +.fi + +The other header parameters are the same because this is artificial +data using the same template header. + +3. Dump the set of image headers on a printer in long format. + +.nf + cl> slist *.ms.imh l+ | lprint +.fi + +4. The short form of SLIST may be used to get some of the aperture +information for use in a script. The following simply prints the +image line corresponding to a specified aperture. In a real application +something more complex would be done. + +.nf + procedure example (images, aperture) + + string images {prompt="List of images"} + int aperture {prompt="Aperture"} + + begin + string temp, image + int line + + # Use SLIST to print to a temporary file. + temp = mktemp ("example") + slist (images, aperture=aperture, long=no, > temp) + + # Scan each line and print the line number. + list = temp + while (fscan (list, image, line) != EOF) + print (image, ": ", line) + list = "" + delete (temp, verify=no) + end +.fi +.ih +REVISIONS +.ls SLIST V2.10 +This task was revised to be relevant for the current spectral image +formats. The old version is still available in the IRS/IIDS package. +.le +.ih +SEE ALSO +imheader, hselect +.endhelp diff --git a/noao/onedspec/doc/specplot.hlp b/noao/onedspec/doc/specplot.hlp new file mode 100644 index 00000000..222d77ff --- /dev/null +++ b/noao/onedspec/doc/specplot.hlp @@ -0,0 +1,387 @@ +.help specplot Jan96 noao.onedspec +.ih +NAME +specplot -- stack and plot multiple spectra +.ih +USAGE +specplot spectra +.ih +PARAMETERS +.ls spectra +List of spectra to plot. The spectra are assigned index numbers increasing +from one in the order of the list. +.le +.ls apertures = "" +List of apertures to plot. An empty list selects all apertures. +An aperture list consists of a comma separated list of aperture numbers or +hyphen separated range of numbers. A step size may also be specified preceded +by 'x'. See \fBranges\fR for more. +.le +.ls bands = "1" +List of bands to plot if the image is three dimensional. The list has +the same syntax as for the apertures. +.le +.ls dispaxis = 1, nsum = 1 +Parameters for defining vectors in 2D images. The +dispersion axis is 1 for line vectors and 2 for column vectors. +A DISPAXIS parameter in the image header has precedence over the +\fIdispaxis\fR parameter. These may be changed interactively. +.le +.ls autolayout = yes +Automatically layout the spectra by shifting or scaling to a common mean +and determining a separation step which does overlaps the spectra +by the specified fraction? The algorithm uses the following parameters. +.ls autoscale = yes +Scale the spectra to a common mean? If no then the spectra are shifted +to a common mean and if yes they are scaled to a common mean. +.le +.ls fraction = 1. +The separation step which just avoids overlapping the spectra is multiplied +by this number. Numbers greater than 1 increase the separation while numbers +less than 1 decrease the separation and provide some amount of overlap. +.le +.le +.ls units = "" +Dispersion coordinate units. If the spectra have known units, currently +this is generally Angstroms, the plotted units may be converted +for plotting to other units as specified by this parameter. +If this parameter is the null string then the units specified by the +world coordinate system attribute "units_display" is used. If neither +is specified than the units of the coordinate system are used. +The units +may also be changed interactively. See the units section of the +\fBonedspec\fR help for a further description and available units. +.le +.ls transform = "none" (none|log) +Transform for the input pixel values. Currently only "log" is implemented. +If all pixels are negative the spectrum values will be unchanged and if +some pixels are negative they are mapped to the lowest non-negative value in +the spectrum. Note that this cannot be changed interactively or applied +independently for each spectrum. To change the setting one must exit +the task and execute it with the new value. +.le +.ls scale = 1., offset = 0. (value, @file, keyword) +The scale and offset to apply to each spectrum. The value of the parameter +may be a constant value applying to all spectra, a file containing the +values specified as @<file> where <file> is the filename, or an image +header keyword whose value is to be used. +.le +.ls step = 0 +The step separating spectra when not using the autolayout option. +The value of this parameter depends on the range of the data. +.le +.ls ptype = "1" +Default plotting type for the spectra. A numeric value selects line plots +while marker type strings select marker plots. The sign of the line type +number selects histogram style lines when negative or connected pixel +values when positive. The absolute value selects the line type with 0 +being an invisible line, 1 being a solid line, and higher integers +different types of lines depending on the capabilities of the graphics +device. The marker type strings are "point", "box", "plus", "cross", +"diamond", "hline", "vline", "hebar", "vebar", and "circle". +The types for individual spectra may be changed interactively. +.le +.ls labels = "user" +Spectrum labels to be used. If the null string or the word "none" is +given then the spectra are not labeled. The word "imname" labels the +spectra with the image name, the word "imtitle" labels them wih the +image title, the word "index" labels them with the index number, and +the word "user" labels them with user defined labels. The user labels +may be given in the file specified by the parameter \fIulabels\fR, which +are matched with the list of spectra, and also added interactively. +.le +.ls ulabels = "" +File containing user labels. +.le +.ls xlpos = 1.02, ylpos = 0.0 +The starting position for the spectrum labels in fractions of the +graph limits. The horizontal (x) position is measured from the left +edge while the vertical position is measured from the mean value of the +spectrum. For vertical positions a negative value may be used to label +below the spectrum. The default is off the right edge of the graph at +the mean level of the spectrum. +.le +.ls sysid = yes +Include system banner and separation step label? This may be changed +interactively using ":/sysid". +.le +.ls yscale = no +Draw a Y axis scale? Since stacked plots are relative labeling the Y +axes may not be useful. This parameter allows adding the Y axis scale +if desired. The default is to not have a Y axis scale. +.le +.ls title = "", xlabel = "", ylabel = "" +Title, x axis label, and y axis label for graphs. These may be changed +interactively using ":/title", ":/xlabel", and ":/ylabel". +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The default limits for the initial graph. If INDEF then the limit is +determined from the range of the data (autoscaling). These values can +be changed with 'w' cursor key or the cursor commands ":/xwindow" and +":/ywindow". +.le +.ls logfile = "" +Logfile to record the final set of spectra and scale factors displayed. +.le +.ls graphics = "stdgraph" +Output graphics device. One of "stdgraph", "stdplot", "stdvdm", +@(enviroment variable), or actual device. +.le +.ls cursor = "" +Graphics cursor input. When null the standard cursor is used otherwise +the specified file is used. +.le +.ih +DESCRIPTION +\fBSpecplot\fR plots multiple spectra with provisions for scaling them, +separating them vertically, shifting them horizontally, and labeling them. +The layout can be defined by an automatic algorithm or explicitly and +adjusted noninteractively (with some limitations) or interactively. The +plotting units can be selected and the vertical axis scale can be shown or +not as desired. This task is used for compressing many spectra to a page +for review, intercomparison of spectra, classification against standards, +and final display. + +The input list of spectra consists of one, two, or three dimensional images. +The set of spectra may be restricted to specific apertures using the +\fIapertures\fR parameter. Note that for true 2D images, such as long slit +spectra, the aperture number corresponds to the line or column to be plotted +and the dispersion axis and nsum parameter are determined either from the +image header or the package parameters. Spectra extracted +with the \fBapextract\fR package may be three dimensional where the 3rd +dimension corresponds to related data. The higher dimensional data is +also plotted though it may be restricted with the \fIbands\fR +parameter. + +Each spectrum has a number of associated parameters which are initially +assigned default values but which may be changed interactively. First each +spectrum is assigned an index number. This is generally sequential +starting from 1. Spectra added interactively are assigned the next higher +or lower index relative to the spectrum being appended or inserted. The +index is used for refering to parameters of a particular spectrum and for +separating the spectra vertically. The spectra are scaled and shifted by +the equation + + I = value * scale + offset + (index - 1) * step + +where "I" is the final plotted value, "value" is the pixel value, "scale" +is a multiplicative scaling, "offset" is a additive offset, and "step" is +an additive separation step used to stack spectra vertically. + +The default values of the vertical scaling parameters may be set by an +automatic layout algorithm or with explicit constants (the same for all +spectra). The automatic mode is selected with the parameter +\fIautolayout\fR and works as follows. All spectra are scaled or shifted +to a common mean (depending on the parameter \fIautoscale\fR) relative to +the lowest indexed spectrum. A step size is then computed to just avoid +overlapping of the minimum of one spectrum with the maximum of another. +Note that this may not yield a good layout if the spectra have large +continuum slopes. Finally, to add some extra space between the spectra or +to allow some overlap, the minimum step is multiplied by a specified +overlap factor, \fIfraction\fR. + +In nonautomatic mode the user specifies the intensity scale, offset, +and separation step explicitly with the parameters, \fIscale, offset\fR +and \fIstep\fR. If the step is zero then spectra will be directly +overplotted while a positive or negative value will separate the +spectra either upward or downward with the index 1 spectrum having no +offset. The scale and offset parameters may be specified as either +constant values, the name of file containing the values (one per line) +preceded by the '@' character, or the name of an image header keyword. +This parameter as well as the scale and offset may be set or +changed interactively via colon commands and the "offset" may also be +set using the cursor to shift a spectrum vertically. + +In addition to shifting spectra vertically they may also be shifted +horizontally as a velocity/redshift or a zero point change with either +cursor or colon commands. The dispersion, inteval per pixel, may be +modified, either with the 't' key or the "wpc" command, in which case if +the dispersion is nonlinear the spectra will be linearized. + +Each spectrum may have a label associated with it. The label type may +be the image name, the image title, the index number, or a user defined +label. The default label type is specified by the parameter +\fIlabels\fR. For user labels the initial labels may be specified in a +file. Interactively the label type may be changed using the ":labels" +command and the user assigned labels may be defined by a colon command +or by using the cursor to mark the position for the label. The label +position is given relative to the range of the graph and the mean +intensity. The default values are set by the parameters \fIxlpos\fR +and \fIylpos\fR. The positions may be changed interactively for all +the spectra or individually. The latter may be done using the cursor +to mark exactly where the label is to go. + +Each spectrum has an associated plotting type. The default type which +applies to all spectra initially is specified by the parameter +\fIptype\fR. This parameter specifies both whether line mode or +marker mode is used and the line type, line style, or marker type to use. +The line +mode and types are given by a small integers with the style, connected +pixel centers or histogram style, chosed by the sign of the integer. +The type of lines produced depend on the capabilities of the terminal. In most +cases a zero line type is invisible. (This may be used interactively +to temporarily eliminate a spectrum from a plot instead of deleting the +spectrum from the list of spectra). A line type of 1 is a solid line +and additional line types are specified by higher numbers. +The marker types are given by name as described in the parameter +section. There is currently no combination of line and marker (such as +connected points with vertical bars) or histogram type plotting. The +plotting type may be changed interactively for individual spectra or +for all spectra using colon commands. + +The cursor and colon commands generally apply to the spectrum nearest +the cursor. This is determined by finding the nearest data point to +the cursor. For the colon commands the spectrum may also be specified +explicitly by the index number using an optional suffix "[index]", where +index is the index number for the spectrum. Also the special index "*" +may be specified to apply to all spectra. + +The operations of adding, deleting, moving, or shifting spectra affect +the index numbers of the other spectra. When deleting a spectrum the +index numbers of all spectra with greater index numbers are decreased +by one resulting in the plotted spectra moving down (positive step). +When adding a spectrum the index numbers above the inserted spectrum +are increased by one resulting in the spectra moving up. Moving a +spectrum to a new index number is equivalent to deleting the spectrum +and then inserting it at the new index position. Spectra may be +shifted to insert gaps in the plotted spectra. The specified value is +added to all spectra above and including the one indicated if the value +is positive to all spectra below and including the one indicated if the +value is negative. +.ih +CURSOR COMMANDS + +The indicated spectrum is the one with a point closest to the cursor position. +.nf + +? - Print help summary +a - Append a new spectrum following the indicated spectrum +i - Insert a new spectrum before the indicated spectrum +d - Delete the indicated spectrum +e - Insert last deleted spectrum before indicated spectrum +f - Toggle between world coordinates and logical pixel coordinates +l - Define the user label at the indicated position +p - Define the label position at the indicated position +o - Reorder the spectra to eliminate gaps +q - Quit +r - Redraw the plot +s - Repeatedly shift the indicated spectrum position with the cursor + q - Quit shift x - Shift horizontally in velocity + s - Shift vertically in scale y - Shift vertically in offset + t - Shift horizontally in velocity z - Shift horizontally in velocity + and vertically in scale and vertically in offset +t - Set a wavelength scale using the cursor +u - Set a wavelength point using the cursor +v - Set velocity plot with zero point at cursor +w - Window the plot +x - Cancel all scales and offsets +y - Automatically layout the spectra with offsets to common mean +z - Automatically layout the spectra scaled to common mean +.fi +.ih +COLON COMMANDS + +A command without a value generally shows the current value of the +parameter while with a value it sets the value of the parameter. The show +commands print to the terminal unless a file is given. For the spectrum +parameters the index specification, "[index]", is optional. If absent the +nearest spectrum to the cursor when the command is given is selected except +for the "units" command which selects all spectra. The index is either a +number or the character *. The latter applies the command to all the +spectra. + +.nf +:show <file> Show spectrum parameters (file optional) +:vshow <file> Show verbose parameters (file optional) +:step <value> Set or show step +:fraction <value> Set or show autolayout fraction +:label <value> Set or show label type + (none|imtitle|imname|index|user) + +:move[index] <to_index> Move spectrum to new index position +:shift[index|*] <value> Shift spectra by adding to index +:w0[index|*] <value> Set or show zero point wavelength +:wpc[index|*] <value> Set or show wavelength per channel +:velocity[index|*] <value> Set or show radial velocity (km/s) +:redshift[index|*] <value> Set or show redshift +:offset[index|*] <value> Set or show intensity offset +:scale[index|*] <value> Set or show intensity scale +:xlpos[index|*] <value> Set or show X label position +:ylpos[index|*] <value> Set or show Y label position +:ptype[index|*] <value> Set or show plotting type +:color[index|*] <value> Set or show color (1-9) +:ulabel[index|*] <value> Set or show user labels +:units[index|*] <value> Change coordinate units + +:/title <value> Set the title of the graph +:/xlabel <value> Set the X label of the graph +:/ylabel <value> Set the Y label of the graph +:/xwindow <min max> Set the X graph range + (use INDEF for autoscaling) +:/ywindow <min max> Set the X graph range + (use INDEF for autoscaling) + + +Examples: + w0 Print value of wavelength zero point + w0 4010 Set wavelength zero point of spectrum nearest the cursor + w0[3] 4010 Set wavelength zero point of spectrum with index 3 + w0[*] 4010 Set wavelength zero point of all spectra +.fi +.ih +EXAMPLES +1. To make a nice plot of a set of spectra with the default layout: + + cl> specplot spec* + +2. To set the colors or line types for multiple spectra in a batch +mode application create a cursor file like: + + cl> type cursor.dat + :color[1] 2 + :color[2] 3 + :color[3] 4 + r + cl> specplot im1,im2,im3 cursor=cursor.dat + +Note that the 'r' key is necessary redraw the graph with the changed +attributes. +.ih +REVISIONS +.ls SPECPLOT V2.11 +The scale and offset parameters may now be a value, a filename, or +and image header keyword. + +The 'f' key was added to toggle between world and logical pixel coordinates. +.le +.ls SPECPLOT V2.10.3 +A color parameter was added for graphics terminals supporting color. + +The :units command was extended to have an optional spectrum specifier. +This is primarily intended to plot different (or the same) spectra in +velocity but with different velocity zeros. + +The default task units parameter has been changed to "" to allow picking +up a "units_display" WCS attribute if defined. +.le +.ls SPECPLOT V2.10 +New parameters were added to select apertures and bands, plot +additional dimensions (for example the additional output from the extras +option in \fBapextract\fR), suppress the system ID banner, suppress the Y +axis scale, output a logfile, and specify the plotting units. The \fIptype\fR +parameter now allows negative numbers to select histogram style lines. +Interactively, the plotting units may be changed and the 'v' key allows +setting a velocity scale zero point with the cursor. The new version +supports the new spectral WCS features including nonlinear dispersion +functions. +.le +.ih +NOTES +The automatic layout algorithm is relatively simple and may not +provide visually satisfactory results in all cases. The fonts and Y axis +scale capabilities are not as good as might be desired for publication +quality plots. +.ih +SEE ALSO +bplot, splot, onedspec, gtools, ranges +.endhelp diff --git a/noao/onedspec/doc/specshift.hlp b/noao/onedspec/doc/specshift.hlp new file mode 100644 index 00000000..c72ebd0a --- /dev/null +++ b/noao/onedspec/doc/specshift.hlp @@ -0,0 +1,67 @@ +.help specshift Oct92 noao.onedspec +.ih +NAME +specshift -- Shift dispersion coordinate systems +.ih +USAGE +specshift spectra shift +.ih +PARAMETERS +.ls spectra +List of spectra to be modified. +.le +.ls shift +Dispersion coordinate shift to be added to the current dispersion coordinate +system. +.le +.ls apertures = "" +List of apertures to be modified. The null list +selects all apertures. A list consists of comma separated +numbers and ranges of numbers. A range is specified by a hyphen. An +optional step size may be given by using the 'x' followed by a number. +See \fBxtools.ranges\fR for more information. This parameter is ignored +for N-dimensional spatial spectra such as long slit and Fabry-Perot. +.le +.ls verbose = no +Print a record of each aperture modified? +.le +.ih +DESCRIPTION +This task applies a shift to the dispersion coordinate system of selected +spectra. The image data is not modified as with \fBimshift\fR but rather +the coordinate system is shifted relative to the data. The spectra to be +modified are selected by specifying a list of images and apertures. If no +aperture list is specified then all apertures in the images are modified. +For N-dimensional spatial spectra such as long slit and Fabry-Perot the +aperture list is ignored. + +The specified shift is added to the existing world coordinates. For linear +coordinate systems this has the effect of modifying CRVAL1, for linear +"multispec" coordinate systems this modifies the dispersion coordinate of +the first physical pixel, and for nonlinear "multispec" coordinate systems +this modifies the shift coefficient(s). + +It is also possible to shift the linearized coordinate systems (but not the +nonlinear coordinate systems) with \fBsapertures\fR or possibly with +\fBwcsedit\fR or \fBhedit\fR if the coordinate system is stored with a +global linear system. + +The \fIverbose\fR parameter lists the images, the apertures, the shift, and +the old and new values for the first physical pixel are printed. +.ih +EXAMPLES +1. To add 1.23 Angstroms to the coordinates of all apertures in the +image "ngc456.ms": + +.nf + cl> specshift ngc456.ms 1.23 +.fi +.ih +REVISIONS +.ls SPECSHIFT V2.10.3 +First version. +.le +.ih +SEE ALSO +sapertures, dopcor, imcoords.wcsreset, hedit, ranges, onedspec.package +.endhelp diff --git a/noao/onedspec/doc/specwcs.hlp b/noao/onedspec/doc/specwcs.hlp new file mode 100644 index 00000000..ed8852e3 --- /dev/null +++ b/noao/onedspec/doc/specwcs.hlp @@ -0,0 +1,586 @@ +.help specwcs Mar93 noao.onedspec + +.ce +\fBThe IRAF/NOAO Spectral World Coordinate Systems\fR + + +.sh +1. Types of Spectral Data + +Spectra are stored as one, two, or three dimensional images with one axis +being the dispersion axis. A pixel value is the flux over +some interval of wavelength and position. The simplest example of a +spectrum is a one dimensional image which has pixel values as a +function of wavelength. + +There are two types of higher dimensional spectral image formats. One type +has spatial axes for the other dimensions and the dispersion axis may be +along any of the image axes. Typically this type of format is used for +long slit (two dimensional) and Fabry-Perot (three dimensional) spectra. +This type of spectra is referred to as \fIspatial\fR spectra and the +world coordinate system (WCS) format is called \fIndspec\fR. +The details of the world coordinate systems are discussed later. + +The second type of higher dimensional spectral image consists of multiple, +independent, one dimensional spectra stored in the higher dimensions with +the first image axis being the dispersion axis; i.e. each line is a +spectrum. This format allows associating many spectra and related +parameters in a single data object. This type of spectra is referred to +as \fImultispec\fR and the there are two coordinate system formats, +\fIequispec\fR and \fImultispec\fR. The \fIequispec\fR format applies +to the common case where all spectra have the same linear dispersion +relation. The \fImultispec\fR format applies to the general case of spectra +with differing dispersion relations or non-linear dispersion functions. +These multi-spectrum formats are important since maintaining large numbers +of spectra as individual one dimensional images is very unwieldy for the +user and inefficient for the software. + +Examples of multispec spectral images are spectra extracted from a +multi-fiber or multi-aperture spectrograph or orders from an echelle +spectrum. The second axis is some arbitrary indexing of the spectra, +called \fIapertures\fR, and the third dimension is used for +associated quantities. The IRAF \fBapextract\fR package may produce +multiple spectra from a CCD image in successive image lines with an +optimally weighted spectrum, a simple aperture sum spectrum, a background +spectrum, and sigma spectrum as the associated quantities along the third +dimension of the image. + +Many \fBonedspec\fR package tasks which are designed to operate on +individual one dimensional spectra may operate on spatial spectra by +summing a number of neighboring spectra across the dispersion axis. This +eliminates the need to "extract" one dimensional spectra from the natural +format of this type of data in order to use tasks oriented towards the +display and analysis of one dimensional spectra. The dispersion axis is +either given in the image header by the keyword DISPAXIS or the package +\fIdispaxis\fR parameter. The summing factors across the +dispersion are specified by the \fInsum\fR package parameter. +See "help onedspec.package" for information on these parmaeters. + +One dimensional spectra, whether from multispec spatial spectra, have +several associated quantities which may appear in the image header as part +of the coordinate system description. The primary identification of a +spectrum is an integer aperture number. This number must be unique within +a single image. There is also an integer beam number used for various +purposes such as discriminating object, sky, and arc spectra in +multi-fiber/multi-aperture data or to identifying the order number in +echelle data. For spectra summed from spatial spectra the aperture number +is the central line, column, or band. In 3D images the aperture index +wraps around the lowest non-dispersion axis. Since most one dimensional +spectra are derived from an integration over one or more spatial axes, two +additional aperture parameters record the aperture limits. These limits +refer to the original pixel limits along the spatial axis. This +information is primarily for record keeping but in some cases it is used +for spatial interpolation during dispersion calibration. These values are +set either by the \fBapextract\fR tasks or when summing neighboring vectors +in spatial spectra. + +An important task to be aware of for manipulating spectra between image +formats is \fBscopy\fR. This task allows selecting spectra from multispec +images and grouping them in various ways and also "extracts" apertures from +long slit and 3D spectra simply and without resort to the more general +\fBapextract\fR package. +.sh +2. World Coordinate Systems + +IRAF images have three types of coordinate systems. The pixel array +coordinates of an image or image section, i.e. the lines and +columns, are called the \fIlogical\fR coordinates. The logical coordinates of +individual pixels change as sections of the image are used or extracted. +Pixel coordinates are tied to the data, i.e. are fixed to features +in the image, are called \fIphysical\fR coordinates. Initially the logical +and physical coordinates are the equivalent but differ when image sections +or other tasks which modify the sampling of the pixels are applied. + +The last type of coordinate system is called the \fIworld\fR coordinate +system. Like the physical coordinates, the world coordinates are tied to +the features in the image and remain unchanged when sections of the image +are used or extracted. If a world coordinate system is not defined for an +image, the physical coordinate system is considered to be the world +coordinate system. In spectral images the world coordinate system includes +dispersion coordinates such as wavelengths. In many tasks outside the +spectroscopy packages, for example the \fBplot\fR, \fBtv\fR and +\fBimages\fR packages, one may select the type of coordinate system to be +used. To make plots and get coordinates in dispersion units for spectra +with these tasks one selects the "world" system. The spectral tasks always +use world coordinates. + +The coordinate systems are defined in the image headers using a set of +reserved keywords which are set, changed, and updated by various tasks. +Some of the keywords consist of simple single values following the FITS +convention. Others, the WAT keywords, encode long strings of information, +one for each coordinate axis and one applying to all axes, into a set of +sequential keywords. The values of these keywords must then be pasted +together to recover the string. The long strings contain multiple pieces +called WCS \fIattributes\fR. In general the WCS keywords should be left to +IRAF tasks to modify. However, if one wants modify them directly some +tasks which may be used are \fBhedit\fR, \fBhfix\fR, \fBwcsedit\fR, +\fBwcsreset\fR, \fBspecshift\fR, \fBdopcor\fR, and \fBsapertures\fR. The +first two are useful for the simple keywords, the two "wcs" tasks are +useful for the linear ndspec and equispec formats, the next two are for the +common cases of shifting the coordinate zero point or applying a doppler +correction, and the last one is the one to use for the more complex +multispec format attributes. +.sh +3. Physical Coordinate System + +The physical coordinate system is used by the spectral tasks when there is +no dispersion coordinate information (such as before dispersion +calibration), to map the physical dispersion axis to the logical dispersion +axis, and in the multispec world coordinate system dispersion functions +which are defined in terms of physical coordinates. + +The transformation between logical and physical coordinates is defined by +the header keywords LTVi, LTMi_j (where i and j are axis numbers) through +the vector equation + +.nf + l = |m| * p + v +.fi + +where l is a logical coordinate vector, p is a physical +coordinate vector, v is the origin translation vector specified by +the LTV keywords and |m| is the scale/rotation matrix +specified by the LTM keywords. For spectra rotation terms (nondiagonal +matrix elements) generally do not make sense (in fact many tasks will not +work if there is a rotation) so the transformations along each axis are +given by the linear equation + +where l is a logical coordinate vector, p is a physical coordinate vector, +v is the origin translation vector specified by the LTV keywords and |m| is +the scale/rotation matrix specified by the LTM keywords. For spectra a +rotation term (nondiagonal matrix elements) generally does not make sense +(in fact many tasks will not work if there is a rotation) so the +transformations along each axis are given by the linear equation + +.nf + li = LTMi_i * pi + LTVi. +.fi + +If all the LTM/LTV keywords are missing they are assumed to have zero +values except that the diagonal matrix terms, LTMi_i, are assumed to be 1. +Note that if some of the keywords are present then a missing LTMi_i will +take the value zero which generally causes an arithmetic or matrix +inversion error in the IRAF tasks. + +The dimensional mapping between logical and physical axes is given by the +keywords WCSDIM and WAXMAP01. The WCSDIM keyword gives the dimensionality +of the physical and world coordinate system. There must be coordinate +information for that many axes in the header (though some may be missing +and take their default values). If the WCSDIM keyword is missing it is +assumed to be the same as the logical image dimensionality. + +The syntax of the WAXMAP keyword are pairs of integer values, +one for each physical axis. The first number of each pair indicates which +current \fIlogical\fR axis corresponds to the original \fIphysical\fR axis +(in order) or zero if that axis is missing. When the first number is zero +the second number gives the offset to the element of the original axis +which is missing. As an example consider a three dimensional image in +which the second plane is extracted (an IRAF image section of [*,2,*]). +The keyword would then appear as WAXMAP01 = '1 0 0 1 2 0'. If this keyword +is missing the mapping is 1:1; i.e. the dimensionality and order of the +axes are the same. + +The dimensional mapping is important because the dispersion axis for +the nspec spatial spectra as specified by the DISPAXIS keyword or task +parameter, or the axis definitions for the equispec and or multispec +formats are always in terms of the original physical axes. +.sh +4. Linear Spectral World Coordinate Systems + +When there is a linear or logarithmic relation between pixels and +dispersion coordinates which is the same for all spectra the WCS header +format is simple and uses the FITS convention (with the CD matrix keywords +proposed by Hanisch and Wells 1992) for the logical pixel to world +coordinate transformation. This format applies to one, two, and three +dimensional data. The higher dimensional data may have either linear +spatial axes or the equispec format where each one dimensional spectrum +stored along the lines of the image has the same dispersion. + +The FITS image header keywords describing the spectral world coordinates +are CTYPEi, CRPIXi, CRVALi, and CDi_j where i and j are axis numbers. As +with the physical coordinate transformation the nondiagonal or rotation +terms are not expected in the spectral WCS and may cause problems if they +are not zero. The CTYPEi keywords will have the value LINEAR to identify +the type of coordinate system. The transformation between dispersion +coordinate, wi, and logical pixel coordinate, li, along axis i is given by + +.nf + wi = CRVALi + CDi_i * (li - CRPIXi) +.fi + +If the keywords are missing then the values are assumed to be zero except +for the diagonal elements of the scale/rotation matrix, the CDi_i, which +are assumed to be 1. If only some of the keywords are present then any +missing CDi_i keywords will take the value 0 which will cause IRAF tasks to +fail with arithmetic or matrix inversion errors. If the CTYPEi keyword is +missing it is assumed to be "LINEAR". + +If the pixel sampling is logarithmic in the dispersion coordinate, as +required for radial velocity cross-correlations, the WCS coordinate values +are logarithmic and wi (above) is the logarithm of the dispersion +coordinate. The spectral tasks (though not other tasks) will recognize +this case and automatically apply the anti-log. The two types of pixel +sampling are identified by the value of the keyword DC-FLAG. A value of 0 +defines a linear sampling of the dispersion and a value of 1 defines a +logarithmic sampling of the dispersion. Thus, in all cases the spectral +tasks will display and analyze the spectra in the same dispersion units +regardless of the pixel sampling. + +Other keywords which may be present are DISPAXIS for 2 and 3 dimensional +spatial spectra, and the WCS attributes "system", "wtype", "label", and +"units". The system attribute will usually have the value "world" for +spatial spectra and "equispec" for equispec spectra. The wtype attribute +will have the value "linear". Currently the label will be either "Pixel" +or "Wavelength" and the units will be "Angstroms" for dispersion corrected +spectra. In the future there will be more generality in the units +for dispersion calibrated spectra. + +Figure 1 shows the WCS keywords for a two dimensional long slit spectrum. +The coordinate system is defined to be a generic "world" system and the +wtype attributes and CTYPE keywords define the axes to be linear. The +other attributes define a label and unit for the second axis, which is the +dispersion axis as indicated by the DISPAXIS keyword. The LTM/LTV keywords +in this example show that a subsection of the original image has been +extracted with a factor of 2 block averaging along the dispersion axis. +The dispersion coordinates are given in terms of the \fIlogical\fR pixel +coordinates by the FITS keywords as defined previously. + +.ce +Figure 1: Long Slit Spectrum + +.nf + WAT0_001= 'system=world' + WAT1_001= 'wtype=linear' + WAT2_001= 'wtype=linear label=Wavelength units=Angstroms' + WCSDIM = 2 + DISPAXIS= 2 + DC-FLAG = 0 + + CTYPE1 = 'LINEAR ' + LTV1 = -10. + LTM1_1 = 1. + CRPIX1 = -9. + CRVAL1 = 19.5743865966797 + CD1_1 = 1.01503419876099 + + CTYPE2 = 'LINEAR ' + LTV2 = -49.5 + LTM2_2 = 0.5 + CRPIX2 = -49. + CRVAL2 = 4204.462890625 + CD2_2 = 12.3337936401367 +.fi + +Figure 2 shows the WCS keywords for a three dimensional image where each +line is an independent spectrum or associated data but where all spectra +have the same linear dispersion. This type of coordinate system has the +system name "equispec". The ancillary information about each aperture is +found in the APNUM keywords. These give the aperture number, beam number, +and extraction limits. In this example the LTM/LTV keywords have their +default values; i.e. the logical and physical coordinates are the same. + +.ce +Figure 2: Equispec Spectrum + +.nf + WAT0_001= 'system=equispec' + WAT1_001= 'wtype=linear label=Wavelength units=Angstroms' + WAT2_001= 'wtype=linear' + WAT3_001= 'wtype=linear' + WCSDIM = 3 + DC-FLAG = 0 + APNUM1 = '41 3 7.37 13.48' + APNUM2 = '15 1 28.04 34.15' + APNUM3 = '33 2 43.20 49.32' + + CTYPE1 = 'LINEAR ' + LTM1_1 = 1. + CRPIX1 = 1. + CRVAL1 = 4204.463 + CD1_1 = 6.16689700000001 + + CTYPE2 = 'LINEAR ' + LTM2_2 = 1. + CD2_2 = 1. + + CTYPE3 = 'LINEAR ' + LTM3_3 = 1. + CD3_3 = 1. +.fi +.sh +5. Multispec Spectral World Coordinate System + +The \fImultispec\fR spectral world coordinate system applies only to one +dimensional spectra; i.e. there is no analog for the spatial type spectra. +It is used either when there are multiple 1D spectra with differing +dispersion functions in a single image or when the dispersion functions are +nonlinear. + +The multispec coordinate system is always two dimensional though there may +be an independent third axis. The two axes are coupled and they both have +axis type "multispec". When the image is one dimensional the physical line +is given by the dimensional reduction keyword WAXMAP. The second, line +axis, has world coordinates of aperture number. The aperture numbers are +integer values and need not be in any particular order but do need to be +unique. This aspect of the WCS is not of particular user interest but +applications use the inverse world to physical transformation to select a +spectrum line given a specified aperture. + +The dispersion functions are specified by attribute strings with the +identifier \fIspecN\fR where N is the \fIphysical\fR image line. The +attribute strings contain a series of numeric fields. The fields are +indicated symbolically as follows. + +.nf + specN = ap beam dtype w1 dw nw z aplow aphigh [functions_i] +.fi + +where there are zero or more functions having the following fields, + +.nf + function_i = wt_i w0_i ftype_i [parameters] [coefficients] +.fi + +The first nine fields in the attribute are common to all the dispersion +functions. The first field of the WCS attribute is the aperture number, +the second field is the beam number, and the third field is the dispersion +type with the same function as DC-FLAG in the \fInspec\fR and +\fIequispec\fR formats. A value of -1 indicates the coordinates are not +dispersion coordinates (the spectrum is not dispersion calibrated), a value +of 0 indicates linear dispersion sampling, a value of 1 indicates +log-linear dispersion sampling, and a value of 2 indicates a nonlinear +dispersion. + +The next two fields are the dispersion coordinate of the first +\fIphysical\fR pixel and the average dispersion interval per \fIphysical\fR +pixel. For linear and log-linear dispersion types the dispersion +parameters are exact while for the nonlinear dispersion functions they are +approximate. The next field is the number of valid pixels, hence it is +possible to have spectra with varying lengths in the same image. In that +case the image is as big as the biggest spectrum and the number of pixels +selects the actual data in each image line. The next (seventh) field is a +doppler factor. This doppler factor is applied to all dispersion +coordinates by multiplying by 1/(1+z) (assuming wavelength dispersion +units). Thus a value of 0 is no doppler correction. The last two fields +are extraction aperture limits as discussed previously. + +Following these fields are zero or more function descriptions. For linear +or log-linear dispersion coordinate systems there are no function fields. +For the nonlinear dispersion systems the function fields specify a weight, +a zero point offset, the type of dispersion function, and the parameters +and coefficients describing it. The function type codes, ftype_i, +are 1 for a chebyshev polynomial, 2 for a legendre polynomial, 3 for a +cubic spline, 4 for a linear spline, 5 for a pixel coordinate array, and 6 +for a sampled coordinate array. The number of fields before the next +function and the number of functions are determined from the parameters of +the preceding function until the end of the attribute is reached. + +The equation below shows how the final wavelength is computed based on +the nfunc individual dispersion functions W_i(p). Note that this +is completely general in that different function types may be combined. +However, in practice when multiple functions are used they are generally of +the same type and represent a calibration before and after the actual +object observation with the weights based on the relative time difference +between the calibration dispersion functions and the object observation. + +.nf + w = sum from i=1 to nfunc {wt_i * (w0_i + W_i(p)) / (1 + z)} +.fi + +The multispec coordinate systems define a transformation between physical +pixel, p, and world coordinates, w. Generally there is an intermediate +coordinate system used. The following equations define these coordinates. +The first one shows the transformation between logical, l, and physical, +p, coordinates based on the LTM/LTV keywords. The polynomial functions +are defined in terms of a normalized coordinate, n, as shown in the +second equation. The normalized coordinates run between -1 and 1 over the +range of physical coordinates, pmin and pmax which are +parameters of the function, upon which the coefficients were defined. The +spline functions map the physical range into an index over the number of +evenly divided spline pieces, npieces, which is a parameter of the +function. This mapping is shown in the third and fourth equations where +s is the continuous spline coordinate and j is the nearest integer less +than or equal to s. + +.nf + p = (l - LTV1) / LTM1_1 + n = (p - pmiddle) / (prange / 2) + = (p - (pmax+pmin)/2) / ((pmax-pmin) / 2) + s = (p - pmin) / (pmax - pmin) * npieces + j = int(s) +.fi +.sh +5.1 Linear and Log Linear Dispersion Function + +The linear and log-linear dispersion functions are described by a +wavelength at the first \fIphysical\fR pixel and a wavelength increment per +\fIphysical\fR pixel. A doppler correction may also be applied. The +equations below show the two forms. Note that the coordinates returned are +always wavelength even though the pixel sampling and the dispersion +parameters may be log-linear. + +.nf + w = (w1 + dw * (p - 1)) / (1 + z) + w = 10 ** {(w1 + dw * (p - 1)) / (1 + z)} +.fi + +Figure 3 shows an example from a multispec image with +independent linear dispersion coordinates. This is a linearized echelle +spectrum where each order (identified by the beam number) is stored as a +separate image line. + +.ce +Figure 3: Echelle Spectrum with Linear Dispersion Function + +.nf + WAT0_001= 'system=multispec' + WAT1_001= 'wtype=multispec label=Wavelength units=Angstroms' + WAT2_001= 'wtype=multispec spec1 = "1 113 0 4955.44287109375 0.05... + WAT2_002= '5 256 0. 23.22 31.27" spec2 = "2 112 0 4999.0810546875... + WAT2_003= '58854293 256 0. 46.09 58.44" spec3 = "3 111 0 5043.505... + WAT2_004= '928358078002 256 0. 69.28 77.89" + WCSDIM = 2 + + CTYPE1 = 'MULTISPE' + LTM1_1 = 1. + CD1_1 = 1. + + CTYPE2 = 'MULTISPE' + LTM2_2 = 1. + CD2_2 = 1. +.fi +.sh +5.2 Chebyshev Polynomial Dispersion Function + +The parameters for the chebyshev polynomial dispersion function are the +order (number of coefficients) and the normalizing range of physical +coordinates, pmin and pmax, over which the function is +defined and which are used to compute n. Following the parameters are +the order coefficients, ci. The equation below shows how to +evaluate the function using an iterative definition where x_1 = 1, +x_2 = n, and x_i = 2 * n * x_{i-1} - x_{i-2}. + +The parameters for the chebyshev polynomial dispersion function are the +order (number of coefficients) and the normalizing range of physical +coordinates, pmin and pmax, over which the function is defined +and which are used to compute n. Following the parameters are the +order coefficients, c_i. The equation below shows how to evaluate the +function using an iterative definition +where x_1 = 1, x_2 = n, and x_i = 2 * n * x_{i-1} - x_{i-2}. + +.nf + W = sum from i=1 to order {c_i * x_i} +.fi +.sh +5.3 Legendre Polynomial Dispersion Function + +The parameters for the legendre polynomial dispersion function are the +order (number of coefficients) and the normalizing range of physical +coordinates, pmin and pmax, over which the function is defined +and which are used to compute n. Following the parameters are the +order coefficients, c_i. The equation below shows how to evaluate the +function using an iterative definition where x_1 = 1, x_2 = n, and +x_i = ((2i-3)*n*x_{i-1}-(i-2)*x_{i-2})/(i-1). + +.nf + W = sum from i=1 to order {c_i * x_i} +.fi + +Figure 4 shows an example from a multispec image with independent nonlinear +dispersion coordinates. This is again from an echelle spectrum. Note that +the IRAF \fBechelle\fR package determines a two dimensional dispersion +function, in this case a bidimensional legendre polynomial, with the +independent variables being the order number and the extracted pixel +coordinate. To assign and store this function in the image is simply a +matter of collapsing the two dimensional dispersion function by fixing the +order number and combining all the terms with the same order. + +.ce +Figure 4: Echelle Spectrum with Legendre Polynomial Function + +.nf + WAT0_001= 'system=multispec' + WAT1_001= 'wtype=multispec label=Wavelength units=Angstroms' + WAT2_001= 'wtype=multispec spec1 = "1 113 2 4955.442888635351 0.05... + WAT2_002= '83 256 0. 23.22 31.27 1. 0. 2 4 1. 256. 4963.0163112090... + WAT2_003= '976664 -0.3191636898579552 -0.8169352858733255" spec2 =... + WAT2_004= '9.081188912082 0.06387049476832223 256 0. 46.09 58.44 1... + WAT2_005= '56. 5007.401409453303 8.555959076467951 -0.176732458267... + WAT2_006= '09935064388" spec3 = "3 111 2 5043.505764869474 0.07097... + WAT2_007= '256 0. 69.28 77.89 1. 0. 2 4 1. 256. 5052.586239197408 ... + WAT2_008= '271 -0.03173489817897474 -7.190562320405975E-4" + WCSDIM = 2 + + CTYPE1 = 'MULTISPE' + LTM1_1 = 1. + CD1_1 = 1. + + CTYPE2 = 'MULTISPE' + LTM2_2 = 1. + CD2_2 = 1. +.fi +.sh +5.4 Linear Spline Dispersion Function + +The parameters for the linear spline dispersion function are the number of +spline pieces, npieces, and the range of physical coordinates, pmin +and pmax, over which the function is defined and which are used to +compute the spline coordinate s. Following the parameters are the +npieces+1 coefficients, c_i. The two coefficients used in a linear +combination are selected based on the spline coordinate, where a and b +are the fractions of the interval in the spline piece between the spline +knots, a=(j+1)-s, b=s-j, and x_0=a, and x_1=b. + +.nf + W = sum from i=0 to 1 {c_(i+j) * x_i} +.fi +.sh +5.5 Cubic Spline Dispersion Function + +The parameters for the cubic spline dispersion function are the number of +spline pieces, npieces, and the range of physical coordinates, pmin +and pmax, over which the function is defined and which are used +to compute the spline coordinate s. Following the parameters are the +npieces+3 coefficients, c_i. The four coefficients used are +selected based on the spline coordinate. The fractions of the interval +between the integer spline knots are given by a and b, a=(j+1)-s, +b=s-j, and x_0 =a sup 3, x_1 =(1+3*a*(1+a*b)), +x_2 =(1+3*b*(1+a*b)), and x_3 =b**3. + +The parameters for the cubic spline dispersion function are the number of +spline pieces, npieces, and the range of physical coordinates, pmin +and pmax, over which the function is defined and which are used to +compute the spline coordinate s. Following the parameters are the +npieces+3 coefficients, c_i. The four coefficients used are selected +based on the spline coordinate. The fractions of the interval between the +integer spline knots are given by a and b, a=(j+1)-s, b=s-j, +and x_0=a**3, x_1=(1+3*a*(1+a*b)), x_2=(1+3*b*(1+a*b)), and x_3=b**3. + +.nf + W = sum from i=0 to 3 {c_(i+j) * x_i} +.fi +.sh +5.6 Pixel Array Dispersion Function + +The parameters for the pixel array dispersion function consists of just the +number of coordinates ncoords. Following this are the wavelengths at +integer physical pixel coordinates starting with 1. To evaluate a +wavelength at some physical coordinate, not necessarily an integer, a +linear interpolation is used between the nearest integer physical coordinates +and the desired physical coordinate where a and b are the usual +fractional intervals k=int(p), a=(k+1)-p, b=p-k, +and x_0=a, and x_1=b. + +.nf + W = sum from i=0 to 1 {c_(i+j) * x_i} +.fi +.sh +5.7 Sampled Array Dispersion Function + +The parameters for the sampled array dispersion function consists of +the number of coordinate pairs, ncoords, and a dummy field. +Following these are the physical coordinate and wavelength pairs +which are in increasing order. The nearest physical coordinates to the +desired physical coordinate are located and a linear interpolation +is computed between the two sample points. +.endhelp diff --git a/noao/onedspec/doc/splot.hlp b/noao/onedspec/doc/splot.hlp new file mode 100644 index 00000000..a5bc3b96 --- /dev/null +++ b/noao/onedspec/doc/splot.hlp @@ -0,0 +1,1118 @@ +.help splot Jul95 noao.onedspec +.ih +NAME +splot -- plot and analyze spectra +.ih +USAGE +splot images [line [band]] +.ih +PARAMETERS +.ls images +List of images (spectra) to plot. If the image is 2D or 3D the line +and band parameters are used. Successive images are plotted +following each 'q' cursor command. One may use an image section +to select a desired column, line, or band but the full image will +be in memory and any updates to the spectrum will be part of the +full image. +.le +.ls line, band +The image line/aperture and band to plot in two or three dimensional +images. For multiaperture spectra the aperture specified by the line +parameter is first sought and if not found the specified image line is +selected. For other two dimensional images, such as long slit spectra, the +line parameter specifies a line or column. Note that if +the line and band parameters are specified on the command line it will not +be possible to change them interactively. +.le +.ls units = "" +Dispersion coordinate units for the plot. If the spectra have known units, +currently this is generally Angstroms, the units may be converted +to other units for plotting as specified by this task parameter. +If this parameter is the null string and the world coordinate system +attribute "units_display" is defined then that will +be used. If both this task parameters and "units_display" are not +given then the spectrum dispersion units will be used. +The units +may also be changed interactively. See the units section of the +\fBpackage\fR help for a further description and available units. +.le +.ls options = "auto" [auto,zero,xydraw,histogram,nosysid,wcreset,flip,overplot] +A list of zero or more, possibly abbreviated, options. The options can +also be toggled with colon commands. The currently defined options are +"auto", "zero", "xydraw", "histogram", "nosysid", "wreset", "flip", and +"overplot". Option "auto" automatically replots the graph whenever changes +are made. Otherwise the graph is replotted with keystrokes 'c' or 'r'. +Option "zero" makes the initial minimum y of the graphs occur at zero. +Otherwise the limits are set automatically from the range of the data or +the \fIymin\fR parameter. Option "xydraw" changes the 'x' draw key to use +both x and y cursor values for drawing rather than the nearest pixel value +for the y value. Option "histogram" plots the spectra in a histogram style +rather than connecting the pixel centers. Option "nosysid" excludes the +system banner from the graph title. Option "wreset" resets the graph +limits to those specified by the \fIxmin, xmax, ymin, ymax\fR parameters +whenever a new spectrum is plotted. The "flip" option selects that +initially the spectra be plotted with decreasing wavelengths. The options +may be queried and changed interactively. The "overplot" options overplots +all graphs and a screen erase only occurs with the redraw key. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The default limits for the initial graph. If INDEF then the limit is +determined from the range of the data (autoscaling). These values can +be changed interactively with 'w' window key options or the cursor commands +":/xwindow" and ":/ywindow" (see \fBgtools\fR). +.le +.ls save_file = "splot.log" +The file to contain any results generated by the equivalent width or +deblending functions. Results are added to this file until the file is +deleted. If the filename is null (""), then no results are saved. +.le +.ls graphics = "stdgraph" +Output graphics device: one of "stdgraph", "stdplot", "stdvdm", or device +name. +.le +.ls cursor = "" +Graphics cursor input. When null the standard cursor is used otherwise +the specified file is used. +.le + +The following parameters are used for error estimates in the 'd', +'k', and 'e' key measurements. See the ERROR ESTIMATES section for a +discussion of the error estimates. +.ls nerrsample = 0 +Number of samples for the error computation. A value less than 10 turns +off the error computation. A value of ~10 does a rough error analysis, a +value of ~50 does a reasonable error analysis, and a value >100 does a +detailed error analysis. The larger this value the longer the analysis +takes. +.le +.ls sigma0 = INDEF, invgain = INDEF +The pixel sigmas are modeled by the formula: + +.nf + sigma**2 = sigma0**2 + invgain * I +.fi + +where I is the pixel value and "**2" means the square of the quantity. If +either parameter is specified as INDEF or with a value less than zero then +no sigma estimates are made and so no error estimates for the measured +parameters are made. +.le + +The following parameters are for the interactive curve fitting function +entered with the 't' key. This function is usually used for continuum +fitting. The values of these parameters are updated during the fitting. +See \fBicfit\fR for additional details on interactive curve fitting. +.ls function = "spline3" +Function to be fit to the spectra. The functions are +"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial), +"spline1" (linear spline), and "spline3" (cubic spline). The functions +may be abbreviated. +.le +.ls order = 1 +The order of the polynomials or the number of spline pieces. +.le +.ls low_reject = 2., high_reject = 4. +Rejection limits below and above the fit in units of the residual sigma. +Unequal limits are used to reject spectral lines on one side of the continuum +during continuum fitting. +.le +.ls niterate = 10 +Number of rejection iterations. +.le +.ls grow = 1. +When a pixel is rejected, pixels within this distance of the rejected pixel +are also rejected. +.le +.ls markrej = yes +Mark rejected points? If there are many rejected points it might be +desired to not mark rejected points. +.le + +The following parameters are used to overplot standard star fluxes with +the 'y' key. See \fBstandard\fR for more information about these parameters. +.ls star_name +Query parameter for the standard star fluxes to be overplotted. +Unrecognized names or a "?" will print a list of the available stars +in the specified calibration directory. +.le +.ls mag +The magnitude of the observed star in the band given by the +\fImagband\fR parameter. If the magnitude is not in the same band as +the blackbody calibration file then the magnitude may be converted to +the calibration band provided the "params.dat" file containing relative +magnitudes between the two bands is in the calibration directory +.le +.ls magband +The standard band name for the input magnitude. This should generally +be the same band as the blackbody calibration file. If it is +not the magnitude will be converted to the calibration band. +.le +.ls teff +The effective temperature (deg K) or the spectral type of the star being +calibrated. If a spectral type is specified a "params.dat" file must exist +in the calibration directory. The spectral types are specified in the same +form as in the "params.dat" file. For the standard blackbody calibration +directory the spectral types are specified as A0I, A0III, or A0V, where A +can be any letter OBAFGKM, the single digit subclass is between 0 and 9, +and the luminousity class is one of I, III, or V. If no luminousity class +is given it defaults to dwarf. +.le +.ls caldir = ")_.caldir" +The standard star calibration directory. The default value redirects the +value to the parameter of the same name in the package parameters. +.le +.ls fnuzero = 3.68e-20 +The absolute flux per unit frequency at a magnitude of zero used to +to convert the calibration magnitudes to absolute flux. +.le + +The following parameters are used for queries in response to particular +keystrokes. +.ls next_image +In response to 'g' (get next image) this parameter specifies the image. +.le +.ls new_image +In response to 'i' (write current spectrum) this parameter specifies the +name of a new image to create or existing image to overwrite. +.le +.ls overwrite = no +Overwrite an existing output image? If set to yes it is possible to write +back into the input spectrum or to some other existing image. Otherwise +the user is queried again for a new image name. +.le +.ls spec2 +When adding, subtracting, multiplying, or dividing by a second spectrum +('+', '-', '*', '/' keys in the 'f' mode) this parameter is used to get +the name of the second spectrum. +.le +.ls constant +When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode) +the parameter is used to get the constant. +.le +.ls wavelength +This parameter is used to get a dispersion coordinate value during deblending or +when changing the dispersion coordinates with 'u'. +.le +.ls linelist +During deblending this parameter is used to get a list of line positions, +peak values, profile types, and widths. +.le +.ls wstart, wend, dw +In response to 'p' (convert to a linear wavelength scale) these parameters +specify the starting wavelength, ending wavelength, and wavelength per pixel. +.le +.ls boxsize +In response to 's' (smooth) this parameter specifies the box size in pixels +to be used for the boxcar smooth. The value must be odd. If an even +value is specified the next larger odd value is actually used. +.le +.ih +DESCRIPTION +\fBSplot\fR provides an interactive facility to display and analyze +spectra. See also \fBbplot\fR for a version of this task useful for making +many plots noninteractively. Each spectrum in the image list is displayed +successively. To quit the current image and go on to the next the 'q' +cursor command is used. If an image is two-dimensional, such as with +multiple aperture or long slit spectra, the aperture or image column/line +to be displayed is needed. If the image is three-dimensional, such as with +the extra information produced by \fBapextract\fR, the band is needed. +These parameters are queried unless specified on the command line. If +given on the command line it will not be possible to change them +interactively. + +The plots are made on the specfied graphics device which is usually to +the graphics terminal. The initial plot limits are set with the parameters +\fIxmin, xmax, ymin\fR, and \fIymax\fR. If a limit is INDEF then that limit +is determined from the range of the data. The "zero" option may also +be set in the \fIoptions\fR parameter to set the lower intensity limit +to zero. Other options that may be set to control the initial plot +are to exclude the system identification banner, and to select a +histogram line type instead of connecting the pixel centers. +The dispersion units used in the plot are set by the \fIunits\fR +parameter. This allows converting to units other than those in which the +dispersion coordinates are defined in the spectra. + +The \fIoption\fR parameter, mentioned in the previous paragraph, is a +a list of zero or more options. As previously noted, some of the options +control the initial appearance of the plots. The "auto" option determines +how frequently plots are redrawn. For slow terminals or via modems one +might wish to minimize the redrawing. The default, however, is to redraw +when changes are made. The "xydraw" parameter is specific to the 'x' +key. + +After the initial graph is made an interactive cursor loop is entered. +The \fIcursor\fR parameter may be reset to read from a file but generally +the graphics device cursor is read. The cursor loop takes single +keystroke commands and typed in commands begun with a colon, called +colon commands. These commands are described below and a summary of +the commands may be produced interactively with the '?' key or +a scrolling help on the status line with the '/' key. + +Modifications to the spectra being analyzed may be saved using the 'i' key +in a new, the current, or other existing spectra. A new image is created +as a new copy of the current spectrum and so if the current spectrum is +part of a multiple spectrum image (including a long slit spectrum) the +other spectra are copied. If other spectra in the same image are then +modified and saved use the overwrite option to replace then in the new +output image. If the output spectrum already exists then the +\fIoverwrite\fR flag must be set to allow modifying the data. This +includes the case when the output spectrum is the same as the input +spectrum. The only odd case here is when the input spectrum is one +dimensional and the output spectrum is two dimensional. In this case the +user is queried for the line to be written. + +The other form of output, apart from that produced on the terminal, are +measurements of equivalent widths, and other analysis functions. This +information will be recorded in the \fIsave_file\fR if specified. + +The following keystrokes are active in addition to the normal IRAF +cursor facilities (available with ":.help"): + +.ls ? +Page help information. +.le +.ls / +Cycle through short status line help. +.le +.ls <space> +The space bar prints the cursor position and value of the nearest +pixel. +.le +.ls a +Expand and autoscale to the data range between two cursor positions. +See also 'w', and 'z'. Selecting no range, that is the two +cursor positions the same, produces an autoscale of the whole spectrum. +.le +.ls b +Set the plot base level to zero rather than autoscaling. +.le +.ls c +Clear all windowing and redraw the full current spectrum. This redraws the +spectrum and cancels any effects of the 'a', 'z', and 'w' keys. The 'r' +key is used to redraw the spectrum with the current windowing. +.le +.ls d +Mark two continuum points and fit (deblend) multiple line profiles. +The center, continuum at the center, core intensity, integrated flux, +equivalent width, FWHMs for each profile are printed and saved +in the log file. See 'k' for fitting a single profile and +'-' to subtract the fitted profiles. +.le +.ls e +Measure equivalent width by marking two continuum points around the line +to be measured. The linear continuum is subtracted and the flux is +determined by simply summing the pixels with partial pixels at the ends. +Returned values are the line center, continuum at the region center, +flux above or below the continuum, and the equivalent width. +.le +.ls f +Enter arithmetic function mode. This mode allows arithmetic functions to be +applied to the spectrum. The pixel values are modified according to the +function request and may be saved as a new spectrum with the 'i' +command. Operations with a second spectrum are done in wavelength +space and the second spectrum is automatically resampled if necessary. +If one spectrum is longer than the other, only the smaller number of +pixels are affected. To exit this mode type 'q'. + +The following keystrokes are available in the function mode. Binary +operations with a constant or a second spectrum produce a query for the +constant value or spectrum name. +.ls a +Absolute value +.le +.ls d +Power of base 10 (inverse log base 10) +.le +.ls e +Power of base e (inverse log base e) +.le +.ls i +Inverse/reciprocal (values equal to zero are set to 0.0 in the inverse) +.le +.ls l +Log base 10 (values less than or equal to 0.0 are set to -0.5) +.le +.ls m +Multiply by a constant (constant is queried) +.le +.ls n +Log base e (values less than or equal to 0.0 are set to -0.5) +.le +.ls p +Add by a constant (constant is queried) +.le +.ls q +Quit Function mode +.le +.ls s +Square root (values less than 0.0 are set to 0.0) +.le +.ls + +Add another spectrum +.le +.ls -3 - +Subtract another spectrum +.le +.ls * +Multiply by another spectrum +.le +.ls / +Divide by another spectrum +.le +.le +.ls g +Get another spectrum. The current spectrum is replaced by the new spectrum. +The aperture/line and band are queried is necessary. +.le +.ls h +Measure equivalent widths assuming a gaussian profile with the width +measured at a specified point. Note that this is not a gaussian fit (see +'k' to fit a gaussian)! The gaussian profile determined here may be +subtracted with the '-' key. A second cursor key is requested with one of +the following values: +.ls a +Mark the continuum level at the line center and use the LEFT half width +at the half flux point. +.le +.ls b +Mark the continuum level at the line center and use the RIGHT half width +at the half flux point. +.le +.ls c +Mark the continuum level at the line center and use the FULL width +at the half flux point. +.le +.ls l +Mark a flux level at the line center relative to a normalized continuum +and use the LEFT width at that flux point. +.le +.ls r +Mark a flux level at the line center relative to a normalized continuum +and use the RIGHT width at that flux point. +.le +.ls k +Mark a flux level at the line center relative to a normalized continuum +and use the FULL width at that flux point. +.le +.le +.ls i +Write the current spectrum out to a new or existing image. The image +name is queried and overwriting must be confirmed. +.le +.ls j +Set the value of the nearest pixel to the x cursor to the y cursor position. +.le +.ls k + (g, l or v) +Mark two continuum points and fit a single line profile. The second key +selects the type of profile: g for gaussian, l for lorentzian, and v for +voigt. Any other second key defaults to gaussian. The center, continuum +at the center, core intensity, integrated flux, equivalent width, and FWHMs +are printed and saved in the log file. See 'd' for fitting multiple +profiles and '-' to subtract the fit. +.le +.ls l +Convert to flux per unit wavelength (f-lambda). The spectrum is assumed +to be flux calibrated in flux per unit frequency (f-nu). See also 'n'. +.le +.ls m +Compute the mean, RMS, and signal-to-noise over a region marked with two +x cursor positions. +.le +.ls n +Convert to flux per unit frequency (f-nu). The spectrum is assumed +to be flux calibrated in flux per unit wavelength (f-lambda). See also 'l'. +.le +.ls o +Set overplot flag. The next plot will overplot the current plot. +Normally this key is immediately followed by one of 'g', '#', '%', '(', or ')'. +The ":overplot" colon command and overplot parameter option may be +used to set overplotting to be permanently on. +.le +.ls p +Define a linear wavelength scale. The user is queried for a starting +wavelength and an ending wavelength. If either (though not both) +are specified as INDEF a dispersion is queried for and used to compute +an endpoint. A wavelength scale set this way will be used for +other spectra which are not dispersion corrected. +.le +.ls q +Quit and go on to next input spectrum. After the last spectrum exit. +.le +.ls r +Redraw the spectrum with the current windowing. To redraw the full +spectrum and cancel any windowing use the 'c' key. +.le +.ls s +Smooth via a boxcar. The user is prompted for the box size. +.le +.ls t +Fit a function to the spectrum using the ICFIT mode. Typically +interactive rejection is used to exclude spectra lines from the fit +in order to fit a smooth continuum. A second keystroke +selects what to do with the fit. +.ls / +Normalize by the fit. When fitting the continuum this continuum +normalizes the spectrum. +.le +.ls -3 - +Subtract the fit. When fitting the continuum this continuum subtracts +the spectrum. +.le +.ls f +Replace the spectrum by the fit. +.le +.ls c +Clean the spectrum by replacing any rejected points by the fit. +.le +.ls n +Do the fitting but leave the spectrum unchanged (a NOP on the spectrum). +This is useful to play with the spectrum using the capabilities of ICFIT. +.le +.ls q +Quit and don't do any fitting. The spectrum is not modified. +.le +.le +.ls u +Adjust the user coordinate scale. There are three options, 'd' mark a +position with the cursor and doppler shift it to a specified value, +'z' mark a position with the cursor and zeropoint shift it to a specified +value, or 'l' mark two postions and enter two values to define a linear +(in wavelength) dispersion scale. The units used for input are those +currently displayed. A wavelength scale set this way will be used for +other spectra which are not dispersion corrected. +.le +.ls v +Toggle to a velocity scale using the position of the cursor as the +velocity origin and back. +.le +.ls w +Window the graph. For further help type '?' to the "window:" prompt or +see help under \fBgtools\fR. To cancel the windowing use 'a'. +.le +.ls x +"Etch-a-sketch" mode. Straight lines are drawn between successive +positions of the cursor. Requires 2 cursor settings in x. The nearest pixels +are used as the endpoints. To draw a line between arbitrary y values first +use 'j' to adjust the endpoints or set the "xydraw" option. +.le +.ls y +Overplot standard star values from a calibration file. +.le +.ls z +Zoom the graph by a factor of 2 in x. +.le +.ls ( +In multiaperture spectra go to the spectrum in the preceding image line. +If there is only one line go to the spectrum in the preceding band. +.le +.ls ) +In multiaperture spectra go to the spectrum in the following image line. +If there is only one line go to the spectrum in the following band. +.le +.ls # +Get a different line in multiaperture spectra or two dimensional images. +The aperture/line/column is queried. +.le +.ls % +Get a different band in a three dimensional image. +.le +.ls $ +Switch between physical pixel coordinates and world (dispersion) coordinates. +.le +.ls -4 - +Subtract the fits generated by the 'd' (deblend), 'k' (single profile fit), +and 'h' (gaussian of specified width). The region to be subtracted is +marked with two cursor positions. +.le +.ls -4 ',' +Shift the graph window to the left. +.le +.ls . +Shift the graph window to the right. +.le +.ls I +Force a fatal error interupt to leave the graph. This is used because +the normal interupt character is ignored in graphics mode. +.le + +.ls :show +Page the full output of the previous deblend and equivalent width +measurements. +.le +.ls :log +Enable logging of measurements to the file specified by the parameter +\fIsave_file\fR. When the program is first entered logging is enabled +(provided a log file is specified). There is no way to change the file +name from within the program. +.le +.ls :nolog +Disable logging of measurements. +.le +.ls :dispaxis <val> +Show or change dispersion axis for 2D images. +.le +.ls :nsum <val> +Show or change summing for 2D images. +.le +.ls :units <value> +Change the coordinate units in the plot. See below for more information. +.le +.ls :# <comment> +Add comment to logfile. +.le +.ls Labels: +.ls :label <label> <format> +Add a label at the cursor position. +.le +.ls :mabove <label> <format> +Add a tick mark and label above the spectrum at the cursor position. +.le +.ls :mbelow <label> <format> +Add a tick mark and label below the spectrum at the cursor position. +.le + +The label must be quoted if it contains blanks. A label beginning +with % (i.e. %.2f) is treated as a format for the x cursor position. +The optional format is a gtext string (see help on "cursors"). +The labels are not remembered between redraws. +.le + +.ls :auto [yes|no] +Enable/disable autodraw option +.le +.ls :zero [yes|no] +Enable/disable zero baseline option +.le +.ls :xydraw [yes|no] +Enable/disable xydraw option +.le +.ls :hist [yes|no] +Enable/disable histogram line type option +.le +.ls :nosysid [yes|no] +Enable/disable system ID option +.le +.ls :wreset [yes|no] +Enable/disable window reset for new spectra option +.le +.ls :flip [yes|no] +Enable/disable the flipped coordinates option +.le +.ls :overplot [yes|no] +Enable/disable the permanent overplot option +.le + + +.ls :/help +Get help on GTOOLS options. +.le +.ls :.help +Get help on standard cursor mode options +.le +.ih +PROFILE FITTING AND DEBLENDING +The single profile ('k') and multiple profile deblending ('d') commands fit +gaussian, lorentzian, and voigt line profiles with a linear background. +The single profile fit, 'k' key, is a special case of the multiple profile +fitting designed to be simple to use. Two cursor positions define the +region to be fit and a fixed linear continuum. The second key is used to +select the type of profile to fit with 'g' for gaussian, 'l' for +lorentzian, and 'v' for voigt. Any other second key will default to a +gaussian profile. The profile center, peak strength, and width(s) are then +determined and the results are printed on the status line and in the log +file. The meaning of these quantities is described later. The fit is also +overplotted and may be subtracted from the spectrum subsequently with +the '-' key. + +The more complex deblending function, 'd' key, defines the fitting region +and initial linear continuum in the same way with two cursor positions. +The continuum may be included in the fitting as an option. The lines to be +fit are entered with the cursor near the line center ('g' for gaussian, 'l' +for lorentzian, 'v' for voigt), by typing the wavelengths ('t'), or read +from a file ('f'). The latter two methods are useful if the wavelengths of +the lines are known accurately and if fits restricting the absolute or +relative positions of the lines will be used. The 't' key is +restricted to gaussian fits only. + +The 'f' key asks for a line list file. The format of this file has +one or more columns. The columns are the wavelength, the peak value +(relative to the continuum with negative values being absorption), +the profile type (gaussian, lorentzian, or voigt), and the +gaussian and/or lorentzian FWHM. End columns may be missing +or INDEF values may be used to have values be approximated. +Below are examples of the file line formats + +.nf + wavelength + wavelength peak + wavelength peak (gaussian|lorenzian|voigt) + wavelength peak gaussian gfwhm + wavelength peak lorentzian lfwhm + wavelength peak voigt gfwhm + wavelength peak voigt gfwhm lfwhm + + 1234.5 <- Wavelength only + 1234.5 -100 <- Wavelength and peak + 1234.5 INDEF v <- Wavelength and profile type + 1234.5 INDEF g 12 <- Wavelength and gaussian FWHM +.fi + +where peak is the peak value, gfwhm is the gaussian FWHM, and lfwhm is +the lorentzian FWHM. This format is the same as used by \fBfitprofs\fR +and also by \fBartdata.mk1dspec\fR (except in the latter case the +peak is normalized to a continuum of 1). + +There are four queries made to define the set of parameters to be fit or +constrained. The positions may be held "fixed" at their input values, +allowed to shift by a "single" offset from the input values, or "all" +positions may be fit independently. The widths may be +constrained to a "single" value or "all" fit independently. The linear +background may be included in the fit or kept fixed at that input using the +cursor. + +As noted above, sometimes the absolute or relative wavelengths of the lines +are known a priori and this information may be entered by typing the +wavelengths explicitly using the 't' option or read from a file using the +'f' option during marking. In this case one should fix or fit a single +shift for the position. The latter may be useful if the lines are known +but there is a measurable doppler shift. + +After the fit, the modeled lines are overplotted. The line center, +flux, equivalent width, and full width half maxima are printed on the +status line for the first line. The values for the other lines and +the RMS of the fit may be examined by scrolling the status line +using the '+', '-', and 'r' keys. To continue enter 'q'. + +The fitting may be repeated with different options until exited with 'q'. +For each line in the blend the line center, continuum intensity at the +line center, the core intensity above or below the continuum, the +FWHM for the gaussian and lorentzian parts, the flux above or below the continuum, and the +equivalent width are recorded in the log file. All these parameters +except the continuum are based on the fitted analytic profiles. +Thus, even though the fitted region may not extend into the wings of a line +the equivalent width measurements include the wings in the fitted profile. +For direct integration of the flux use the 'e' key. + +The fitted model may be subtracted from the data (after exiting the +deblending function) using the '-' (minus) keystroke to delimit the region +for which the subtraction is to be performed. This allows you to fit a +portion of a line which may be contaminated by a blend and then subtract +away the entire line to examine the remaining components. + +The fitting uses an interactive algorithm based on the Levenberg-Marquardt +method. The iterations attempt to improve the fit by varying the parameters +along the gradient of improvement in the chi square. This method requires +that the initial values for the parameters be close enough that the +gradient leads to the correct solution rather than an incorrect local +minimum in the chi square. The initial values are determined as follows: + +.nf + 1. If the lines are input from a data file then those values + in the file are used. Missing information is determined + as below. + 2. The line centers are those specified by the user + either by marking with the cursor, entering the wavelenths, + for read from a file. + 3. The initial widths are obtained by dividing the width of + the marked fitting region by the number of lines and then + dividing this width by a factor depending on the profile + type. + 4. The initial peak intensities are the data values at the + given line centers with the marked continuum subtracted. +.fi + +Note that each time a new fitting option is specified the initial parameters +are those from the previous fits. +Thus the results do depend on the history of previous fits until the +fitting is exited. +Within each fit an iteration of parameters is performed as +described next. + +The iteration is more likely to fail if one initially attempts to fit too +many parameters simultaneously. A constrained approach to the solution +is obtained by iterating starting with a few parameters and then adding +more parameters as the solution approaches the true chi square minimum. +This is done by using the solutions from the more constrained options +as the starting point for the less constrained options. In particular, +the positions and a single width are fit first with fixed background. +Then multiple widths and the background are added. + +To conclude, here are some general comments. The most restrictive +(fixed positions and single width(s)) will give odd results if the initial +positions are not close to the true centers. The most general +(simultaneous positions, widths, and background) can also lead to +incorrect results by using unphysically different widths to make one +line very narrow and another very broad in an attempt to fit very +blended lines. The algorithm works well when the lines are not +severely blended and the shapes of the lines are close to the profile +type. +.ih +CENTROID, FLUX, AND EQUIVALENT WIDTH DETERMINATIONS +There are currently five techniques in SPLOT to measure equivalent widths +and other line profile parameters. The simplest (conceptually) is by +integration of the pixel values between two marked pixels. This is +invoked with the 'e' keystroke. The user marks the two edges of the line +at the continuum. The measured line center, contiuum value, line flux, and +equivalent width are given by: + +.nf + center = sum (w(i) * (I(i)-C(i))**3/2) / sum ((I(i)-C(i))**3/2) + continuum = C(midpoint) + flux = sum ((I(i)-C(i)) * (w(i2) - w(i1)) / (i2 - i2) + eq. width = sum (1 - I(i)/C(i)) +.fi + +where w(i) is the wavelength of pixel i, i1 and i2 are the nearest integer +pixel limits of the integrated wavelength range, I(i) is the data value of +pixel i, C(i) is the continuum at pixel (i), and the sum is over the marked +range of pixels. The continuum is a linear function between the two points +marked. The factor mulitplying the continuum subtracted pixel values +in the flux calculation is the wavelength interval per pixel so that +the flux integration is done in wavelength units. (See the discussion +at the end of this section concerning flux units). + +The most complex method for computing line profile parameters is performed +by the profile fitting and deblending commands which compute a non-linear +least-squares fit to the line(s). These are invoked with the 'd' or 'k' +keystroke. These were described in detail previously. + +The fourth and fifth methods, selected with the 'h' key, determine the +equivalent width from a gaussian profile defined by a constant continuum +level "cont", a core depth "core", and the width of the line "dw" at some +intermediate level "Iw". + +.nf + I(w) = cont + core * exp (-0.5*((w-center)/sigma)**2) + sigma = dw / 2 / sqrt (2 * ln (core/Iw)) + fwhm = 2.355 * sigma + flux = core * sigma * sqrt (2*pi) + eq. width = abs (flux) / cont +.fi + +where w is wavelength. + +For ease of use with a large number of lines only one cursor position is +used to mark the center of the line and one flux level. Note that both +the x any y cursor positions are read simultaneously. From the x cursor +position the line center and core intensity are determined. The region around +the specified line position is searched for a minimum or maximum and a +parabola is fit to better define the extremum. + +The two methods based on the simple gaussian profile model differ in how +they use the y cursor position and what part of the line is used. After +typing 'h' one selects the method and whether to use the left, right, or +both sides of the line by a second keystroke. The 'l', 'r', and 'k' keys +require a continuum level of one. The y cursor position defines where the +width of the line is determined. The 'a', 'b', and 'c' keys use the y +cursor position to define the continuum and the line width is determined at +the point half way between the line core and the continuum. In both cases +the width at the appropriate level is determined by the interception of the +y level with the data using linear interpolation between pixels. The +one-sided measurements use the half-width on the appropriate side and +the two-sided measurements use the full-width. + +The adopted gaussian line profile is drawn over the spectrum and the +horizontal and vertical lines show the measured line width and the depth of +the line center from the continuum. This model may also be subtracted +from the spectrum using the '-' key. + +The major advantages of these methods are that only a single cursor setting +(both the x and y positions are used) is required and they are fast. The +'l', 'r', and 'k' keys give more flexibility in adjusting the width of the +gaussian line at the expense or requiring that the spectrum be normalized +to a unit continuum. The 'a', 'b', and 'c' keys allow measurements at any +continuum level at the expense of only using the half flux level to +determine the gaussian line width. + +All these methods print and record in the log file the line center, +continuum intensity at the line center, the flux, and the equivalent +width. For the 'e' key the flux is directly integrated while for the other +methods the fitted gaussian is integrated. In addition, for the profile +fitting methods the core intensity above or below the continuum, and the +FWHMs are also printed. A zero value is record for the gaussian or +lorentzian width if the value is not determined by profile fit. A brief +line of data for each measurement is printed on the graphics status line. +To get the full output and the output from previous measurements use the +command ":show". This pages the output on the text output which may +involve erasing the graphics. + +The integrated fluxes for all the methods are in the same units as the +intensities and the integration is done in the same units as the +plotted scale. It is the user's responsibility to keep track of the flux +units. As a caution, if the data is in flux per unit frequency, say +ergs/cm2/sec/hz, and the dispersion in Angstroms then the integrated +flux will not be in the usual units but will be A-ergs/cm2/sec/hz. +For flux in wavelength units, ergs/cm2/sec/A and the dispersion scale +in Angstroms the integrated flux will be correct; i.e. ergs/cm2/sec. + +Note that one can compute integrated flux in pixel units by using the '$' +to plot in pixels. This is appropriate if the pixel values are in +data numbers or photon counts to get total data number or photons. +.ih +ERROR ESTIMATES +The deblending ('d'), single profile fitting ('k'), and profile integration and +equivalent width ('e') functions provide error estimates for the measured +parameters. This requires a model for the pixel sigmas. Currently this +model is based on a Poisson statistics model of the data. The model +parameters are a constant gaussian sigma and an "inverse gain" as specified +by the parameters \fIsigma0\fR and \fIinvgain\fR. These parameters are +used to compute the pixel value sigma from the following formula: + +.nf + sigma**2 = sigma0**2 + invgain * I +.fi + +where I is the pixel value and "**2" means the square of the quantity. + +If either the constant sigma or the inverse gain are specified as INDEF or +with values less than zero then no noise model is applied and no error +estimates are computed. Also if the number of error samples is less than +10 then no error estimates are computed. Note that for processed spectra +this noise model will not generally be the same as the detector readout +noise and gain. These parameters would need to be estimated in some way +using the statistics of the spectrum. The use of an inverse gain rather +than a direct gain was choosed to allow a value of zero for this +parameters. This provides a model with constant uncertainties. + +The direct profile integration error estimates are computed by error +propagation assuming independent pixel sigmas. Also it is assumed that the +marked linear background has no errors. The error estimates are one sigma +estimates. They are given in the log output (which may also be view +without exiting the program using the :show command) below the value to +which they apply and in parenthesis. + +The deblending and profile fit error estimates are computed by Monte-Carlo +simulation. The model is fit to the data (using the sigmas) and this model +is used to describe the noise-free spectrum. A number of simulations, +given by the \fInerrsample\fR parameter, are created in which random +gaussian noise is added to the noise-free spectrum using the pixel +sigmas from the noise model. The model fitting is done for each simulation +and the absolute deviation of each fitted parameter to model parameter is +recorded. The error estimate for the each parameter is then the absolute +deviation containing 68.3% of the parameter estimates. This corresponds to +one sigma if the distribution of parameter estimates is gaussian though +this method does not assume this. + +The Monte-Carlo technique automatically includes all effects of +parameter correlations and does not depend on any approximations. +However the computation of the errors does take a significant +amount of time. The amount of time and the accuracy of the +error estimates depend on how many simulations are done. A +small number of samples (of order 10) is fast but gives crude +estimates. A large number (greater than 100) is slow but gives +good estimates. A compromise value of 50 is recommended +for many applications. +.ih +UNITS +The dispersion units capability of \fBsplot\fR allows specifying the +units with the \fIunits\fR parameter and interactively changing the units +with the ":units" command. In addition the 'v' key allows plotting in +velocity units with the zero point velocity defined by the cursor +position. + +The units are specified by strings having a unit type from the list below +along with the possible preceding modifiers, "inverse", to select the +inverse of the unit and "log" to select logarithmic units. For example "log +angstroms" to plot the logarithm of wavelength in Angstroms and "inv +microns" to plot inverse microns. The various identifiers may be +abbreviated as words but the syntax is not sophisticated enough to +recognized standard scientific abbreviations except as noted below. + +.nf + angstroms - Wavelength in Angstroms + nanometers - Wavelength in nanometers + millimicrons - Wavelength in millimicrons + microns - Wavelength in microns + millimeters - Wavelength in millimeters + centimeter - Wavelength in centimeters + meters - Wavelength in meters + hertz - Frequency in hertz (cycles per second) + kilohertz - Frequency in kilohertz + megahertz - Frequency in megahertz + gigahertz - Frequency in gigahertz + m/s - Velocity in meters per second + km/s - Velocity in kilometers per second + ev - Energy in electron volts + kev - Energy in kilo electron volts + mev - Energy in mega electron volts + + nm - Wavelength in nanometers + mm - Wavelength in millimeters + cm - Wavelength in centimeters + m - Wavelength in meters + Hz - Frequency in hertz (cycles per second) + KHz - Frequency in kilohertz + MHz - Frequency in megahertz + GHz - Frequency in gigahertz + wn - Wave number (inverse centimeters) +.fi + +The velocity units require a trailing value and unit defining the +velocity zero point. For example to plot velocity relative to +a wavelength of 1 micron the unit string would be: + +.nf + km/s 1 micron +.fi + +Some additional examples of units strings are: + +.nf + milliang + megahertz + inv mic + log hertz + m/s 3 inv mic +.fi +.ih +EXAMPLES +This task has a very large number of commands and capabilities which +are interactive and graphical. Therefore it these examples are +fairly superficial. The user is encouraged to simply experiment with +the task. To get some help use the '?' or '/' keys. + +1. To plot a single spectrum and record any measurements in the file +'ngc7662': + + cl> splot spectrum save_file=ngc7662 + +2. To force all plots to display zero as the minimum y value: + + cl> splot spectrum options="auto, zero" + +Note that the options auto and zero can be abbreviated to one character. + +3. To successively display graphs for a set of spectra with the wavelength +limits set to 3000 to 6000 angstroms: + + cl> splot spec* xmin=3000 xmax=6000 + +4. To make batch plots create a file containing the simple cursor command + + 0 0 0 q + +or an empty file and then execute one of the following: + +.nf + cl> splot spec* graphics=stdplot cursor=curfile + cl> set stdvdm=splot.mc + cl> splot spec* graphics=stdvdm cursor=curfile + cl> splot spec* cursor=curfile >G splot.mc +.fi + +The first example sends the plots to the standard plot device specified +by the environment variable "stdplot". The next example sends the plots +to the standard virtual display metacode file specified by the +environment variable "stdvdm". The last example redirects the +standard graphics to the metacode file splot.mc. To spool the metacode +file the tasks \fBstdplot\fR and \fBgkimosaic\fR may be used. +For a large number of plots \fBgkimosaic\fR is prefered since it places +many plots on one page instead of one plot per page. +The other GKI tasks in the \fBplot\fR package may be used to examine +the contents of a metacode file. A simple script call \fBbplot\fR is provided +which has the default cursor file given above and default device of "stdplot". + +5. More complex plots may be produced both interactively using the +'=' key or the ":.snap" or ":.write" commands or by preparing a script +of cursor commands. +.ih +REVISIONS +.ls SPLOT V2.11 +The profile fitting and deblending was expanded to include lorentzian +and voigt profiles. A new parameter controls the number of Monte-Carlo +samples used in the error estimates. + +Added colon commands for labeling. +.le +.ls SPLOT V2.10.3 +The 'u' key now allows three ways to adjust the dispersion scale. The +old method of setting a linear dispersion scale is retained as well +as adding a doppler and zeropoint adjustment. The coordinates are +input in the currently displayed units. + +If a wavelength scale is set with either 'p' or 'u' then any other +spectra which are not dispersion corrected will adopt this wavelength +scale. + +The '(' and ')' keys cycle through bands if there is only one spectrum. + +A new option, "flip", has been added to the options parameter to select +that the spectra are plotted in decreasing wavelength. + +A new options "overplot" has been added to the options parameters and +colon commands to permanently set overplotting. This allows quickly +overplotting many spectra. + +This task will now write out the current display units in the "units_display" +WCS attribute. The default task units have been changed to "" to allow +picking up the "units_display" units if defined. + +The deblending and gaussian fitting code now subsamples the profile by +a factor of 3 and fits the data pixels to the sum of the three +subsamples. This accounts for finite sampling of the data. + +Error estimates are provided for the deblending ('d'), gaussian fitting +('k'), and profile integration ('e') results. +.le +.ls SPLOT V2.10 +This is a new version with a significant number of changes. In addition to +the task changes the other general changes to the spectroscopy packages +also apply. In particular, long slit spectra and spectra with nonlinear +dispersion functions may be used with this task. The image header or +package dispaxis and nsum parameters allow automatically extracting spectra +from 2D image. The task parameters have been modified primarily to obtain +the desired initial graph without needing to do it interactively. In +particular, the new band parameter selects the band in 3D images, the units +parameter selects the dispersion units, and the new histogram, nosysid, and +xydraw options select histogram line type, whether to include a system ID +banner, and allow editing a spectrum using different endpoint criteria. + +Because nearly every key is used there has been some shuffling, +consolidating, or elimination of keys. One needs to check the run time '?' +help or the help to determine the key changes. + +Deblending may now use any number of components and simultaneous fitting of +a linear background. A new simplified version of Gaussian fitting for a +single line has been added in the 'k' key. The old 'k', 'h', and 'v' +equivalent width commands are all part of the single 'h' command using a +second key to select a specific option. The Gaussian line model from these +modes may now be subtracted from the spectrum in the same way as the +Gaussian fitting. The one-sided options, in particular, are interesting in +this regard as a new capability. + +The arithmetic functions between two spectra are now done in wavelength +with resampling to a common dispersion done automatically. The 't' key now +provides for the full power of the ICFIT package to be used on a spectrum +for continuum normalization, subtraction, or line and cosmic ray removal. +The 'x' editing key may now use the nearest pixel values rather than only +the y cursor position to replace regions by straight line segments. The +mode is selected by the task option parameter "xydraw". + +Control over the graph window (plotting limits) is better integrated so +that redrawing, zooming, shifting, and the GTOOLS window commands all work +well together. The new 'c' key resets the window to the full spectrum +allowing the 'r' redraw key to redraw the current window to clean up +overplots from the Gaussian fits or spectrum editing. + +The dispersion units may now be selected and changed to be from hertz to +Mev and the log or inverse (for wave numbers) of units taken. As part of +the units package the 'v' key or colon commands may be used to plot in +velocity relative to some origin. The $ key now easily toggles between the +dispersion units (whatever they may be) and pixels coordinates. + +Selection of spectra has become more complex with multiaperture and long +slit spectra. New keys allow selecting apertures, lines, columns, and +bands as well as quickly scrolling through the lines in multiaperture +spectra. Overplotting is also more general and consistent with other tasks +by using the 'o' key to toggle the next plot to be overplotted. Overplots, +including those of the Gaussian line models, are now done in a different +line type. + +There are new colon commands to change the dispersion axis and summing +parameters for 2D image, to toggle logging, and also to put comments +into the log file. All the options may also be set with colon commands. +.le +.ih +SEE ALSO +bplot, gtools, icfit, standard, package, specplot, graph, implot, fitprofs +.endhelp diff --git a/noao/onedspec/doc/standard.hlp b/noao/onedspec/doc/standard.hlp new file mode 100644 index 00000000..d0c84aef --- /dev/null +++ b/noao/onedspec/doc/standard.hlp @@ -0,0 +1,551 @@ +.help standard Jan00 noao.onedspec +.ih +NAME +standard -- Add standard stars to sensitivity file +.ih +USAGE +standard input [records] output +.ih +PARAMETERS +.ls input +List of input standard star spectra or root names if using the record number +extension format. All spectra of the same aperture must be of the same +standard star. In beam switch mode or when the same star parameter is set +all spectra must be of the same standard star regardless of aperture number. +Normally the spectra will not be extinction corrected but if they are +then the extinction file should also be given and the same extinction +file should be used with \fBsensfunc\fR. +.le +.ls records (imred.irs and imred.iids only) +List of records or ranges of records to be appended to the input spectra +names when using record number extension format. The +syntax of this list is comma separated record numbers or ranges of record +numbers. A range consists of two numbers separated by a hyphen. +A null list may be used if no record number extensions are +desired. This is a positional query parameter only if the record +format is specified. +.le +.ls output +The name of a text file which will contain the output from \fBstandard\fR. +Each execution of \fBstandard\fR appends to this file information about the +standard stars, the calibration bandpasses, and observed counts (see the +DESCRIPTION section for more details). The output must be explicitly +deleted by the user if the filename is to be reused. +.le +.ls samestar = yes +Is the same star in all apertures? If set to no then each aperture may +contain a different standard star. The standard star name is queried +each time a new aperture is encountered. Note that this occurs only +once per aperture and multiple spectra with the same aperture number +must be of the same star. If set to yes the standard star name is only +queried once. When in beam switch mode this parameter is ignored since +all apertures must contain the same star. +.le +.ls beam_switch = no +Beam switch the spectra? If yes then a beam switch mode is used for the spectra +in which successive pairs of object and sky observations from the same aperture +are sky subtracted. This requires that the object type flag OFLAG be present +and that the spectra are appropriately ordered. All object observations must be +of the same standard star and the \fIsamestar\fR parameter is ignored. +.le +.ls apertures = "" +List of apertures to be selected from the input list of spectra. If no list +is specified then all apertures are selected. The syntax is the same as the +record number extensions. +.le +.ls bandwidth = INDEF, bandsep = INDEF +Bandpass widths and separations in wavelength units. If INDEF then the +default bandpasses are those given in the standard star calibration +file. If values for these parameters are specified then a default set +of bandpasses of equal width and separation are defined over the range +of the input spectrum. In both cases the default bandpasses can be +changed interactively if desired. +.le +.ls fnuzero = 3.68e-20 +The absolute flux per unit frequency at an AB magnitude of zero. This is used +to convert the calibration AB magnitudes to absolute flux by the formula + +.nf + f_nu = fnuzero * 10. ** (-0.4 * m_AB) +.fi + +The flux units are also determined by this parameter. However, the +frequency to wavelength interval conversion assumes frequency in hertz. +The default value is based on a calibration of Vega at 5556 Angstroms of +3.52e-20 ergs/cm2/s/Hz for an AB magnitude of 0.0336. This default value +is that used in earlier versions of this task which did not allow the +user to change this calibration. +.le +.ls extinction = <no default> +Extinction file used to make second order extinction corrections across +the bandpasses. The default value is redirected to the package +parameter of the same name. See \fBlcalib\fR for a list of standard +extinction files. Normally the input spectra will not be extinction +corrected. But if they are this file will be used to remove the +extinction and then the same file should be specified in \fBsensfunc\fR. +Note that one can choose to use a null extinction file in both. +.le +.ls caldir = ")_.caldir" +Calibration directory containing standard star data. The +default value of ")_.caldir" means to use the package parameter "caldir". +A list of standard calibration directories may be obtained by listing the +file "onedstds$README"; for example: + +.nf + cl> page onedstds$README +.fi + +The user may copy or create their own calibration files and specify the +directory. The directory "" refers to the current working directory. The +standard calibration directory for blackbody curves is +"onedstds$blackbody/". +.le +.ls observatory = ")_.observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. The default is a redirection to look +in the parameters for the parent package for a value. The observatory may +be one of the observatories in the observatory database, "observatory" to +select the observatory defined by the environment variable "observatory" or +the parameter \fBobservatory.observatory\fR, or "obspars" to select the +current parameters set in the \fBobservatory\fR task. See help for +\fBobservatory\fR for additional information. +.le +.ls interact = no +If set to no, then the default wavelength set (either that from the star +calibration file or the set given by the \fIbandwidth\fR and \fIbandsep\fR +parameters) is used to select wavelength points along the spectrum where the +sensitivity is measured. If set to yes, the spectra may be plotted +and the bandpasses adjusted. +.le +.ls graphics = "stdgraph" +Graphics output device for use with the interactive mode. Normally this is +the user's graphics terminal. +.le +.ls cursor = "" +Graphics cursor input for use with the interactive mode. When null the +standard graphics cursor is used otherwise the specified file is used. +.le +.ls star_name +The name of the star observed in the current series of spectra. Calibration +data for the star must be in the specified calibration directory "caldir". +This is normally a interactive query parameter and should not be specified on +the command line unless all spectra are of the same standard star. +.le + +The following three queried parameters apply if the selected calibration +file is for a blackbody. +.ls mag +The magnitude of the observed star in the band given by the +\fImagband\fR parameter. If the magnitude is not in the same band as +the blackbody calibration file then the magnitude may be converted to +the calibration band provided the "params.dat" file containing relative +magnitudes between the two bands is in the calibration directory +.le +.ls magband +The standard band name for the input magnitude. This should generally +be the same band as the blackbody calibration file. If it is +not the magnitude will be converted to the calibration band. +.le +.ls teff +The effective temperature (deg K) or the spectral type of the star being +calibrated. If a spectral type is specified a "params.dat" file must exist +in the calibration directory. The spectral types are specified in the same +form as in the "params.dat" file. For the standard blackbody calibration +directory the spectral types are specified as A0I, A0III, or A0V, where A +can be any letter OBAFGKM, the single digit subclass is between 0 and 9, +and the luminousity class is one of I, III, or V. If no luminousity class +is given it defaults to dwarf. +.le + +The following two parameters are queried if the image does not contain +the information. +.ls airmass, exptime +If the airmass and exposure time are not in the header nor can they be +determined from other keywords in the header then these query parameters +are used to request the airmass and exposure time. The values are updated +in the image. +.le + +The following parameter is for the task to make queries. +.ls answer +Interactive query parameter. +.le +.ih +CURSOR KEYS +.nf +? Display help page +a Add a new band by marking the endpoints +d Delete band nearest the cursor in wavelength +r Redraw current plot +q Quit with current bandpass definitions +w Window plot (follow with '?' for help) +I Interrupt task immediately + +:show Show current bandpass data +.fi +.ih +DESCRIPTION +Observations of standard stars are integrated over calibration bandpasses +and written to an output file along with the associated calibration +fluxes. The fluxes are obtained from tabulated standard star calibration +files or a model flux distribution (currently just a blackbody) based on +the magnitude and spectral type of the star. The output data is used by +the task \fBsensfunc\fR to determine the detector sensitivity function and +possibly the extinction. The spectra are required to be dispersion +corrected. The input spectra may be in either "onedspec" or "echelle" +format and may have many different observation apertures. The spectra may +also be beam switched and use the a record number extension format. + +The input spectra are specified by a list of names or root names if using +the record number extension format. In the latter case each name in the +list has each of the specified record numbers appended. A subset of the +input spectra may be selected by their aperture numbers using the parameter +\fIapertures\fR. The spectrum name, aperture number, and title are printed +to the standard output. The airmass is required but if absent from the image +header it may be computed from the observation header parameters and the +latitude task parameter (normally obtained from the \fBobservatory\fR task). +If the airmass cannot be computed, due to missing keywords, then a +query is made for the airmass. The airmass is then updated in the header. + +The name of the standard star or blackbody curve is obtained by querying +the user. If the parameter \fIsamestar\fR is yes or beam switch mode is +selected then all spectra are assumed to be of the same standard star and +the query is made once. If the parameter is no then a query is made for +each aperture. This allows each aperture to contain a different standard +star. Note however that multiple observations with the same aperture +number must be of the same standard star. + +The standard star name is either the name of an actual standard star or of +a blackbody calibration. The latter generally have a star name consisting +of just the standard bandpass identifier. If the standard star name is not +recognized a menu of the available standard stars in the calibration +directory, the file "standards.men", is printed and then the query is +repeated. Thus, to get a list you can type ? or help. + +The standard star names must map to a file containing tabulated +calibration data. The calibration filename is formed from the star +name with blanks, "+", and "-" removed, converted to lower case, and +the extension ".dat" added. This name is appended to a calibration +directory, so the directory name must have an appropriate directory +delimiter such as "$" or "/". Generally one of the system calibration +directories is used but one may copy and modify or create new +calibration files in a personal directory. For the current working +directory the calibration directory is either null or "./". + +The calibration files may include comment parameter information consisting +of the comment character '#', a parameter name, and the parameter value. +These elements are separated by whitespace. Any other comment where the +first word does not match one of the allowed parameter names is ignored by +the program. The parameter names are "type" identifying the type of +calibration file, "units" identifying wavelength units, "band" identifying +the band for magnitudes, and "weff" identifying the effective wavelength of +the band. + +There are two types of standard star calibration files as described +below. + +.ls STANDARD STAR CALIBRATION FILES +This type of file is any file that does not contain the parameter "type" +with a value of "blackbody". The only other parameter used by this type of +calibration file is the "units" parameter for the wavelength units. If the +units are not specified then the wavelengths default to Angstroms. All +older calibration files will have no parameter information so they are +interpreted as standard star calibration files with wavelengths in +Angstroms. + +The calibration files consist of lines with wavelengths, calibration +magnitudes, and bandpass widths. The magnitudes are m_AB defined as + +.nf + m_AB(star) = -2.5 * log10 (f_nu) - 48.60 +.fi + +where f_nu is in erg/cm^2/s/Hz. The m_AB calibration magnitudes +are converted to absolute flux per unit frequency using the +parameter \fIfnuzero\fR defined by + +.nf + f_nu = fnuzero * 10. ** (-0.4 * m_AB) +.fi + +Thus, \fIfnuzero\fR is the flux at m_AB of zero. The flux units are +determined by this number. The default value was chosen such that Vega +at 5556 Angstroms has an AB magnitude of 0.0336 and a flux of 3.52e-20 +ergs/cm2/s/Hz. This is the same value that was used by all previous +versions of this task. +.le + +.ls BLACKBODY CALIBRATION FILES +This type of file has the comment parameter "type" with a value of +"blackbody". It must also include the "band" and "weff" +comment parameters. If no "units" comment parameter is given then +the default units are Angstroms. + +The rest of the file consists of lines with wavelengths, m_AB of a zero +magnitude star (in that band magnitude system), and the bandpass widths. +The m_AB are defined as described previously. Normally all the m_AB values +will be the same though it is possible to adjust them to produce a +departure from a pure blackbody flux distribution. + +The actual m_AB calibration magnitudes for the star are obtained by +the relation + +.nf + m_AB(star) = mag + m_AB(m=0) - + 2.5 * log10 (B(weff,teff)/B(w,teff)) +.fi + +where m is the magnitude of the star in the calibration band, m_AB(m=0) is +the calibration value in the calibration file representing the magnitude of +a m=0 star (basically the m_AB of Vega), weff is the effective wavelength +for the calibration file, and teff is the effective temperature of the +star. The function B(w,T) is the blackbody function in f_nu that provides +the shape of the calibration. Note how the normalization is such that at +weff the last term is zero and m_AB(star) = m + m_AB(m=0). + +The m_AB(star) computed using the calibration values and the blackbody +function are then in the same units and form as for the standard +star files. The conversion to f_nu and the remaining processing +proceeds in the same way as for standard star calibration data. + +The parameters \Imag\fR and \fIteff\fR are specified by the user for each +star as described in the section BLACKBODY PARAMETERS. These parameters +are queried by the task for each star (unless forced to a value on the +command line). +.le + +The beam switch mode is selected with the \fIbeam_switch\fR parameter. +This mode requires that all apertures are of the same star, the header +keyword OFLAG be present to identify object and sky spectra, and that +the sequence of spectra specified are paired such that if an object +spectrum is encountered first the next spectrum for that aperture +(spectra from other apertures may appear in between) is a sky spectrum +or the reverse. These restrictions are not fundamental but are made so +that this mode behaves the same as with the previous version of this +task. The sky spectrum is subtracted from the object spectrum and the +result is then used in generating the observed intensities in the calibration +bandpasses. + +If the spectra have been extinction corrected (EX-FLAG = 0) the +extinction correction is removed. The specified extinction file is +used for this operation and so must be the same as that used when the +extinction correction was made. The airmass is also required in this step +and, if needed to compute the airmass, the observatory specified in the +image or observatory parameter is used. The +treatment of extinction in this task is subtle. The aim of this task +is to produce observed integrated instrumental intensities without +extinction correction. Thus, the extinction correction is removed from +extinction corrected spectra. However, a correction is made for an +extinction gradient across the bandpasses. This is done by applying an +extinction correction, integrating across the bandpass, and then +correcting the integrated intensity for the extinction at the center of +the bandpass. An alternative way to look at this is that the integral +is weighted by the ratio of the extinction correction at each pixel to +the extinction correction at the center of the bandpass. This +correction or weighting is why the extinction file and latitude are +parameters in this task even though for nonextinction corrected spectra +they appear not to be needed. + +The observed instrumental intensities are integrated within a set of +bandpasses by summing the pixels using partial pixels at the bandpass +edges. Initial bandpasses are defined in one of two ways. A set of +evenly spaced bandpasses of constant width covering the range of the +input spectrum may be specified using the parameters \fIbandwidth\fR +and \fIbandsep\fR in the same units as the spectrum dispersion. If +these parameters have the value INDEF then the bandpasses from the +calibration file which are entirely within the spectrum are selected. +Generally these bandpasses are the actual measured bandpasses though +one is free to make calibration files using estimated points. The +calibration bandpasses are preferable because they have been directly +measured and they have been placed to avoid troubles with spectral +lines. However, when the coverage or resolution is such that these +bandpasses do not allow a good determination of the instrumental +response the evenly spaced bandpasses may be needed. The calibration +fluxes are linearly interpolated (or extrapolated) from the calibration +data points to the defined bandpasses. + +Each spectrum adds a line to the output file containing the spectrum image +name, the sky spectrum image name if beam switching, the aperture or beam +number, the number of points in the spectrum, the exposure time, airmass, +wavelength range, and title. If the airmass is not found in the image +header it is computed using the latitude parameter and observation +information from the header. If the airmass cannot be computed, due to +missing keywords, then a query is made for the airmass. + +Following the spectrum information, calibration data is added for each +bandpass. The bandpass wavelength, absolute flux (per Angstrom), +bandpass width, and observed instrumental intensity in the bandpass are +added to the output file. As discussed above, the observed intensity +does not include an extinction term but does apply a small correction +or weighting for the variation of the extinction across the bandpass. + +The setting and editing of the bandpasses may be performed +interactively if the \fIinteract\fR flag is set. In this case the user +is queried for each spectrum. The answers to this query may be "no" or +"yes" to skip editing or edit the bandpasses for this spectrum, "NO" or +"YES" to skip or not skip editing all spectra of the same aperture with +no further queries for this aperture, and "NO!" or "YES!" to skip +editing or edit all spectra with no further queries. + +When editing the bandpasses a graph of the spectrum is made with the +bandpasses plotted at the computed intensity per pixel. The cursor and +colon commands available are summarized in the section CURSOR KEYS. +Basically bandpasses may be added or deleted and the current bandpass +data may be examined. Additional keys allow the usual windowing and +cursor mode operations. When satisfied with the bandpasses exit with +'q'. The edited bandpasses for that aperture remain in effect until +changed again by the user. Thus if there are many spectra from the +same aperture one may reply with "NO" to queries for the next spectra +to accept the current bandpasses for all other spectra of the same +aperture. + +BLACKBODY PARAMETERS + +When a blackbody calibration is selected (the calibration file selected by +the \fIstar_name\fR parameter has "# type blackbody") there are two +quantities needed to scale the blackbody to the observation. These are the +magnitude of the star in the same band as the observation and the effective +temperature. The magnitude is used for the flux scaling and the effective +temperature for the shape of the flux distribution. The values are +obtained or derived from the user specified parameters \fImag\fR, +\fImagband\fR, and \fIteff\fR. This section describes how the the +values are derived from other parameters using the data file "params.dat" +in the calibration directory. + +The effective temperature in degrees Kelvin may be specified directly or it +may be derived from a spectral type for the star. In the latter case the +file "params.dat" is searched for the effective temperature. The file +consists of lines with the first value being the spectral type and the +second the effective temperature. Other columns are described later. The +spectral type can be any string without whitespace that matches what is in +the file. However, the program finds the last spectral type that matches +the first two characters when there is no complete match. This scheme is +intended for the case where the spectral types are of the form A0I, A0III, +or A0V, where A can be any spectral type letter OBAFGKM, the single digit +subtype is between 0 and 9, and the luminousity class is one of I, III, or +V. The two character match selects the last spectral type independent of +the luminosity class. The standard file "onedstds$blackbody/params.dat" +uses these spectral type identifiers with the dwarf class acting as the +default. + +The magnitude band is specified along with the input magnitude. If the +band is the same as the calibration band given in the calibration file then +no further transformation is required. However if the magnitude is +specified in a different band, a conversion is performed using information +from the "params.dat" file based on the spectral type of the star. + +When an effective temperature is specified rather and a spectral type then +the nearest tabulated temperature for the spectral types that have "V" as +the third character is used. For the standard spectral type designations +this means that when an effective temperature is specified the dwarf +spectral type is used for the magnitude transformation. + +As mentioned previously, the "params.dat" data file has additional columns +following the spectral type and effective temperature. These columns are +relative magnitudes in various bands. The standard file has V magnitudes +of zero so in this case the columns are also the X-V colors (where X is the +appropriate magnitude). Given the spectral type the relative magnitudes +for the calibration band, m_1, and the input magnitude band, m_2, are found +and the calibration magnitude for the star is given by + +.nf + m_calibration = m_input + m_1 - m_2 +.fi + +If one of the magnitudes is missing, given as "INDEF" because the +transformation is not available for the spectral type, the last spectral +type matching the first two characters which does specify the two +magnitudes will be used. For example if there is no information for a +B3III star for a M-J color then the spectral type B3V might be used. + +In order for the program to determine the bands for each column in the data +file there must be a comment before the data with the column names. It must +begin with "# Type Teff" and then be followed by the same band identifiers +used in the blackbody calibration files and as specified by the +\fImagband\fR parameter. Any amount whitespace (space or tab) is used to +separate the various fields in the comment and in the fields of the table. +For example the file might have the comment + +.nf + # Type Teff V J H K L Lprime M +.fi + +identifying the third column of the file as the V magnitude and the +ninth file as the M magnitude. +.ih +EXAMPLES +1. To compile observations of three standard stars using a beam +switched instrument like the IIDS: + +.nf + cl> standard.recformat=yes + cl> standard nite1 1001-1008 std beam_switch+ interact- + [nite1.1001][0]: HZ 44 - Night 1 + [nite1.1004][0]: HZ 44 - Night 1 + [nite1.1005][0]: HZ 44 - Night 1 + [nite1.1008][0]: HZ 44 - Night 1 + Star name in calibration list: hz 44 + cl> standard nite1 1009-1016 std beam_switch+ interact- + ... + cl> standard nite1 1017-1024 std beam_switch+ interact- + ... +.fi + +This will create a file "std" which will contain sensitivity measurements +from the beam-switched observations of the three standard stars given. +Note that \fBstandard\fR is run separately for each standard star. + +The spectra will be from the images: nite1.1001, nite.1002 ... nite1.1024, +and the default calibration file, "onedstds$irscal.dat" will be used. + +2. For echelle spectra all apertures, the orders, are of the same star and +so the samestar parameter is set. Usually the resolution is much higher than +the calibration data so in order to get sufficient coverage bandpasses must +be interpolated from the calibration data. Therefore the evenly spaced +bandpasses are used. + +.nf + cl> standard.recformat=no + cl> standard.samestar=yes + cl> standard ech001.ec std bandwidth=10 bandsep=15 + [ech001.ec][0]: Feige 110 + Star name in calibration list: feige 110 + [ech001.ec][0]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): yes + [ech001.ec][1]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): yes + [ech001.ec][2]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): NO! +.fi + +3. To use a blackbody infrared calibration where the V magnitude of +the star is known. + +.nf + cl> standard std1.ms std caldir=onedstds$blackbody/ + std1.ms(1): Standard Star + Star name in calibration list: J + Magnitude of star: 10.3 + Magnitude type (|V|J|H|K|L|Lprime|M|): V + Effective temperature or spectral type: B3III + WARNING: Effective temperature for B3III not found - using B3V + Blackbody: V = 10.30, J = 10.32, Teff = 19000 + std1[1]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!) (yes): +.fi + +Note the warning message and the confirmation information. +.ih +REVISIONS +.ls STANDARD V2.10.4 +The calibration files can be defined to compute blackbody values. +.le +.ls STANDARD V2.10.3 +A query for the airmass and exposure time is now made if the information +is not in the header and cannot be computed from other header keywords. +.le +.ls STANDARD V2.10 +Giving an unrecognized standard star name will page a list of standard +stars available in the calibration directory and then repeat the +query. +.le +.ih +SEE ALSO +observatory, lcalib, sensfunc +.endhelp diff --git a/noao/onedspec/doc/sys/1and2dspec.hlp b/noao/onedspec/doc/sys/1and2dspec.hlp new file mode 100644 index 00000000..01f01763 --- /dev/null +++ b/noao/onedspec/doc/sys/1and2dspec.hlp @@ -0,0 +1,66 @@ +.help onedspec (Oct84) "Spectral Reductions" +.ce +Relationship Between Onedspec and Twodspec +.ce +Discussion +.ce +October 24, 1984 +.sp 3 +Two types of interactions between one dimensional and two dimensional +spectra may be defined: + +.ls (1) +Perform a one dimensional operation on the average or sum of a set +of lines in a two dimensional image. +.le +.ls (2) +Perform a one dimensional operation successively on a set of lines +in a two dimensional image. +.le + +The two functions might be combined as: + +.ls (3) +Perform a one dimensional operation on the average or sum of a set +of lines in a two dimensional image and apply the one dimensional +result successively on a set of lines in a two dimensional image. +.le + +Examples of this are dispersion solutions and flux calibrations for +longslit spectra. + + Some choices for implementation are: + +.ls (1) +Use a 2-D to 1-D operator to create a 1-D spectrum by averaging or summing +lines. +.le +.ls (2) +Use an apply a 1-D arithmetic correction to a 2-D image operator. +Alternatively, expand a 1-D correction to a 2-D correction. +.le +.ls (3) +Convert the 2-D image to a group of 1-D images and provide the 1-D operators +with the ability to perform averaging or summation. +.le +.ls (4) +To perform a one dimensional operation successively on +a set of lines first convert the two dimensional image into a group +of one dimensional spectra. Perform the 1-D operation on the desired +elements of the group and then reconstruct the 2-D image from the group +of 1-D images. +.le +.ls (5) +Built separate operators for 2-D images using the 1-D subroutines. +.le +.ls (6) +Provide the ability in the 1-D operators to perform the desired 2-D +operations directly. +.le + + Options (1) and (2) are essentially what is done on the IPPS. Option (5) +would lessen the amount of development but increase the number of tasks +to be written. I find option (6) desirable because of its +increased generality but it would require a +further definition of the data structures allowed and the syntax. +.endhelp diff --git a/noao/onedspec/doc/sys/Headers.hlp b/noao/onedspec/doc/sys/Headers.hlp new file mode 100644 index 00000000..9bb394b7 --- /dev/null +++ b/noao/onedspec/doc/sys/Headers.hlp @@ -0,0 +1,189 @@ +.LP +.SH +Image Header Parameters +.PP +The ONEDSPEC package uses the extended image header to extract +information required to direct processing of spectra. If the +header information were to be ignored, the user would need to +enter observing parameters to the program at the risk of +typographical errors, and with the burden of supplying the +data. For more than a few spectra this is a tedious job, +and the image header information provides the means to eliminate +almost all the effort and streamline the processing. +.PP +However, this requires that the header information be present, +correct, and in a recognizable format. To meet the goal of +providing a functional package in May 1985, the first iteration +of the header format was to simply adopt the IIDS/IRS headers. +This allowed for processing of the data which would be first +used heavily on the system, but would need to be augmented at +a later date. The header elements may be present in any order, +but must be in a FITS-like format and have the following names +and formats for the value fields: +.sp 1 +.TS +l c l +l l l. +Parameter Value Type Definition + +HA SX Hour angle (+ for west, - for east) +RA SX Right Ascension +DEC SX Declination +UT SX Universal time +ST SX Sidereal time +AIRMASS R Observing airmass (effective) +W0 R Wavelength at center of pixel 1 +WPC R Pixel-to-pixel wavelength difference +NP1 I Index to first pixel containing good data (actually first-1) +NP2 I Index to last pixel containing good data (last really) +EXPOSURE I Exposure time in seconds (ITIME is an accepted alias) +BEAM-NUM I Instrument aperture used for this data (0-49) +SMODE I Number of apertures in instrument - 1 (IIDS only) +OFLAG I Object or sky flag (0=sky, 1=object) +DF-FLAG I Dispersion fit made on this spectrum (I=nr coefs in fit) +SM-FLAG I Smoothing operation performed on this spectrum (I=box size) +QF-FLAG I Flat field fit performed on this spectrum (0=yes) +DC-FLAG I Spectrum has been dispersion corrected (0=linear, 1=logarithmic) +QD-FLAG I Spectrum has been flat fielded (0=yes) +EX-FLAG I Spectrum has been extinction corrected (0=yes) +BS-FLAG I Spectrum is derived from a beam-switch operation (0=yes) +CA-FLAG I Spectrum has been calibrated to a flux scale (0=yes) +CO-FLAG I Spectrum has been coincidence corrected (0=yes) +DF1 I If DF-FLAG is set, then coefficients DF1-DFn (n <= 25) exist +.TE +.PP +The values for the parameters follow the guidelines adopted for +FITS format tapes. All keywords occupy 8 columns and contain +trailing blanks. Column 9 is an "=" followed by a space. The value field +begins in column 11. Comments to the parameter may follow a "/" after +the value field. The value type code is as follows: +.RS +.IP SX +This is a sexagesimal string of the form '12:34:56 ' where the first +quote appears in column 11 and the last in column 30. +.IP R +This is a floating point ("real") value beginning in column 11 and +extending to column 30 with leading blanks. +.IP I +This is an integer value beginning in column 11 and extending to +column 30 with leading blanks. +.RE +.sp 1 +.PP +The parameters having FLAG designations all default to -1 to indicate +that an operation has not been performed. +The ONEDSPEC subroutines "load_ids_hdr" and "store_keywords" follow +these rules when reading and writing spectral header fields. +If not present in a header, load_ids_hdr will assume a value of zero +except that all flags are set to -1, and the object flag parameter +defaults to object. +.PP +When writing an image, only the above parameters are stored by store_keywords. +Other header information is lost. This needs to be improved. +.PP +Not all programs need all the header elements. The following table +indicates who needs what. Tasks not listed generally do not require +any header information. Header elements not listed are not used. +The task SLIST requires all the elements listed above. +The task WIDTAPE requires almost all (except NP1 and NP2). +The headings are abbreviated task names as follows: +.sp 1 +.nr PS 8 +.ps 8 +.TS +center; +l l | l l | l l. +ADD addsets COE coefs FIT flatfit +BSW bswitch COM combine REB rebin +CAL calibrate DIS dispcor SPL splot +COI coincor FDV flatdiv STA standard +.TE +.sp 1 +.TS +center, tab(/); +l | l | l | l | l | l | l | l | l | l | l | l | l. +Key/ADD/BSW/CAL/COI/COE/COM/DIS/FDV/FIT/REB/SPL/STA +_ +HA// X////////// X/ +RA// X////////// X/ +DEC// X////////// X/ +ST// X////////// X/ +UT// X////////// X/ +AIRMASS// X////////// X/ +W0// X/ X/// X//// X/ X/ X/ +WPC// X/ X/// X//// X/ X/ X/ +NP1/////////// X/// +NP2/////////// X/// +EXPOSURE/ X/ X/// X/ X///// X/// +BEAM-NUM// X/ X//// X/ X/ X// X/ X// +OFLAG// X////////// X/ +DF-FLAG//// X +DC-FLAG// X//// X//// X/ X/ X/ +QD-FLAG//////// X/ +EX-FLAG// X/ +BS-FLAG// X/ +CA-FLAG/ X// X//////// X/ +CO-FLAG///// X// +DFn//// X/ +.TE +.nr PS 10 +.ps 10 +.bp +.SH +Headers From Other Instruments +.PP +The header elements listed above are currently created only when reading +IIDS and IRS data from one of the specific readers: RIDSMTN and RIDSFILE. +The time-like parameters, (RA, DEC, UT, ST, HA), are created in a +compatible fashion by RCAMERA and RFITS (when the FITS tape is written +by the KPNO CCD systems). +.PP +For any other header information, the ONEDSPEC package is at a loss +unless the necessary information is edited into the headers with +an editing task such as HEDIT. This is not an acceptable long term +mode of operation, and the following suggestion is one approach to +the header problem. +.PP +A translation table can be created as a text file which outlines +the mapping of existing header elements to those required by the +ONEDSPEC package. A mapping line is needed for each parameter +and may take the form: +.sp 1 +.RS +.DC +1D_param default hdr_param key_start value_start type conversion +.DE +.RE +where the elements of an entry have the following definitions: +.TS +center; +l l. +1D_param T{The name of the parameter expected by the ONEDSPEC package, +such as EXPOSURE, OFLAG, BEAM-NUM. T} + +default T{A value to be used if no entry is found for this parameter.T} + +hdr_param T{The string actually present in the existing image header to be +associated with the ONEDSPEC parameter. T} + +key_start T{The starting column number at which the string starts +in the header. T} + +value_start T{The starting column number at which the string describing the +value of the parameter starts in the header. T} + +type T{The format type of the parameter: integer, real, string, boolean, +sexagesimal. T} + +conversion T{If the format type is string, a further conversion may +optionally be made to one of the formats listed under type. T} +.TE +.sp 1 +.PP +A translation file can be built for each instrument and its +peculiar header formats, and the file name associated with a +package parameter. The two subroutines in ONEDSPEC dealing +directly with the headers (load_ids_hdr and store_keywords) +can be modified or replaced to access this file and +translate the header elements. +.endhelp diff --git a/noao/onedspec/doc/sys/Onedspec.hlp b/noao/onedspec/doc/sys/Onedspec.hlp new file mode 100644 index 00000000..85a3f20e --- /dev/null +++ b/noao/onedspec/doc/sys/Onedspec.hlp @@ -0,0 +1,2219 @@ +.help spbasic +.sh +One Dimensional Package - Basic Operators + +.sh +INTRODUCTION + + The IRAF One Dimensional Package is intended to provide the basic +tools required to reduce, analyze, and display data having a +single dimension. This primarily refers to spectra, but may have +applicability to time series photometry, or any other +source of data which can be considered a simple vector. +All such data will be referred to as spectra in the following discussion. +Furthermore, the spectrum vector is assumed to be equally spaced +along the independent variable (wavelength, channel, frequency, +wavenumber,...). For the purposes of discussion, the independent +variable will be referred to as wavelength but may be any of the +possible physical transformations. + + Spectra are to be stored as 2 dimensional IRAF floating point images +having a single line +and are therefore limited to lengths smaller than or equal to the +largest representable positive integer. For 32 bit machines, this +is about 2 billion points, so that disk space will likely be the +operational limit. The precision and dynamic range for each pixel +will be determined by the local machine. +The second dimension of the spectrum is spatial, and therefore +represents a special case of the long slit spectroscopic mode. + + Each spectrum will, by default, be stored as a separate image +file. Alternatively, an association +can be declared for a related set of spectra +through a "data group" mechanism. A data group can be defined to +contain any number of related spectra so that an operation can +be specified for the group. For example, one can group a single +night of IIDS spectra into a group labeled JAN28, and then +wavelength linearize JAN28. This helps minimize +the user interaction which would otherwise be repetitive, and +also reduces the user bookkeeping required. + + Data input to the package is provided through the DATAIO +package. Tape readers will be provided for FITS, IIDS and IRS mountain +formats, Text ("card-image"), REDUCER and PDS. The descriptor fields +included in these formats will be mapped into standard IRAF +image header fields when possible. Special fields will be +added to the image header to represent instrument +related parameters. + + Data output to tape (for visitor take home) will be +either in FITS or text format. + + A variety of graphics display options will be provided +for both interactive use and for hardcopy generation. +Scale expansion and contraction, labeling, multiple spectra +plots, and axis limit specification are to be included in the +options. + + Specific reduction scripts will be provided to efficiently +process raw data from the Kitt Peak instruments IIDS and IRS. + + +.sh +SCOPE OF SPECIFICATIONS + +This paper specifies the command format, parameters, and +operations for the Basic contents of the One Dimensional +Spectral Package. The Basic functions are those comprising the +minimum set to reduce a large variety of spectra. +More complicated operators and analysis functions +are described in a companion paper on Intermediate Functions. +Major projects in spectral analysis will be considered at +a later date in the Advanced function set. + +The primary functions within the Basic operator set are: + +.ls 4 Transport +Primarily magtape readers for the common tape formats. Included +are FITS, IIDS/IRS, REDUCER, PDS, and Card-image formats. +Tape writers will be initially limited to FITS and Card-image. +.le +.ls 4 Mathematical +Add, subtract, multiply, divide spectra by spectra or constants. +Apply functional operators such as log, exp, sqrt, sin, cos. +Weighted sums and averages of spectra. +.le +.ls 4 Reduction operators +Line identification, dispersion solution, flux calibration, +coincidence correction, atmospheric extinction correction, +flat fielding. +.le +.ls 4 Plotting +Terminal package to expand, overplot, annotate plots. Hard +copy package for printer/plotters. +.le +.ls 4 Utilities +Header examination and modification. List, copy, delete spectra. +Define, add, delete entries in a data group. +.le +.ls 4 Artificial spectra +Generate ramps, Gaussian and Voigt lines, noise. +.le + +These functions will be considered in detail in the following +discussion. + +.ks +A summary of the commands is given below: + +.nf +rfits -- Convert FITS data files to IRAF data files +riids -- Convert IIDS mountain tape format to IRAF data files +rreducer -- Convert Reducer format tape to IRAF data files +rpds -- Convert a PDS format tape to IRAF data files +rtext -- Convert a card-image text file to an IRAF image file +wfits -- Convert IRAF data files to FITS data format +wtext -- Convert an IRAF image file to a card-image text file +.sp 1 +coin_cor -- Correct specified spectra for photon coincidence +line_list -- Create a new line list, or modify an existing one +mlinid -- Manually identify line features in a spectrum +alinid -- Automatically locate spectral features in a spectrum +disp_sol -- Determine the dispersion relation for a set of spectra +disp_cor -- Linearize spectra having dispersion relation coefficients +cr_flat -- Create a flat field spectrum +flt_field -- Correct spectra for pixel-to-pixel variations +std_star -- Define the standard stars to be used for solving the + extinction and system sensitivity functions +crext_func -- Create an extinction function from a set of observations +crsens_func -- Create system sensitivity function +ext_cor -- Extinction correct specified spectra +sens_cor -- Correct the specified spectra for system sensitivity +.fi +.ju +.ke + +.bp +.sh +TRANSPORT - INPUT + +Although the primary data input source for the near future +will be magtape, direct links from other computers will +be a likely source of input. The IRAF DATAIO package +treats magtape as simple bit streams so that alternate +input devices (e.g. disk, ethernet, phone lines) can also +be accommodated with no programming modifications. + +This section describes the different formats to be made +available in the initial release of the Spectroscopic +package. Additional formats may be added if needed. + +In general, the following information will be copied to +the standard image header: length of spectrum, title, +abscissa units, brightness units, reference pixel +abscissa value and increment, right ascension and declination +of telescope. + +Non-standard header parameters include but are not limited to: +integration time, UT and LST of the observation, airmass (or +zenith distance), processing history, and comments. + +.sh +FITS +.ih +NAME +rfits -- Convert FITS data files to IRAF data files +.ih +USAGE +rfits [source, filename, files] +.ih +DESCRIPTION +FITS data is read from the specified source. +The FITS header may optionally be printed on the standard +output as either a full listing or a short description. Image data may +optionally be converted to an IRAF image of specified data type. + +Eventually all data from the mountain will be in FITS format, +with the exception of time-critical data transfer projects +and special applications. The IRAF FITS reader will +copy the data to disk for most applications. + +.ih +PARAMETERS +.ls 4 fits_source +The FITS data source. If the data source is a disk file or an explicit tape file +specification of the form mt*[n] where n is a file number then only that file +is converted. If the general tape device name is given, i.e. mta, mtb800, etc, +then the files specified by the files parameter will be read from the tape. +.le +.ls filename +The IRAF file which will receive the FITS data if the make_image parameter +switch set. For tape files specified by the files parameter the filename +will be used as a prefix and the file number will be appended. Otherwise, +the file will be named as specified. Thus, +reading files 1 and 3 from a FITS tape with a filename of data will produce +the files data1 and data3. It is legal to use a null filename. However, +converting a source without a file number and with a null filename will cause +a default file fits to be created. +.le +.ls files +The files to be read from a tape are specified by the files string. The +string can consist of any sequence of file numbers separated by +at least one of whitespace, comma, or dash. +A dash specifies a range of files. For example the string + +1 2, 3 - 5,8-6 + +will convert the files 1 through 8. +.le +.ls print_header +If this switch is set header information is printed on the standard output +output. (default = yes) +.le +.ls short_header +This switch controls the format of the header information printed when the +print_header switch is set. +When the short_header switch is set only the output filename, +the FITS OBJECT string, and the image dimensions are printed. +Otherwise, the output filename is followed by the full FITS header. +(default = yes) +.le +.ls bytes_per_record +The FITS standard record size is 2880 bytes which is the default for this +parameter. However, non-standard FITS tapes with different record sizes can +be read by setting the appropriate size. +.le +.ls make_image +This switch determines whether FITS image data is converted to an IRAF image +file. This switch is set to no to obtain just header information with the +print_header switch. (default = yes) +.le +.ls data_type +The IRAF image file may be of a different data type than the FITS image data. +The data type may be specified as s for short, l for long, and r for real. +The user must beware of truncation problems if an inappropriate data type is +specified. If the FITS keywords BSCALE and BZERO are found then the image +data is scaled appropriately. In this case the real data type may be most +appropriate. +.le +.sh +For spectroscopic applications, the parameter data_type would be +specified as r for real, and the filename would probably be assigned +as the "group" name as well. (see section on data groups.) + + +.sh +IIDS/IRS +.ih +NAME +riids -- Convert IIDS mountain tape format to IRAF data files +.ih +USAGE +riids [source, filename, form, records] +.ih +DESCRIPTION +IIDS/IRS mountain format data is read from the specified source. +The header may be printed +on the standard output either in short form, label only, or a long +form containing telescope and time information, processing flags, +and wavelength solution values. + +Either raw or "mountain reduced" tapes can be specified with the +parameter form. + +The IIDS format is destined for extinction. A FITS format will +replace the current tape format, but an interim period will exist +for which this tape reader must exist. +.ih +PARAMETERS +.ls 4 iids_source +The data source, either magtape or a data stream (e.g. disk file). +The current IIDS tape format produces tapes having only a single +file. If the source is a magtape, the general tape specification +mt*[n], should either have n specified as 1, or [n] should not be present. +.le +.ls 4 filename +The IRAF file which will contain the data if the make_image parameter +is set. The filename will be used as a prefix and the record number +will be used as the suffix. Thus reading records 1 through 100 from +an IIDS tape with a file name of 'blue' will produce 100 files having +names blue1, blue2, ..., blue100. A null filename will default to 'iids'. +.le +.ls 4 form +This string parameter defines the tape to be either 'new' or 'red'. +The 'new' designation refers to tapes made after January 1977, and +'red' refers to mountain reduced tapes. (default = 'red') +.le +.ls 4 records +The records specified by this string parameter will be copied to disk. +The syntax is identical to that for the files parameter of the FITS reader. +.le +.ls 4 print_header +If this switch is set, header information is printed on the standard +output. (default = yes) +.le +.ls 4 short_header +If this switch is set, only the filename and label information will be printed +if the print_header switch is also set. If set to 'no', the long form +will be printed. (default = yes) +.le +.ls 4 make_image +See definition of this parameter under FITS. +.le + + +.sh +REDUCER + +REDUCER tapes require several considerations beyond the +previous simple formats. The spectra actually consist of +many spectra having lengths of 4096 but slightly different +spectral sampling. Thus, the reader can create many small +independent spectra, or interpolate the data onto a common +spectral scale to create a single large spectrum. +The latter alternative seems to be more generally useful, +unless the interpolation process introduces significant errors. +Probably the initial reader will provide both options. + +A second consideration is the 60 bit word length conversion. +The IRAF images are limited to 32 bit reals on most 32 bit machines. +Some loss of precision and dynamic range will result while reading REDUCER +format data. + +Also, there may be a considerable number (~100) of non-standard header +elements. These can be handled in a normal fashion, and tools +will be provided to extract or modify these elements as needed. +New elements may be added as well. + +.ih +NAME +rreducer -- Convert Reducer format tape to IRAF data files +.ih +USAGE +rreducer [source, filename, files] +.ih +DESCRIPTION +REDUCER format data is read from the specified source. +The header may be printed on the standard output either in short form +consisting of the 80 character ID field, or a long form containing some +selection (to be agreed upon) of the many header elements. + +Either a single long spectrum requiring interpolation +to match the spectral characteristics of the first data block, or +multiple short spectra having individual spectral parameters can +be specified with the hidden parameter, interp. +Interpolation is performed via a fifth order polynomial. + +Subsets of the spectrum can be selected with the blocks string +parameter. This specifies which blocks in the file are to be extracted. + +.ih +PARAMETERS +.ls 4 reducer_source +The data source, either magnetic tape or a data stream (e.g. disk +file). See the definition of fits_source above for a description +of how this parameter interacts with the files parameter. +.le +.ls 4 filename +The filename which will contain the data. +See the definition of this parameter under FITS. +If no name is given, the default of 'reducer' will be used. +.le +.ls 4 files +The files to be read from tape are given by the files string. See +the description of this parameter under FITS. +.le +.ls 4 print_header +If this switch is set header information will be printed on the +standard output. (default = yes) +.le +.ls 4 short_header +If this switch is set only the filename and the first 60 characters +of the 80 character ID field will be printed if the print_header +switch is also set. If set to no, the long form of the header +will be printed, containing selected elements of the 100 word +header record. (default = yes) +.le +.ls 4 make_image +See the definition of this parameter under FITS. +.le +.ls 4 interp +If this switch is set, a single long spectrum is produced. If +set to no, multiple spectra will be generated, one for each +header-data block. The resulting filenames will have suffixes +of '.1' , '.2' ... '.n'. For example, if the given filename is +fts and the tape file is 2, the resulting spectrum will be +fts2 if interp is set to yes, but will be fts2.1, fts2.2, and +fts2.3 if there are 3 header-data block sets and interp is set +to no. (default = yes). +.le +.ls 4 blocks +This string parameter allows selected extraction of the +specified header-block sets, rather than the entire spectrum. +Thus subsets of the spectrum may be extracted. The parameter +specifies the starting block and ending block within a tape file. +If an end-of-file is found prior to exhaustion of the +specification, reading is terminated. +For example, the string '12 19' specifies that the eight sets +starting with the twelfth block are to be extracted to +form the spectrum. (default = '1 32767', or all) +.le + + +.sh +PDS + +Tapes from the new PDS 11/23 system will be either FITS or +old format PDS 9 track tapes. This reader will accept the +old format tapes which are based on the PDP 8 character set +and either 10 or 12 bit format. + +.ih +NAME +rpds -- Convert a PDS format tape to IRAF data files +.ih +USAGE +rpds [source, filename, files] +.ih +DESCRIPTION +PDS format data is read from the specified source. The header +may be printed on the standard output either in short form +consisting of the 40 character ID field, filename, and size, +or in long form including raster parameters and origin. + +Because PDS data is limited to no more than 12 bit data, the output image +will be short integers if the number of lines ("scans") implies +two dimensional data. If one dimensional data is implied, the +output image will be converted to reals. +.ih +PARAMETERS +.ls 4 pds_source +The data source, either magtape or a data stream. See the definition +of fits_source above for a description of how this parameter interacts +with the files parameter. +.le +.ls 4 filename +If no filename is given, the default of 'pds' will be used. +.le +.ls 4 files +See the definition of this parameter under FITS. +.le +.ls 4 print_header +If this switch is set, header information will be printed on the +standard output. (default = yes). +.le +.ls 4 short_header +If this switch is set, only the filename, size, and the 40 character ID +field will be printed if the print_header switch is also set. +If set to no, the long form of the header will be printed +containing the full information block (delta X, delta Y, scan type, +speed, origin, corner, travel). (default = yes) +.le +.ls 4 make_image +See the definition of this parameter under FITS. (default = yes) +.le +.ls 4 data_type +Specifies the IRAF image file output data type. Normally one +dimensional PDS data (NSCANS=1) will be stored as real and +two dimensional PDS data (NSCANS>1) will be stored as short. +The data type may be specified as s (short), l (long), or r +(real). +.le + + +.sh +TEXT (Read Card-Image) + +Card-image tapes are probably the most portable form of data transport. +Unlike FITS, there is no standard for internally documenting the +contents of the text file. Header information is essentially +lost. This makes card-image data transfer a relatively unattractive +format. + + +.ih +NAME +rtext -- Convert a card-image text file to an IRAF image file. +.ih +USAGE +rtext [source, filename, files, ncols, nlines, label] +.ih +DESCRIPTION +The card-image text file specified by the source parameter is +converted to an IRAF image file. The file is read in a free form +mode (values separated by spaces) converting data along lines (1-ncols) first. +No header information is stored except for the image size and +the label. + +If additional header information is to be stored, the standard +image header utility must be used. + +Pixel values exactly equal to some constant will be assumed to be blanks +if the blank switch is set to yes. The flag value for blanks can be +set with the blank_value parameter. + +.ih +PARAMETERS +.ls 4 text_source +The input data source. See the definition of this parameter under FITS. +.le +.ls 4 filename +The IRAF file which will contain the image data if the make_image +switch is set. If no filename is given, the default of 'text' +will be used. +.le +.ls 4 files +See the definition of this parameter under FITS. +.le +.ls 4 ncols +The number of columns of data which describe the image extent. +.le +.ls 4 nlines +The number of lines (or 'rows') of data which describe the image extent. +For one dimensional spectra, this parameter will be 1. +.le +.ls 4 label +This string parameter becomes the image identification label. +Up to 80 characters may be stored. +.le +.ls 4 print_header +If this switch is set, header information consisting of the filename, +image label, and image size will be printed on the standard output. +(default = yes) +.le +.ls 4 make_image +If this switch is set, an IRAF image will be created. (default = yes) +.le +.ls 4 data_type +The IRAF image may be either s (short), l (long), or r (real). +(default = r) +.le +.ls 4 card_length +The number of columns on the "card" in the card-image file. +(default = 80) +.le +.ls 4 blank_value +The value used to flag blank pixels if the blank switch is set to yes. +(default = -32767) +.le +.ls 4 blank +If this switch is set to yes, any pixel having exactly the value +specified by the parameter blank_value will be flagged as a blank +pixel. If set to no, all pixel values are assumed to be valid. +.le + + +.bp +.sh +TRANSPORT - OUTPUT + +The primary format for take away tapes will eventually be FITS. +Because many facilities currently cannot read FITS format, +the card-image format will also be provided. + +.sh +FITS +.ih +NAME +wfits -- Convert IRAF data files to FITS data format +.ih +USAGE +wfits [destination, filename, files] +.ih +DESCRIPTION +Data is read from the specified filename(s) and written to the +destination, usually a magnetic tape specification. +A short header consisting of the filename, size, and label +may optionally be printed on the standard output. + +The data will be automatically scaled to either 16 or 32 bit integer format +(BITPIX = 16 or 32) depending on the number of bits per pixel in the +image data, unless the bitpix parameter is specified +otherwise. The scaling parameters may be forced to +exactly represent the original data (BSCALE = 1.0, BZERO = 0.0) +by setting the scale switch to no. + +If only the header information is to be copied to the destination, +the write_image parameter can be set to no. If this is the case, +then the NAXIS FITS keyword will be assigned the value of 0; +otherwise the value for +NAXIS will be taken from the IRAF image header. + +Each non-standard header element will be written into the FITS file +in a form to be determined. These elements may be entered as FITS +COMMENT records, or perhaps added to the file as FITS "special +records". + +Other keywords will be written following standard FITS specifications. +A few special cases will be set as follows: + +.ls 4 NAXISn +The NAXIS1, NAXIS2, ... NAXISn values will be taken from the +image header +.le +.ls 4 OBJECT +The first 60 characters of the image label will be used. +.le +.ls 4 BLANK +Blank pixels will be written to tape having the IRAF value for +indefinite appropriate to 8, 16, or 32 bit integers. +.le +.ls 4 ORIGIN = 'KPNO IRAF' +.le + +.ih +PARAMETERS +.ls 4 fits_destination +The data destination, usually a magnetic tape, but may be a disk +file or STDOUT. If magtape, +the tape should be specified with a file number of either 1 +or "eot". The file number refers to the file which will be written. +Thus a file number of 2 would overwrite file 2. If the tape already +has data written on it, the safest specification would be "eot". +This forces the tape to be positioned between the double end-of-tape +marks prior to writing. +.le +.ls 4 filename +The IRAF filename providing the root for the source name. The files +string, if given, will be used as the suffix for the file names +to be written to tape. For example, if the filename is given as +"image", and the files string is "1 -5", then files image1, image2, +image3, image4, and image5 will be written to the destination +in FITS format. If the files string is empty, only the specified +filename will be converted. +.le +.ls 4 files +See the definition of this parameter under the FITS reader. +.le +.ls 4 print_header +If this switch is set, a short header will be printed on the +standard output for each image converted. (default = yes) +.le +.ls 4 write_image +If this switch is set to no, only header information will be +written to the destination, but no image data. +By using this parameter, +one can generate a FITS tape containing header information only +and may be used as a means for examining the IRAF image header +or for generating a table of contents on a tape prior to writing +the data. (default = yes) +.le +.ls 4 bitpix +This parameter must be either 8, 16, or 32 to specify the +allowable FITS pixel sizes. +.le +.ls 4 scale +If this switch parameter is set to no, the FITS scaling +parameters BSCALE and BZERO will be set to 1.0 and 0.0 +respectively. The data will be copied as it appears in the +original data, with possible loss of dynamic range. +Values exceeding the maximum value implied by the bitpix +parameter will be set to the maximum representable value. +(default = yes) +.le + + +.sh +TEXT (Write Card-Image) + +Although this format is easily readable by the destination +machine, there is no real standard for encoding information, +neither the image data itself nor the descriptive parameters. + +.ih +NAME +wtext -- Convert an IRAF image file to a card-image text file +.ih +USAGE +wtext [destination, filename, files] +.ih +DESCRIPTION +Data is read from the specified filename(s) and written to +the destination, usually a magnetic tape. The data will be +blank padded, ASCII in a format consistent with the data type +of the image pixels, (integer or floating point). +A short header description, consisting of the filename +being converted and the image label, may optionally be printed +on the standard output. + +The column length of the "card" may be changed from the default +of 80 using the card_length parameter, and the field width +to be allocated for each data element may be changed from the +default of 10 columns by setting the field_width parameter. + +If the data are integers, the equivalent of the FORTRAN format +I<field_width> will be used; +if the data are reals, the equivalent of the FORTRAN format +1P<n>E<field_width>.3 +will be used, where n is the number of elements which can +be output into one card length. For the default values of +card_length = 80, and field_width = 10, n will be 8. (1P8E10.3). + +Several cards may be written as a single "block" for +improving the efficiency on magtape. Reasonable efficiency (80 percent) +is attained with a blocking factor of 50, but this value +may be modified by changing the parameter blocking_factor. +If the last block is unfilled, it will be truncated to the +minimum number of card images required to flush the data. + +A legitimate value must be defined to represent blank pixels. +The parameter blank_value is used to define this value and +defaults to -32767. + +.ih +PARAMETERS +.ls 4 text_destination +See the definition for fits_destination for a description of this +parameter. +.le +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 print_header +If this switch is set, a short header is printed for each +file converted. (default = yes) +.le +.ls 4 card_length +The number of columns on the "card" to be generated. (default = 80) +.le +.ls 4 field_width +The number of columns on the "card" to be allocated for each pixel value. +(default = 10) +.le +.ls 4 blocking_factor +The number of card images to be written as a single blocked record. +(default = 50) +.le +.ls 4 blank_value +The value to be assigned to blank pixels for the purpose of +representing them on the card image. (default = -32767) +.le +.bp + + +.sh +MATHEMATICAL OPERATORS + +Because spectra are stored as IRAF images, the standard image +calculator utility provides the basic arithmetic services. +For example, to create a spectrum (called spavg) which is the average of two +other spectra (sp1 and sp2), one can enter the command: +.ls 8 cl>imcalc "spavg = (sp1 + sp2) / 2" +.le + +Other arithmetic operations are performed in a similar fashion. +The general form of the command string is +output_image = expression where "expression" may consist of: +.ls 8 1. Spectra or segments of spectra +A segment of a spectrum is specified by the notation spectrum[x1:x2] +where x1 and x2 are pixel indices along the spectrum. For example, +to create a spectrum which is the difference of the first 100 +pixels of two other spectra, the following command would be used: +.ls 16 cl> imcalc "spdiff = sp1[1:100] - sp2[1:100]" +.le +An option to specify wavelength delineated segments may be added +if this appears generally feasible. +.le +.ls 8 2. Numeric constants +.le +.ls 8 3. Data group names +If an operation is performed on a data group, the output +will be a new data group containing spectra which have been +individually treated by the specified calculation. +For example, if JAN28 is a group containing 100 congruent spectra +and response is the instrumental response as a function of +wavelength as determined from a set of standards, then +the after the following command is entered: +.ls 16 cl> imcalc "JAN28X = JAN28 * response" +.le + +a new data group will be generated containing 100 spectra which +have been calibrated for the instrument response. The new spectra will +be given names JAN28X1 through JAN28X100. +.le +.ls 8 4. Intrinsic functions +.ks +The following intrinsic functions are to be provided: + +.nf + abs atan2 cos int min sin + acos ceil cosh log mod sinh + aimag char double log10 nint sqrt + asin complex exp long real tan + atan conjug floor max short tanh +.fi +.ke +.le + +Expression elements are to be +separated by arithmetic and boolean operators (+,-,*,/,**,<,>,<=,=>,==,!,!=). +The boolean operators provide a means to generate masks. + +Rules governing operations on non-congruent spectra are not yet fully defined. +.bp + +.sh +REDUCTION OPERATORS + +Most of the reduction operators discussed in this section are +intended for spectra of the IIDS/IRS class, although they +are sufficiently general to accommodate data obtained with +the CryoCam (either multi-aperture or long-slit mode), Echelle, +Coude Feed, and photographic (PDS) instruments. Some +application to FTS data is also feasible. + +It is intended that many of these operators will never be +directly executed by users, but that they will be driven by +CL command scripts tuned for individual instruments. +In some cases the scripts will be fairly elaborate and extensive +to lead new users through the reduction phase along a reliable +path. + +It will no doubt be necessary to either modify some +of these operators, or create more specific operators for +certain other instruments. These operators should be considered +a sample of what will eventually be available in this package. + +The basic path which most spectroscopic data follows is: + +.ls 4 1. +Coincidence Correction. +.ls +Many detectors can respond to incoming photevents at a limited +rate. Once an event occurs, the detector cannot respond for some +instrument dependent period, or dead-time. If events occur during +this period, they will not be counted. If the event rate +does not greatly exceed the detector limits, the uncounted events +can be corrected for statistically. + +For many detectors, the coincidence correction is a well +determined function and can be applied to the raw data +to produce a reasonably corrected spectrum. +.le +.le +.ls 4 2. +Wavelength linearization. +.ls +Few instruments produce spectra having pixel to pixel wavelength +differences which are constant across the entire spectrum. +For subsequent reduction and analysis purposes, it is +desirable to rectify the spectra. This is done by mapping the spectrum +from the non-linear wavelength coordinate to a linear one. +It is also desirable to provide a means of forcing the mapping +to a grid which is common to many observations, and in some cases, +to observations acquired with other instruments as well. + +The processes required for the mapping are outlined below. + +.le +.ls 4 a. +Manually identify a small number of spectral features having +known wavelengths thereby creating a table of wavelength as +a function of pixel number. +.le +.ls 4 b. +Compute estimated relationship between wavelength and pixel number +.le +.ls 4 c. +Automatically locate many features found in a user definable line list. +Optionally locate additional features from other spectra using an alternate +line list. (This allows spectra from several different sources to be used +for the wavelength calibration, such as arc lamps, night/day sky.) +.le +.ls 4 d. +Compute improved relationship between wavelength and pixel number. +.le +.ls 4 e. +Perform 2.c. and 2.d. for all other spectral entries in the wavelength +calibration data group. +.le +.ls 4 f. +Compute relationship for wavelength as a function of pixel number and time (or +zenith distance, or some other flexure parameter) as deduced from 2.e. +.le +.ls 4 g. +Apply inverse of wavelength function to a data group. This requires +interpolation of the data at pixels having fixed steps in wavelength. +The start wavelength and the step size must be user definable. +The interpolation may be via a polynomial of a user specified order (typically +1 to 5), or a more sophisticated interpolator. The linearization +in wavelength may also be a simple rebinning of the data to exactly preserve +photon statistics. +.le +.le +.ls 4 3. +Field flattening. +.ls +Pixel to pixel sensitivity variations and other small scale +fluctuations are removed by dividing the object spectra by the spectrum of +a continuum source. The latter spectrum should have a very high +signal-to-noise ratio so as not to introduce additional uncertainties +into the data. + +If the spectrum of the continuum source has much low frequency +modulation, +it may be necessary to filter these variations before the division is performed. +Otherwise fluctuations not characteristic +of the instrument response may be introduced, and may be difficult to remove +during the subsequent flux calibration process. +.le +.le +.ls 4 4. +Sky Subtraction +.ls +Except for extremely bright sources, all spectra require that the +spectrum of the night sky be removed. In some cases, sky will +be the dominant contributor to the raw spectrum. +Sky subtraction is a simple subtraction operation and can be +accomplished with the image calculator tools. +.le +.le +.ls 4 5. +Extinction Correction +.ls +The effects of the Earth's atmosphere produce a wavelength dependent +reduction of flux across the spectrum. The extinction function +is approximately known from extensive photometric measurements +obtained at the observatory over a period of many years. But on +any given night this function may deviate from the average, sometimes +significantly. If the spectroscopic observer has acquired the necessary +data, it is possible to solve for the extinction function directly. + +Therefore, it should be possible for the user to either derive the +extinction function, input a user-defined function, or use the +standard average function and subsequently correct spectra for the +effects of the atmosphere as described by that function and the effective +observing airmass. (Note that because exposures may be quite long, the +effective airmass must be calculated as a function +of position on the sky.) +.le +.le +.ls 4 6. +Flux Calibration (Correction for Instrument Response) +.ls +By observing objects having known wavelength dependent flux +distributions, it is possible to determine the sensitivity +variations of the instrument as a function of wavelength. +Usually several standards are observed for each group of data +and these must be averaged together after corrections for +"grey shift" variations (wavelength independent flux reductions +such as those introduced by thin clouds). + +Although the actual flux of the standards is generally known only +for a limited selection of wavelengths, the instrument response +usually varies smoothly between those wavelengths and a smooth +interpolator generally provides satisfactory calibration values +at intermediate wavelengths. + +In some cases, the system sensitivity response may be known +from other observations, and the user will be allowed to directly +enter the sensitivity function. +.le +.le + +The above reduction path is primarily tuned to IIDS/IRS style data. +Other instruments may require additional or alternate steps. +It may be necessary for multiaperture Cryocam spectra, for example, +to undergo an additional hole to hole sensitivity correction +based on the total sky flux through each hole. + +The tasks performing the procedures outlined above will be described +in more detail in the following discussion. + +.sh +COINCIDENCE CORRECTION +.ih +NAME +coin_cor -- Correct specified spectra for photon coincidence +.ih +USAGE +coin_cor [filename, files, destination, dead_time] +.ih +DESCRIPTION +The spectra specified by the root filename and the files parameter +are corrected for photon counting losses due to detector dead-time. +The corrected spectra are written to filenames having the root +specified by the destination. + +The correction, if typical of photomultiplier discriminators, +is usually of the form: + +.br + Co(i) = C(i) exp[C(i) dt], +.br + dt = t/T, +.br + +where Co(i) is the corrected count at pixel i, C(i) is the raw count, +t is the detector/discriminator dead-time, and T is the +exposure time at pixel i. + +Clearly, the correction factor can become extremely large when the +count rate, C(i)/T, is large compared with the dead-time, t. +The above formula cannot be expected to +exactly remove the effects of undetected photo-events when +large corrections are required. + +The exposure time will be read from the image header. +If no value exists, or if the value is less than or equal to +zero, a request from standard input will be issued for this parameter. + +Because each detector may have unique coincidence properties, +this routine may be package dependent. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 destination +The IRAF filename providing the root for the name of the result +spectra. The files parameter, if specified, will be used for the +suffix. If the filename parameter is actually a data group name, +the destination name will be used to create a new data group +containing spectra having IRAF filenames with the destination +group name as a root and a suffix starting with 1 and incremented for +each converted spectrum. +.le +.ls 4 dead_time +The value of this parameter, in seconds, represents the detector +dead-time. +.le +.ls 4 print_header +If this switch is set, a short header will be printed on the +standard output for each spectrum corrected. (default = yes) +.le +.ls 4 exposure +This parameter should be entered into the image header. If not +present or not realistic, a request is made from standard input. +.le + +.sh +WAVELENGTH LINEARIZATION + +A package of routines is required to perform the operations +leading to linearized data. These include: +.ls 4 1. Spectral line list definition and editing facility +.le +.ls 4 2. Manual line identifier using graphics cursor. +.le +.ls 4 3. Automatic line identifier using preliminary identifications +from manual identifier and locating lines from the predefined list. +.le +.ls 4 4. Computation of dispersion relationship as a function of +pixel coordinate and a flexure parameter, probably zenith distance. +.le +.ls 4 5. Linearization of spectra according to dispersion relation. +Correction can be to either a linear or logarithmic dispersion in +the pixel coordinate. +.le + +Perhaps the most critical aspect of determining the dispersion +relation is the algorithm for locating spectral line centers. +A variety of techniques are available, and some testing will +be required before adopting a standard scheme. Probably several +algorithms will be available and switch selectable at the command +level. + +.sh +LINE LIST PREPARATION +.ih +NAME +line_list -- Create a new line list, or modify an existing one +.ih +USAGE +line_list [filename, option] +.ih +DESCRIPTION +The line list specified by the IRAF filename parameter will be +either created, listed, or modified according to the option +given. The IRAF database facility will be used to manage the +line list file. + +Each entry within the list will contain an identification tag (e.g. HeII) +a reference value (e.g. wavelength, frequency, wavenumber), and a weighting +value such as 1.0 or 2.0 to be used later in the least-squares fitting. +An optional descriptive header may be associated with the line list. +(e.g. "HeII arc from 3500 to 11,000A") + +Either the header, entry identifier or value may be changed +if the modify option is specified. Deletion or addition of +entries is also possible with the appropriate option flags +specifications. +.ih +PARAMETERS + +.ls 4 filename +The IRAF filename to be assigned to the line list. The list will +referenced by this name thereafter. +.le +.ls 4 option +This string parameter determines the action of the line list task. +If no option is specified, the default action is to list the +specified line list on the standard output if the line list +exists; if it does not exist, a new line list will be created +with the given name. +.ls 4 = create +The identifications and values for the line list are read from +the standard input on a record by record basis. Each input +record contains data for one line according to the format: +.br +.ls 4 identification value +.le +.le +.ls 4 = header +A descriptive header is read from the standard input. +.le +.ls 4 = list (default) +The line list is listed on the standard output. +.le +.ls 4 = add +Additional entries to the list are read from the standard input. +.le +.ls 4 = delete +The entries defined by the values read from the standard input +are deleted from the line list. The entries deleted will be those +having values nearest the entered value, unless the absolute +difference from the listed value is too large. For example, one +can enter 5015 to delete the helium line at 5015.675, but entering +5014 would result in an error message that no match could be found. +.le +.ls 4 = id +The entries defined by values entered as for delete will be modified. +Input is expected in the format: +.br +approxvalue newidentifier +.le +.ls 4 = value +As for option = id except that the input format contains +the newvalue instead of the newidentifier. +.le +.ls 4 = weight +As for option = id except that the nput format contains the newweight +instead of the newidentifier. +.le +.le + +.sh +MANUAL LINE IDENTIFICATION + +This routine provides the option of manually identifying the locations +of spectral features by either setting a graphics cursor interactively, +or by entering a list of feature positions. + +The primary uses for this routine are to identify features of known +wavelength in preparation for a dispersion solution, and also to +identify features in linearized spectra for velocity measurements. + +.ih +NAME +mlinid -- Manually identify line features in a spectrum +.ih +USAGE +mlinid [filename, files] +.ih +DESCRIPTION +A list file is created for each of +the spectra specified by the IRAF filename parameter and files string +containing the locations of spectral features and their associated +reference value (e.g. wavelength, frequency, wavenumber). +If invoked as an interactive task from a graphics terminal, +the spectra will be displayed and cursor input requested to ascertain +the approximate position of the feature. An improved position will +be obtained via one of the line centering algorithms, and +a request will be made for the reference value of the feature. +The requests continue until EOF is detected. +The name of the created list file is added to the spectral image +header. + +Positions of features are given in the coordinate system defined +by the standard image header entries CRPIX and CDELT +defining the reference pixel and the +pixel to pixel distance. For raw spectra these values simply define +the pixel position of the feature. For dispersion corrected spectra +these values define the position of the feature in wavelength units. + +If invoked as a background task, or from a non-graphics terminal, +additional requests for the cursor x-coordinate and intensity +will be made from the standard input. + +The procedure is repeated for all specified spectra. + +Because the dispersion solution may be a function of an additional +instrument dependent parameter (e.g. zenith distance), +the driving package script can indicate the header entry to be +used as the second parameter. Values for this parameter, if present, +will be written to the output list file. +.ih +PARAMETERS + +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 cur (x,y) +This is a list structured parameter of type "graphics cursor". +The list contains the approximate values of the pixel +coordinate for the spectral features to be identified +and the intensity value of the continuum at the feature. If the +task is invoked from a graphics terminal in an interactive mode, +values for this parameter will be read from the terminal's +graphics cursor. +.le +.ls 4 value +This is a list structured parameter containing the reference values +for the spectral features to be identified. If the task is invoked in +an interactive mode, the user will be prompted for these values. +.le +.ls 4 center_option +This string parameter controls which algorithm is to be used during +the improved centering phase of the process. (default = cg) +.ls 4 = cg +This specifies a center of gravity algorithm defined as the +first moment of the intensity above the continuum level +across the spectral feature. +The integrals are evaluated using the trapezoidal rule and +the intensity will be weighted by the square root of the intensity +if the switch parameter cgweight is set to yes. The integral +is evaluated from the approximate position defined by x cursor position +plus and minus the number of pixels specified by the parameter +cgextent. +.ls 4 cgweight +This switch defines whether a weighted moment is used in the +center of gravity centering algorithm. (default = yes) +.le +.ls 4 cgextent +This integer parameter defines the limits of the integrals in the +center of gravity centering algorithm. The integral extends from +the approximate position minus the extent to the approximate position +plus the extent in units of pixels. (default = 5). +.le +.le +.ls 4 = parabola +This specifies that the centering algorithm is to be a parabolic +fit to the central 3 pixels. The improved center is taken as the +center of the parabola. The central 3 pixels are defined as the +most extreme local pixel plus and minus one pixel. The most extreme +local pixel is that pixel nearest the approximate center having the +greatest deviation from the local average value of the spectrum. The +extent of "local" is taken as plus and minus the parameter parextent. +.ls 4 parextent +This integer parameter defines the extent in units of pixels +of the search for a local extreme pixel. (default = 3) +.le +.le +.ls 4 = gauss +(This algorithm will not be implemented in the initial system release.) +This specifies that the centering algorithm is to be a Gaussian +fit to the region near the approximate center. The fit is +made to a region specified by the parameter gextent. Because +this is a three parameter non-linear least-squares fit +(center, width, peak intensity), it is likely to +be slow. It may also produce poor results with noisy data +although centering on high signal to noise data should be +excellent. +.ls 4 gextent +This integer parameter specifies the extent in pixels of the Gaussian fit. +It may be necessary to include a significant region of continuum. +(default = 9) +.le +.le +.ls 4 = none +If this option is chosen, no improvement to the approximate center +will be made. This may be useful for asymmetric and weak features +where the other techniques can be systematically incorrect. +.le +.ls 4 second_order +This string parameter defines the name of the image header entry to be +used as the second order correction parameter in the dispersion +solution. Values for this parameter, if present, are read from the image header +and written to the output list file. Examples of values are zenith_distance, +sidereal_time, instr_temp. (default = none) +.le + +.sh +AUTOMATIC LINE IDENTIFICATION + +This task allows a user to locate a set of spectral features defined +in a previously prepared list. + +.ih +NAME +alinid -- Automatically locate spectral features in a spectrum +.ih +USAGE +alinid [filename, files, mfilename, mfiles, list] +.ih +DESCRIPTION +A list file is created for each of the spectra specified by the +IRAF filename and files parameters. The file will contain +the positions of the features defined in the line list file +specified by the list parameter. The name of the list file +will be added to the spectral image header. + +A preliminary estimate of the +relationship of feature position as a function of feature +wavelength is obtained from the list file(s) created by the +task MLINID and defined by the parameters mfilename and mfiles. +A single preliminary estimate may be applied to a number of +spectra by specifying a null mfiles string. Otherwise, +a one-to-one correspondence is assumed between preliminary +list files and spectra. If the entry for mfilename is also null, +the linear dispersion relation for the pixel coordinate contained +in the image header will be used. This provides the option +of locating features in linearized spectra. + +The initial position estimate is improved using one of the centering +algorithms defined by the center_option parameter and then +written to a list file. Also written to the list file will be +the feature's reference value (e.g. wavelength), weight, +identification string, and the acceptability of the line. +Acceptibility is noted as either accepted, set, deleted, or not +found (see below). + +If the task is invoked from a graphics terminal as an interactive +task, the interact switches may be set to yes. +Then each spectrum will +be displayed in segments expanded about each feature with the +automatically defined center marked. The user can then accept +the given position, mark a new center, or declare the line +unacceptable. + +If the display switch is set, the spectrum is displayed +and the features marked. + +If the task is invoked as a background task, or if the +user terminal is non-graphics, then the display and interact +switches cannot assume values of yes. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS +.le +.ls 4 files +See the definition of this parameter under RFITS +.le +.ls 4 mfilename +The root for the spectra names used to define the preliminary +relationship between spectral feature coordinate and reference +value. The mfiles string parameter is used to define the +suffix of the spectral name. If this parameter is null, the +preliminary relationship is assumed to be linear and defined +by the standard image header entries CRPIX and CDELT. +.le +.ls 4 mfiles +This string parameter serves the same purpose for mfilename +as the files parameter serves for filename. Note that if this +parameter is null, the single spectrum defined by mfilename +is used to define the preliminary relationship for all +spectra defined by filename and files. +.le +.ls 4 list +This parameter specifies the IRAF file name containing the +spectral line list to be scanned for features. (See the +task LINE_LIST) +.le +.ls 4 interact +If this switch is set to yes and the task is invoked interactively +from a graphics terminal, the spectrum will be displayed on the +terminal. Each feature will be marked with its computed center +and the user can type one of the following single keystrokes: +.ls 4 a +to accept the displayed position +.le +.ls 4 s +to set the cursor to the desired position +.le +.ls 4 d +to delete the displayed feature from the line list during this +invocation of the task +.le +.ls 4 b +to reset the operational mode to a "batch" environment where +no display or interaction is desired +.le +.ls 4 p +to reset the operational mode to a "passive" environment where +the spectra are displayed and marked, but no interaction is desired +.le +.le +.ls 4 display +If this switch is set to yes, and the task is invoked from +a graphics terminal, the spectrum will be displayed and the +identified lines marked for the user's inspection. No +interaction is allowed unless the interact switch is also set to yes. +(default = yes) +.le +.ls 4 center_option +See the description of this parameter under MLINID. +.le +.ls 4 second_order +See the description of this parameter under MLINID. +.le + +.sh +DISPERSION SOLUTION + +After several spectral features have been identified, either +manually with MLINID or automatically with ALINID, the relationship +between feature reference value and pixel coordinate can be calculated. +The dispersion relation may require a second order correction +to account for variations as a function of some additional +parameter, such as zenith distance or time of day. + +.ih +NAME +disp_sol -- Determine the dispersion relation for a set of spectra. +.ih +USAGE +disp_sol [filename, files, order, global] +.ih +DESCRIPTION +The list files containing the postions and reference values for +features in the specified spectra are combined to solve for the +dispersion relation by a polynomial least-squares fit to the lists. +The solution can include a second order +correction parameter which is also contained in the list file. + +The solution takes the form of a polynomial in the pixel +coordinate having the specified order. The second order +is also fit by a polynomial. (The choice of a polynomial +applies to the initial release. Additional forms, selectable by +parameter, of the solution may be available later.) +The polynomial coefficients are stored in the spectral image header +if the store_coeffs switch is set to yes and the spectrum does not already +contain a solution. If a solution already exists, the user is +asked for confirmation to overwrite the solution, unless the overwrite +switch is set to yes. + +If filename is the name of a data group, all line list files for +spectra in that data group are combined into the solution. + +If invoked as an interactive task from a graphics terminal, +a representation of the solution will be displayed and the user +will be allowed to alter the weights of the line entries. +If invoked from a non-graphics terminal, the representation +will be in a tabular format (also available at a graphics terminal) +for inspection and alteration. If invoked as a background task, +an attempt will be made to reject discrepant points. + +The solution is made using all available line lists combined +into a single data set if the global switch is set to yes. +If global is set to no, each spectrum is treated as an +independent data set. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 order +The order of the polynomial for a least-squares fit to the +dispersion solution. If the specified order exceeds the number +of free parameters, the order will be reset to the maximum +allowable. (default = 1 --> linear). +.le +.ls 4 global +This switch determines if the data from all the specified spectra are +to be treated as a single large data set. This is appropriate if the +data represent a single congruent "setup". But if the data represent +several different configurations, such as for multiaperture data, +the global switch should be set to no. Note that if global is no, then +no second order parameter solution is possible. +.le +.ls second_order +This parameter specifies the order for the fit to the second +order parameter. The limit described for the order parameter +applies. (default = 0 --> no second parameter solution). +.le +.ls 4 interact +If this switch is set to yes and the task is invoked interactively +from a graphics terminal, the residuals of the solution will be displayed +on the terminal. The user can type one of the following keystrokes: +.ls 4 a +to accept the current solution. The parameters of the fit +are written into the headers of the spectra contributing to the fit. +.le +.ls 4 e +to exit without saving the solution +.le +.ls 4 w +to reset the weight of the point near the cursor positioned by the user. +The user is then prompted for the new weight which may be set to zero +to delete the point from the solution. +.le +.ls 4 t +to display the solution parameters in tabular form +.le +.ls 4 o +to specify a new order for the solution +.le +.ls 4 s +to specify a new order for the second order parameter solution +.le +.ls 4 b +to revert to batch mode to process the remainder of the solutions. +This is only meaningful if the global switch is set to no. +.le +.ls 4 p +to revert to passive mode as for ALINID. This is only meaningful +if the global switch is set to no +.le +.le +.ls 4 store_coeffs +If this switch is set to yes, the dispersion solution polynomial +coefficients will be written into the image header as special +header elements. Otherwise, the solution is discarded. (default = yes) +.le +.ls 4 overwrite +If this switch is set to yes, any existing dispersion solution contained +in the image header will be overwritten without any request for confirmation +from the user. If set to no, the user is asked if overwriting of the solution +is acceptable. If no prior solution exists, this switch has no meaning. +(default = no) +.le + +.sh +DISPERSION CORRECTION + +After the dispersion relation has been determined, the spectra +are usually re-binned to create spectra having a linear +relationship with wavelength. Although this is not always +done, nor is it always desirable, subsequent processing +is often simplified greatly by having to deal with only +linearized data. + +.ih +NAME +disp_cor -- Linearize spectra having dispersion relation coefficients +.ih +USAGE +disp_cor [filename, files, destination, option] +.ih +DESCRIPTION +The spectra specified by the root filename and the files parameter +are corrected for deviations from a linear wavelength relationship. +The corrected spectra are written to filenames having the root +specified by the destination parameter. + +The correction is performed by solving for the inverse relationship +of pixel number as a function of equal increments in the wavelength. +The new starting wavelength and increment are optionally specified +by the parameters start and increment. If not specified, the current +wavelength of the first pixel will be taken as the starting wavelength +and the increment will be chosen to exactly fill the length of the +current spectrum. The spectrum will be padded with INDEF on either +end if the specified parameters request a larger spectral window than +actually exists. + +The actual re-binning can be performed using one of several algorithms. +The most efficient minimally smoothing algorithm to be available in the +initial release is the fifth order polynomial interpolation. +The most efficient count preserving algorithm is the simple partial-pixel +summer. + +The interpolation can be either linear in wavelength or in the logarithm +of wavelength. The latter is useful for subsequent radial velocity +analyses. The choice is specified by the logarithm switch. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS +.le +.ls 4 destination +See the definition of this parameter under COIN_COR. +.le +.ls 4 option +This parameter specifies the algorithm to be used for the +re-binning operation. The initial release will contain the +following options: +.ls 4 = linear +to use a linear interpolation +.le +.ls 4 = poly +to use a fifth order polynomial +.le +.ls 4 = sinc +to use a sinc function interpolator +.le +.ls 4 = sum +to use partial pixel summation +.le +.le +.ls 4 start +This parameter specifies the wavelength at which the corrected +spectrum is to begin. The wavelength of the first pixel will +be assigned this value. This parameter, combined with the increment +parameter, allows data taken on different nights +or with different instruments to be forced to be congruent. +(default = value at first pixel) +.le +.ls 4 increment +This parameter specifies the pixel to pixel wavelength (or logarithm of +wavelength) increment +that is to be used during the linearization process. +(default = [wavelength at last pixel minus wavelength at first pixel] +divided by [number of points in spectrum - 1]) +.le +.ls 4 logarithm +If this switch is set to yes, the linearization occurs with equal +increments in the logarithm of wavelength. Otherwise, equal +increments of wavelength are used. (default = no) +.le +.ls 4 print_header +See the definition of this parameter for COIN_COR. +.le + +.sh +FIELD FLATTENING + +Most detectors exhibit variations in sensitivity across the field +of interest. These are removed by dividing all observations by +the spectrum of a smooth continuous source, such as an incandescant +lamp. In order that these lamps, which usually have a low color +temperature, produce sufficient energy in the blue and ultraviolet, +they are often enclosed in a quartz rather than a glass bulb. +Thus, the field flattening operation is often referred to as +"quartz division". + +The operation is of marginal value unless the continuum source is +observed properly. First, a very high signal-to-noise ratio per +pixel is required. For certain detectors and applications this +may not be possible in a reasonable amount of time. Second, the +continuum source should not have any significant variations +across small regions of the spectrum (high frequency "bumps"). +Otherwise the division will add these variations into the spectrum. + +There are basically two aspects to flat fielding spectra. The first +is the removal of pixel-to-pixel sensitivity variations. The second +is a more global pattern due to non-uniform iillumination and +spatial and wavelength sensitivity variations across the detector. + +The very high frequency pixel-to-pixel variations are easily handled +by a straightforward division of the observations by the continuum +spectrum. + +The second problem is usually postponed in one-dimensional data +reductions and included in the +solution for the system sensitivity by observing standard stars. +This aspect of the problem is adequately handled in this fashion +and no special operators are provided in this package. + +If the continuum source exhibits large low frequency variations +across the spectrum, it may be desirable to filter these. +This is most easily done by fitting a moderately high order +polynomial through the spectrum, and then dividing the polynomial +representation into the original continuum spectrum. The result +is a flat spectrum having an average value of unity and +containing only the pixel-to-pixel sensitivity variations. + +Finally, it should be noted that the field flattening operation +is most properly performed prior to the wavelength linearization +of the spectra because the linearization process can smooth +pixel-to-pixel variations. + +Flat fielding consists of two logical operations. The first +is the solution for a continuum spectrum with the low frequency +variations removed (CR_FLAT). It is assumed that multiple observations +of the continuum source have been already averaged (using the +image calculator program, for example). + +The second operation is the actual field flattening of the object +spectra (FLT_FIELD). + +.ih +NAME +cr_flat -- Create a flat field spectrum +.ih +USAGE +cr_flat [filename, destination] +.ih +DESCRIPTION +The continuum spectrum specified by filename is corrected for +low frequency spectral variations. Several algorithms may be +available. The initial release will contain only a polynomial +fitting technique. A fourier filtering algorithm may be added +at a later date. + +The spectrum is fit by a polynomial in the pixel coordinate +and the polynomial is divided into the original spectrum. +Discrepant pixels may be rejected and the solution re-iterated. + +If invoked as an interactive task from a graphics terminal, the +resultant spectrum is displayed and the user may alter the +solution parameters if the interact switch is set to yes. +If invoked from a non-graphics terminal, sufficient information +concerning the fit is written to the terminal to allow +the user to judge the quality of the fit and then alter the +solution parameters. + +If invoked as a background task, or if the interact switch is set +to no, default parameters will be assumed. + +The parameters of the fit are added to the image header for +the corrected spectra. +.ih +PARAMETERS +.ls 4 filename +The IRAF filename containing the spectrum of the continuum +source. If this is a data group name, then all spectra +in the group will be corrected. +.le +.ls 4 destination +The IRAF filename into which the resultant corrected +spectrum is written. If the source filename is a data group, +then the destination will be a new data group containing +the names of the corrected spectra. The names will be +assigned using the destination as a root name, and the +ordinal of the spectrum in the list as a suffix. +.le +.ls 4 option +This string parameter specifies the algorithm to be used +in the correction process. Currently only option = poly +is recognized. +.le +.ls 4 order +This integer parameter specifies the initial order of the +polynomial fit. (default = 8) +.le +.ls 4 reject +This parameter specifies the number of standard deviations +beyond which pixels are to be rejected. If the task +is interactive, pixel rejection is performed only on command. +If invoked as a background task, rejection is iterated +until no further pixels are rejected, or until the iteration +count has been attained (see parameter niter). (default = 2.2) +.le +.ls 4 niter +This integer parameter specifies the number of iterations +to be performed in background mode. It may be set to 0 to +specify no pixel rejection. (default = 2). +.le +.ls 4 interact +If this switch is set to yes and the task is invoked as +an interactive task, the user can alter the fit parameters +order, reject, and niter. If at a graphics terminal, the resultant +spectrum is displayed and the user can command the operation +with the following single keystrokes: +.ls 4 a +to accept the solution +.le +.ls 4 o +to change the order of the fit +.le +.ls 4 r +to reset the reject parameter +.le +.ls 4 n +to reset the niter parameter +.le +.ls 4 b +to reset the operational mode to a batch environment +.le +.ls 4 p +to reset the operational mode to a passive environment +.le +.le + +If at a non-graphics terminal, the fit parameters are +written to the terminal so that the user may assess the quality +of the fit. A request for one of the interactive commands +is then issued and the user may proceed as if on a graphics +terminal. +.le + +.ih +NAME +flt_field -- Correct spectra for pixel-to-pixel variations +.ih +USAGE +flt_field [filename, files, flatname, destination] +.ih +DESCRIPTION +The spectra specified by the IRAF filename parameter and the files +string are divided by the flat field spectra specified by +the parameter flatname. If filename and flatname are data group names, +the division is performed on a one-for-one basis. + +This operation is little more than a simple division. An image +header entry is added indicating that flattening by the +appropriate spectrum has been performed. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 flatname +This string parameter sepcifies the name of the flat field +spectrum, or spectra if a data group name. +It is not necessary that the flat field spectra be corrected +for low frequency spectral variations. +It is required that the spectra be congruent with the spectra +to be flattened; that is, all spectra must have the same +length, reference pixel, and pixel-to-pixel increment. +.le +.ls 4 destination +See the definition of this parameter under COIN_COR. +.le +.ls 4 print_header +See the definition of this parameter under COIN_COR. +.le + +.sh +EXTINCTION CORRECTION/FLUX CALIBRATION + +At each wavelength (lambda) along the spectrum, the observed +flux (fobs) must be corrected for extinction (k) due to the +Earth's atmosphere and the system sensitivity (S) to obtain +a true flux (f) above the atmosphere. +.sp 1 +fobs(lambda) = f(lambda) * exp{-z[k(lambda)+C]} * S(lambda) +.sp 1 +where z is the path through the Earth's atmosphere during the +observation and C is an optional "grey" opacity term. + +For most observations, the standard extinction function is adequate, +but occasionally the additive term is beneficial. In rare cases, +the observer has acquired sufficient high quality data to +determine the extinction function across the spectral region +of interest. And in other cases, the user may have a priori +knowledge of the extinction function. + +Observations of standard stars are used to determine +either the additive constant or a new extinction function, +and the system sensitivity. +The two operations, determining the extinction parameters +and the system sensitivity curve, are therefore intimately +related. + +The process breaks down into four basic operations: +.ls 4 1. +Define the standard stars and their observations. (STD_STAR) +.le +.ls 4 2. +Define the extinction solution option and solve for the extinction +additive term or complete function if necessary. (CREXT_FUNC) +.le +.ls 4 3. +Determine the system sensitivity function. (CRSENS_FUNC) +.le +.ls 4 4. +Remove the effects of the extinction and the system sensitivity +from the observations. (EXT_COR, SENS_COR) +.le + +These will be described below in more detail. + +.ih +NAME +std_star -- Define the standard stars to be used for solving the extinction and +system sensitivity functions. +.ih +USAGE +std_star [fnamelist, filelist, namelist, std_file] +.ih +DESCRIPTION +The spectra defined by the list of filenames and associated files +contained in the string list parameters fnamelist and filelist +are compared with the standard flux measurements for the stars +listed in the string list parameter namelist. The resultant +table of ratios as a function of wavelength are saved in the +IRAF file specified by the std_file parameter. + +All spectra must be wavelength linearized. The star names given +in namelist must be in a form similar to that in the IIDS Reduction +manual. If a star name cannot be matched to the standards contained +in a calibration file, the user is prompted for additional +information. The calibration file containing the list of reference +flux values is specified by the calib_file parameter. +.ih +PARAMETERS +.ls 4 fnamelist +This is a list structured parameter containing the IRAF filenames +associated with the spectra for each of the standard stars contained +in the list of starnames defined by the list structured parameter +namelist. Both these parameters must have the same number of elements. +The filename specifications are defined as in RFITS. +.le +.ls 4 fileslist +This is also a list structured parameter having the same number of +elements as fnamelist although some may be null. +The entries are defined as in RFITS. +.le +.ls 4 namelist +This is also a list structured parameter having the same number +of elements as fnamelist. All elements must exist and have a +form to be decided on, but probably similar to that given in the IIDS +Reduction manual, page 36. For example, a typical star name might +be BD+8 2015, or HILTNER 102. Case will not be significant. +.le +.ls 4 std_file +This string parameter defines the IRAF filename in which the +results from the standard star observations are stored. +This file will be used to contain further calibration information +such as the extinction and sensitivity function for the +current set of observations. +.le +.ls 4 calib_file +This string parameter defines which of several calibration +data files are to be accessed for the comparison of the +observational data to the standard fluxes. Separate tools +to examine, modify, and create these files are available +in the utilities package. (default = onedspec$iids.cal) +.le +.ls 4 print_header +If this parameter is set to yes, an informative header +is listed on the standard output as the standard stars are processed +(default = yes). +.le + +.ih +NAME +crext_func -- Create an extinction function from a set of observations +.ih +USAGE +crext_func [std_file, option] +.ih +DESCRIPTION +The user may specify via the option parameter which of the four +extinction solutions is to be used. These are: +.sp 1 +.ls 4 1. +Adopt standard extinction function (option = standard). +.le +.ls 4 2. +Solve for an additive constant (option = additive). +.le +.ls 4 3. +Solve for extinction function (option = new_function). +.le +.ls 4 4. +Input a tabular extinction function consisting of extinction +values at specified wavelengths (option = input). +.le +.sp 1 +If the first or last options are chosen, the std_file may be empty. +If the second option is chosen, several observations at +differing air masses must be included in the file specified by std_file. +If the third option is chosen, +at least two standard stars must be included in the list of observations. + +The derived extinction function is added to the IRAF file specified +by the std_file parameter by creating a new spectrum containing the +function and adding the spectrum name to the std_file. +The new spectrum will adopt a name having a root from the +name std_file and a suffix of ".ext". The spectrum is created by +a spline interpolation through the extinction values. + +If invoked as an interactive task from a graphics terminal, the +derived extinction function is displayed. The user may interactively +alter the derived extinction values using the graphics cursor. +If invoked from a non-graphics terminal, the user may alter the +values by specifying the wavelength and new extinction value +from the standard input. Interaction may be suppressed by setting the +interact switch to no. + +.ih +PARAMETERS +.ls 4 std_file +See the definition of this parameter under STD_STAR. +.le +.ls 4 option +This parameter specifies which aspects of the extinction solution +are to be computed. See description section for CREXT_FUNC. +.le +.ls 4 interact +If this switch is set the user may alter the derived extinction values. +If invoked from a graphics terminal and interact is set to yes, the +following single keystroke commands may be typed: +.ls 4 a +to accept the current solution +.le +.ls 4 m +to modify the extinction value at the cursor wavelength position (cursor-x) +to the cursor extinction value position (cursor-y). +.le +.ls 4 i +to insert a new wavelength-extinction value pair at the current +crosshair position. +.le +.ls 4 d +to delete the wavelength-extinction value pair at the current +cursor wavelength position. +.le +.le + +.ih +NAME +crsens_func -- Create system sensitivity function. +.ih +USAGE +crsens_func [std_file, option] +.ih +DESCRIPTION +The standard star data and extinction function contained in the +IRAF file specified by the std_file parameter are used to +compute the system sensitivity as a function of wavelength. +The derived function is written to the file specified by +std_file. + +There must be at least one standard star observation contained +in the std_file, unless the parameter option = input. +This allows the user to enter any function in the +form of wavelength-sensitivity pairs. + +If option = shift, a "grey" shift is applied to all observations +necessary to bring relatively faint values up to the brightest +to account for possible cloud variations. + +If invoked as an interactive task from a graphics terminal, +and the interact switch is set to yes, the sensitivity values +from each standard are plotted with any "grey" shift correction +added. The user may delete or add new points as desired using +the cursor. If invoked from a non-graphics terminal, a tabular +list of the solution is presented and additions or deletions +may be entered through the standard input. + +The final function written to the std_file is simply the name of a new +spectrum derived from a spline fit to the sensitivity +if the spline switch is set to yes. If spline = no, a linear +interpolation between sensitivity points will be used. +The sensitivity spectrum name will be taken from the file name +given to std_file and with the suffix ".sen". +.ih +PARAMETERS +.ls 4 std_file +See the definition of this parameter under STD_STAR. +.le +.ls 4 option +This parameter can assume the following string values: +.ls 4 = input +to indicate that the sensitivity function is to be entered as +wavelength-sensitivity pairs. +.le +.ls 4 = shift +to force a "grey" shift between all standard star spectra to +account for clouds. This is actually a multiplicative factor +across each of the affected spectra. +.le +.le +.ls 4 spline +This switch parameter determines if a spline fit is to be made +between the sensitivity points (spline = yes), or a linear +fit (spline = no). (default = yes). +.le +.ls 4 interact +If invoked as an interactive task, the user may alter the sensitivity +function values. If at a graphics terminal, the sensitivity curve +is displayed first for each star in the solution. The user may +add or delete values for any or all stars at a given wavelength. +Subsequently, the derived average curve is displayed and the user +may further modify the solution. The following keystrokes are +available from the graphics terminal: +.ls 4 a +to accept the current displayed data (solution). +.le +.ls 4 d +to delete the value at the cross-hairs. If several values +are very close together, an expanded display is presented. +.le +.ls 4 i +to insert the sensitivity value of the y-cursor at the wavelength position. +.le +.ls 4 c +to "create" new sensitivity values at the wavelength position of the +x-cursor. Normally sensitivity values are computed only at pre-defined +wavelengths specified in the calib_file. Additional values +may be computed by interpolation of the standard star fluxes +from the calib_file. The name of the calib_file and the spectra +in the current solution are taken from the std_file. +.le +.le + +.ih +NAME +ext_cor -- Extinction correct specified spectra +.ih +USAGE +ext_cor [filename, files, std_file, destination] +.ih +DESCRIPTION +The spectra specified by the filename and files parameters +are corrected for atmospheric extinction according to the +extinction correction function pointed to by the function +name in std_file. The resulting new spectra are created with the +root of the destination parameter and having suffixes of +1 through n corresponding to the n spectra corrected. +If filename is a data group name, a new data group will be created having +the name given by the destination parameter. + +The correction has the form: +.sp 1 +f(lambda) = fobs(lambda) / 10**{-z[a(lambda) + C]} +.sp 1 +where: +.ls 4 f(lambda) = the flux at wavelength lambda above the Earth's atmosphere. +.le +.ls 4 fobs(lambda) = the flux observed through the atmosphere +.le +.ls 4 z = the path length through the atmosphere is units of air masses +(= 1 at the zenith) +.le +.ls 4 a(lambda) = the extinction function at wavelength lambda +in magnitudes per airmass. +.le +.ls 4 C = the additive constant, if any, in magnitudes per airmass. +.le +.sp 1 +For each spectrum, the zenith distance must be present in the image header. +This is assumed to be correct for the beginning of the observation. +For short exposures, this is adequate for the correction, but for +long exposures, an effective air mass must be calculated over the +integration. To do so requires knowledge of the altitude and azimuth +of the telescope (or equivalantly RA, Dec, and sidereal time). +If these are not present, the approximate air mass calculation will be used +based solely on the available zenith distance. If the zenith distance +is not present, user input is requested. + +The air mass is calculated according to the following equation for a given +telescope position (based on Allen p.125,133): +.sp 1 +z = sqrt{[q sin (alt)]**2 + 2q + 1} - q sin(alt) +.sp 1 +where: +.ls 4 q += atmospheric scale height (approx = 750). +.le +.ls 4 alt += telescope altitude +.le +.sp 1 +If the telescope traverses a significant distance in elevation during +the integration, an effective correction can be computed as: +.sp 1 +f(lambda)a = f(lambda)obs*T / integral{10**[-z(t)(a(lambda) + c)]}dt +.sp 1 +where the integral is over the integration time, T. + +This expression can then be evaluated numerically at each wavelength. +Because this is a time-consuming operation, the switch effective_cor +can be set to no and then a simplified correction scheme will be used. +This will be to compute a midpoint airmass if sufficient information +is available, or simply to use the header airmass otherwise. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 std_file +See the definition of this parameter under STD_STAR. +.le +.ls 4 destination +See the definition of this parameter under COIN_COR. +.le +.ls 4 effective_cor +If this switch is set to yes, the procedure to compute an effective +corrective term averaged over the integration time will be used. +Although a slow process, this method is more accurate than +simply using the correction at any given time of the integration +such as the midpoint. If set to no, a midpoint zenith distance +will be computed and used if sufficient header information +exists. (default = no). +.le +.ls 4 print_header +See the definition of this parameter for COIN_COR. +.le + +.ih +NAME +sens_cor -- Correct the specified spectra for system sensitivity +variations across the spectrum. +.ih +USAGE +sens_cor [filename, files, std_file, destination] +.ih +DESCRIPTION +The spectra specified by the filename and files parameters are +corrected for instrumental sensitivity by the +function pointed to by the spectrum name contained in std_file. +The resulting spectra are stored according to the destination parameter. +Filename may be a data group name. If so, then destination will be +a new data group containing the names of the corrected spectra. + +This correction is a simple vector multiplcation. +.ih +PARAMETERS +.ls 4 filename +See the definition of this parameter under RFITS. +.le +.ls 4 files +See the definition of this parameter under RFITS. +.le +.ls 4 std_file +See the definition of this parameter under STD_STAR. +.le +.ls 4 destination +See the definition of this parameter under COIN_COR. +.le +.ls 4 print_header +See the definition of this parameter under COIN_COR. +.le +.endhelp diff --git a/noao/onedspec/doc/sys/Review.hlp b/noao/onedspec/doc/sys/Review.hlp new file mode 100644 index 00000000..5139f630 --- /dev/null +++ b/noao/onedspec/doc/sys/Review.hlp @@ -0,0 +1,512 @@ +.help onedspec Sep84 "Spectral Reductions" +.ce +\fBOne Dimensional Spectral Reductions\fR +.ce +Analysis and Discussion +.ce +September 4, 1984 +.sp 3 +.nh +Introduction + + The \fBonedspec\fR package is a collection of programs for the reduction +and analysis of one dimensional spectral data. The more general problem of +operations upon one dimensional images or vectors shall be dealt with elsewhere, +primarily in the \fBimages\fR and \fBplot\fR packages. The problems of getting +data in and out of the system are handled by the \fBdataio\fR package, at least +for the standard data formats such as FITS. + +The operators provided in \fBonedspec\fR shall be general purpose and, as far +as possible, independent of the instrument which produced the data. Instrument +dependent reductions tailored for specific instruments will be implemented as +subpackages of the \fBimred\fR (image reductions) package. For example, +the subpackages \fBiids\fR and \fBirs\fR will be provided in \fBimred\fR for +reducing data from the KPNO instruments of the same name. The \fBimred\fR +packages shall call upon the basic operators in \fBonedspec\fR, \fBimages\fR, +and other packages to reduce the data for a specific instrument. + + +.ks +.nf + iids(etc) + imred + imredtools + onedspec + plot + tv + dataio + images + dbms + lists + system + language + +.fi +.ce +Relationship of \fBOnedspec\fR to other IRAF Packages +.ke + + +The relationship of the \fBonedspec\fR packages to other related packages in +the IRAF system is shown above. A program (CL script) in a package at one +level in the hierarchy may only call programs in packages at lower levels. +The system will load packages as necessary if not already loaded by the +user. The user is expected to be familiar with the standard system packages. + +.nh +Basic Functions Required for One-Dimensional Spectral Reductions + + The following classes of functions have been identified (in the preliminary +specifications document for \fBonedspec\fR) as necessary to perform basic one +dimensional spectral reductions. Only a fraction of the functionality +required is specific to the reduction of spectral data and is therefore +provided by the \fBonedspec\fR package itself. + +.ls Transport +Provided by the \fBdataio\fR package, although we do not currently have a +reader for REDUCER format data tapes. Readers for all standard format +tapes are either available or planned. +.le +.ls Mathematical +Standard system functions provided by \fBimages\fR (arithmetic, forward and +inverse FFT, filtering, etc.). +.le +.ls Reduction Operators +The heart of \fBonedspec\fR. Operators are required (at a minimum) for +coincidence correction, dispersion determination and correction, flat +fielding, sky subtraction, extinction correction, and flux calibration. +Operators for flat fielding and sky subtraction are already available elsewhere +in IRAF. Basic continuum fitting and subtraction is possible with existing +software but additional algorithms designed for spectral data are desirable. +.le +.ls Plotting +Standard system functions provided by the \fBplot\fR package. +.le +.ls Utilities +Standard system functions provided by the \fBdbms\fR package. +.le +.ls Artificial Spectra +These functions belong in the \fBartdata\fR package, but it is expected that +prototype operators will be built as part of the initial \fBonedspec\fR +development. +.le + +.nh +Data Structures + + Spectra will be stored as one or two dimensional IRAF images embedded in +database format files. A free format header is associated with each image. +Spectra may be grouped together as lines of a two dimensional image provided +all can share the same header, but more commonly each image will contain a +single spectrum. The second image dimension, if used, will contain vectors +directly associated with the images, such as a signal to noise vector. +If the image is two dimensional the spectrum must be the first image line. +The database facilities will allow images to be grouped together in a single +file if desired. + +While most or all \fBonedspec\fR operators will expect a one dimensional +image as input, image sections may be used to operate on vector subsections +of higher dimensioned images if desired. The datatype of an image is +arbitrary, but all pixel data will be single precision real within +\fBonedspec\fR. While the IRAF image format does not impose any restrictions on +the size of an image or image line, not all spectral operators may be usable +on very large images. In general, pointwise and local operations may easily +be performed on images of any size with modest memory requirements, and +most of the \fBonedspec\fR operations appear to fall into this class. + +.nh 2 +The IRAF Database Faciltities + + An understanding of the IRAF database facilities is necessary to visualize +how data will be treated by operators in \fBonedspec\fR and other packages. +The database facilities will be used not just for image storage but also for +program intercommunication, program output, and the storage of large +astronomical catalogs (e.g. the SAO catalog). Access to both small and +large databases will be quite efficient; achieving this requires little +innovation since database technology is already highly developed. We begin by +defining some important terms. + +.ls +.ls DBIO +The database i/o package, used by compiled programs to access a database. +.le +.ls DBMS +The database management package, a CL level package used by the user to +inspect, analyze, and manipulate the contents of a database. +.le +.ls database +A set of one or more "relations" or tables (DBIO is a conventional relational +database). A convenient way to think of an IRAF database is as a directory. +The relations appear as distinct files in the directory. +.le +.ls relation +A relation is a set of \fBrecords\fR. Each record consists of a set of +\fBfields\fR, each characterized by a name and a datatype. All the records +in a relation have the same set of fields. Perhaps the easiest way to +visualize a relation is as a \fBtable\fR. The rows and columns of the table +correspond to the records and fields of the relation. +.le +.ls field +A field of a record is characterized by an alphanumeric name, datatype, and +size. Fields may be one dimensional arrays of variable size. Fields may be +added to a relation dynamically at run time. When a new field is added to +a relation it is added to all records in the relation, but the value of the +field in a particular record is undefined (and consumes no storage) until +explicitly written into. +.le +.ls key +.br +A function of the values of one or more fields, used to select a subset of +rows from a table. Technically, a valid key will permit selection of any +single row from a table, but we often use the term is a less strict sense. +.le +.le + + +An \fBimage\fR appears in the database as a record. The record is really +just the image header; the pixels are stored external to the database in a +separate file, storing only the name of the pixel storage file in the record +itself (for very small images we are considering storing the pixels directly +in the database file). Note that the record is a simple flat structure; +this simple structure places restrictions on the complexity of objects which +can be stored in the database. + +The records in a relation form a set, not an array. Records are referred to +by a user-defined key. A simple key might be a single field containing a +unique number (like an array index), or a unique name. More complex keys +might involve pattern matching over one or more fields, selection of records +with fields within a certain range of values, and so on. + +From the viewpoint of \fBonedspec\fR, a relation can be considered a +\fBdata group\fR, consisting of a set of \fBspectra\fR. + +.nh 2 +Image Templates + + The user specifies the set of spectra to be operated upon by means of an +image template. Image templates are much like the filename templates commonly +used in operating systems. The most simple template is the filename of +a single data group; this template matches all spectra in the group. If there +is only one spectrum in a file, then only one spectrum is operated upon. +A slightly more complex template is a list of filenames of data groups. +More complex templates will permit use of expressions referencing the values +of specific fields to select a subset of the spectra in a group. The syntax +of such expressions has not yet been defined (examples are given below +nonetheless), but the function performed by an image template will be the same +regardless of the syntax. In all cases the image template will be a single +string valued parameter at the CL level. + +.nh 2 +Standard Calling Sequence + + The standard calling sequence for a unary image operator is shown below +The calling sequence for a binary operator would be the same with a second input +parameter added as the second argument. In general, any data dependent +control parameters should be implemented as positional arguments following +the primary operands, and data independent or optional (rarely used) parameters +should be implemented as hidden parameters. + + +.ks +.nf + imop (input, output, data_dependent_control_params) + + imop image operator name + input image template specifying set of input images + output filename of output datagroup + + data_dependent_control_parameters + (hidden parameters) + +for example, + + coincor (spectra, newgroup, dead_time) +.fi +.ke + + +If a series of spectra are to be processed it seems reasonable to add the +processed spectra to a new or existing data group (possibly the same as an +input datagroup). If the operation is to be performed in place a special +notation (e.g. the null string) can be given as the output filename. +At the \fBonedspec\fR level output filenames will not be defaulted. + +.nh 2 +Examples + + Some examples of image templates might be useful to give a more concrete +idea of the functionality which will be available. Bear in mind that what we +are describing here is really the usage of one of the fundamental IRAF system +interfaces, the DBMS database management subsystem, albeit from the point of +view of \fBonedspec\fR. The same facilities will be available in any program +which operates upon images, and in some non-image applications as well (e.g. +the new \fBfinder\fR). Our philosopy, as always, is to make standard usage +simple, with considerable sophistication available for those with time to +learn more about the system. + +The simplest case occurs when there is one spectrum per data group (file). +For example, assuming that the file "a" contains a single spectrum, the +command + + cl> coincor a, b, .2 + +would perform coincidence correction for spectrum A, placing the result in +B, using a dead time parameter of .2. For a more complex example, consider +the following command: + + cl> coincor "a.type=obj&coincor=no,b", a, .2 + +This would perform coincidence correction for all spectra in group B plus all +object spectra in group A which have not already been coincidence corrected, +adding the corrected spectra to group A (notation approximate only). If the +user does not trust the database explicit record numbers may be used and +referenced via range list expressions, e.g., + + cl> coincor "a.recnum=(1,5,7:11),b", a, .2 + +would select records 1, 5, and 7 through 11 from data group A. Alternatively +the database utilities could be used to list the spectra matching the selection +criteria prior to the operation if desired. For example, + + cl> db.select "a.type=obj" + +would write a table on the standard output (the terminal) wherein each spectrum +in data group A is shown as a row of field values. If one wanted to generate +an explicit list of records to be processed with help from the database +utilities, a set of records could be selected from a data group and selected +fields from each record written into a text file: + + cl> db.select "a.type=obj", "recnum, history" > reclistfile + +The output file "reclistfile" produced by this command would contain the +fields "recnum" (record number) and "history" (description of processing +performed to generate the record). The editor could be used to delete +unwanted records, producing a list of record numbers suitable for use as +an image template: + + cl> coincor "a.recnum=@reclistfile", a, .2 + +.nh +Reduction Operators + +.nh 2 +Line List Preparation + + I suggest maintaining the line lists as text files so that the user can +edit them with the text editor, or process them with the \fBlists\fR operators. +A master line list might be maintained in a database and the DBMS \fBselect\fR +operator used to extract ASCII linelists in the wavelength region of interest, +but this would only be necessary if the linelist is quite large or if a linelist +record contains many fields. I don't think we need the \fBline_list\fR task. + +.nh 2 +Dispersion Solution + + The problem with selecting a line list and doing the dispersion solution +in separate operations is that the dispersion solution is invaluable as an aid +for identifying lines and for rejecting lines. Having a routine which merely +tweaks up the positions of lines in an existing lineset (e.g., \fBalinid\fR) +is not all that useful. I would like to suggest the following alternate +procedure for performing the dispersion solution for a set of calibration +spectra which have roughly the same dispersion. + +.ls +.ls [1] Generate Lineset [and fit dispersion] +.sp +Interactively determine the lineset to be used, i.e., wavelength (or whatever) +and approximate line position in pixel units for N lines. Input is one or more +comparison spectra and optionally a list of candidate lines in the region +of interest. Output is the order for the dispersion curve and a linelist of +the following (basic) form: + + L# X Wavelength [Weight] + +It would be very useful if the program, given a rough guess at the dispersion, +could match the standard linelist with the spectra and attempt to automatically +identify the lines thus detected. The user would then interactively edit the +resultant line set using plots of the fitted dispersion curve to reject +misidentified or blended lines and to adjust weights until a final lineset +is produced. +.le + +.ls [2] Fit Dispersion +.sp +Given the order and functional type of the curve to be fitted and a lineset +determined in step [1] (or a lineset produced some any other means, e.g. with +the editor), for each spectrum in the input data group tweak the center of +each line in the lineset via an automatic centering algorithm, fit the +dispersion curve, and save the coefficients of the fitted curve in the +image header. The approximate line positions would be used to find and measure +the positions of the actual lines, and the dispersion curve would be fitted and +saved in the image header of each calibration spectrum. + +While this operator would be intended to be used noninteractively, the default +textual and graphics output devices could be the terminal. To use the program +in batch mode the user would redirect both the standard output and the graphics +output (if any), e.g., + +.nf + cl> dispsol "night1.type=comp", linelistfile, order, + >>> device=stdplot, > dispsol.spool & +.fi + +Line shifts, correlation functions, statistical errors, the computed residuals +in the fitted dispersion curves, plots of various terms of the dispersion +curves, etc. may be generated to provide a means for later checking for +erroneous solutions to the individual spectra. There is considerable room for +innovation in this area. +.le + +.ls [3] Second Order Correction +.sp +If it is desired to interpolate the dispersion curve in some additional +dimension such as time or hour angle, fit the individual dispersion solutions +produced by [1] or [2] as a group to one or more additional dimensions, +generating a dispersion solution of one, two or more dimensions as output. +If the output is another one dimensional dispersion solution, the input +solutions are simply averaged with optional weights. This "second order" +correction to a group of dispersion solutions is probably best performed by +a separate program, rather than building it into \fBalineid\fR, \fBdispsol\fR, +etc. This makes the other programs simpler and makes it possible to exclude +spectra from the higher dimensional fit without repeating the dispersion +solutions. +.le +.le + +If the batch run [2] fails for selected spectra the dispersion solution for +those spectra can be repeated interactively with operator [1]. +The curve fitting package should be used to fit the dispersion curve (we can +extend the package to support \fBonedspec\fR if necessary). + +.nh 2 +Dispersion Correction + + This function of this procedure is to change the dispersion of a +spectrum or group of spectra from one functional form to another. +At a mimimum it must be possible to produce spectra linear in wavelength or +log wavelength (as specified), but it might also be useful to be able +to match the dispersion of a spectrum to that of a second spectrum, e.g., to +minimize the amount of interpolation required to register spectra, or +to introduce a nonlinear dispersion for testing purposes. This might be +implemented at the CL parameter level by having a string parameter which +takes on the values "linear" (default), "log", or the name of a record +defining the dispersion solution to be matched. + +It should be possible for the output spectrum to be a different size than +the input spectrum, e.g., since we are already interpolating the data, +it might be nice to produce an output spectrum of length 2**N if fourier +analysis is to be performed subsequently. It should be possible to +extract only a portion of a spectrum (perform subraster extraction) in the +process of correcting the dispersion, producing an output spectrum of a +user-definable size. It should be possible for an output pixel to lie at +a point outside the bounds of the input spectrum, setting the value of the +output pixel to INDEF or to an artificially generated value. Note that +this kind of generality can be implemented at the \fBonedspec\fR level +without compromising the simplicity of dispersion correction for a particular +instrument at the \fBimred\fR level. + +.nh 3 +Line Centering Algorithms + + For most data, the best algorithm in the set described is probably the +parabola algorithm. To reject nearby lines and avoid degradation of the +signal to noise the centering should be performed within a small aperture, +but the aperture should be allowed to move several pixels in either direction +to find the peak of the line. + +The parabola algorithm described has these features, +but as described it finds the extrema within a window about the +initial position. It might be preferable to simply walk up the peak nearest +to the initial center. This has the advantage that it is possible to center +on a line which has a nearby, stronger neighbor which cannot itself be used +for some reason, but which might fall within \fBparextent\fR pixels of the +starting center. The parabola algorithm as described also finds a local extrema +rather than a local maximum; probably not what is desired for a dispersion +solution. The restriction to 3 pixels in the final center determination is +bad; the width of the centering function must be a variable to accommodate +the wide range of samplings expected. + +The parabola algorithm described is basically a grid search over +2*\fIparextent\fR pixels for the local extrema. What I am suggesting is +an iterative gradient search for the local maximum. The properties of the +two algorithms are probably sufficiently different to warrant implementation +of both as an option (the running times are comparable). I suspect that +everyone else who has done this will have their own favorite algorithm as +well; probably we should study half a dozen but implement only one or two. + +.nh 2 +Field Flattening + + It is not clear that we need special flat fielding operators for +\fBonedspec\fR. We have a two-dimensional operator which fits image lines +independently which might already do the job. Probably we should experiment +with both the smoothing spline and possibly fourier filtering for removing +the difficult medium frequency fluctuations. The current \fBimred\fR flat field +operator implements the cubic smoothing spline (along with the Chebyshev and +Legendre polynomials), and is available for experimentation. + +Building interactive graphics into the operator which fits a smooth curve to +the continuum is probably not necessary. If a noninteractive \fBimred\fR or +\fBimages\fR operator is used to fit the continuum the interactive graphics +can still be available, but might better reside in a higher level CL script. +The basic operator should behave like a subroutine and not write any output +to the terminal unless enabled by a hidden parameter (we have been calling +this parameter \fIverbose\fR in other programs). + +.nh 3 +Extinction Correction and Flux Calibration + + I did not have time to review any of this. + +.nh +Standard Library Packages + + The following standard IRAF math library packages should be used in +\fBonedspec\fR. The packages are very briefly described here but are +fully documented under \fBhelp\fR on the online (kpnob:xcl) system. + +.nh 2 +Curve Fitting + + The curve fitting package (\fBcurfit\fR) is currently capable of fitting +the Chebyshev and Legendre polynomials and the cubic smoothing spline. +Weighting is supported as an option. +We need to add a piecewise linear function to support the +dispersion curves for the high resolution FTS spectra. We may have to add a +double precision version of the package to provide the 8-10 digits of +precision needed for typical comparison line wavelength values, but +normalization of the wavelength values may make this unnecessary for moderate +resolution spectra. + +Ordinary polynomials are not supported because their numerical properties are +very much inferior to those of orthogonal polynomials (the ls matrix can have +a disastrously high condition number, and lacking normalization the function +begin fitted is not invariant with respect to scale changes and translations +in the input data). For low order fits the Chebyshev polynomials are +considered to have the best properties from an approximation theoretic point +of view, and for high order fits the smoothing spline is probably best because +it can follow arbitrary trends in the data. + +.nh 2 +Interpolation + + The image interpolation package (\fBiminterp\fR) currently supports the +nearest neighbor, linear, third and fifth order divided differences, +cubic interpolating spline, and sinc function interpolators. +We should add the zeroth and first order partial pixel ("flux conserving") +interpolants because they offer unique properties not provided by any +of the other interpolants. + +.nh 2 +Interactive Graphics + + We will define a standard interactive graphics utility package for +interactive operations upon data vectors (to be available in a system library +in object form). It should be possible to define a general package which +can be used anywhere a data vector is to be plotted and +examined interactively (not just in \fBonedspec\fR). Standard keystrokes +should be defined for common operations such as expanding a region of +the plot and restoring the original scale. This will not be attempted +until an interactive version of the GIO interface is available later this +fall. +.endhelp diff --git a/noao/onedspec/doc/sys/TODO b/noao/onedspec/doc/sys/TODO new file mode 100644 index 00000000..0dfa136b --- /dev/null +++ b/noao/onedspec/doc/sys/TODO @@ -0,0 +1,28 @@ +scombine: + 1. Combine with weights: + By signal level + By sigma spectrum + +doc: + Install SENSFUNC memo in the doc directory. (8/14) + +calibrate: + Have calibrate apply neutral density filter function. This may also + have to be included in STANDARD and SENSFUNC. (2/25/87) + +splot: + Add a deblend option for PCYGNI profiles. (Tyson, 3/19/87) + +Tim Heckman (U. Maryland) came by with questions and requests +concerning deblending in SPLOT. Tim's comments are indicated in +quotations. + +2. "The deblending should allow additional constraints if known. +Specifically fixing the ratios of lines based on atomic physics." + +3. "The deblending should provide some uncertainty estimates." I added +that there has also been a request to use known statistics in the +pixel data themselves to generate uncertainty estimates. + +4. "It would be useful to provide other choices for the profile rather +than just gaussians." diff --git a/noao/onedspec/doc/sys/coincor.ms b/noao/onedspec/doc/sys/coincor.ms new file mode 100644 index 00000000..1b4d29cc --- /dev/null +++ b/noao/onedspec/doc/sys/coincor.ms @@ -0,0 +1,46 @@ +.EQ +delim $$ +.EN +.OM +.TO +IIDS Users +.FR +F. Valdes +.SU +IIDS count rate corrections +.PP +The IRAF task \fBcoincor\fR transforms the observed count rates to +something proportional to the input count rate. The correction applied +to the observed count rates depends upon the count rate and is instrument +dependent. One correction common to photomultiplier detectors and the +IIDS is for coincident events, which is the origin of the task name. +The parameter \fIccmode\fR selects a particular type of correction. +The value \fIccmode\fR = "iids" applies the following transformation to +observed IIDS count rates. + +.EQ (1) + C sup ' ~=~(- ln (1- deadtime C)/ deadtime ) sup power +.EN + +where $C$ is the orginal count rate, $C sup '$ is the corrected count +rate, and $deadtime$ and $power$ are \fBcoincor\fR parameters. The term +inside the parenthesis is the correction for dead-time in the counting +of coincident events on the back phospher of the image tube. The power +law correction is due to the non-linearity of the IIDS image tube chain. +.PP +The correction applied with the Mountain Reduction Code is only for +coincidences, i.e. equation (1) with $power = 1$. To obtain just this +correction with \fBcoincor\fR set $power = 1$. To take mountain reduced +data and correct only for the non-linearity set \fIccmode\fR = "power". +With raw IIDS data use \fBcoincor\fR with the default +parameters. + +.LP +References: +.IP (1) +L. Goad, \fBSPIE 172\fR, 1979, p. 86. +.IP (2) +G. Jacoby, Some Notes on the ONEDSPEC Package, \fBIRAF Handbook\fR +.IP (3) +P. Massey and J. De Veny, How Linear is the IIDS, \fBNOAO Newsletter\fR, +#6, June 1986. diff --git a/noao/onedspec/doc/sys/identify.ms b/noao/onedspec/doc/sys/identify.ms new file mode 100644 index 00000000..6a69204b --- /dev/null +++ b/noao/onedspec/doc/sys/identify.ms @@ -0,0 +1,347 @@ +.RP +.TL +Radial Velocity Measurements with IDENTIFY +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +August 1986 +Revised August 1990 +.AB +The IRAF task \fBidentify\fP may be used to measure radial velocities. +This is done using the classical method of determining +the doppler shifted wavelengths of emission and absorption lines. +This paper covers many of the features and techniques available +through this powerful and versatile task which are not immediately +evident to a new user. +.AE +.sp 3 +.NH +\fBIntroduction\fP +.PP +The task \fBidentify\fP is very powerful and versatile. It can +be used to measure wavelengths and wavelength shifts for +doing radial velocity measurements from emission and +absorption lines. When combined with the CL's ability +to redirect input and output both from the standard text +streams and the cursor and graphics streams virtually +anything may be accomplished either interactively or +automatically. This, of course, requires quite a bit of +expertise and experience with \fBidentify\fP and with +the CL which a new user is not expected to be aware of initially. +This paper attempts to convey some of the possibilities. +There are many variations on these methods which the user +will learn through experience. +.PP +I want to make a caveat about the suggestions made in +this paper. I wrote the \fBidentify\fP task and so I am +an expert in its use. However, I am not a spectroscopist, +I have not been directly involved in the science of +measuring astronomical radial velocities, and I am not +very familiar with the literature. Thus, the suggestions +contained in this paper are based on my understanding of +the basic principles and the abilities of the \fBidentify\fP +task. +.PP +The task \fBidentify\fP is used to measure radial velocities +by determining the wavelengths of individual emission +and absorption lines. The user must compute the +radial velocities separately by relating the observed +wavelengths to the known rest wavelengths via the Doppler +formula. This is a good method when the lines are +strong, when there are only one or two features, and +when there are many, possibly, weaker lines. The +accuracy of this method is determined by the accuracy +of the line centering algorithm. +.PP +The alternative method is to compare an observed spectrum +to a template spectrum of known radial velocity. This +is done by correlation or fourier ratio methods. These +methods have the advantage of using all of the spectrum +and are good when there are many very weak and possibly +broad features. Their disadvantages are confusion +with telluric lines, they don't work well with just a +few real features, and they require a fair amount of +preliminary manipulation of the spectrum to remove +continuum and interpolate the spectrum in logarithmic +wavelength intervals. IRAF tasks for correlation +and fourier ratio methods are under development at +this time. Many people assume that these more abstract +methods are inherently better than the classical method. +This is not true, it depends on the quality and type of +data. +.PP +Wavelength measurements are best done on the original +data rather than after linearizing the wavelength +intervals. This is because 1) it is not necessary as +will be shown below and 2) the interpolation used to +linearize the wavelength scale can change the shape +of the lines, particularly strong, narrow emission +lines which are the best ones for determining radial +velocities. +.PP +This paper is specifically about \fBidentify\fP but one +should be aware of the task \fBsplot\fP which also may +be used to measure radial velocities. It differs in +several respects from \fBidentify\fP. \fBSplot\fP works +only on linearized data; the wavelength and pixel +coordinates are related by a zero point and wavelength +interval. The line centering algorithms are different; +the line centering is generally less robust (tolerant +of error) and often less accurate. It has many nice +features but is not designed for the specific purpose +of measuring positions of lines and, thus, is not as +easy to use for this purpose. +.PP +There are a number of sources of additional information +relating to the use of the task \fBidentify\fP. The +primary source is the manual pages for the task. As +with all manual pages it is available online with the +\fBhelp\fP command and in the \fIIRAF User Handbook\fP. +The NOAO reduction guides or cookbooks for the echelle +and IIDS/IRS include additional examples and discussion. +The line centering algorithm is the most critical +factor in determining dispersion solutions and radial +velocities. It is described in more detail under the +help topic \fBcenter1d\fP online or in the handbook. +.NH +Method 1 +.PP +In this method, arc calibration images are used to determine +a wavelength scale. The dispersion solution is then transferred +to the object spectrum and the wavelengths of emission and +absorption lines are measured and recorded. This is +relatively straightforward but some tricks will make this easier +and more accurate. +.NH 2 +Transferring Dispersion Solutions +.PP +There are several ways to transfer the dispersion solution +from an arc spectrum to an object spectrum differing in the +order in which things are done. +.IP (1) +One way is to determine the dispersion solution for all the arc images +first. To do this interactively specify all the arc images as the +input to \fBidentify\fP. After determining the dispersion solution for +the first arc and quitting (\fIq\fP key) the next arc will be displayed +with the previous dispersion solution and lines retained. Then use the +cursor commands \fIa\fP and \fIc\fP (all center) to recenter and +\fIf\fP (fit) to recompute the dispersion solution. If large shifts +are present use \fIs\fP (shift) or \fIx\fR (correlate peaks) to shift, +recenter, and compute a wavelength zero point shift to the dispersion +function. A new dispersion function should then be fit with \fIf\fP. +These commands are relatively fast and simple. +.IP +An important reason for doing all the arc images first +is that the same procedure can be done mostly noninteractively +with the task \fBreidentify\fP. After determining a +dispersion solution for one arc image \fBreidentify\fP +does the recenter (\fIa\fP and \fIc\fP), shift and +recenter (\fIs\fP), or correlation features, shift, and +recenter (\fIx\fP) to transfer the dispersion solutions +between arcs. This is usually done as a background task. +.IP +To transfer the solution to the object spectra specify +the list of object spectra as input to \fBidentify\fP. +For each image begin by entering the colon command +\fI:read arc\fP where arc is the name of the arc image +whose dispersion solution is to be applied; normally +the one taken at the same time and telescope position as +the object. This will read the dispersion solution and arc +line positions. Delete the arc line positions with the +\fIa\fP and \fId\fP (all delete) cursor keys. You +can now measure the wavelengths of lines in the spectrum. +.IP (2) +An alternative method is to interactively alternate between +arc and object spectra either in the input image list or +with the \fI:image name\fP colon command. +.NH 2 +Measuring Wavelengths +.IP (1) +To record the feature positions at any time use the \fI:features +file\fP colon command where \fIfile\fP is where the feature +information will be written. Repeating this with the same +file appends to the file. Writing to the database with the +\fI:write\fP colon command also records this information. +Without an argument the results are put in a file with +the same name as the image and a prefix of "id". You +can use any name you like, however, with \fI:write +name\fP. The \fI:features\fP command is probably preferable +because it only records the line information while the +database format includes the dispersion solution and +other information not needed for computing radial +velocities. +.IP (2) +Remember that when shifting between emission and absorption +lines the parameter \fIftype\fP must be changed. This may be done +interactively with the \fI:ftype emission\fP and \fI:ftype +absorption\fP commands. This parameter does not need to be +set except when changing between types of lines. +.IP (3) +Since the centering of the emission or absorption line is the +most critical factor, one should experiment with the parameter +\fIfwidth\fP. To change this parameter type \fI:fwidth value\fP. +The positions of the marked features are not changed until a +center command (\fIc\fP) command is given. +.IP +A narrow \fIfwidth\fP is less influenced by blends and wings but +has a larger uncertainty. A broad \fIfwidth\fP uses all of the +line profile and is thus stable but may be systematically influenced +by blending and wings. One possible approach is to measure +the positions at several values of \fIfwidth\fP and decide which +value to use or use some weighting of the various measurements. +You can record each set of measurements with the \fI:fe +file\fP command. +.IP (4) +For calibration of systematic effects from the centering one should +obtain the spectrum of a similar object with a known radial +velocity. The systematic effect is due to the fact that the +centering algorithm is measuring a weighted function of the +line profile which may not be the true center of the line as +tabulated in the laboratory or in a velocity standard. By +using the same centering method on an object with the same line +profiles and known velocity this effect can be eliminated. +.IP (5) +Since the arcs are not obtained at precisely the same time +as the object exposures, there may be a wavelength shift relative +to the arc dispersion solution. This may be calibrated from +night sky lines in the object itself (the night sky lines are +"good" in this case and should not be subtracted away). There are +generally not enough night sky lines to act as the primary +dispersion calibrator but just one can determine a possible +wavelength zero point shift. Measure the night sky line +positions at the same time the object lines are measured. +Determine a zero point shift from the night sky to be +taken out of the object lines. +.NH +Method 2 +.PP +This method is similar to the correlation method in that a +template spectrum is used and the average shift relative +to the template measures the radial velocity. This has the +advantage of not requiring the user to do a lot of calculations +(the averaging of the line shifts is done by identify) but is +otherwise no better than method 1. The template spectrum must +have the same features as the object spectrum. +.IP (1) +Determine a dispersion solution for the template spectrum +either from the lines in the spectrum or from an arc calibration. +.IP (2) +Mark the features to be correlated in the template spectrum. +.IP (3) +Transfer the template dispersion solution and line positions +to an object spectrum using one of the methods described +earlier. Then, for the current feature, point the cursor near +the same feature in the object spectrum and type \fIs\fP. The +mean shift in pixels, wavelength, and fractional wavelength (like +a radial velocity without the factor of the speed of light) +for the object is determined and printed. A new dispersion +solution is determined but you may ignore this. +.IP (4) +When doing additional object spectra, remember to start over +again with the template spectrum (using \fI:read template\fP) +and not the solution from the last object spectrum. +.IP (5) +This procedure assumes that the dispersion solution between +the template and object are the same. Checks for zero point +shifts with night sky lines, as discussed earlier, should be +made if possible. The systematic centering bias, however, is +accounted for by using the same lines from the template radial +velocity standard. +.IP (6) +One possible source of error is attempting to use very weak +lines. The recentering may find the wrong lines and affect +the results. The protections against this are the \fIthreshold\fP +parameter and setting the centering error radius to be relatively small. +.NH +Method 3 +.PP +This method uses only strong emission lines and works with +linearized data without an \fBidentify\fP dispersion +solution; though remember the caveats about rebinning the +spectra. The recipe involves measuring +the positions of emission lines. The +strongest emission lines may be found automatically using +the \fIy\fP cursor key. The number of emission lines to +be identified is set by the \fImaxfeatures\fP parameter. +The emission line positions are then written to a data file +using the \fI:features file\fP colon command. This may +be done interactively and takes only a few moments per +spectrum. If done interactively, the images may be chained +by specifying an image template. The only trick required +is that when proceeding to the next spectrum the previous +features are deleted using the cursor key combination \fIa\fP +and \fId\fP (all delete). +.PP +For a large number of images, on the order of hundreds, this +may be automated as follows. A file containing the cursor +commands is prepared. The cursor command format consists +of the x and y positions, the window (usually window 1), and +the key stroke or colon command. Because each new image from +an image template does not restart the cursor command file, +the commands would have to be repeated for each image in +the list. Thus, a CL loop calling the task each time with +only one image is preferable. Besides redirecting the +cursor input from a command file, we must also redirect the +standard input for the response to the database save query, the +standard output to discard the status line information, and , +possibly, the graphics to a metacode file which can then be +reviewed later. The following steps indicate what is to be +done. +.IP (1) +Prepare a file containing the images to be measured (one per line). +This can usually be done using the sections command to expand +a template and directing the output into a file. +.IP (2) +Prepare a cursor command file (let's call it cmdfile) +containing the following two lines. +.RS +.IP +.nf +.ft CW +1 1 1 y +1 1 1 :fe positions.dat +.ft P +.fi +.RE +.IP (3) +Enter the following commands. +.RS +.IP +.nf +.ft CW +list="file" +while (fscan (list,s1) !=EOF){ +print ("no") \(or identify (sl,maxfeatures=2, cursor="cmdfile", +>"dev$null", >G "plotfile") +} +.ft P +.fi +.RE +.LP +Note that these commands could be put in a CL script and executed +using the command +.sp +.IP +.ft CW +on> cl <script.cl +.ft P +.sp +.PP +The commands do the following. The first command initializes the +image list for the loop. The second command is the loop to +be run until the end of the image file is reached. The +command in the loop directs the string "no" to the standard +input of identify which will be the response to the database save +query. The identify command uses the image name obtained from the list +by the fscan procedure, sets the maximum number of features to be +found to be 2 (this can be set using \fBeparam\fP instead), the +cursor input is taken from the cursor command file, the standard +output is discarded to the null device, and the STDGRAPH output +is redirected to a plot file. If the plot file redirection is +not used, the graphs will appear on the specified graphics +device (usually the graphics terminal). The plot file can then +be disposed of using the \fBgkimosaic\fP task to either the +graphics terminal or a hardcopy device. diff --git a/noao/onedspec/doc/sys/onedproto.ms b/noao/onedspec/doc/sys/onedproto.ms new file mode 100644 index 00000000..b1b05201 --- /dev/null +++ b/noao/onedspec/doc/sys/onedproto.ms @@ -0,0 +1,1673 @@ +.RP +.ND +.TL +Some Notes on the ONEDSPEC Package +.AU +G. Jacoby +.AI +.K2 "" "" "*" +June 1985 +.AB +The first phase of the ONEDSPEC prototype package is complete. +Comments and some internal description is presented for each task +in the package. Also presented are some more global descriptions +of strategies used in the package and considerations for future +improvements. +.AE +.SH +1. Why is ONEDSPEC Different? +.PP +This section describes some of the ways in which the ONEDSPEC +package diverges from other IRAF package strategies. +A few of these should someday be modified to more closely +adhere to IRAF conventions, but in other cases, restrictions +or limitations in the IRAF system are revealed. +.sp 1 +.SH +Quantity +.PP +One of the major differences between a two dimensional image processing +package and a one dimensional package is that spectra +frequently congregate in groups of hundreds to thousands while two-dimensional +images live in groups of tens to hundreds. What this means is that spectral +processing must be somewhat more automated and streamlined - the software cannot +rely on user input to provide assistance and it cannot afford +excessive overhead; otherwise a large fraction of the processing time will be +spent where it is least useful. +.PP +To process large volumes of spectra in a reasonably automated fashion, +the software must be smart enough to know what to do with a variety +of similar but different spectra. The way adopted here is to key +off header parameters which define the type of spectrum and the +processing required. In fact, most of the ONEDSPEC package will not +work smoothly without some header parameter information. +.PP +It is also important that each task be self-reliant so that the +overhead of task stop and restart is avoided. For many operations, +the actual computation time is a fraction of a second, yet no +operation in the ONEDSPEC package is faster than one second per spectrum +due to task overhead. If task startup and stop were required for each +spectrum, then the overhead would be much worse. +.PP +So the philosophy is one in which each task uses as much information +as it can reasonably expect from the spectral image header. +Usually this is not more than three or four elements. +The strategy of using header information should not be limited to +ONEDSPEC. Many image processing problems can be automated +to a large degree if header information is used. The success of +the KPNO CCD Mountain reduction system emphasizes this point. +It would seem prudent that other IRAF applications make use of +such information when possible. +[See section 3 for a more detailed discussion of headers.] +.sp 1 +.SH +Spectral Image Names +.PP +One implication of the quantity problem is that it must be easy for the user to +specify the names of large numbers of spectra. The approach taken for ONEDSPEC +was to assign a root name to a group of spectra and then +append an index number of 4 or more digits starting with 0000. +So spectra, by default, have the form root.0000, root.0001, ... +To specify the spectra, the user types only the root name and the range +of indices such as "root" and "0-99,112-113,105-108". +The range decoder accesses the spectral indices in the order given +as opposed to access in ascending order, so that the spectrum root.0112 +will be processed before root.0105 in the example specification above. +Spectra having more general names may be specified using the +standard IRAF filename expansion methods if the +the range specification is given as null. +.PP +The specification of large numbers of images is an area where +most IRAF applications are weak. Resorting to odd combinations +of bracket and backslash characters in filename specifications +is obscure to new users and still fails to +meet the general need. The range specification adopted for ONEDSPEC +comes closer but introduces a fixed image name format. +.sp 1 +.SH +Apertures -- A way to group data +.PP +Many spectrographs generate multiple spectra simultaneously by +placing more than one slit or aperture in the focal plane. +Examples include the IIDS, IRS, and Cryogenic Camera in use +at Kitt Peak. The Echelle may be considered a multi-aperture +instrument for purposes of reductions by associating each order +with an "aperture" number. +.PP +The concept of aperture can be generalized to indicate a set of +spectral data having common group properties such as +wavelength coverage. Most tasks in ONEDSPEC will key off +an aperture number in the image header and treat those +common aperture spectra uniformly. +Defining data groups which are to be processed in this fashion +is a technique not generally exploited by reduction programs. +This is due in part to the problem of image header usage. +.PP +For programming convenience and to avoid an additional level +of indirectness, in ONEDSPEC the aperture number is used directly as an +index in many static arrays. The current implementation has +a declaration for 50 apertures and due to the IIDS/IRS +notation of apertures 0 and 1, the apertures are zero-indexed, contrary +to standard IRAF nomenclature, +from 0-49. It would certainly be better to map the aperture numbers +to the allowable index range, but the added complexity of another +level of indirectness seemed distracting. Actually the mapping +can still be done by the header reader, "load_ids_hdr", and +unmapped by the header writer, "store_keywords". +.sp 1 +.SH +Static versus dynamic arrays +.PP +Although dynamic storage would alleviate some of the memory +requirements in the package, the use of static arrays aids +readability and accounts for only about 10 percent of the total +task memory space. Many of the arrays are arrays of pointers. +For example, in the task BSWITCH, there is an array (called "imnames") +of pointers for the names of spectral images, several for each aperture. +The actual space for the names is dynamically allocated, +so first we allocate an array of pointers for each +aperture: +.sp 1 +.DS + call salloc (imnames[aperture], nr_names, TY_POINT) +.DE +.sp 1 +Then, for each of these pointers, space must be allocated for the +character arrays: +.sp 1 +.DS + do i = 1, nr_names + call salloc (Memp[imnames[aperture]+i-1], SZ_LINE, TY_CHAR) +.DE +.sp 1 +Later to access the character strings, a name is specified as: +.sp 1 +.DS + Memc[Memp[imnames[aperture]+nr_of_this_spectrum-1]] +.DE +.sp 1 +If the "imnames" array was also dynamically allocated, the +above access would be even less readable. +If memory requirements become a serious problem, then these ONEDSPEC +tasks should be modified. +.sp 1 +.SH +Output image names +.PP +To retain the consistent usage of root names and ranges, output +spectra also have the form root.nnnn. For user convenience, +the current output root name and next suffix are maintained as +package parameters onedspec.output and onedspec.next_rec. +The latter parameter is automatically updated each time a +new spectrum is written. This is done by the individual tasks +which directly access this package parameter. +.PP +There is an interesting side effect when using indirect parameters +(e.g. )onedspec.output) for input. In the local task parameter +file, the mode of the parameter must be declared hidden. So when the user +does an "lpar task", those parameters appear to be unnecessary +(that is, they are enclosed in parenthesis). When run, +prompts appear because the parameter is an automatic mode +parameter in the package parameter file. +If run as a background task, this is more annoying. +Unfortunately, any other choice of parameter modes produces +less desirable actions. +.sp 1 +.SH +ONEDUTIL +.PP +As the number of tasks in ONEDSPEC started growing, the +need for a subdivision of the package became clear. +The first cut was made at the utility level, and a number +of task names (not necessarily physical tasks) were +moved out into the ONEDUTIL submenu. In the future, +additional tasks will eventually require another subpackage. +.PP +Actually, many of the tasks in ONEDUTIL may be more at home +in some other package, but a conscious effort was made to +avoid contaminating other IRAF packages with tasks written for +the ONEDSPEC project. If all the following tasks are relocated, +then the need for ONEDUTIL is reduced. +.PP +Two of the entries in ONEDUTIL may be considered as more appropriate +to DATAIO - RIDSMTN and WIDSTAPE. In fact RIDSMTN can +replace the version currently in DATAIO. WIDSTAPE may replace the +DATAIO task WIDSOUT if the usage of header parameters does not +present a problem. +.PP +The task MKSPEC may be a candidate for the ARTDATA package. +It should be enhanced to include optional noise generation. +Also, it may be appropriate for SINTERP to replace INTERP +in the UTILITY package. +.PP +I suppose one could argue that SPLOT belongs in the PLOT package. +Certainly, the kludge script BPLOT should be replaced by a more +general batch plot utility in PLOT. +Also, the two task names, IDENTIFY and REIDENTIFY are present +in the ONEDSPEC menu for user convenience, but the task declarations +in ONEDSPEC.CL refer to tasks in the LONGSLIT package. +.PP +Because ONEDUTIL is a logical separation of the tasks, not +a complete physical task breakup, there is no subdirectory +for ONEDUTIL as there is in other packages. This is a bit messy +and it may be best to completely disentangle the tasks in the +subpackage into a true package having all the implications. +.LP +.SH +2. Task Information +.PP +There are currently about 30 tasks in the ONEDSPEC package. +These are summarized in the menu listing below and +a brief description of some less obvious aspects of each follows. +.sp 1 +.DS L + ONEDSPEC + + addsets - Add subsets of strings of spectra + batchred - Batch processing of IIDS/IRS spectra + bswitch - Beam-switch strings of spectra to make obj-sky pairs + calibrate - Apply sensitivity correction to spectra + coincor - Correct spectra for photon coincidence + dispcor - Dispersion correct spectra + extinct - Correct data for atmospheric extinction + flatfit - Sum and normalize flat field spectra + flatdiv - Divide spectra by flat field + identify - Identify features in spectrum for dispersion solution + iids - Set reduction parameters for IIDS + irs - Set reduction parameters for IRS + onedutil - Enter ONEDSPEC Utility package + process - A task generated by BATCHRED + reidentify- Automatically identify features in spectra + sensfunc - Create sensitivity function + slist - List spectral header elements + splot - Preliminary spectral plot/analysis + standard - Identify standard stars to be used in sensitivity calc + subsets - Substract pairs in strings of spectra + + ONEDUTIL + + bplot - Batch plots of spectra + coefs - Extract mtn reduced ceofficients from henear scans + combine - Combine spectra having different wavelength ranges + lcalib - List calibration file data + mkspec - Generate an artificial spectrum + names - Generate a list of image names from a string + rebin - Rebin spectra to new dispersion parameters + ridsmtn - Read IIDS/IRS mountain format tapes + sinterp - Interpolate a table of x,y pairs to create a spectrum + widstape - Write Cyber format IDSOUT tapes +.DE +.sp 1 +.SH +ADDSETS +.PP +Spectra for a given object may have been observed through more than +one instrument aperture. For the IIDS and IRS, this is the most common +mode of operation. Both apertures are used to alternately observe +the program objects. +.PP +Each instrument aperture may be considered an +independent instrument having unique calibration properties, and +the observations may then be processed completely independently +until fully calibrated. At that point the data may be combined to +improve signal-to-noise and reduce systematic errors associated +with the alternating observing technique. Because the data are +obtained in pairs for IIDS and IRS (but may be obtained in groups +of larger sizes from other instruments), ADDSETS provides a way +to combine the pairs of observations. +.PP +Each pair in the input string is added to produce a single output +spectrum. Although the word "pair" is used here, the parameter +"subset" defines the number of elements in a "pair" (default=2). +The input string is broken down into groups where each group +consists of the pair of spectra defined in order of the input +list of image names. +.PP +"Add" in ADDSETS means: +.RS +.IP 1. +Average the pairs if the data are calibrated to flux (CA_FLAG=0) +optionally weighted by the integration time. +.IP 2. +Add the pairs if uncalibrated (CA_FLAG=-1). +.RE +.sp 1 +.SH +BATCHRED +.PP +This is a script task which allows spectra from dual aperture instruments +to be processed completely in a batch mode after the initial wavelength +calibration and correction has been performed. The processes which +may be applied and the tasks referenced are: +.RS +.IP 1. +Declaring observations as standard stars for flux calibration (STANDARD). +.IP 2. +Solving for the sensitivity function based on the standard stars (SENSFUNC). +.IP 3. +Generating object minus sky differences and summing individual +observations if several were made (BSWITCH). +.IP 4. +Correcting for atmospheric extinction (BSWITCH). +.IP 5. +Applying the system sensitivity function to generate flux calibrated +data (CALIBRATE). +.IP 6. +Adding pairs of spectra obtained through the dual apertures (ADDSETS). +.RE +Any or all of these operations may be selected through the task +parameters. +.PP +BATCHRED generates a secondary script task called PROCESS.CL +which is a text file containing constructed commands to the +ONEDSPEC package. This file may be edited by the user if an +entry to BATCHRED is incorrect. It may also be saved, or appended +by further executions of BATCHRED. +.PP +BATCHRED also generates a log file of the output generated by the +ONEDSPEC tasks it calls. +.sp 1 +.SH +BSWITCH +.PP +This task combines multiple observations of a single object +or multiple objects taken through a multiaperture instrument. +Object minus sky differences are generated as pairs of +spectra are accumulated, then optionally corrected for +atmospheric extinction, and the differences added together +with optional weighting using counting statistics. +Each instrument aperture is considered an independent +device. +.PP +Despite the apparently simple goal of this task, it is probably +the most complicated in the ONEDSPEC package due to the +bookkeeping load associated with automated handling of large data sets +having a number of properties associated with each spectrum (e.g +object or sky, aperture number, exposure times). +.PP +There are several modes in which BSWITCH can operate. The mode +appropriate to the IIDS and IRS assumes that the spectra +are input in an order such that after 2N (N=number of +instrument apertures) spectra have been +accumulated, an equal number of object and sky spectra have been +encountered in each aperture. +When in this mode, a check is made after 2N spectra +have been processed, and the optional extinction correction is +applied to the differences of the object minus sky, and then +(optionally weighted and) added into an accumulator for the aperture. +.PP +If the IIDS mode is switched off, then no guarantee can be +made that sky and object spectra pair off. If extinction +correction is required, it is performed on each spectrum +as it arrives, including sky spectra if any. The spectra are +then added into separate accumulators for object and sky for +each aperture after optional weighting is applied. +.PP +If after all spectra have been processed, there are no sky +spectra, the object spectrum is written out. If there is no +object spectrum, the sky spectrum is written out after +multiplying by -1. (This allows adding an object later on with +addsets, but the -1 multiply is probably a mistake.) +If at least one of each, object and sky spectra were encountered, +then the difference is computed and written out. Since +all accumulations are performed in count rates and later converted +back to counts, the object and sky spectra may have different +exposure times (non IIDS mode only). +.PP +A statistics file is maintained to provide an indication of the +quality of the individual spectra going into the sum. The +statistics information is maintained internally and only +written out after the sums have been generated. +The basic data in the file is the count rate of the spectrum +having the largest count rate, and the ratios of the count rates from +all other spectra to that one. +.PP +If weighting is selected, the weights are taken as proportional to +the count rate (prior to extinction correction) over a wavelength +delimited region of the spectrum. (Perhaps the weight +should be proportional to counts, not count rate.) +The default wavelength region is the entire spectrum. +If the total count rate is negative, the weight is assigned +a value of 0.0 and will be disregarded in the sum. (The counts +may be negative if the object minus sky difference approaches zero +on a bright and cloudy night.) +.PP +If extinction is selected, an extinction table is read from the +package calibration file. An optional additive term may be applied +as computed by the system sensitivity task SENSFUNC which is placed +in the parameter sensfunc.add_const. A revision to the standard +extinction table (delta extinction as a function of wavelength) +may be read from a text file whose name is specified by the parameter +sensfunc.rev_ext_file. The file format is that of a text file +having pairs of (wavelength, delta extinction) on each line. +[The option to solve for this function in SENSFUNC has not yet been +implemented, but BSWITCH can read the file that would be generated. +Thus, one can experiment with revisions, although this has never been +tested.] BSWITCH will interpolate the values given in the file +so that a course estimate of the revision may be entered, say if the +deltas at U, B, V, R, and I are known. +.PP +BEWARE that the extinction correction is performed assuming the +header parameters used for airmass refer to a "mean" airmass value +for the exposure. In general the header value is wrong! It usually +refers to the beginning, middle, or end of the exposure. I have +never seen a header airmass value which was an equivalent airmass +for the duration of the exposure. This is partly because there is +no way to compute a single effective airmass; it is a function +of wavelength, telescope position as a function of time, and +the extinction function. Fortunately, for most observations +this is not very significant. But anyone taking a one hour exposure near +3500 Angstroms at airmass values greater than 2, should not complain +when the fluxes look a bit odd. +.sp 1 +.SH +CALIBRATE +.PP +Having a system sensitivity function allows the data to be +placed on an absolute flux scale. CALIBRATE performs this +correction using the output sensitivity function from SENSFUNC. Operations are +keyed to the instrument aperture, and a system sensitivity +function is required for each observing aperture, although +this requirement may be overriden. +.PP +A valid exposure time is required (a value of 1.0 should +probably be assumed if not present) to compute the observed +count rate. Input counts are transformed to units of +ergs/cm2/sec/Angstrom (or optionally ergs/cm2/sec/Hz). +CALIBRATE will calibrate two dimensional images as well, applying the +sensitivity function to all image lines. +.PP +The operation is performed on a pixel-by-pixel basis so that +the defined sensitivity function should overlap precisely +with data in terms of wavelength. +.sp 1 +.SH +COINCOR +.PP +This task applies a statistical correction to each pixel +to account for undetected photoevents as a result of +coincidental arrival of photons. This is a detector +specific correcton, although the photoelectric detector +model provides a reasonable correction for many detectors +when a judicious value for the deadtime parameter is chosen. +This model assumes that the correction follows the +typical procedures applied to photoelectric photometer data: +.sp 1 +.DS L + Ic = Io * exp [Io * dt / T] +.DE +.sp 1 +where Ic is the corrected count rate in a pixel, Io is the +observed count rate in that pixel, dt is the detector deadtime, +and T is the observation integration time. +.PP +In addition to the photoelectric model, a more accurate model +is available for the IIDS and is included in COINCOR. This +model is taken from Goad (1979, SPIE Vol 172, 86.) and the correction +is applied as: +.sp 1 +.DS L + Ic = ln [1 - Io * t] / t +.DE +.sp 1 +where t is sweep time between pixel samples (t=1.424 msec). +The IIDS differs from a photomultiplier detector, in that +there is a fixed rate at which each pixel is sampled due to +time required for the dissector to sweep across the image tube +phospher whether a photoevent has occurred in a pixel or not. +The photomultiplier plus discriminator system +assumes that once a photoevent has been recorded, the detector is +dead until a fixed interval has elapsed. +.sp 1 +.SH +DISPCOR +.PP +If a relation is known linking pixel coordinate to user coordinate +(i.e. wavelength as a function of pixel number), then any non-linearities +can be removed by remapping the pixels to a linear wavelength coordinate. +This procedure, dispersion correction, is complicated by the +lack of a wavelength-pixel solution which is derived from data simultaneously +obtained with the object data. Any drifts in the detector then require +an interpolation among solutions for the solution appropriate to +the object observations. Depending on the detector, this interpolation +may be a function of the time of observation, temperature, or some telescope +parameter such as airmass. +When multiple solutions are available, DISPCOR will linearly interpolate +the solution in any available header parameter known to ONEDSPEC (see +section 3). +.PP +Each solution is read from the database file created by the IDENTIFY +task (in TWODSPEC$LONGSLIT), and the image name leading to that solution +is also read from the database file. The image is opened to extract +the header parameter to be used in the above interpolation. +A null name for the interpolation parameter indicates that none +is to be used. In this case, one of the options on the "guide" +parameter should be set to indicate what solution should be used. +The guide may be "precede", "follow", or "nearest" to select +the most appropriate choice for each spectrum. +.PP +If an explicit wavelength solution is to be used, the parameter +"reference" may be used to specify the image name of a comparison +spectrum to be used as the reference for the wavelength solution. +In this case all spectra will be corrected using a single solution - +no flexure correction will be applied. +.PP +If the parameter to be used for interpolation is a "time-like" +variable, such as RA, UT, ST, then the variable is discontinuous +at 24|0 hours. If UT is the chosen parameter (as has been the +case for IIDS and IRS spectra), the discontinuity occurs at +5 PM local Kitt Peak time. A comparison spectrum taken at 4:59PM +(=23:59h UT, =just before dinner), will be treated as an "end of +the night" observation rather than a beginning of the night +observation. To circumvent this error, the parameter, "time_wrap", +can be specified to a time at which a true zero should be assigned. +For UT at Kitt Peak, a choice like 17h UT (=10AM local, =asleep), +is an unlikely hour for nighttime observations to be made. Then for +a given night's observations, 17h UT becomes the new zero point in time. +.PP +Each solution in the database may be any of the forms legal +to IDENTIFY: legendre, chebyshev, spline3, or spline1 - the form +is encoded in the database and will automatically be recalled. +The interpolation in the solution is performed by locating the +pixel location for each required wavelength for the two +solutions bounding each observation and linearly interpolating +for the appropriate pixel location. One cannot simply interpolate +across the coefficients of the solutions to derive a new +single solution because the solutions may have different forms +or orders, so that the coefficients may have quite different +meanings. +.PP +Dispersion correction requires that there be equal intervals +of wavelength between pixels. The wavelength solution +is of a form describing the wavelength for a given pixel location, +not a pixel location for a given wavelength. So the solution +must be inverted. +.PP +The inversion to pixel location for wavelength is done in the +following way: The pixel coordinate in the solution is incremented +until the desired wavelength is bounded. The pixel value for the +desired wavelength is obtained by linearly interpolating across these +two bounding pixel locations. A linear approximation appears to be +very good for typical solutions, providing proper pixel locations to +better than 0.01 pixels. An improvement may be obtained by +increasing the order of the interpolation, but the improvement +is generally not warranted because the wavelength solutions +are rarely known to this accuracy. [Note that the use of real +and not double precision limits the precision of this technique! +For spectra longer than 50,000 pixels, the errors due to +the precision of reals can be serious.] +.PP +Note that a transformation to +a wavelength coordinate which is linear in the logarithm of +wavelength only requires that the inversion occur at wavelengths +selected by equal increments in the logarithm of wavelength. +.PP +During the actual remapping, 5 possible techniques are available. +Actually there are only two techniques: re-interpolation in 4 flavors, +and rebinning by partial pixel summation. The re-interpolation +may be performed with polynomials of order 1 (=linear), 3, or 5, +or by a cubic spline. The 3rd and 5th order polynomials may introduce +some ringing in the wings of strong, sharp, features, but the 5th order +is good at preserving the high frequency component of the data. +The linear and spline interpolators introduce significant smoothing. +The rebinning algorithm offers conservation of flux but also smooths +the data. In fact, rebinning to a course grid offers a good smoothing +algorithm. +.PP +At some future date, it would be a good idea to include a "synch" +function interpolator in the image interpolator package. This would +be a little slower to process, but results in very good frequency +response. +.PP +Other options in DISPCOR include "ids_mode" which forces spectra +from all apertures to a single output mapping (starting wavelength +and pixel-to-pixel increment), and "cols_out" forces the output spectra +to a specified length, zero-filling if necessary. +.PP +DISPCOR will correct two-dimensional data by applying the +remapping to all lines in the image. If the input two-dimensional +spectrum has only one line, the output spectrum will be written as +a one-dimensional spectrum. +.sp 1 +.SH +EXTINCT +.PP +Extinction is currently only available as a script file which drives +BSWITCH. This is possible by suppressing all options: weighting, +ids_mode, statistics file, and setting the subset pair size to the +number of instrument apertures. +.sp 1 +.SH +FLATDIV +.PP +This task divides the specified spectra by their flat field spectra. +This is not much more than an "en mass" spectrum divider, with the +exceptions that the header elements are used to key on the +aperture number so that the appropriate flat field spectrum is used, +and that the header processing flags are checked to prevent +double divisions and subsequently set after the division. Also, +division by zero is guarded by setting any zeroes in the flat field +spectrum to 1.0 prior to the division. +.sp 1 +.SH +FLATFIT +.PP +Pixel-to-pixel variations in the detector response can be removed +by dividing all observations by a flat field spectrum. +Flat field spectra are generally obtained by observing a source +having a continuous energy distribution, such as a tungsten filament +lamp. This is sometimes called a "quartz" lamp when the enclosing +glass bulb is made with quartz rather than silicon. The quartz +enclosure transmits ultraviolet light much better than glass. +.PP +If the color temperature of the source is very low (or very high, though +this is extremely unlikely), then a color term would be introduced +into the data when the flat is divided into the data. +Large scale variations in the system sensitivity also introduce a +color term into the flat - the same variations that are introduced into +any spectrum taken with the system. [Large scale variations are +evaluated by STANDARD and SENSFUNC, and removed by CALIBRATE.] +This is not of any particular importance except that counting +statistics are destroyed by the division. +.PP +To preserve the statistics, many find it desirable to divide by a flat +field spectrum which has been filtered to remove any large scale variations +but in which the pixel-to-pixel variations have been retained. +A filtered flat can be obtained by fitting a low order polynomial +through the spectrum and dividing the spectrum by the polynomial. +The result is a spectrum normalized to 1.0 and having high frequency +variations only. If one does not care to preserve the statistics, +then this procedure is not required. In fact, for certain instruments +(the IRS), the fitting and normalizing procedure is not recommended +because some intermediate order curvature can be introduced. +.PP +The purpose of FLATFIT is to find the combination of parameters +which produces a well flattened flat with a minimum of wiggles. +The usual curve fitting package is used to fit a function (chebyshev, +legendre, spline3, spline1) to the flats. Pixel rejection is +user selectable by a choice of cutoff sigmas, both above and below +the mean, and an optional growing region [A growing region is the number +of pixels on either side of one rejected which will also be rejected - +Growing regions are not recommended for most spectral applications]. +Any number of iterations may be used to further reject discrepant +pixels. The fitting may be performed interactively and controlled by cursor +keystrokes to select the fitting order, and other fit parameters. +.PP +Prior to the fit, the specified spectra are read, optionally corrected +for coincidence losses, and added to accumulators appropriate to +their instrument apertures. Each aperture is treated independently, +except that, the interactive fitting mode may be selected to operate +on the first aperture only, and then apply the same fitting parameters +to all other aperture accumulations. Or the interactive procedure +may be selected to operate on all apertures or none. +.PP +After the fit has been done, the fit is divided into the accumulation +and written as a new spectrum having a specified root name and a trailing +index indicating the aperture. +.sp 1 +.SH +IDENTIFY +.PP +This task (written by Frank Valdes) is used to identify features +in the comparison arcs to be used in the solution for a wavelength calibration. +The solution is performed interactively for at least one spectrum +and then optionally in a batch mode using REIDENTIFY. +IDENTIFY writes to a database file which will contain the solutions +generated from each input comparison spectrum. The database is +later used by DISPCOR to correct spectra according to the solution. +.sp 1 +.SH +IIDS +.PP +This script file initializes several hidden parameters in a +variety of tasks to values appropriate to the IIDS instrument. +There is also a script for the IRS. There should probably be +a script for resetting the parameters to a default instrument. +These parameters are: +.RS +.IP 1. +onedspec.calib_file - the package parameter indicating which file +should be used for standard star calibration data and the atmospheric +extinction table (=onedspec$iids.cl.) +.IP 2. +addsets.subset - the number of instrument apertures (=2). +.IP 3. +bswitch.ids_mode - assume and check for data taken in beam-switched +quadruple mode (=yes). +.IP 4. +coincor.ccmode - coincidence correction model (=iids). +.IP 5. +coincor.deadtime - detector deadtime (=1.424e-3 seconds) +.IP 6. +dispcor.flex_par - the name of the parameter to be used as the +guide to removing flexure during the observations (=ut). +.IP 7. +dispcor.time_wrap - the zero point to be adopted for the +flexure parameter if it is a time-like variable having a discontinuity +at 0/24 hours (=17). +.IP 8. +dispcor.idsmode - should data from all instrument apertures be dispersion +corrected to a uniform wavelength scale? (=yes). +.IP 9. +dispcor.cols_out - the number of columns (row length of the spectrum) +to which the output corrected spectrum should be forced during +mapping (=1024). +.IP 10. +extinct.nr_aps - the number of instrument apertures (=2). +.IP 11. +flatfit.order - the order of the fit to be used when fitting to +the flat field spectra (=6). +.IP 12. +flatfit.coincor - apply coincidence correction to the flat field +spectra during accumulations (=yes). +.IP 13. +flatdiv.coincor - apply coincidence correction to all spectra during +the flat field division process (=yes). +.IP 14. +identify.function - the fitting function to be used during the wavelength +solution process (=chebyshev). +.IP 15. +identify.order - the order of the fit to be used during the wavelength +solution process (=6). +.RE +.sp 1 +.SH +IRS +.PP +This script file initializes several hidden parameters in a +variety of tasks to values appropriate to the IRS instrument. +These parameters are: +.RS +.IP 1. +onedspec.calib_file - the package parameter indicating which file +should be used for standard star calibration data and the atmospheric +extinction table (=onedspec$irs.cl.) +.IP 2. +addsets.subset - the number of instrument apertures (=2). +.IP 3. +bswitch.ids_mode - assume and check for data taken in beam-switched +quadruple mode (=yes). +.IP 4. +coincor.ccmode - coincidence correction model (=iids). +.IP 5. +coincor.deadtime - detector deadtime (=1.424e-3 seconds) +.IP 6. +dispcor.flex_par - the name of the parameter to be used as the +guide to removing flexure during the observations (=ut). +.IP 7. +dispcor.time_wrap - the zero point to be adopted for the +flexure parameter if it is a time-like variable having a discontinuity +at 0/24 hours (=17). +.IP 8. +dispcor.idsmode - should data from all instrument apertures be dispersion +corrected to a uniform wavelength scale? (=yes). +.IP 9. +dispcor.cols_out - the number of columns (row length of the spectrum) +to which the output corrected spectrum should be forced during +mapping (=1024). +.IP 10. +extinct.nr_aps - the number of instrument apertures (=2). +.IP 11. +flatfit.order - the order of the fit to be used when fitting to +the flat field spectra. IRS users have frequently found that +any curvature in the fit introduces wiggles in the resulting +calibrations and a straight divide by the flat normalized to the +mean works best (=1). +.IP 12. +flatfit.coincor - apply coincidence correction to the flat field +spectra during accumulations (=no). +.IP 13. +flatdiv.coincor - apply coincidence correction to all spectra during +the flat field division process (=no). +.IP 14. +identify.function - the fitting function to be used during the wavelength +solution process (=chebyshev). +.IP 15. +identify.order - the order of the fit to be used during the wavelength +solution process. The IRS has strong deviations from linearity +in the dispersion and a fairly high order is required to correct +the dispersion solution (=8). +.RE +.sp 1 +.SH +ONEDUTIL +.PP +This is a group of utility operators for the ONEDSPEC package. They +are documented separately after the ONEDSPEC operators. ONEDUTIL +is a "pseudo-package" - it acts like a package under ONEDSPEC, but +many of its logical tasks are physically a part of ONEDSPEC. This +is done to minimize disk storage requirements, and to logically +separate some of the functions from the main ONEDSPEC menu which +was getting too large to visually handle. +.sp 1 +.SH +PROCESS +.PP +This task generally does not exist until the user executes the +script task BATCHRED which creates PROCESS.CL, a secondary script +file containing a CL command stream to batch process spectra. +The task is defined so that the CL is aware of its potential +existence. It is not declared as a hidden task so that the +user is also aware of its existence and may execute PROCESS +in the foreground or background. +.sp 1 +.SH +REIDENTIFY +.PP +This task (written b Frank Valdes) is intended to be used after +IDENTIFY has been executed. Once a wavelength solution has been +found for one comparison spectrum, it may be used as a starting point +for subsequent spectra having similar wavelength characteristics. +REIDENTIFY provides a batch-like means of performing wavelength solutions +for many spectra. The output solution is directed to a database text file +used by DISPCOR. +.sp 1 +.SH +SENSFUNC +.PP +This task solves for the system sensitivity function across +the wavelength region of the spectra by comparison of observations +of standard stars to their (assumed) known energy distribution. +Each instrument aperture is treated completely independently +with one exception discussed later. SENSFUNC is probably the +largest task in the ONEDSPEC package due to heavy use of +interactive graphics which represents more than half of the +actual coding. +.PP +Input to SENFUNC is the "std" text file produced by STANDARD +containing the ratio of the count rate adjusted for atmospheric extinction +to the flux of the star in ergs/cm2/s/Angstrom. Both the count rates and +fluxes are the average values in the pre-defined bandpasses tabulated +in the calibration file (indicated by the parameter onedspec.calib_file). +.PP +Each entry is the "std" file may have an independent set of wavelength sampling +points. After all entries have been loaded, a table containing all sampled +wavelengths is built (a "composite" wavelength table) and all sensitivity +values are reinterpolated onto this sampling grid. This allows the inclusion +of standards in which the observational samples are not uniform. +.PP +When multiple measurements are available, one of two corrections may +be applied to the data to account for either clouds or an additive extinction +term. The effect of clouds is assumed to be grey. Each contributing +observation is compared to the one producing the highest count rate ratio +at each wavelength sample. The deviation averaged over all wavelengths +for a given observation is derived and added back to +each wavelength sample for that observation. This produces a shift +(in magnitudes) which, on the average across the spectrum, accounts +for an extinction due to clouds. This process is called "fudge" +primarily for historical reasons (from the IPPS, R.I.P.) and also +because there is questionable justification to apply this correction. +One reason is so that one can better assess the errors +in the data after a zero-point correction has been made. +Another is that the sensitivity function is that closest to a cloud-free +sky so that claibrations may approach a true flux system if one +standard was observed during relatively clear conditions. +Alsom there are claims that the "color solution" is improved by "fudging", but +I admit that I don't fully understand this argument. +.PP +[Perhaps it goes as follows: +Although a grey scale correction is applied to each observation, +a color term is introduced in the overall solution. Consider the +case where 5 magnitudes of cloud extinction obscure one standard +relative to another. This star generates a sensitivity curve which +is a factor of 100 smaller. When averaged with the other curve, +any variations are lost, and the net curve will be +very similar to the first curve divided by 2. Now apply a "fudge" +of 5 magnitudes to the second curve. On the average, both curves have +similar amplitudes, so variations in the second now influence the +average. The net curve then has color dependent variations not +in the "un-fudged" net curve. If we assume that the variations in +the individual observations are not systematic, then "fudge" will +improve the net color solution. Amazing, isn't it? +End of hypothesis.] +.PP +The second form of correction is much more justifiable. In ONEDSPEC +it is referred to as a "grey shift" and accounts for possible +changes in the standard atmospheric extinction model due to +a constant offset. SENSFUNC will optionally solve for this constant +provided the observations sample a range of airmass values. +The constant is computed in terms of magnitudes per airmass, so +if the airmass range is small, then a large error is likely. +To solve for this value, a list of pairs of delta magnitude (from the +observation having the greatest sensitivity) as a function of +delta airmass (relative to the same observation) is generated +for all observations. The list is fit using a least squares solution +of the form: +.sp 1 +.DS L + delta_mag = delta_airmass * grey_shift +.DE +.sp 1 +Note that this is a restricted least-squares in the sense that there +is no zero-point term. The standard curve fit package in IRAF +does not support this option and the code to perform this is included +in SENSFUNC. +.PP +Because the atmosphere is likely to be the same one for observations +with each instrument aperture, it is not appropriate to limit +the least-squares solution to the individual apertures, but rather +to combine all the data to improve the solution. This would mean +that the user could not view the effects of applying the grey term +until all apertures had been analyzed. So, although each aperture is +solved independently to derive a preliminary value, a final value is +computed at the end when all data have been reviewed. This is the +one exception to the independent aperture equals independent +instrument philosophy. +.PP +When "fudging" is applied, the sensitivity function that is generated +is altered to account for the shifts to the observations. But when +the "grey shift" is computed, it cannot be directly applied to +the sensitivity function because it must be modified by the +observing airmass for each individual object. So the grey shift +constant is written into the image headers of the generated +sensitivity functions (which are IRAF images), and also placed +into the task parameter "add_const" to be used later by BSWITCH. +.PP +SENSFUNC can be run in an interactive mode to allow editing +of the sensitivity data. There are two phases of interaction: +(1) a review of the individual observations in which every data +element can be considered and edited, and (2) a review of the +composite sensitivity table and the calculated fit to the table. +In the interactive mode, both phases are executed for every instrument +aperture. +.PP +At both phases of the interactive modes there will be a plot of the +error in the input values for each wavelength. This is an RMS +error. [The IPPS plotted standard error which is always a smaller number +and represents the error in the mean; the RMS represents the error +in the sample. I'm not sure which is better to use, but RMS is easier +to understand. RMS is the same as the standard deviation.] +During phase one, the rms is computed as the standard deviation of +the sensitivity in magnitudes; but during phase two, it is computed +as the standard deviation in raw numbers +and then converted to a magnitude equivalent. The latter is more +correct but both converge for small errors. +.PP +There is one option in SENSFUNC which has never been tried and it won't +work - the option to enter a predefined table of sensitivities as +a function of wavelength as a simple text file. This option may +be useful a some time and should probably be fixed. I think the +only problem with it is a lack of consistency in the units. +.PP +An additional option has been requested but it is not clear that it +is a high priority item - the ability to compute the extinction +function. There may be instances when the mean extinction table +is not appropriate, or is not known. If sufficient data are +available (many observations of high precision over a range of airmasses +during a photometric night), then the extinction function is +calculable. Presently SENSFUNC can only compute a constant offset to +the extinction function, but the same algorithm used may be applied +at each wavelength for which observations are made to compute a +correction to an adopted extinction function (which may be zero), +and the correction can then be written out to the revised extinction +table file. This file will then be read by BSWITCH during the +extinction correction process. +So at each wavelength, pairs of delta magnitude as a function of +delta airmass are tabulated and fit as above: +.sp 1 +.DS L + delta_mag[lambda] = delta_airmass * delta_extinction[lambda] +.DE +.sp 1 +Because the data have been heavily subdivided into wavelength bins, +there are only a few measurements available for solving this +least-squares problem and the uncertainties are large unless many +observations have been taken. Experience has shown that at least +7-8 measurements are needed to come close, and 15 measurements are +about the minimum to get a good solution. Unless the data are of +high quality, the uncertainty in the solution is comparable to +the error in assuming a constant offset to the mean extinction function. +Nevertheless, the option should be installed at some time since +some observers do obtain the necessary data. +.sp 1 +.SH +SLIST +.PP +The spectrum specific header elements are listed in either a short +or long form. See the discussion on headers (section 3) for an explanation +of the terms. Values for airmass are printed if present in the header; +otherwise, the value is given as the string "?????" to indicate no +value present (even if one can be calculated from the telescope +pointing information elsewhere in the header). +.PP +The short form header lists only the image name, whether it is +an object or sky observation, the spectrum length, and the title. +.sp 1 +.SH +SPLOT +.PP +This is probably the second largest task in the ONEDSPEC package. It continues +to grow as users provide suggestions for enhancement, although +the growth rate appears to be slowing. SPLOT is an interactive +plot program with spectroscopy in mind, although it can be used +to plot two dimensional images as well. +.PP +SPLOT should still be considered a prototype - many of the algortihms +used in the analysis functions are crude, provided as interim +software to get results from the data until a more elaborate package +is written. It would probably be best to create an analysis specific +package - SPLOT is reasonably general, and to enhance it further +would complicate the keystroke sequences. +.PP +Ideally it should be possible to do anything to a spectrum with +a single keystroke. In reality, several keystrokes are required. +And after 15 or 20 functions have been installed, the keystroke +nomenclature becomes obscure - all the best keys are used up, and +you have to resort to things like '(' which is rather less +mneumonic than a letter. So some of the functionality in SPLOT +has been assigned to the "function" submenu invoked by 'f' and +exited by 'q' keystrokes. These include the arithmetic operators: +add, multiply by a constant, add, subtract, multiply, divide by +a spectrum, and logarithms, square root, inverse, and absolute +value of a spectrum. +.PP +Some of the analysis functions include: equivalent width, line centers, +flux integration under a line, smoothing, spectrum flattening, +and deblending of lines. +.PP +The deblender has serious limitations but handles about half the +cases that IIDS/IRS users are interested in. It fits only +Gaussian models to the blends, and only a single width parameter. +The fit is a non-linear least-squares problem, so starting values +present some difficulties. All starting values are initialized to 1.0 - +this includes the width, relative strengths of the lines, and deviation +from intial marked centers. The iterative solution usually converges +for high signal-to-noise data, but may go astray, resulting in +a numerical abort for noisy data. If this occurs, it is often +possible to find a solution by fitting to a single strong line +to force a better approximation to the starting values, and then refit +the blend of interest. +.PP +The non-linear least-squares routine is one obtained from an industrial +source. The code is very poorly written and in FORTRAN. No one should +attempt to understand it. The basic algorithm is an unconstrained simplex +minization search combined with a parabolic linear least-squares approximation +when in the region of a local minimum. +A test was made comparing this to the algorithm in Bevington, and the +Bevington algorithm appeared less likely to converge on noisy data. +Only one test case was used, so this is hardly a fair benchmark. +.PP +The problem with non-convergence is that a floating point error is +almost surely to arise. This is usually a floating point over/under +flow while computing an exponential (as required for a Gaussian). +In UNIX, there is apparently no easy way to discriminate from +FORTRAN which floating point exception has occurred, and so there +is no easy way to execute a fix up and continue. This is most +unfortunate because the nature of these non-linear techniques is +that given a chance, they will often recover from searching +down the wrong alley. A VMS version of the same routines seems to +survive the worst data because the error recovery is handled +somewhat better. [The VMS version also seems to run much faster, +presumably because the floating point library support is better +optimized.] +.PP +The net result of all this, is that a weird undocumented subroutine +is used which provides no error estimate. The Bevington routines +do provide an error estimate which is why I wanted to use them. +[In fact, there is no way to exactly compute the errors in the +fit of a non-linear least-squares fit. One can however apply +an approximation theory which assumes the hypersurface can be +treated locally as a linear function.] +.PP +There are several methods for computing equivalent widths in SPLOT. +The first method for measuring equivalent width is simply to integrate the +flux above/under a user defined continuum level. Partial pixels +are considered at the marked endpoints. A correction for the pixel size, +in Angstroms, is applied because the units of equivalent width are Angstroms. +You will probably get a different answer when doing equivalent +width measurements in channel mode ('$' keystroke) as compared to +wavelength mode ('p'). +.PP +Centering is performed as a weighted first moment of the region: +.sp 1 +.DS L + int1 = integral [ (I-Ic) * sqrt (I-Ic) * w] + int2 = integral [ (I-Ic) * sqrt (I-Ic) ] + xc = int1 / int2 +.DE +.sp 1 +where I is the intensity at the pixel at wavelength w, and Ic is +the estimated continuum intensity. The square root term provides +the weighting assuming photon statistics [sigma = sqrt(I)], and xc +is the derived center of the region. +.PP +An alternative method for equivalent widths was supplied by Caty +Pilachowski and is described in some detail in the help file for +SPLOT. This method is fast and insensitive to cursor settings, so +the user can really zip through a spectrum quickly. +.PP +Smoothing is performed using a simple boxcar smooth of user specified +size (in pixels). To handle edge effects, the boxcar size is +dynamically reduced as the edge is approached, thereby reducing +the smoothing size in those regions. +.PP +The flattening operator is a preliminary one, written before the +curve fitting package was available in IRAF. This operator +should probably be re-written to include the interactive +style used in FLATFIT. Currently the flattening is done +using classic polynomial least-squares with pixel rejection +chosen to preferentially reject absorption lines and strong +emission lines. The rejection process is repeated through +a number of iterations specifiable as a hidden parameter to SPLOT. +This is poorly done - the order of the fit and the number of +iterations should be controllable while in SPLOT. However, +experimentation has shown that for a given series of spectra, +the combination of rejection criteria, order, and iteration count +which works well on one spectrum will generally work well +on the other spectra. Note that the flatten operator attempts to +find a continuum level and normalize to that continuum, not to the +average value of the spectrum. +.PP +There are also the usual host of support operators - expansion, +overplotting, and so forth. There is also a pixel modifer mode +which connects two cursor positions. This forces a replot of the entire +spectrum after each pair of points has been entered. This should +probably be changed to inhibit auto-replot. +.PP +Some users have requested that all two cursor operators allow +an option to escape from the second setting in case the wrong +key was typed. I think this is a good idea, and might be implemented +using the "esc" key (although I could not seem to get this keystroke +through the GIO interface). +.PP +Another user request is the option to overplot many spectra with +autoscaling operational on the entire range. This is also a good +idea. Yet another improvement could be made by allowing the user +to specify the x and y range of the plot, rather than autoscaling. +.PP +There is one serious problem with respect to plotting spectra +corrected to a logarithmic wavelength scale. It would be nice to +plot these spectra using the logarithmic axis option, but this +option in GIO requires that at least one entire decade of x axis +be plotted. So for optical data, the x axis runs from 1000 Angstroms +to 10,000 Angstroms. Imagine a high dispersion plot having only 100 +Angstroms of coverage - the plot will look like a delta function! +The current version of SPLOT uses a linear axis but plots in +the log10 of wavelength. Not very good, is it. +.sp 1 +.SH +STANDARD +.PP +This task computes the sensitivity factor of the instrument +at each wavelength for which an a priori measured flux value is known +and within the wavelength range of the observations. +Sensitivity is defined as +[average counts/sec/Angstrom]/[average ergs/cm2/sec/Angstrom] +over the specified bandpass for which the star has been measured. +Both numerator and denominator refer to quantities above the +Earth's atmosphere and so the count rates must be corrected for +extinction. +The wavelengths of known measurements, the bandpasses, the +fluxes (in magnitudes), and the mean extinction table +are read from a calibration file whose name is specified +by the calib_file parameter (see LCALIB for a description of this +file). If a magnitude is exactly 0.0, it is assumed +that no magnitude is known for this star at the wavelength +having a 0.0 magnitude. This allows entries having incomplete +information. +.PP +As each observation is read, it is added into an accumulator for +its aperture. Or subtracted if it is a sky measurement. After +a pair of object and sky observations have been added, the +difference is corrected for extinction (as in BSWITCH), converted +to counts per second, and integrations performed over the bandpasses +for which flux measures are known. The bandpasses must be completely +contained within the spectrum - partial coverage of a bandpass +disqualifies it from consideration. The integrations are compared +with the known flux values and the ratio is written to a text +file (the "std" file) along with the wavelength of the measurement +and the total counts in the bandpass. The total counts value may +be used by SENSFUNC for weighting the measurements during averaging. +.PP +Many users are surprised by the order of the spectral names +printed out as STANDARD executes since the order is not necessarily +ascending through the spectrum list. This is because the name +printed is the name of the object spectrum most recently associated +with an object-sky pair. So if a sky pair is several spectra down the +list, an intervening object-sky pair taken through a different +instrument aperture may be processed in the meantime. +For example, say spectra 1-8 are taken so that object spectra +numbers 1 and 7 and sky spectra 3 and 5 are taken through aperture 0, +object spectra 4 and 6 and sky spectra 2 and 8 are taken through +aperture 1. [This is a very common pattern for IIDS/IRS users.] +Then spectrum 1 and 3 will pair up and be processed first (spectrum +name 1 will be printed). Then 4 and 2 (name 4 printed), then +7 and 5 (name 7 printed), and then 6 and 8 (name 6 printed). +So the order of names printed will be 1,4,7,6. Simple, isn't it? +.PP +If the input spectra are not taken in a beam-switched mode +then the parameter "beam_switch" should be set to no. +Then no sky subtraction will be attempted. +.PP +The user may enter sensitivity values directly into a file and use +it as the "std" file for a correction. +See the help file for STANDARD for a description of the entries in +the file, and see a typical file. +.PP +STANDARD offers a limited interactive mode. The first sky subtracted +spectrum is displayed and the bandpasses at which sensitivity +measurements are made will be shown as boxes. This provides a means +to see where the measurements are falling on the observational +data and to assess whether a bandpass may be including some +absorption edge which may be affecting the measurement. While it +is true that the wavelengths of the reference measurements should +fall in the same place, the effects of instrument resolution and +inaccuracies in the wavelength calibration may shift the positions +of the apparent bandpasses. The samples may then be biased. +.PP +The second purpose of the interactive mode is to allow the user +to artificially create new bandpasses on the fly. By placing the +cursor to bound a new wavelength region, STANDARD will interpolate +in the magnitude table of the reference star to estimate the magnitude +of the star at the bounded wavelength. The sensitivity will be calculated +at that wavelength just as if the bandpass had come from the calibration +file. This option should be exercised with care. Obviously, points +should not be generated between reference wavelengths falling on +strong absorption lines, or on a line either. This option is most useful +when at a high dispersion and few samples happen to fall in the +limited wavelength region. Sufficient space is allocated for 10 +artificial samples to be inserted. Once the artificial bandpasses +have been designated, they are applied to the entire sequence of +spectra for the current invocation of STANDARD. Once STANDARD +completes, the added bandpasses are forgotten. This prevents +an accidental usage of newly created bandpasses on stars of different +spectral types where a bandpass may fall in a region of continuum +for one star, but on an absorption line in another. +.sp 1 +.SH +SUBSETS +.PP +This is a simple task to subtract the second spectrum from the +first in a series of spectra. So if spectra 1-10 are input, +5 new spectra will be created from 1 minus 2, 3 minus 4, and so on. +This is a straight subtraction, pixel for pixel, with no +compensation for exposure time differences. +The header from the first spectrum of the pair is applied to the +output spectrum. +.sp 1 +.SH +The ONEDUTIL tasks +.PP +These utility tasks are logically separated from the ONEDSPEC +package. +.sp 1 +.SH +COEFS +.PP +This task reads the header parameters contained in comparison arc spectra +describing the wavelength solution generated by the mountain reduction +program and re-writes the solution parameters into a database +text file for use by DISPCOR. Otherwise those solutions would be +lost. COEFS assumes that the coefficients represent a Legendre +polynomial which is what the mountain reduction programs use. +.sp 1 +.SH +COMBINE +.PP +When an object has been observed over a wide range of wavelength +coverage by using more than one instrumental setup (such as +a blue and a red setting) or with different instruments (such +as IUE and the IRS), it is often desirable to combine the +spectra into a single spectrum. COMBINE will rebin a group of +spectra to new spectra having a single dispersion and average the +new spectra to create a single long spectrum. +If there are gaps in the composite spectrum, zeroes are used +as fillers. Ideally those pixels which have no known value +should be considered blank pixels. IRAF does not currently +support blank pixels, so zeroes are used for now. [One +might suggest using INDEF, but then all other routines will +have to check for this value.] +A side effect of choosing 0.0 is that during the averaging +of overlapping spectra, a true 0.0 will be ignored by COMBINE. +The basic rebinning algorithms used in DISPCOR are used in COMBINE +(and also REBIN). +.PP +The averaging can be weighted by exposure time, or by user assigned weights. +It would be better if each spectrum had an associated vector of +weights (one weight at each wavelength) so that the weighted averaging +could be done on a pixel basis. This is very expensive in terms +of both storage and file access overhead since each spectrum would +require twice the storage and number of files. +[Actually weights could be small 4 bit integers and take up very little space.] +.PP +A less ideal alternative would be to place a small number +(about 16) of weight parameters +in the header file which represent the approximate weights of that many +regions of the spectrum, and then one could interpolate in these parameters +for a weight appropriate to the pixel of interest. +.PP +A third solution (and even less ideal) +is to place a single parameter in the header which +represents an average weight of the entire spectrum. For the latter two cases, +the header weights could be derived from the average counts per +wavelength region - the region being the entire spectrum in the last case. +The weights must be entered into the header during the BSWITCH operation +since that is the last time that true counts are seen. [An implicit +assumption is that counts are proportional to photons. If data from +two different instruments are to be averaged, then the weights should be +expressed in photons because the ratio of counts to photons is highly +instrument dependent.] +.PP +COMBINE suffers from a partial pixel problem at the end points. +Interpolation at the ends can lead to an underestimate of the flux +in the last pixels because the final pixel is not filled. When averaging +in data from another spectrum or instrument, these pixels show up +as sharp drops in the spectrum. The problem appears due to the +rebinning algorithm and should be corrected someday (also in DISPCOR +and REBIN). +.sp 1 +.SH +LCALIB +.PP +This utility provides a means of checking the calibration files +containing the standard star fluxes and extinction table. +Any of the entries in the file may be listed out - the bandpasses, +extinction, standard star names, standard star fluxes in either +magnitudes, flambda, or fnu. For a description of the calibration +file format, see the help documentation for LCALIB. +.PP +The primary uses for LCALIB are to verify that new entries in +the tables are correct, to generate a list of standard star names +in a calibration file, and to produce a table of fluxes for a given standard +star. The table may then be used to generate a spectrum over a specified +wavelength region using SINTERP and overplotted with observational +data to check the accuracy of the reductions. +.sp 1 +.SH +MKSPEC +.PP +MKSPEC provides a way to generate a limited set of artificial +spectra. Noise generation is not available. The current options +are to generate a spectrum which is either a constant, a ramp, +or a black body. The spectrum may be two dimensional, but +all image lines will be the same. +.sp 1 +.SH +NAMES +.PP +This is the simplest task in the ONEDSPEC package. It +generates the image file names which are implied by a +root name and record string. The primary use for this +task is to generate a list of image names to be used +as input for some other program such as WFITS. +The output from NAMES can be redirected to file +and that file used with the "@file" notation for image +name input. An optional parameter allows an additional +string to be appended to the generated file name +to allow a subraster specification. +.sp 1 +.SH +REBIN +.PP +Spectra are rebinned to the wavelength parameters specified +by either matching to a reference spectrum or by user input. +The algorithms are those used by DISPCOR and the same options +for the interpolation method are available. REBIN is useful +when data are obtained with different instruments or setups +producing roughly comparable wavelength ranges and possibly +different dispersions, and the data are to be compared. +REBIN may also be used as a shift operator by specifying a +new starting wavelength. Or it may be used as a smoothing operator +by specifying a course dispersion. It may also be used +to convert between the two formats - linear in wavelength and +linear in the logarithm of wavelength. This latter option has +not been thoroughly exercised - proceed with caution. +.sp 1 +.SH +RIDSMTN +.PP +This task was stolen from the DATAIO package to make the following +modification: IIDS and IRS data are both written as 1024 pixel +spectra at the mountain. But the detectors do not produce a full +1024 pixels of acceptable data. In fact the IRS only has 936 pixels. +The data are written this way to conform to the IIDS ideal spectrum +which does have 1024 pixels, but the first few (about 6) are not usable. +To signal the good pixels, the IIDS/IRS header words NP1 and NP2 are +set to the beginning and ending good pixels. Actually NP1 points to +the first good pixel minus one. [Really actually NP1 and NP2 may be reversed, +but one is big and the other small so you can tell them apart.] +.PP +The version of RIDSMTN in ONEDUTIL keys off these parameters and writes +images containing only good pixels which means that the images will be +smaller than 1024 pixels. The user has the option of overriding the +header values with the task parameters "np1" and "np2". These may be +specified as 1 and 1024 to capture the entire set of pixels written to +tape or any other subset. Beware that np1 and np2 as task parameters +refer to the starting pixel and ending pixel respectively. None of this +nonsense about possible role reversals or "first good minus one" is +perpetuated. +.sp 1 +.SH +SINTERP +.PP +I think this is a handy little program. It provides a way to make +an IRAF spectral image from a table of values in a text file. +The table is interpolated out to any length and at any sampling +rate. A user can create a table of corrections to be applied to +a set of spectra, for example, use SINTERP to build a spectrum, +and run CALIBRATE to multiply a group of spectra by the correction. +.PP +The original raison d'etre for SINTERP was to create spectra of +standard stars from the listing of fluxes generated by LCALIB. +Using SPLOT the created spectrum can be overplotted with calibrated +observations to compare the true tabulated fluxes with the observed +fluxes. +.PP +SINTERP grew out of the task INTERP in the UTILITIES package +and works pretty much the same way. One major change is that +the table containing the x-y pairs is now stored in a dynamically +allocated array and can be as large as the user requests. The +default size is 1024 pairs, but the parameter tbl_size can +be set to a larger value. This then allows one to create a spectrum +from its tabulated values of wavelength and flux even if the +the table is several thousand elements long. +Note that the option to route the output from INTERP to +STDOUT has been retained if a new table is to be generated rather +than an IRAF image. +.PP +Another major change from INTERP is the use of the IRAF curve fitting +routines as an option. These were not originally available. +The choices now include linear or curvey interpolators, Legendre +or Chebyshev polynomial fits, and cubic or linear splines. +.sp 1 +.SH +WIDSTAPE +.PP +This task has vague origins in the DATAIO task WIDSOUT which writes +a tape having the format of the IDSOUT package which ran on the +CYBER (R.I.P.). For convenience to users this format has been +maintained for spectra having lengths up to 1024 pixels. +The version in DATAIO requires that the user enter all the header +parameters as task parameters. For several hundred spectra, this +approach is unwieldy. Because the ONEDSPEC package uses the header +parameters heavily, it is able to read them directly and write the +values to the tape file without user intervention. +.PP +The output tape (or diskfile) may be in either ASCII or EBCDIC format. +Spectra shorter than 1024 are zero filled. Each invocation of +the task write a new tape file followed by a tape mark (EOF). +.LP +.SH +3. Image Header Parameters +.PP +The ONEDSPEC package uses the extended image header to extract +information required to direct processing of spectra. If the +header information were to be ignored, the user would need to +enter observing parameters to the program at the risk of +typographical errors, and with the burden of supplying the +data. For more than a few spectra this is a tedious job, +and the image header information provides the means to eliminate +almost all the effort and streamline the processing. +.PP +However, this requires that the header information be present, +correct, and in a recognizable format. To meet the goal of +providing a functional package in May 1985, the first iteration +of the header format was to simply adopt the IIDS/IRS headers. +This allowed for processing of the data which would be first +used heavily on the system, but would need to be augmented at +a later date. The header elements may be present in any order, +but must be in a FITS-like format and have the following names +and formats for the value fields: +.sp 1 +.TS +l c l +l l l. +Parameter Value Type Definition + +HA SX Hour angle (+ for west, - for east) +RA SX Right Ascension +DEC SX Declination +UT SX Universal time +ST SX Sidereal time +AIRMASS R Observing airmass (effective) +W0 R Wavelength at center of pixel 1 +WPC R Pixel-to-pixel wavelength difference +NP1 I Index to first pixel containing good data (actually first-1) +NP2 I Index to last pixel containing good data (last really) +EXPOSURE I Exposure time in seconds (ITIME is an accepted alias) +BEAM-NUM I Instrument aperture used for this data (0-49) +SMODE I Number of apertures in instrument minus one (IIDS only) +OFLAG I Object or sky flag (0=sky, 1=object) +DF-FLAG I Dispersion fit made on this spectrum (I=nr coefs in fit) +SM-FLAG I Smoothing operation performed on this spectrum (I=box size) +QF-FLAG I Flat field fit performed on this spectrum (0=yes) +DC-FLAG I Spectrum has been dispersion corrected (0=linear, 1=logarithmic) +QD-FLAG I Spectrum has been flat fielded (0=yes) +EX-FLAG I Spectrum has been extinction corrected (0=yes) +BS-FLAG I Spectrum is derived from a beam-switch operation (0=yes) +CA-FLAG I Spectrum has been calibrated to a flux scale (0=yes) +CO-FLAG I Spectrum has been coincidence corrected (0=yes) +DF1 I If DF-FLAG is set, then coefficients DF1-DFn (n <= 25) exist +.TE +.PP +The values for the parameters follow the guidelines adopted for +FITS format tapes. All keywords occupy 8 columns and contain +trailing blanks. Column 9 is an "=" followed by a space. The value field +begins in column 11. Comments to the parameter may follow a "/" after +the value field. The value type code is as follows: +.RS +.IP SX +This is a sexigesimal string of the form '12:34:56 ' where the first +quote appears in column 11 and the last in column 30. +.IP R +This is a floating point ("real") value beginning in column 11 and +extending to column 30 with leading blanks. +.IP I +This is an integer value beginning in column 11 and extending to +column 30 with leading blanks. +.RE +.sp 1 +.PP +The parameters having FLAG designations all default to -1 to indicate +that an operation has not been performed. +The ONEDSPEC subroutines "load_ids_hdr" and "store_keywords" follow +these rules when reading and writing spectral header fields. +If not present in a header, load_ids_hdr will assume a value of zero +except that all flags are set to -1, and the object flag parameter +defaults to object. +.PP +When writing an image, only the above parameters are stored by store_keywords. +Other header information is lost. This needs to be improved. +.PP +Not all programs need all the header elements. The following table +indicates who needs what. Tasks not listed generally do not require +any header information. Header elements not listed are not used. +The task SLIST requires all the elements listed above. +The task WIDTAPE requires almost all (except NP1 and NP2). +The headings are abbreviated task names as follows: +.sp 1 +.nr PS 8 +.ps 8 +.TS +center; +l l | l l | l l. +ADD addsets COI coincor FIT flatfit +BSW bswitch COM combine REB rebin +CAL calibrate DIS dispcor SPL splot +COE coefs FDV flatdiv STA standard +.TE +.sp 1 +.TS +center, tab(/); +l | l | l | l | l | l | l | l | l | l | l | l | l. +Key/ADD/BSW/CAL/COE/COI/COM/DIS/FDV/FIT/REB/SPL/STA +_ +HA// X////////// X/ +RA// X////////// X/ +DEC// X////////// X/ +ST// X////////// X/ +UT// X////////// X/ +AIRMASS// X////////// X/ +W0// X/ X/// X//// X/ X/ X/ +WPC// X/ X/// X//// X/ X/ X/ +NP1/////////// X/// +NP2/////////// X/// +EXPOSURE/ X/ X/// X/ X///// X/// +BEAM-NUM// X/ X//// X/ X/ X// X/ X// +OFLAG// X////////// X/ +DF-FLAG//// X +DC-FLAG// X//// X//// X/ X/ X/ +QD-FLAG//////// X/ +EX-FLAG// X/ +BS-FLAG// X/ +CA-FLAG/ X// X//////// X/ +CO-FLAG///// X// +DFn//// X/ +.TE +.nr PS 11 +.ps 11 +.bp +.SH +Headers From Other Instruments +.PP +The header elements listed above are currently created only when reading +IIDS and IRS data from one of the specific readers: RIDSMTN and RIDSFILE. +The time-like parameters, (RA, DEC, UT, ST, HA), are created in a +compatible fashion by RCAMERA and RFITS (when the FITS tape is written +by the KPNO CCD systems). +.PP +For any other header information, the ONEDSPEC package is at a loss +unless the necessary information is edited into the headers with +an editing task such as HEDIT. This is not an acceptable long term +mode of operation, and the following suggestion is one approach to +the header problem. +.PP +A translation table can be created as a text file which outlines +the mapping of existing header elements to those required by the +ONEDSPEC package. A mapping line is needed for each parameter +and may take the form: +.sp 1 +.RS +.DC +1D_param default hdr_param key_start value_start type conversion +.DE +.RE +.sp 1 +where the elements of an entry have the following definitions: +.sp 1 +.TS +center, tab( ); +l lw(5i). +1D_param T{ +The name of the parameter expected by the ONEDSPEC package, +such as EXPOSURE, OFLAG, BEAM-NUM. +T} + +default T{ +A value to be used if no entry is found for this parameter or if +no mapping exists. +T} + +hdr_param T{ +The string actually present in the existing image header to be +associated with the ONEDSPEC parameter. +T} + +key_start T{ +The starting column number at which the string starts +in the header. +T} + +value_start T{ +The starting column number at which the string describing the +value of the parameter starts in the header. +T} + +type T{ +The format type of the parameter: integer, real, string, boolean, +sexigesimal. +T} + +conversion T{ +If the format type is string, a further conversion may +optionally be made to one of the formats listed under type. +The conversion may requires some expression evaluation. +T} +.TE +.sp 1 +.PP +Consider the example where the starting wavelength of a +spectrum is contained in a FITS-like comment and the object- +sky flag in a similar fashion: +.sp 1 +.DS + COMMENT = START-WAVE 4102.345 / Starting wavelength + COMMENT = OBJECT/SKY 'SKY '/ Object or Sky observation +.DE +.sp 1 +The translation file entries for this would be: +.sp 1 +.DS + W0 0.0 START-WAVE 12 24 R + OFLAG 0 OBJECT/SKY 12 25 S SKY=0;OBJECT=1 +.DE +.sp 1 +The first entry is fairly simple. The second requires an expression +evaluation and second conversion. +.PP +A translation file can be built for each instrument and its +special header format, and the file name can be associated with a +ONEDSPEC package parameter. The two subroutines in ONEDSPEC dealing +directly with the headers (load_ids_hdr and store_keywords) +can be modified or replaced to access this file and +translate the header elements. diff --git a/noao/onedspec/doc/sys/onedv210.ms b/noao/onedspec/doc/sys/onedv210.ms new file mode 100644 index 00000000..431c84f5 --- /dev/null +++ b/noao/onedspec/doc/sys/onedv210.ms @@ -0,0 +1,680 @@ +.nr PS 9 +.nr VS 11 +.de LS +.RT +.if \\n(1T .sp \\n(PDu +.ne 1.1 +.if !\\n(IP .nr IP +1 +.if \\n(.$-1 .nr I\\n(IR \\$2n +.in +\\n(I\\n(IRu +.ta \\n(I\\n(IRu +.if \\n(.$ \{\ +.ds HT \&\\$1 +.ti -\\n(I\\n(IRu +\\*(HT +.br +.. +.ND +.TL +ONEDSPEC/IMRED Package Revisions Summary: IRAF Version 2.10 +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +May 1992 +.NH +Introduction +.LP +The IRAF NOAO spectroscopy software, except for the \fBlongslit\fR +package, has undergone major revisions. The revisions to the aperture +extraction package, \fBapextract\fR, are described in a separate +document. This paper addresses the revisions in the \fBonedspec\fR +package and the spectroscopic image reduction packages in the +\fBimred\fR package. In addition to the revisions summary given here +there is a new help topic covering general aspects of the new +\fBonedspec\fR package such as image formats, coordinate systems, and +units. This help topic is referenced under the name +"onedspec.package". +.LP +There are a large number of revisions both minor and major. To avoid +obscuring the basic themes and the major revisions in a wealth of minor +detail, this document is organized into sections of increasing detail. The +most important aspects of the revisions are described in a major highlight +section followed by a minor highlight section. Then a reorganization chart +for the \fBonedspec\fR package is presented showing where various +tasks have been moved, which have been deleted, and which are new. +Finally, a summary of the revisions to each task is presented. +.LP +I hope that the many new capabilities, particularly as presented in the +highlight section, will outweigh any disruption in accomodating to so +many changes. +.NH +Major Highlights +.LP +The major highlights of the revisions to the NOAO spectroscopy software +are listed and then discussed below. + +.DS +\(bu Non-linear dispersion calibration +\(bu Integration of dispersion coordinates with the core system +\(bu Sinc interpolation +\(bu Plotting in user selected units including velocity +\(bu Integration of long slit spectra and 1D formats +\(bu New \fBimred\fR packages featuring streamlined reductions +.DE + +Possibly the most significant revision is the generalization allowing +non-linear dispersion calibration. What this means is that spectra do +not need to be interpolated to a uniform sampling in wavelength or +logarithmic wavelength. The dispersion functions determined from +calibration arc lines by \fBidentify\fR, \fBreidentify\fR, +\fBecidentify\fR, or \fBecreidentify\fR can be simply assigned to the +spectra and used throughout the package. It is also possible to assign +a dispersion table or vector giving the wavelengths at some or all of +the pixels. Note, however, that it is still perfectly acceptible to +resample spectra to a uniform linear or log-linear dispersion as was +done previously. +.LP +For data which does not require geometric corrections, combining, or +separate sky subtraction the observed sampling need never be changed +from the original detector sampling, thus avoiding any concerns over +interpolation errors. In other cases it is possible to just +interpolate one spectrum, say a sky spectrum, to the dispersion of +another spectrum, say an object spectrum, before operating on the two +spectra. There are several new tasks that perform interpolations to a +common dispersion, not necessarily linear, when operating on more than +one spectrum. In particular, the new task \fBsarith\fR and the older +task \fBsplot\fR now do arithmetic on spectra in wavelength space. +Thus, one no longer need be concerned about having all spectra +interpolated to the same sampling before doing arithmetic operations as +was the case previously. +.LP +The trade-off in using non-linear dispersion functions is a more complex +image header structure. This will make it difficult to import to non-IRAF +software or to pre-V2.10 IRAF systems. However, one may resample to a +linear coordinate system in those cases before transfering the spectra as +FITS images having standard linear coordinate keywords. +.LP +On the subject of interpolation, another important addition is the +implementation of sinc interpolation. This is generally considered +the best interpolation method for spectra, however, it must be used +with care as described below. +Sinc interpolation approximates applying a phase shift to the fourier +transform of the spectrum. Thus, repeated interpolations do not accumulate +errors (or nearly so) and, in particular, a forward and reverse +interpolation will recover the original spectrum much more closely than +other interpolation methods. However, for undersampled (where the fourier +transform is no longer completely represented), strong features, such as +cosmic rays or narrow emission or absorption lines, the ringing can be much +more severe than the polynomial interpolations. The ringing is especially +a concern because it extends a long way from the feature causing the +ringing; 30 pixels with the truncated algorithm that has been added. Note +that it is not the truncation of the interpolation function which is at +fault but the undersampling of the narrow features! +.LP +Because of the problems seen with sinc interpolation it should be used with +care. Specifically, if there are no undersampled, narrow features it is a +good choice but when there are such features the contamination of the +spectrum by ringing is more severe, corrupting more of the spectrum, +than with other interpolation types. +.LP +The dispersion coordinates are now interfaced through the IRAF WCS +(world coordinate system) interface. This is important to users for +two reasons. First, operations performed on spectral images by IRAF +core system tasks and the IRAF image I/O system will have access to the +dispersion coordinates and will properly modify them as necessary. The +most common such operation is applying an image section to a spectrum +either during an image copy or as input to another task. In this case +the relation between the pixels in the image section and their +wavelengths is preserved. For example one may \fBsplot\fR a section of +a large spectrum and get the correct wavelengths. The second reason is +to allow use of proper dispersion coordinates in such IRAF tasks as +\fBlistpixels\fR, \fBimplot\fR, and \fBgraph\fR. +.LP +The new package supports a variety of spectral image formats. The +older formats are understood when reading them. In particular the one +dimensional "onedspec" and the two dimensional "multispec" format will +still be acceptable as input. Note that the image naming syntax for +the "onedspec" format using record number extensions is a separate +issue and is still provided but only in the \fBimred.iids\fR and +\fBimred.irs\fR packages. Any new spectra created are either a one +dimensional format using relatively simple keywords and a two or three +dimensional format which treats each line of the image as a separate +spectrum and uses a more complex world coordinate system and keywords. +For the sake of discussion the two formats are still called "onedspec" +and "multispec" though they are not equivalent to the earlier formats. +.LP +In addition, the one dimensional spectral tasks may also now operate on +two dimensional images directly. This is done by using the DISPAXIS +keyword in the image header or a package dispaxis parameter if the +keyword is missing to define the dispersion axis. In addition there is +a summing parameter in the packages to allow summing a number of lines +or columns. If the spectra are wavelength calibrated long slit +spectra, the product of the \fBlongslit.transform\fR task, the +wavelength information will also be properly handled. Thus, one may +use \fBsplot\fR or \fBspecplot\fR for plotting such data without having +to extract them to another format. If one wants to extract one +dimensional spectra by summing columns or lines, as opposed to using +the more complex \fBapextract\fR package, then one can simply use +\fBscopy\fR (this effectively replaces \fBproto.toonedspec\fR). +.LP +The tasks \fBsplot\fR and \fBspecplot\fR allow use of and changes +between various dispersion units. Spectra may be plotted in units all +the way from Hertz to Mev. The units may also be inverted to plot in +wavenumbers, such as inverse centimeters, and the decimal log may be +applied, to plot something like log wavelength or log frequency. One +special "unit" which is available is a velocity computed about a +specified wavelength/frequency. The multiple unit capability was one +of the last major changes made before the V2.10 release so the complete +generalization to arbitrary units has not been completed. Dispersion +calibration and image world coordinate system generally must still be +done in Angstroms, particularly if flux calibration is to be done. The +generalization to other units throughout the package is planned for a +later release. +.LP +The last of the changes catagorized as a major highlight is the +addition of a number of special packages for generic or specific +types of instruments and data in the \fBimred\fR package. Most of these +package include a highly streamlined reduction task that combines +all of the reduction operations into a single task. For example, +the \fBspectred.doslit\fR task can extract object, standard star, and +arc spectra from long slit images, apply a consistent dispersion +function based on only a single interactively performed dispersion +solution, compute a sensitivity function and end up with flux +calibrated spectra. Another example, is \fBhydra.dohydra\fR for +extracting, flatfielding, dispersion calibrating, and sky subtracting +spectra from the NOAO Hydra multifiber spectrograph. There are user's +guides for each of these new reduction tasks. +.NH +Minor Highlights +.LP +There are some further highlights which are also quite important +but which are secondary to the previous highlights. These are listed +and discussed below. + +.DS +\(bu Greater use of package parameters +\(bu An observatory database +\(bu A more flexible \fBidentify/reidentify\fR +\(bu Only one \fBdispcor\fR +\(bu Spatial interpolation of dispersion solutions +\(bu Deblending of arbitrary number of gaussian components +\(bu Manipulating spectral formats +\(bu Improved fitting of the continuum and related features +\(bu Various new tasks +.DE + +There is an even greater use of package parameters than in the previous +release. Package parameters are those which are common to many of the +the tasks in the package and which one usually wants to change in +one place. The new package parameters are the default observatory for +the data if the observatory is not identified in the image header +(discussed further below), the interpolation type used +when spectra need to be resampled either for dispersion calibration +or when operating on pairs of spectra with different wavelength +calibration, and the default dispersion axis and summing parameters +for long slit and general 2D images (as discussed in the last section). +You will find these parameters not only in the \fBonedspec\fR package but in +all the spectroscopic packages in the \fBimred\fR package. +.LP +A number of spectroscopic tasks require information about the location +of the observation. Typically this is the observatory latitude for +computing air masses if not defined in the header. Radial velocity +tasks, and possible future tasks, may require additional information +such as longitude and altitude. The difficulty is that if such +parameters are specified in parameter files the default may well be +inappropriate and even if the users set then once, they may forget to +update them in later reductions of data from a different observatory. +In other words this approach is prone to error. +.LP +To address this concern observatory parameters are now obtained from an +observatory database keyed by an observatory identifier. If the image data +contains an observatory keyword, OBSERVAT, the tasks will look up the +required parameters from the observatory database. Thus, if the images +contain the observatory identifier, as does data from the NOAO +observatories, they will always be correctly reduced regardless of the +setting of any parameters. Of course one has to deal with data from +observatories which may not include the observatory identifier and may not +have an entry in the observatory database. There are provisions for sites +and individual users to define local database files and to set the default +observatory parameters. This is all discussed in the help for the +\fBobservatory\fR task. +.LP +The dispersion function fitting tasks \fBidentify\fR and +\fBreidentify\fR have been improved in a number of important ways. +These tasks now treat the input images as units. So for long slit and +multispectrum images one can move about the image with a few +keystrokes, transfer solutions, and so on. When transfering solutions +between a multispectrum reference image and another multispectrum image +with the same apertures using \fBreidentify\fR, the features and +dispersion solutions are transfered aperture by aperture. This avoids +problems encountered by having to trace successively between apertures +and having the apertures be in the same order. +.LP +On the subject of tracing in \fBreidentify\fR, in some cases it is +desirable to use the same reference spectrum with all other sampled +lines or columns in a long slit spectrum or apertures in a +multispectrum image rather than propagating solutions across the +image. The latter method is necessary if there is a continuous and +progress shift in the features. But if this is not the situation then +the loss of features when tracing can be a problem. In this case the +alternative of reidentifying against the same starting reference is now +possible and there will not be the problem of an increasing loss of +features. On the other hand, the problem of lost features, whether +tracing or not, can also be addressed using another new feature of +\fBreidentify\fR, the ability to add features from a line list. For +both tracing and nontracing reidentifications, another useful new +feature is automatic iterative rejection of poorly fitting lines in +determining a new dispersion function noninteractively. +.LP +The nontracing reidentifications, the automatic addition of new lines, and +the iterative rejection of poorly fitting lines in determining a new +dispersion function are all responses to make the reidentification process +work better without intervention. However, as a last resort there is also +a new interactive feature of \fBreidentify\fR. By monitoring the log output of +the reidentification process one can have a query be made after the +automatic reidentification and function fitting to allow selectively +entering the interactive feature identification and dispersion function +fitting based on the logged output. Thus if a fit has a particularly large +RMS or a large number of features are not found one can chose to intervene +in the reidentification process. +.LP +Dispersion calibration is now done exclusively by the task +\fBdispcor\fR regardless of the spectrum format or dispersion solution +type; i.e. solutions from \fBidentify\fR or \fBecidentify\fR. In addition to +allowing assignment of non-linear dispersion functions, as described +earlier, \fBdispcor\fR has other new features. One is that, in +addition to interpolating dispersion solutions between two calibration +images (usually weighted by time), it is now possible to interpolate +zero point shifts spatially when multiple spectra taken simultaneously +include arc spectra. This is mostly intended for the new generation of +multifiber spectrographs which include some fibers assigned to an arc +lamp source. However, it can be used for the classic photographic case +of calibration spectra on the same plate. +.LP +The limitation to four lines on the number of gaussian components which +can be deblended by the deblending option in \fBsplot\fR has been removed. +A new feature is that line positions may be input from a line list as +well as the original cursor marking or terminal input. +In addition an option to simultaneously determine a linear background +has been added. As a spinoff of the deblending option a new, noninteractive +task, called FITPROFS, has been added. This task takes a list of initial +line positions and sigmas and simultaneously fits gaussians with a +linear background. One can constrain various combination of parameters +and output various parameters of the fitting. While it can be used to +fit an entire spectrum it becomes prohibitively slow beyond a number like +30. A banded matrix approach is required in that case. +.LP +As mentioned earlier there is a new task called \fBscopy\fR for manipulating +spectra. It allows changing between various formats such as producing +the separate, simple keyword structure, one dimensional images from multispec +format images, combining multiple one dimensional spectra into the +more compact multispec format, and extracting line or column averaged one +dimensional spectra from two dimensional images. It can also be +used to select any subset of apertures from a multispec format, +merge multiple multispec format spectra, and extract regions of spectra +by wavelength. +.LP +The \fBcontinuum\fR task has been revised to allow independent +continuum fits for each aperture, order, line, or column in images +containing multiple spectra. Instead of being based on the +\fBimages.fit1d\fR task it is based on the new task \fBsfit\fR. +\fBSfit\fR allows fitting the \fBicfit\fR functions to spectra and +outputing the results in several ways such as the ratio (continuum +normalization), difference (continuum subtraction), and the actual +function fit. In addition it allows outputing the input data with +points found to be deviant by the iterative rejection algorithm of +\fBicfit\fR replaced by the fitted value. This is similar to +\fBimages.lineclean\fR. In all cases, this is may be done +independently and interactively or noninteractively when there are +multiple spectra in an image. +.LP +A number of useful new tasks have already been mentioned: +\fBfitprofs\fR, \fBsarith\fR, \fBscombine\fR, \fBscopy\fR, and +\fBsfit\fR. There are two more new tasks of interest. The task \fBdopcor\fR +applies doppler shifts to spectra. It applies the shift purely to the +dispersion coordinates by adding a redshift factor which is applied by +the coordinate system interface. This eliminates reinterpolation and +preserves both the shift applied and the original observed dispersion +function (either linear or nonlinear). The task can also modify the +pixel values for various relativistic and geometric factors. This task +is primarily useful for shifting spectra at high redshifts to the local +rest frame. The second new task is called \fBderedden\fR. It applies +corrections for interstellar reddening given some measure of the +extinction along the line of site. +.NH +ONEDSPEC Package Task Reorganization +.LP +The \fBonedspec\fR package dates back to the earliest versions of IRAF. Some of +its heritage is tied to the reduction of IRS and IIDS spectra. One of +the revisions made for this release has been to reorganize the various +tasks and packages. A few tasks have been obsoleted by new tasks or +the functionality of the new dispersion coordinate system, a number +of new tasks have been added, and a number of IRS and IIDS specific +tasks have been moved to the \fBimred\fR packages for those instruments. +While these packages are organized for those particular instruments they may +also be used by data having similar characteristics of beam switching, +coincidence corrections, and the requirement of sequential numeric +extensions. +.LP +The table below provides the road map to the reorganization showing +tasks which have disappeared, been moved, been replaced, or are new. + +.DS +.TS +center; +r l l l r l l. +V2.9 V2.10 ALTERNATIVE V2.9 V2.10 ALTERNATIVE + +addsets irs/iids process irs/iids +batchred irs/iids rebin scopy/dispcor +bplot bplot refspectra refspectra +bswitch irs/iids reidentify reidentify +calibrate calibrate sapertures +coincor iids sarith +combine scombine scombine +continuum continuum scopy + deredden sensfunc sensfunc +dispcor dispcor setdisp hedit + dopcor sextract scopy + fitprofs sfit +flatdiv irs/iids sflip scopy/imcopy [-*,*] +flatfit irs/iids shedit hedit +identify identify sinterp sinterp +lcalib lcalib slist slist +mkspec mkspec specplot specplot +names names splot splot + ndprep standard standard +observatory noao subsets irs/iids +powercor iids sums irs/iids +.TE +.DE +.NH +IMRED Packages +.LP +Many of the \fBonedspec\fR tasks from the previous release have been +moved to the \fBiids\fR and \fBirs\fR packages, as indicated above, +since they were applicable only to these and similar instruments. +.LP +A number of new specialized spectroscopic instrument reduction packages +have been added to the \fBimred\fR package. Many of these have been in +use in somewhat earlier forms in the IRAF external package called +\fBnewimred\fR. In addition the other spectroscopic package have been +updated based on the revisions to the \fBonedspec\fR and +\fBapextract\fR packages. Below is a table showing the changes between +the two version and describing the purpose of the spectroscopic +packages. Note that while many of these package are named for and +specialized for various NOAO instruments these packages may be applied +fairly straightforwardly to similar instruments from other +observatories. In addition the same tools for multifiber and slit +spectra are collected in a generic package called \fBspecred\fR. + +.DS +.TS +center; +r l l s +r l l l. +V2.9 V2.10 SPECTROSCOPY PACKAGE + argus Fiber: CTIO Argus Reductions +specphot ctioslit Slit: CTIO Slit Instruments +echelle echelle Fiber Slit: Generic Echelle + hydra Fiber: KPNO Hydra (and Nessie) Reductions +iids iids Scanner: KPNO IIDS Reductions +irs irs Scanner: KPNO IRS Reductions +coude kpnocoude Fiber/Slit: KPNO Coude (High Res.) Reductions + kpnoslit Slit: KPNO Slit Instruments +msred specred Fiber/Slit: Generic fiber and slit reductions +observatory -> noao +setairmass +.TE +.DE +.LP +An important feature of most of the spectroscopic packages are specialized +routines for combining and streamlining the different reduction operations +for a particular instrument or type of instrument. These tasks are: + +.DS +.TS +center; +r r r. +argus.doargus ctioslit.doslit echelle.doecslit +echelle.dofoe hydra.dohydra iids.batchred +irs.batchred kpnocoude.do3fiber kpnocoude.doslit +kpnoslit.doslit specred.dofibers specred.doslit +.TE +.DE +.NH +ONEDSPEC Task Revisions in V2.10 +.LS ADDSETS 2 +Moved to the \fBiids/irs\fR packages. +.LS BATCHRED +Moved to the \fBiids/irs\fR packages. +.LS BPLOT +The APERTURES and BAND parameters been added to select +apertures from multiple spectra and long slit images, and bands +from 3D images. Since the task is a script calling \fBsplot\fR, the +many revisions to that task also apply. The version in the +\fBiids/irs\fR packages selects spectra using the record number +extension syntax. +.LS BSWITCH +Moved to the \fBiids/irs\fR packages. +.LS CALIBRATE +This task was revised to operate on nonlinear dispersion +corrected spectra and 3D images (the \fBapextract\fR "extras"). The +aperture selection parameter was eliminated (since the header +structure does not allow mixing calibrated and uncalibrated +spectra) and the latitude parameter was replaced by the +observatory parameter. The observatory mechanism insures that +if the observatory latitude is needed for computing an airmass +and the observatory is specified in the image header the +correct calibration will be applied. The record format syntax +is available in the \fBiids/irs\fR packages. The output spectra are +coerced to have real pixel datatype. +.LS COINCOR +Moved to the \fBiids\fR package. +.LS COMBINE +Replaced by \fBscombine\fR. +.LS CONTINUUM +This task was changed from a script based on \fBimages.fit1d\fR to a +script based on \fBsfit\fR. This provides for individual independent +continuum fitting in multiple spectra images and for additional +flexibility and record keeping. The parameters have been +largely changed. +.LS DEREDDEN +This task is new. +.LS DISPCOR +This is a new version with many differences. It replaces the +previous three tasks \fBdispcor\fR, \fBecdispcor\fR and \fBmsdispcor\fR. It +applies both one dimensional and echelle dispersion functions. +The new parameter LINEARIZE selects whether to interpolate the +spectra to a uniform linear dispersion (the only option +available previously) or to assign a nonlinear dispersion +function to the image without any interpolation. The +interpolation function parameter has been eliminated and the +package parameter INTERP is used to select the interpolation +function. The new interpolation type "sinc" may be used but +care should be exercised. The new task supports applying a +secondary zero point shift spectrum to a master dispersion +function and a spatial interpolation of the shifts when +calibration spectra are taken at the same time on a different +region of the same 2D image. The optional wavelength table may +now also be an image to match dispersion parameters. The +APERTURES and REBIN parameters have been eliminated. If an +input spectrum has been previously dispersion corrected it will +be resampled as desired. Verbose and log file parameters have +been added to log the dispersion operations as desired. The +record format syntax is available in the \fBiids/irs\fR packages. +.LS DOPCOR +This task is new. +.LS FITPROFS +This task is new. +.LS FLATDIV +Moved to the \fBiids/irs\fR packages. +.LS FLATFIT +Moved to the \fBiids/irs\fR packages. +.LS IDENTIFY +The principle revision is to allow multiple aperture images and +long slit spectra to be treated as a unit. New keystrokes +allow jumping or scrolling within multiple spectra in a single +image. For aperture spectra the database entries are +referenced by image name and aperture number and not with image +sections. Thus, \fBidentify\fR solutions are not tied to specific +image lines in this case. There is a new autowrite parameter +which may be set to eliminate the save to database query upon +exiting. The new colon command "add" may be used to add +features based on some other spectrum or arc type and then +apply the fit to the combined set of features. +.LS LCALIB +This task has a more compact listing for the "stars" option and +allows paging a list of stars when the star name query is not +recognized. +.LS MKSPEC +This task is unchanged. +.LS NAMES +This task is unchanged. +.LS NDPREP +This task was moved from the \fBproto\fR package. It was originally +written at CTIO for CTIO data. It's functionality is largely +unchanged though it has been updated for changes in the +\fBonedspec\fR package. +.LS OBSERVATORY +New version of this task moved to \fBnoao\fR root package. +.LS POWERCOR +Moved to the \fBiids\fR package. +.LS PROCESS +Moved to the \fBiids/irs\fR package. +.LS REBIN +This task has been eliminated. Use \fBscopy\fR or \fBdispcor\fR. +.LS REFSPECTRA +A group parameter was added to allow restricting assignments by +observing period; for example by night. The record format +option was removed and the record format syntax is available in +the \fBiids/irs\fR packages. +.LS REIDENTIFY +This task is a new version with many new features. The new +features include an interactive options for reviewing +identifications, iterative rejection of features during +fitting, automatic addition of new features from a line list, +and the choice of tracing or using a single master reference +when reidentifying features in other vectors of a reference +spectrum. Reidentifications from a reference image to another +image is done by matching apertures rather than tracing. New +apertures not present in the reference image may be added. +.LS SAPERTURES +This task is new. +.LS SARITH +This task is new. +.LS SCOMBINE +This task is new. +.LS SCOPY +This task is new. +.LS SENSFUNC +The latitude parameter has been replaced by the observatory +parameter. The 'i' flux calibrated graph type now shows flux +in linear scaling while the new graph type 'l' shows flux in +log scaling. A new colon command allows fixing the flux limits +for the flux calibrated graphs. +.LS SETDISP +This task has been eliminated. Use \fBhedit\fR or the package +DISPAXIS parameter. +.LS SEXTRACT +Replaced by \fBscopy\fR. +.LS SFIT +This task is new. +.LS SFLIP +This task has been eliminated. Use image sections. +.LS SHEDIT +This task has been eliminated. Use \fBhedit\fR if needed. +.LS SINTERP +This task is unchanged. +.LS SLIST +This task was revised to be relevant for the current spectral +image formats. The old version is still available in the +\fBiids/irs\fR package. +.LS SPECPLOT +New parameters were added to select apertures and bands, plot +additional dimensions (for example the additional output from +the extras option in \fBapextract\fR), suppress the system ID banner, +suppress the Y axis scale, output a logfile, and specify the +plotting units. The PTYPE parameter now allows negative +numbers to select histogram style lines. Interactively, the +plotting units may be changed and the 'v' key allows setting a +velocity scale zero point with the cursor. The new version +supports the new spectral WCS features including nonlinear +dispersion functions. +.LS SPLOT +This is a new version with a significant number of changes. In +addition to the task changes the other general changes to the +spectroscopy packages also apply. In particular, long slit +spectra and spectra with nonlinear dispersion functions may be +used with this task. The image header or package dispaxis and +nsum parameters allow automatically extracting spectra from 2D +image. The task parameters have been modified primarily to +obtain the desired initial graph without needing to do it +interactively. In particular, the new band parameter selects +the band in 3D images, the units parameter selects the +dispersion units, and the new histogram, nosysid, and xydraw +options select histogram line type, whether to include a system +ID banner, and allow editing a spectrum using different +endpoint criteria. +.LS +Because nearly every key is used there has been some shuffling, +consolidating, or elimination of keys. One needs to check the +run time '?' help or the help to determine the key changes. +.LS +Deblending may now use any number of components and +simultaneous fitting of a linear background. A new simplified +version of gaussian fitting for a single line has been added in +the 'k' key. The old 'k', 'h', and 'v' equivalent width +commands are all part of the single 'h' command using a second +key to select a specific option. The gaussian line model from +these modes may now be subtracted from the spectrum in the same +way as the gaussian fitting. The one-sided options, in +particular, are interesting in this regard as a new capability. +.LS +The arithmetic functions between two spectra are now done in +wavelength with resampling to a common dispersion done +automatically. The 't' key now provides for the full power of +the ICFIT package to be used on a spectrum for continuum +normalization, subtraction, or line and cosmic ray removal. +The 'x' editing key may now use the nearest pixel values rather +than only the y cursor position to replace regions by straight +line segments. The mode is selected by the task option +parameter "xydraw". +.LS +Control over the graph window (plotting limits) is better +integrated so that redrawing, zooming, shifting, and the \fBgtools\fR +window commands all work well together. The new 'c' key resets +the window to the full spectrum allowing the 'r' redraw key to +redraw the current window to clean up overplots from the +gaussian fits or spectrum editing. +.LS +The dispersion units may now be selected and changed to be from +hertz to Mev and the log or inverse (for wave numbers) of units +taken. As part of the units package the 'v' key or colon +commands may be used to plot in velocity relative to some +origin. The $ key now easily toggles between the dispersion +units (whatever they may be) and pixels coordinates. +.LS +Selection of spectra has become more complex with multiaperture +and long slit spectra. New keys allow selecting apertures, +lines, columns, and bands as well as quickly scrolling through +the lines in multiaperture spectra. Overplotting is also more +general and consistent with other tasks by using the 'o' key to +toggle the next plot to be overplotted. Overplots, including +those of the gaussian line models, are now done in a different +line type. +.LS +There are new colon commands to change the dispersion axis and +summing parameters for 2D image, to toggle logging, and also to +put comments into the log file. +.LS STANDARD +Giving an unrecognized standard star name will page a list of +standard stars available in the calibration directory and then +repeat the query. +.LS SUBSETS +Moved to the \fBiids/irs\fR packages. +.LS SUMS +Moved to the \fBiids/irs\fR packages. diff --git a/noao/onedspec/doc/sys/revisions.v3.ms b/noao/onedspec/doc/sys/revisions.v3.ms new file mode 100644 index 00000000..1c3da8be --- /dev/null +++ b/noao/onedspec/doc/sys/revisions.v3.ms @@ -0,0 +1,382 @@ +.nr PS 9 +.nr VS 11 +.RP +.ND +.TL +ONEDSPEC Package Revisions Summary: IRAF Version 2.10 +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +July 1990 +.AB +This paper summarizes the changes in Version 3 of the IRAF \fBonedspec\fR +package which is part of IRAF Version 2.10. The major new features and +changes are: + +.IP \(bu +\fBIdentify\fR and \fBreidentify\fR now treat multispec format spectra +and two dimensional images as a unit. +.IP \(bu +\fBReidentify\fR supports both tracing (the old method) and always starting +with the primary reference vector when reidentifying other vectors in a +two dimensional reference image. +.IP \(bu +\fBReidentify\fR matches reference lines or apertures when reidentifying +those vectors in different images rather than tracing. +.IP \(bu +\fBReidentify\fR has an interactive capability to review +suspect reidentifications. +.IP \(bu +\fBReidentify\fR provides the capability to add new features. +.IP \(bu +The task \fBmsdispcor\fR provides for spatial interpolation of wavelength +zero point shifts from simultaneous arc spectra. +.IP \(bu +The new task \fBscopy\fR copies subsets of apertures and does format +conversions between the different spectrum formats. +.IP \(bu +The new task \fBsapertures\fR adds or modifies beam numbers and +aperture titles for selected apertures based on an aperture +identification file. +.IP \(bu +The new task \fBsfit\fR fits spectra and outputs the fits in various ways. +Apertures in multispec and echelle format are fit independently. +.IP \(bu +The task \fBcontinuum\fR now does independent fits for multispec and +echelle format spectra. +.IP \(bu +\fBSplot\fR now allows deblending of any number of components and +allows simultaneous fitting of a linear background. +.IP \(bu +The new task \fBfitprofs\fR fits 1D gaussian profiles in images. +.AE +.NH +Introduction +.PP +Though most of the ONEDSPEC package is unchanged there have been +significant changes to a number of the commonly used tasks in IRAF +Version 2.10. The changes will be made available as part of an +external package prior to the release of V2.10. This paper summarizes +the changes and new features. The changes primarily apply to multispec +or echelle format spectra. +.PP +Tables 1 and 2 summarize most of the major and minor changes in the package. + +.ce +TABLE 1: Summary of Major New Features and Changes + +.IP \(bu +\fBIdentify\fR and \fBreidentify\fR now treat multispec format spectra +and two dimensional images as a unit allowing easy movement between +different image lines or columns. The database is only updated upon +exiting the image. +.IP \(bu +\fBReidentify\fR supports both tracing (the old method) and always starting +with the primary reference vector when reidentifying other vectors in a +two dimensional reference image. +.IP \(bu +\fBReidentify\fR matches reference lines or apertures when reidentifying +those vectors in different images rather than tracing. +.IP \(bu +\fBReidentify\fR has an interactive capability to review +suspect reidentifications. +.IP \(bu +\fBReidentify\fR provides the capability to add new features. +.IP \(bu +The task \fBmsdispcor\fR allows using +auxilary reference spectra to provide a shift in the wavelength +zero point to the primary dispersion functions. This includes +spatial interpolation of simultaneous arc spectra in multifiber +spectrographs. +.IP \(bu +The new task \fBscopy\fR copies subsets of apertures and does format +conversions between the different spectrum formats. +.IP \(bu +The new task \fBsapertures\fR adds or modifies beam numbers and +aperture titles for selected apertures based on an aperture +identification file. +.IP \(bu +The new task \fBsfit\fR fits spectra and outputs the fits in various ways. +This includes a new feature to replace deviant points by the fit. +Apertures in multispec and echelle format are fit independently. +.IP \(bu +The task \fBcontinuum\fR now does independent fits for multispec and +echelle format spectra. +.IP \(bu +\fBSplot\fR now allows deblending of any number of components and +allows simultaneous fitting of a linear background. +.IP \(bu +The new task \fBfitprofs\fR fits 1D gaussian profiles to spectral lines or +features in an image line or column. This is done noniteractively and +driven by an input list of feature positions. +.bp +.LP +.ce +TABLE 2: Summary of Other New Features and Changes + +.IP \(bu +The \fBidentify\fR database format uses aperture numbers rather than +image sections for multispec format spectra. +.IP \(bu +The apertures in multispec format images need not be in the same order +or even the same number of apertures as the reference image in +\fBreidentify\fR or \fBmsdispcor\fR. +.IP \(bu +An automatic write parameter has been added to \fBidentify\fR. +.IP \(bu +The tasks \fBmsdispcor\fR and \fBspecplot\fR support the extra information +in the third dimension of multispec format spectra which is optionally +output by the \fBapextract\fR package. +.IP \(bu +\fBMsdispcor\fR and \fBspecplot\fR now include a logfile. +.IP \(bu +\fBSplot\fR selects spectra from multispec or echelle format by their +aperture number. Also a new keystroke was added to select a new +line/aperture without having to enter the image name again. +.IP \(bu +The task \fBspecplot\fR may select apertures from a multispec or +echelle format spectrum. +.IP \(bu +The aperture identification in multispec format is used, if present, +for labeling in \fBsplot\fR, \fBspecplot\fR, and \fBstandard\fR. +.NH +IDENTIFY and REIDENTIFY +.PP +These tasks have been modified for greater flexibility when dealing with +two dimensional images and multispec format spectra in particular. These +tasks were initially designed primarily to work on one dimensional images +with provisions for two dimensional images through image sections and +tracing to other parts of the image. Now these tasks treat such images +as a unit. +.PP +The task \fBidentify\fR has three added keystrokes, 'j', 'k', and 'o'. +These provide for moving between lines and columns of a two dimensional +image and different apertures in a multispec format spectrum. When +changing vectors the last set of features and fit are recalled, if they +have been previously defined, or the last set of features and fit are +inherited. For efficiency and to minimize queries, the feature +information from all the lines or apertures is not written to the +database until you quit the image (or explicitly write it) rather than +one at a time. A new parameter was also added, \fIautowrite\fR, which +may be set to automatically write the results to the database rather +than querying as is currently done. +.PP +The format of the database entries have also been slightly modified in +the case of multispec format images. Instead of using image sections +as part of the image name to define different vectors in the image +(this is still the case for regular two dimensional images) the aperture +number is recorded. This decouples the solutions for an aperture from +the specific image line allowing reference images to have a different +aperture order and additional or missing apertures. +.PP +While the changes to \fBidentify\fR are minor as far as usage, the task +\fBreidentify\fR is quite different and is essentially a new program. +Much of the complexity in this task relates to two dimensional images. +Two additions that apply to both one and two dimensional images is the +capability to add features from a coordinate list and to interactively +review the reidentifications using \fBidentify\fR. The addition of new +features may be useful in cases where the signal-to-noise varies or to +compensate for lost features when tracing across an image. The review +capability first prints the statistical results and then ask the user if +they want to examine the results interactively . This allows +basing the decision to interactively examine the features and fit based +on this information. Ideally, only a few of the worst cases need be +examined interactively. +.PP +There are two phases of reidentifications which apply to two +dimensional and multispec format images. In the first phase, one needs +to expand the identifications in the reference image from an initial, +interactively defined line, column, or aperture to other parts of the +reference image. A very important change is that there are now two +ways to transfer the features list; by successive steps (tracing) using +the previous results as a starting point (the only method provided in +the previous version) or always starting from the original reference +list. The first method is suitable for long slit spectra which have +significant positional trends across the image. If a feature is lost, +however, the feature remains missing (barring automatic addition as +mentioned above) for all following lines or columns. The latter method +is best if there are only small variations relative to the initial +reference or in multispec format spectra where there is no inherent +relation between apertures. +.PP +The second phase of reidentifications is between the reference image +and other images. In the previous version the primary reference vector +was transferred to the new image and then tracing would be applied +again. This compounds the problem with losing features during tracing +and prevents any possible reidentifications from multispec images in +which the wavelength range may vary greatly. In the new version there +is a direct reidentification from the same line, column, or aperture in +the reference to that of the next image. In the case where different +apertures may have significantly different wavelength coverage, as +occurs with aperture masks, it will at least be possible to +interactively identify features and coordinate functions for each +aperture, using the scrolling capability in the new \fBidentify\fR, in +just a single image and then correctly transfer the features to +additional images. +.PP +For multispec format spectra the database information is organized by +aperture number independent of image line number. Thus, it is possible +to reidentify features in multispec format spectra even if the aperture +order is different. If there is only a partial overlap in the aperture +set only those apertures having an entry in the reference image will be +done. +.NH +MSDISPCOR +.PP +The task \fBmsdispcor\fR dispersion corrects (rebins to a linear +dispersion function) multispec format spectra. It was introduced in +V2.8 of IRAF in the prototype \fBimred.msred\fR package. A number of +changes have been made in this task as summarized here. +.PP +The most fundamental change is support for spatial interpolation of +reference dispersion functions from a subset of apertures to other +apertures originating at different positions in a two dimensional +image. This is primarily intended for the case of comparison arc +spectra which are interspersed with object spectra in multifiber +spectrographs. It would also be useful in digitized photographic +spectra having calibration spectra exposed next to the object +spectrum. While usable directly, this feature is intended for the +processing scripts in the new \fBimred\fR fiber instrument packages. +.PP +The interpolation is only for a wavelength zero point shift, as determined +by \fBreidentify\fR with \fIrefit\fR=no. The full dispersion function +is still provided by a calibration image covering all apertures. Thus, +the simultaneous arc apertures are used to monitor shifts in the +detector relative to the full calibration which includes the relative +differences between each aperture and the arc monitoring apertures. +.PP +The multispec spectra containing the apertures used for the spatial +wavelength zero point corrections are specified in the image header +using the keywords REFSHFT1 and REFSHFT2. These are analogous to +the REFSPEC keywords used to define the reference dispersion functions +for the apertures. +.PP +As part of the general theme of multispec format support the +multispec dispersion reference spectra may have additional spectra and +need not be in the same order. However, all aperture in the +images being dispersion corrected must have dispersion relations +in the database. Multispec format spectra may include additional +data in the 3rd image dimension produced by the new +\fBapextract\fR package. \fBMsdispcor\fR rebins this information +in the same way as the spectra, thus, preserving the information +but now in linear wavelength sampling. +.PP +A new parameter, \fIlogfile\fR, has been added to capture information +about the dispersion correction process. +.NH +SCOPY and SAPERTURES +.PP +The task \fBscopy\fR is intended to bridge the gap between the various +spectrum formats and provide a tool to flexibly manipulate multispec +format spectra. It replaces the more primitve tasks +\fBmsred.msselect\fR and \fBechelle.ecselect\fR. Basically, this task +copies all or selected spectra from one format to a new image or images +of the same or different format. The typical uses are: + +.IP \(bu +Extract selected spectra from a multispec format image. +.IP \(bu +Allow converting the voluminous onedspec format from previous reductions +done before the multispec format was introduced into the more compact +multispec format. +.IP \(bu +Splice selected apertures from different multispec images into a new +multispec image. +.IP \(bu +Provide a quick way to convert lines or columns from two dimensional +long slit images into one dimensional spectra. This replaces +the task \fBproto.toonedspec\fR. +.PP +Because \fBscopy\fR can easily change the number and order of apertures +in the multispec image format it is important that the other tasks which +use the multispec format have been modified to be insensitive to which +line a spectrum is in and generally key off the aperture number. +.PP +The task \fBsapertures\fR is a simple way to set the aperture identifications, +APID keyword, and beam number, second field of APNUM keyword, based on +the aperture number and a simple text file. The text file contains lines +with aperture number, beam number, and (optional) title. This file is +used by the \fBapextract\fR package as well. Its likely usage is +to change image titles which might be wrong because of being inherited +from an aperture reference image during extraction. +.NH +SFIT, CONTINUUM, and ECCONTINUUM +.PP +The original version of \fBcontinuum\fR was a simple script based on +the task \fBfit1d\fR. The problem is that \fBfit1d\fR is intended to +process all the lines or columns in a two dimensional image +noninteractively. To do this it applies the same fitting parameters to +every line or column. The interactive step in this task is simply to +adjust fitting parameters. For spectra, particularly multispec and +echelle format spectra, one often needs to fit each spectrum +interactively and independently. When this problem was encountered for +the \fBechelle\fR package Rob Seaman wrote a nice program, +\fBeccontinuum\fR, which allows fitting a set of orders and keeps track +of which orders have been fit. +.PP +The general feature of the continuum fitting tasks is that they fit +spectra using the \fBicfit\fR interactive function fitting interface. +The results of the fit may be output as the fit itself, the difference +or residuals, the ratio, or the input data with rejected points replaced +by the fitted values. The last feature is new an provides a useful +spectrum cleaning option. The general equivalent to \fBfit1d\fR is +the new task \fBsfit\fR which provides the same independent fitting and +image line selection capabilites as \fBeccontinuum\fR. Note this task +is line oriented and does not select by aperture or order number. The +revised version of \fBcontinuum\fR is now based on \fBsfit\fR and +provides the independent continuum fitting capability for onedspec and +multispec format spectra that \fBeccontinuum\fR provides for echelle +format spectra. Technically what has been done is that \fBsfit\fR, +\fBcontinuum\fR, and \fBeccontinuum\fR are the same task; essentially +the task written by Seaman for echelle data. They differ in the +default parameters with the continuum fitting task having default +parameters providing continuum normalization (ratio) output and +iterative rejection values for excluding lines. +.NH +SPLOT, FITPROFS, and SPECPLOT +.PP +\fBSplot\fR has been modified to better support multispec and echelle +format images. The line selection for multispec and echelle format +spectra is now in terms of the aperture number rather than the image +line. The aperture title is used in place of the image title +if present. +.PP +The restriction to a maximum of four lines in the gaussian fitting and +deblending option of \fBsplot\fR has been lifted. Any number of +lines may be fit simultaneously, though execution time will become +long for a large number. In addition the fitting allows determining +a simultaneous linear background as well as using the cursor defined +points. The positions of the lines to be fit may be marked with +the cursor, typed in, or read from a file. The last choice is a new +feature. +.PP +In the past many people have used \fBsplot\fR for bulk, noninteractive +gaussian fitting by going through the trouble of redirecting the cursor +input, ukey input, text output, and graphics output. The main reason +this has been done is the lack of a one dimensional gaussian fitting +task. The task \fBfitprofs\fR has been added to provide simultaneous +gaussian fitting. This task takes a list of positions and optional +sigmas and fits gaussians to a list of images or spectra. The lines, +columns, or apertures may be selected. In addition a linear +background may be specified or included in the fitting. The output +consists of any combination of text similiar to the \fBsplot\fR +logfile, plots showing the data and fit, and image output of the fit or +the difference. This task is noninteractive; the interactive version +is the deblend command of \fBsplot\fR. The multiparameter, nonlinear +fitting software is the same as used in \fBsplot\fR. +.PP +\fBFitprofs\fR complements the task \fBstsdas.fitting.ngaussfit\fR from +the \fBstsdas\fR package (available from the Space Telescope Science +Institute). This task is similar in character to \fBfit1d\fR and has +an interactive one dimensional nonlinear function fitting interface +similar to \fBicfit\fR. +.PP +The task \fBspecplot\fR has a new parameter to select apertures to +plot. Previously there was no way to limit the apertures plotted other +than with image sections. All associated lines of a multispec +spectrum (those in the third dimension) are also plotted for the +selected apertures. This extra information is a new option of the +\fBapextract\fR package. diff --git a/noao/onedspec/doc/sys/revisions.v31.ms b/noao/onedspec/doc/sys/revisions.v31.ms new file mode 100644 index 00000000..f9d6c24f --- /dev/null +++ b/noao/onedspec/doc/sys/revisions.v31.ms @@ -0,0 +1,329 @@ +.nr PS 10 +.nr VS 12 +.RP +.ND +.TL +NOAO Spectroscopy Packages Revisions: IRAF Version 2.10.3 +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +March 1993 +.AB +This paper summarizes the changes in Version 3.1 of the IRAF/NOAO +spectroscopy packages, \fBonedspec\fR, \fBlongslit\fR, \fBapextract\fR, and +those in \fBimred\fR. These changes are part of IRAF Version 2.10.3. A +list of the revisions is: + +.in +2 +.nf +\(bu A simplified \fIequispec\fR image header format +\(bu \fIEquispec\fR format allows a larger number of apertures in an image +\(bu Extensions to allow tasks to work on 3D images +\(bu New task \fBspecshift\fR for applying a zeropoint dispersion shift +\(bu Revised \fBsapertures\fR to edit spectrum coordinate parameters +\(bu Revised \fBdispcor\fR to easily apply multiple dispersion corrections +\(bu Revised \fBscombine\fR weighting and scaling options +\(bu Revised \fBscopy\fR to better handle bands in 3D images +\(bu Revised \fBcalibrate, deredden, dopcor\fR, and \fBspecshift\fR to work on 2D/3D images +\(bu Extended \fBidentify\fR and \fBreidentify\fR to work on 3D images +\(bu New color graphics capabilities in \fBsplot, specplot, sensfunc\fR, and \fBidentify\fR +\(bu All spectral tasks use a common package dispersion axis parameter +\(bu A more complete suite of tasks in the \fBlongslit\fR package +\(bu The \fBimred\fR reductions scripts can now be used with any image format +\(bu A \fIdatamax\fR parameter in the \fBimred\fR reduction scripts for better cleaning +\(bu Revised the \fBimred\fR reduction scripts to abort on non-CCD processed data +\(bu Revised fiber reduction tasks to include a scattered light subtraction option +\(bu Revised fiber reduction tasks to allow as many sky apertures as desired +\(bu Revised \fBdoslit\fR to take the reference arc aperture from the first object +\(bu Bug fixes +.fi +.in -2 +.AE +.NH +Spectral Image Formats and Dispersion World Coordinate Systems +.LP +As with the original release of V2.10 IRAF, the primary changes in the +NOAO spectroscopy +software in V2.10.3 are in the area of spectral image formats and dispersion +world coordinate systems (WCS). A great deal was learned from experience +with the first release and the changes in this release attempt to +address problems encountered by users. The main revisions are: + +.in +2 +.nf +\(bu A new WCS format called \fIequispec\fR. +\(bu Extensions to allow use of 3D images with arbitrary dispersion axis. +\(bu Elimination of limits on the number of apertures in an image under certain conditions. +\(bu Improved tools for manipulating the spectral coordinate systems. +\(bu Bug fixes and solutions to problems found in the previous release. +.fi +.in -2 + +In the previous version all images with multiple spectra used a coordinate +system called \fImultispec\fR. This type of WCS is complex and difficult +to manipulate by image header editing tools. Only the case of a single +linearized spectrum per image, sometimes called \fIonedspec\fR format, +provided a simple header format. However, the \fBapextract\fR package +used the \fImultispec\fR format even in the case of extracting a single +spectrum so to get to the simple format required use of \fBscopy\fR. +.LP +In many cases all the spectra in a multispectrum image have the same linear +dispersion function. The new \fIequispec\fR format uses a simple linear +coordinate system for the entire image. This format is produced by the +spectral software whenever possible. In addition to being simple and +compatible with the standard FITS coordinate representation, the +\fIequispec\fR format also avoids a limitation of the \fImultispec\fR WCS +on the number of spectra in a single image. This has specific application +to multifiber spectrographs with more than 250 fibers. +.LP +For multiple spectrum data in which the spectra have differing +dispersion functions (such as echelle orders) or when the spectra are +not linearized but use nonlinear dispersion functions, the \fImultispec\fR +format is still used. It is the most general WCS representation. +The difficulties with modifying this coordinate system, \fBhedit\fR +cannot be used, are addressed by enhancing the \fBsapertures\fR task +and by the new task \fBspecshift\fR which covers the common case of +modifying the dispersion zeropoint. +.LP +A feature of the spectral tasks which operate on one dimensional spectra +is that they can operate on two dimensional long slit spectra by +specifying a dispersion axis and a summing factor. This feature has +been extended to three dimensional spectra such as occur with +Fabry-Perot and multichannel radio synthesis instruments. The +dispersion axis may be along any axis as specified by the DISPAXIS +image header keyword or by the \fIdispaxis\fR package parameter. The +summing factor parameter \fInsum\fR is now a string which may have +one or two values to allow separate summing factors along two spatial +axes. Also, some additional tasks which previously did not support this +feature are \fBcalibrate\fR, \fBderedden\fR, \fBdopcor\fR, and \fBspecshift\fR. +.LP +The gory details of the spectral image formats and world coordinate +systems are laid out in the new help topic \fIspecwcs\fR (also +available in a postscript version in the IRAF network documentation +archive as iraf/docs/specwcs.ps.Z). +.LP +Some of the bug fixes and solutions to problems found in the previous +release concerning the image formats and WCS are a problem with the WCS +dimensionality (WCSDIM keyword) with 3D images and problems reading various +imported nonstandard formats. It is hoped that all such formats, including +previous IRAF spectral formats will all be allowed by the software in the +latest release. +.NH +DISPCOR +.LP +The previous versions of \fBdispcor\fR, the dispersion correction task, was +designed to prevent accidental repeated application; it is incorrect to +apply the dispersion function from the original data to a linearized +spectrum. However, it is valid to determine a new dispersion solution, say +from a dispersion calibrated arc, and apply that as a second correction. +\fBDispcor\fR would not use a new dispersion function, as specified by the +REFSPEC keywords, if the dispersion calibration flag was set. In order to +override this the user needed to manually change this flag to indicate the +spectrum was uncorrected. The problem was that it was difficult to do this +with \fImultispec\fR format spectra because the flag is part of the complex +WCS attribute strings. +.LP +\fBDispcor\fR was revised to use a different logic to prevent accidental +recalibration using an unintended dispersion function. The logic is as +follows. Previously \fBdispcor\fR would simply change the dispersion +calibration flag after correcting a spectrum while leaving the dispersion +function reference spectrum keywords alone as a record. The revised +\fBdispcor\fR keeps this useful record but moves this it to a new keyword +DCLOGn (where n is a sequential integer). Because the REFSPEC keyword is +removed after each application of \fBdispcor\fR it now takes an explicit +act by the user to assign another dispersion function to a spectrum and so +it is not possible to accidentally reapply the same dispersion function +twice. Thus this version will apply additional dispersion functions by +simply adding new REFSPEC keywords. If they are absent the task resamples +the spectra based on the current dispersion relation as was the case +before. +.LP +The new version can also tell whether the data was calibrated by the +previous version. In this case the check on the dispersion calibration +flag is still used so that during the transition users are still protected +against accidentally applying the same reference dispersion function +twice. The new task \fBsapertures\fR can now be used to change the +dispersion calibration flag to override this checking more easily than was +the case previously. +.NH +New Tasks +.LP +In this release there is only one completely new task and one task which +was significantly redesigned. The new task is \fBspecshift\fR. It is +relatively simple, it adds a zero point shift to the dispersion coordinates +of spectra. This was the most common request for manipulating the spectral +world coordinate system. In this regard there was a common confusion about +the distinction between shifting the coordinate system and shifting the +pixel data. Generally what people want is to apply a shift such that +features in the spectrum move to the desired wavelength. One thought is to +apply the tasks \fBimshift\fR or \fBshiftlines\fR. The surprise is that +this does not to work. The pixels are actually shifted in the image array, +but these tasks also apply the same shift to the coordinate system so that +features in the spectrum remain at the same wavelength. What is really +required is to leave the pixel data alone and shift only the coordinate +system. That is what \fBspecshift\fR does. +.LP +While one hopefully does not need to directly manipulate the image header +keywords describing the coordinate system or other aspects of the spectra, +instead using such tasks as \fBspecshift\fR, there always seem to be cases +where this is needed or desired. In the V2.10 release of the spectral +software this was difficult because the general \fImultispec\fR format was +the norm and it has information encoded in the complex WCS attribute +strings. As mentioned previously several changes have been made reduce the +complexity. Now \fIequispec\fR format will generally be the rule and this +format has keywords which are more easily manipulated with \fBhedit\fR and +\fBwcsedit\fR. However, the task \fBsapertures\fR was revised to provide +an editing capability specifically for spectral images, in either +\fImultispec\fR or \fIequispec\fR format, with options to change various +parameters globally or aperture-by-aperture. +.NH +New Features +.LP +There were a number of miscellaneous minor revisions and bug fixes. One of +the major new capabilities available with V2.10.3 is support for color +graphics if the graphics device supports it. \fBXgterm\fR supports color +on X-window systems with color monitors. Several of the spectral tasks +were modified to use different colors for marks and overplots. These tasks +include \fBsplot\fR, \fBspecplot\fR, \fBidentify\fR, and \fBsensfunc\fR. +In the case of \fBsensfunc\fR the user controls the various color +assignments with a task parameter or \fBgtools\fR colon command while in +other cases the next available color is used. +.LP +There were several changes to \fBscombine\fR equivalent to those in +\fBimcombine\fR. The weighting, when selected, was changed from the square +root of the exposure time or spectrum statistics to the value with no +square root. This corresponds to the more commonly used variance +weighting. Other options were added to specify the scaling and weighting +factors. These allow specifying an image header keyword or a file +containing the scale or weighting factors. A new parameter, "nkeep" has +been added to allow controlling the maximum number of pixels rejected by the +clipping algorithms. Previously it was possible to reject all pixels even +when some of the data was good though with a higher scatter than estimated; +i.e. all pixels might be greater than 3 sigma from the mean without being +cosmic rays or other bad values. Finally a parameter \fIsnoise\fR was +added to include a sensitivity or scale noise component to a Poisson noise +model. +.LP +In \fBsplot\fR the 'p' and 'u' keys which assign and modify the dispersion +coordinates now include options for applying a zero point shift or a +doppler shift in addition to defining an absolute wavelength for a feature +or starting and ending wavelengths. There are also bug fixes to the +equivalent width calculations, it did not handle flux calibrated data, and +the scroll keys '(' and ')'. +.LP +There were several changes to make it easier to deal with with three +dimensional \fImultispec\fR and \fIequispec\fR data; that is the additional +data from the "extras" option in the \fBapextract\fR tasks. One was to fix +problems associated with an incorrect WCSDIM keyword. This allows use of +image sections or \fBimcopy\fR for extracting specific bands and +apertures. Another was to add a "bands" parameter in \fBscopy/sarith\fR to +allow selection of bands. Also the "onedspec" output format in \fBscopy\fR +copies any selected bands to separate one dimensional images. +.LP +As mentioned earlier, many of the \fBonedspec\fR tasks have been extended +to work on 2D and 3D spatial spectra. Some tasks which now have this +capability in this version and not the previous one are \fBcalibrate\fR and +\fBdopcor\fR. \fBIdentify\fR and \fBredentify\fR were extended to operate +on 3D images. This involved extending the syntax for the section parameter +selecting the image vector and the parameter specifying any summing +across the vector direction. +.NH +LONGSLIT +.LP +With the applicability of more \fBonedspec\fR tasks to long slit data +the \fBlongslit\fR package was modified to add many new tasks. +This required adding additional package parameters. One new task +to point out is \fBcalibrate\fR. This task is now the preferred one +to use for extinction and flux calibration of long slit spectra +rather than the obsolete \fBextinction\fR and \fBfluxcalib\fR. +The obsolete tasks are still present in this release. +.NH +APEXTRACT +.LP +The \fBapextract\fR package had a few, mostly transparent, changes. In +the previous version the output image header format was always \fImultispec\fR +even when there was a single spectrum, either because only one aperture +was defined or because the output format parameter was "onedspec". +In this release the default WCS format is the simpler \fIequispec\fR. +.LP +In the \fBonedspec\fR and \fBimred\fR spectral reduction packages there is +a dispersion axis package parameter which is used to defined the dispersion +axis for images without a DISPAXIS keyword. This applies to all tasks. +However, the \fBapextract\fR tasks had the dispersion axis defined by their +own task parameters resulting in some confusion. To make things consistent +the dispersion axis parameter in \fBapextract\fR has been moved from the +tasks to a package parameter. Now in the \fBimred\fR spectral reduction +packages, there is just one dispaxis parameter in the package parameters +which applies to all tasks in those packages, both those from +\fBonedspec\fR and those from \fBapextract\fR. +.LP +Some hidden algorithm parameters were adjusted so that the cleaning and +variance weighting options perform better in some problem cases without +requiring a great deal of knowledge about things to tweak. +.NH +IMRED Spectroscopic Reduction Tasks +.LP +The various spectroscopic reductions tasks, those beginning with "do", have +had some minor revisions and enhancements in addition to those which apply +to the individual tasks which make up these scripts. In the latter class +is the output WCS format is \fBequispec\fR except for the echelle tasks and +when dispersion linearization is not done. Related to this is that the +multifiber tasks can operate on data with more than 250 fibers which was a +limitation of the \fBmultispec\fR format. +.LP +In the previous version only the OIF format images were allowed (the ".imh" +extensions). This has been generalized to allow selecting the image format +by setting the environment parameter \fIimtype\fR. Only images with the +specified extension will be processed and created. +.LP +The dispersion axis parameter in the reduction tasks and in the other tasks +in the \fBimred\fR spectroscopy packages, such as the \fBapextract\fR +tasks, is now solely a package parameter. +.LP +All the scripts now check the input spectra for the presence of the CCDPROC +keyword and abort if it is not found. This keyword indicates that the data +have been processed for basic CCD calibrations, though it does not check +the operations themselves. For data reduced using \fBccdproc\fR this +keyword will be present. If these tasks are used on data not processed by +\fBccdproc\fR then it is a simple matter to add this keyword with +\fBhedit\fR. Obviously, the purpose of this change is to avoid +inadvertently operating on raw data. +.LP +All the "do" tasks now have a parameter "datamax". This minimizes the +effects of very strong cosmic rays during the extraction of object spectra; +it does not apply to flat field or arc spectra. When there is a very large +difference between data pixel values and cosmic ray pixel values, +especially true for very weak spectra, the cosmic ray cleaning operation +does not always work well. If it is possible to specify a threshold value +between the maximum real data value and cosmic rays then the cosmic ray +cleaning can be significantly improved by immediately rejecting those +pixels above the threshold. Of course the user must be careful that real +data does not exceed this value since such data will be excluded. +.LP +The fiber reduction tasks, \fBdoargus, dohydra, dofibers, dofoe\fR, and +\fBdo3fiber\fR have a new processing option for subtracting scattered +light. This is particularly useful if there is significant scattered light +in producing uniform sky spectra for sky subtraction since the fiber +throughput calibration does not generally correct for this. +.LP +The fiber reduction tasks also had a limit on the number of sky fibers +which could be used with the interactive sky editing. This limit has +been eliminated so that it is possible, for example, to have one object +fiber and 99 sky fibers. +.LP +The slit reduction task \fBdoslit\fR previously required that the spectrum +for the reference arc cover the middle of the input data images. There +were cases of instrument configurations where this was not true requiring +additional manipulation to use this task. This requirement has been +eliminated. Instead when the reference arc needs to be extracted it uses +the aperture definition from one of the input object spectra since +definition of the object apertures occurs prior to setting up the +dispersion calibration. +.LP +In addition the task \fBdoslit\fR and \fBdoecslit\fR had a bug in which +the order of the arcs specified by the user was ignored and alphabetical +order was used instead. This has been fixes so that the first arc +specified by the use is the reference arc. diff --git a/noao/onedspec/doc/sys/revisions.v31.ms.bak b/noao/onedspec/doc/sys/revisions.v31.ms.bak new file mode 100644 index 00000000..1c7c3b31 --- /dev/null +++ b/noao/onedspec/doc/sys/revisions.v31.ms.bak @@ -0,0 +1,307 @@ +.nr PS 9 +.nr VS 11 +.RP +.ND +.TL +NOAO Spectroscopy Packages Revision Summary: IRAF Version 2.10.3 +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +March 1993 +.AB +This paper summarizes the changes in Version 3.1 of the IRAF/NOAO +spectroscopy packages, \fBonedspec\fR, \fBlongslit\fR, \fBapextract\fR, +and those in \fBimred\fR. These changes are part of +part of IRAF Version 2.10.3. A list of the revisions is: + +.nf +\(bu A simplified \fIequispec\fR image header format +\(bu \fIEquispec\fR format allows a larger number of apertures in an image +\(bu Extensions to allow tasks to work on 3D images +\(bu New task \fBspecshift\fR for applying a zeropoint dispersion shift +\(bu Revised \fBsapertures\fR to edit spectrum coordinate parameters +\(bu Revised \fBdispcor\fR to easily apply multiple dispersion corrections +\(bu Revised \fBscombine\fR weighting and scaling options +\(bu Revised \fBscopy\fR to better handle bands in 3D images +\(bu Revised \fBcalibrate, dopcor\fR, and \fBspecshift\fR to work on 2D/3D images +\(bu New color graphics capabilities in \fBsplot, specplot, sensfunc\fR, and \fBidentify\fR +\(bu All spectral tasks use a common package dispersion axis parameter +\(bu A more complete suite of tasks in the \fBlongslit\fR package +\(bu A \fIdatamax\fR parameter in the \fBimred\fR reduction scripts for better cleaning +\(bu Revised the \fBimred\fR reduction scripts to abort on non-CCD processed data +\(bu Revised fiber reduction tasks to include a scattered light subtraction option +\(bu Revised \fBdoslit\fR to take the reference arc aperture from the first object +\(bu Bug fixes +.fi +.AE +.NH +Spectral Image Formats and Dispersion World Coordinate Systems +.LP +As with the original release of V2.10 IRAF, the primary changes in the +NOAO spectroscopy +software in V2.10.3 are in the area of spectral image formats and dispersion +world coordinate systems (WCS). A great deal was learned from experience +with the first release and the changes in this release attempt to +address problems encountered by users. The main revisions are: + +.in +4 +.nf +\(bu A new WCS format called \fIequispec\fR. +\(bu Extensions to allow use of 3D images with arbitrary dispersion axis. +\(bu Elimination of limits on the number of apertures in an image under certain conditions. +\(bu Improved tools for manipulating the spectral coordinate systems. +\(bu Bug fixes and solutions to problems found in the previous release. +.fi +.in - 4 + +In the previous version all images with multiple spectra used a coordinate +system called \fImultispec\fR. This type of WCS is complex and difficult +to manipulate by image header editting tools. Only the case of a single +linearized spectrum per image, sometimes called \fIonedspec\fR format, +provided a simple header format. However, the \fBapextract\fR package +used the \fImultispec\fR format even in the case of extracting a single +spectrum so to get to the simple format required use of \fBscopy\fR. +.LP +In many cases all the spectra in a multispectrum image have the same linear +dispersion function. The new \fIequispec\fR format uses a simple linear +coordinate system for the entire image. This format is produced by the +spectral software whenever possible. In addition to being simple and +compatible with the standard FITS coordinate representation, the +\fIequispec\fR format also avoids a limitation of the \fImultispec\fR WCS +on the number of spectra in a single image. This has specific application +to multifiber spectrographs with more than 250 fibers. +.LP +For multiple spectrum data in which the spectra have differing +dispersion functions (such as echelle orders) or when the spectra are +not linearized but use nonlinear dispersion functions, the \fImultispec\fR +format is still used. It is the most general WCS representation. +The difficulties with modifying this coordinate system, \fBhedit\fR +cannot be used, are addressed by enhancing the \fBsapertures\fR task +and by the new task \fBspecshift\fR which covers the common case of +modifying the dispersion zeropoint. +.LP +A feature of the spectral tasks which operate on one dimensional spectra +is that they can operate on two dimensional long slit spectra by +specifying a dispersion axis and a summing factor. This feature has +been extended to three dimensional spectra such as occur with +Fabry-Perot and multichannel radio synthesis instruments. The +dispersion axis may be along any axis as specified by the DISPAXIS +image header keyword or by the \fIdispaxis\fR package parameter. The +summing factor parameter \fInsum\fR is now a string which may have +one or two values to allow separate summing factors along two spatial +axes. Also, some additional tasks which previously did not support this +feature are \fBcalibrate\fR, \fBdopcor\fR, and \fBspecshift\fR. +.LP +The gory details of the spectral image formats and world coordinate +systems are laid out in the new help topic \fIspecwcs\fR (also +available in a postscript version in the IRAF network documentation +archive as iraf/docs/specwcs.ps.Z). +.LP +Some of the bug fixes and solutions to problems found in the previous +release concerning the image formats and WCS are a problem with the WCS +dimensionality (WCSDIM keyword) with 3D images and problems reading various +imported nonstandard formats. It is hoped that all such formats, including +previous IRAF spectral formats will all be allowed by the software in the +latest release. +.NH +DISPCOR +.LP +The previous versions of \fBdispcor\fR, the dispersion correction task, was +designed to prevent accidental repeated application; it is incorrect to +apply the dispersion function from the original data to a linearized +spectrum. However, it is valid to determine a new dispersion solution, say +from a dispersion calibrated arc, and apply that as a second correction. +\fBDispcor\fR would not use a new dispersion function, as specified by the +REFSPEC keywords, if the dispersion calibration flag was set. In order to +override this the user needed to manually change this flag to indicate the +spectrum was uncorrected. The problem was that it was difficult to do this +with \fImultispec\fR format spectra because the flag is part of the complex +WCS attribute strings. +.LP +\fBDispcor\fR was revised to use a different logic to prevent accidental +recalibration using an unintended dispersion function. The logic is as +follows. Previously \fBdispcor\fR would simply change the dispersion +calibration flag after correcting a spectrum while leaving the dispersion +function reference spectrum keywords alone as a record. The revised +\fBdispcor\fR keeps this useful record but moves this it to a new keyword +DCLOGn (where n is a sequential integer). Because the REFSPEC keyword is +removed after each application of \fBdispcor\fR it now takes an explicit +act by the user to assign another dispersion function to a spectrum and so +it is not possible to accidentally reapply the same dispersion function +twice. Thus this version will apply additional dispersion functions by +simply adding new REFSPEC keywords. If they are absent the task resamples +the spectra based on the current dispersion relation as was the case +before. +.LP +The new version can also tell whether the data was calibrated by the +previous version. In this case the check on the dispersion calibration +flag is still used so that during the transition users are still protected +against accidentally applying the same reference dispersion function +twice. The new task \fBsapertures\fR can now be used to change the +dispersion calibration flag to override this checking more easily than was +the case previously. +.NH +New Tasks +.LP +In this release there is only one completely new task and one task which +was significantly redesigned. The new task is \fBspecshift\fR. It is +relatively simple, it adds a zero point shift to the dispersion coordinates +of spectra. This was the most common request for manipulating the spectral +world coordinate system. In this regard there was a common confusion about +the distinction between shifting the coordinate system and shifting the +pixel data. Generally what people want is to apply a shift such that +features in the spectrum move to the desired wavelength. One thought is to +apply the tasks \fBimshift\fR or \fBshiftlines\fR. The surprise is that +this does not to work. The pixels are actually shifted in the image array, +but these tasks also apply the same shift to the coordinate system so that +features in the spectrum remain at the same wavelength. What is really +required is to leave the pixel data alone and shift only the coordinate +system. That is what \fBspecshift\fR does. +.LP +While one hopefully does not need to directly manipulate the image header +keywords describing the coordinate system or other aspects of the spectra, +instead using such tasks as \fBspecshift\fR, there always seem to be cases +where this is needed or desired. In the V2.10 release of the spectral +software this was difficult because the general \fImultispec\fR format was +the norm and it has information encoded in the complex WCS attribute +strings. As mentioned previously several changes have been made reduce the +complexity. Now \fIequispec\fR format will generally be the rule and this +format has keywords which are more easily manipulated with \fBhedit\fR and +\fBwcsedit\fR. However, the task \fBsapertures\fR was revised to provide +an editing cabability specifically for spectral images, in either +\fImultispec\fR or \fIequispec\fR format, with options to change various +parameters globally or aperture-by-aperture. +.NH +New Features +.LP +There were a number of miscellaneous minor revisions and bug fixes. One of +the major new capabilities available with V2.10.3 is support for color +graphics if the graphics device supports it. \fBXgterm\fR supports color +on X-window systems with color monitors. Several of the spectral tasks +were modified to use different colors for marks and overplots. These tasks +include \fBsplot\fR, \fBspecplot\fR, \fBidentify\fR, and \fBsensfunc\fR. +In the case of \fBsensfunc\fR the user controls the various color +assignments with a task parameter or \fBgtools\fR colon command while in +other cases the next available color is used. +.LP +There were several changes to \fBscombine\fR equivalent to those in +\fBimcombine\fR. The weighting, when selected, was changed from the square +root of the exposure time or spectrum statistics to the value with no +square root. This corresponds to the more commonly used variance +weighting. Other options were added to specify the scaling and weighting +factors. These allow specifying an image header keyword or a file +containing the scale or weighting factors. A new parameter, "nkeep" has +been added to allow controling the maximum number of pixels rejected by the +clipping algorithms. Previously it was possible to reject all pixels even +when some of the data was good though with a higher scatter than estimated; +i.e. all pixels might be greater than 3 sigma from the mean without being +cosmic rays or other bad values. Finally a parameter \fIsnoise\fR was +added to include a sensitivity or scale noise component to a Poisson noise +model. +.LP +In \fBsplot\fR the 'p' and 'u' keys which assign and modify the dispersion +coordinates now include options for applying a zero point shift or a +doppler shift in addition to defining an absolute wavelength for a feature +or starting and ending wavelengths. There are also bug fixes to the +equivalent width calculations, it did not handle flux calibrated data, and +the scroll keys '(' and ')'. +.LP +There were several changes to make it easier to deal with with three +dimensional \fImultispec\fR and \fIequispec\fR data; that is the additional +data from the "extras" option in the \fBapextract\fR tasks. One was to fix +problems associated with an incorrect WCSDIM keyword. This allows use of +image sections or \fBimcopy\fR for extracting specific bands and +apertures. Another was to add a "bands" parameter in \fBscopy/sarith\fR to +allow selection of bands. Also the "onedspec" output format in \fBscopy\fR +copies any selected bands to separate one dimensional images. +.LP +As mentioned earlier, many of the \fBonedspec\fR tasks have been extended +to work on 2D and 3D spatial spectra. Some tasks which now have this +capability in this version and not the previous one are \fBcalibrate\fR and +\fBdopcor\fR. \fBIdentify\fR and \fBredentify\fR were extended to operate +on 3D images. +.NH +LONGSLIT +.LP +With the applicablity of more \fBonedspec\fR tasks to long slit data +the \fBlongslit\fR package was modified to add many new tasks. +This required adding additional package parameters. One new task +to point out is \fBcalibrate\fR. This task is now the prefered one +to use for extinction and flux calibration of long slit spectra +rather than the obsolete \fBextinction\fR and \fBfluxcalib\fR. +The obsolete tasks are still present in this release. +.NH +APEXTRACT +.LP +The \fBapextract\fR package had a few, mostly transparent, changes. In +the previous version the output image header format was always \fImultispec\fR +even when there was a single spectrum, either because only one aperture +was defined or because the output format parameter was "onedspec". +In this release the default WCS format is the simpler \fIequispec\fR. +.LP +In the \fBonedspec\fR and \fBimred\fR spectral reduction packages there is +a dispersion axis package parameter which is used to defined the dispersion +axis for images without a DISPAXIS keyword. This applies to all tasks. +However, the \fBapextract\fR tasks had the dispersion axis defined by their +own task parameters resulting in some confusion. To make things consistent +the dispersion axis parameter in \fBapextract\fR has been moved from the +tasks to a package parameter. Now in the \fBimred\fR spectral reduction +packages, there is just one dispaxis parameter in the package parameters +which applies to all tasks in those packages, both those from +\fBonedspec\fR and those from \fBapextract\fR. +.LP +Some hidden algorithm parameters were adjusted so that the cleaning and +variance weighting options perform better in some problem cases without +requiring a great deal of knowledge about things to tweak. +.NH +IMRED Spectroscopic Reduction Tasks +.LP +The various spectroscopic reductions tasks, those beginning with "do", have +had some minor revisions and enhancements in addition to those which apply +to the individual tasks which make up these scripts. In the latter class +is the output WCS format is \fBequispec\fR except for the echelle tasks and +when dispersion linearization is not done. Related to this is that the +multifiber tasks can operate on data with more than 250 fibers which was a +limitation of the \fBmultispec\fR format. +.LP +The dispersion axis parameter in the reduction tasks and in the other tasks +in the \fBimred\fR spectroscopy packages, such as the \fBapextract\fR +tasks, is now solely a package parameter. +.LP +All the scripts now check the input spectra for the presence of the CCDPROC +keyword and abort if it is not found. This keyword indicates that the data +have been processed for basic CCD calibrations, though it does not check +the operations themselves. For data reduced using \fBccdproc\fR this +keyword will be present. If these tasks are used on data not processed by +\fBccdproc\fR then it is a simple matter to add this keyword with +\fBhedit\fR. Obviously, the purpose of this change is to avoid +inadvertently operating on raw data. +.LP +All the "do" tasks now have a parameter "datamax". This minimizes the +effects of very strong cosmic rays during the extraction of object spectra; +it does not apply to flat field or arc spectra. When there is a very large +difference between data pixel values and cosmic ray pixel values, +especially true for very weak spectra, the cosmic ray cleanning operation +does not always work well. If it is possible to specify a threshold value +between the maximum real data value and cosmic rays then the cosmic ray +cleanning can be significantly improved by immediately rejecting those +pixels above the threshold. Of course the user must be careful that real +data does not exceed this value since such data will be excluded. +.LP +The fiber reduction tasks, \fBdoargus, dohydra, dofibers, dofoe\fR, and +\fBdo3fiber\fR have a new processing option for subtracting scattered +light. This is particularly useful if there is significant scattered light +in producing uniform sky spectra for sky subtraction since the fiber +throughput calibration does not generally correct for this. +.LP +The slit reduction task \fBdoslit\fR previously required that the spectrum +for the reference arc cover the middle of the input data images. There +were cases of instrument configurations where this was not true requiring +additional manipulation to use this task. This requirement has been +eliminated. Instead when the reference arc needs to be extracted it uses +the aperture definition from one of the input object spectra since +definition of the object apertures occurs prior to setting up the +dispersion calibration. diff --git a/noao/onedspec/doc/sys/rvidentify.ms b/noao/onedspec/doc/sys/rvidentify.ms new file mode 100644 index 00000000..dadab882 --- /dev/null +++ b/noao/onedspec/doc/sys/rvidentify.ms @@ -0,0 +1,304 @@ +.RP +.TL +Radial Velocity Measurements with IDENTIFY +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +.AB +The IRAF task \fBidentify\fR may be used to measure radial velocities. +This is done using the classical method of determining the doppler shifted +wavelengths of emission and absorption lines. This paper covers many of +the features and techniques available through this powerful and versatile +task which are not immediately evident to a new user. +.AE +.NH +Introduction +.PP +The task \fBidentify\fR is very powerful and versatile. It can be used +to measure wavelengths and wavelength shifts for doing radial velocity +measurements from emission and absorption lines. When combined with +the CL's ability to redirect input and output both from the standard +text streams and the cursor and graphics streams virtually anything may +be accomplished either interactively or automatically. This, of +course, requires quite a bit of expertise and experience with +\fBidentify\fR and with the CL which a new user is not expected to be +aware of initially. This paper attempts to convey some of the +possibilities. There are many variations on these methods which the +user will learn through experience. +.PP +I want to make a caveat about the suggestions made in this paper. I wrote +the \fBidentify\fR task and so I am an expert in its use. However, I am not +a spectroscopist, I have not been directly involved in the science of +measuring astronomical radial velocities, and I am not very familiar with +the literature. Thus, the suggestions contained in this paper are based +on my understanding of the basic principles and the abilities of the +\fBidentify\fR task. +.PP +The task \fBidentify\fR is used to measure radial velocities by +determining the wavelengths of individual emission and absorption +lines. The user must compute the radial velocities separately by +relating the observed wavelengths to the known rest wavelengths via the +Doppler formula. This is a good method when the lines are strong, when +there are only one or two features, and when there are many, possibly, +weaker lines. The accuracy of this method is determined by the +accuracy of the line centering algorithm. +.PP +The alternative method is to compare an observed +spectrum to a template spectrum of known radial velocity. This is done +by correlation or fourier ratio methods. These methods have the +advantage of using all of the spectrum and are good when there are many +very weak and possibly broad features. Their disadvantages are +confusion with telluric lines, they don't work well with just a few +real features, and they require a fair amount of preliminary +manipulation of the spectrum to remove continuum and interpolate the +spectrum in logarithmic wavelength intervals. IRAF tasks for +correlation and fourier ratio methods are under development at this +time. Many people assume that these more abstract methods are inherently +better than the classical method. This is not true, it depends on the +quality and type of data. +.PP +Wavelength measurements are best done on the original data rather than +after linearizing the wavelength intervals. This is because 1) it is +not necessary as will be shown below and 2) the interpolation used to +linearize the wavelength scale can change the shape of the lines, +particularly strong, narrow emission lines which are the best ones for +determining radial velocities. A second reason is that +\fBidentify\fR currently does not recognize the linear wavelength parameters +produced during linearization. This will be fixed soon but +in the mean time the lines must be measured in pixels and converted +later by the user. Alternatively one can determine a linear dispersion solution +with \fBidentify\fR but this is more work than needed. +.PP +This paper is specifically about \fBidentify\fR but one should be aware of the +task \fBsplot\fR which also may be used to measure radial velocities. It +differs in several respects from \fBidentify\fR. \fBSplot\fR works only on linearized +data; the wavelength and pixel coordinates are related by a zero point and +wavelength interval. The line centering algorithms are different; +the line centering is generally less robust (tolerant +of error) and often less accurate. It has many nice features but is +not designed for the specific purpose of measuring positions of lines +and, thus, is not as easy to use for this purpose. +.PP +There are a number of sources of additional information relating to the +use of the task \fBidentify\fR. The primary source is the manual pages for +the task. As with all manual pages it is available online with the +\fBhelp\fR command and in the \fIIRAF User Handbook\fR. The NOAO +reduction guides or cookbooks for the echelle and IIDS/IRS include +additional examples and discussion. The line centering algorithm +is the most critical factor in determining dispersion solutions and +radial velocities. It is described in more detail under the help +topic \fBcenter1d\fR online or in the handbook. +.NH +Method 1 +.PP +In this method arc calibration images are used to determine a wavelength +scale. The dispersion solution is then transferred to the object spectrum +and the wavelengths of emission and absorption lines are measured and +recorded. This is relatively straightforward but some tricks will make +this easier and more accurate. +.NH 2 +Transferring Dispersion Solutions +.PP +There are several ways to transfer the dispersion solution from an arc +spectrum to an object spectrum differing in the order in which things are +done. +.IP (1) +One way is to determine the dispersion solution for all the arc images +first. To do this interactively specify all the arc images as the +input to \fBidentify\fR. After determining the dispersion solution for +the first arc and quitting (\fIq\fR key) the next arc will be displayed +with the previous dispersion solution and lines retained. Then use the +cursor commands \fIa\fR and \fIc\fR (all center) to recenter and +recompute the dispersion solution, \fIs\fR to shift to the cursor +position, recenter, and recompute the dispersion solution, or \fIx\fR +to correlate features, shift, recenter, and recompute the dispersion +solution. These commands are relatively fast and simple. +.IP +A important reason for doing all the arc images first is that this same +procedure can be done mostly noninteractively with the task +\fBreidentify\fR. After determining a dispersion solution for one arc +image \fBreidentify\fR does the recenter (\fIa\fR and \fIc\fR), shift +and recenter (\fIs\fR), or correlation features, shift, and recenter +(\fIx\fR) to transfer the dispersion solutions between arcs. This is +usually done as a background task. +.IP +To transfer the solution to the object spectra specify the list of +object spectra as input to \fBidentify\fR. For each image begin by +entering the colon command \fI:read arc\fR where arc is the name of the +arc image whose dispersion solution is to be applied; normally the one +taken at the same time and telescope position as the object. This will +read the dispersion solution and arc line positions. Delete the arc +line positions with the \fIa\fR and \fId\fR (all delete) cursor keys. +You can now measure the wavelengths of lines in the spectrum. +.IP (2) +An alternative method is to interactively alternate between arc and +object spectra either in the input image list or with the \fI:image +name\fR colon command. +.NH 2 +Measuring Wavelengths +.PP +.IP (1) +To record the feature positions at any time use the \fI:features file\fR +colon command where file is where the feature information will be written. +Repeating this with the same file appends to the file. Writing to +the database with the \fI:write\fR colon command also records this information. +Without an argument the results are put in a file with the same name as the +image and a prefix of "id". You can use any name you like, however, +with \fI:write name\fR. The \fI:features\fR command is probably preferable +because it only records the line information while the database format +includes the dispersion solution and other information not needed for +computing radial velocities. +.IP (2) +Remember that when shifting between emission and absorption lines the +parameter \fIftype\fR must be changed. This may be done interactively with +the \fI:ftype emission\fR and \fI:ftype absorption\fR commands. This parameter +does not need to be set except when changing between types of lines. +.IP (3) +Since the centering of the emission or absorption line is the most +critical factor one should experiment with the parameter \fIfwidth\fR. +To change this parameter type \fI:fwidth value\fR. The positions of the +marked features are not changed until a center command (\fIc\fR) command +is given. \fIWarning: The all center (\fIa\fR and \fIc') command automatically +refits the dispersion solution to the lines which will lose your +arc dispersion solution.\fR +.IP +A narrow \fIfwidth\fR is less influenced by blends and wings but has a larger +uncertainty. A broad \fIfwidth\fR uses all of the line profile and is thus +stable but may be systematically influenced by blending and wings. One +possible approach is to measure the positions at several values of +\fIfwidth\fR and decide which value to use or use some weighting of the +various measurements. You can record each set of measurements with +the \fI:fe file\fR command. +.IP (4) +For calibration of systematic effects from the centering one should obtain +the spectrum of a similar object with a known radial velocity. The systematic +effect is due to the fact that the centering algorithm is measuring a +weighted function of the line profile which may not be the true center of +the line as tabulated in the laboratory or in a velocity standard. +By using the same centering method on an object with the same line profiles +and known velocity this effect can be eliminated. +.IP (5) +Since the arcs are not obtained at precisely the same time as the object +exposures there may be a wavelength shift relative to the arc dispersion +solution. This may be calibrated from night sky lines in the object +itself (the night sky lines are "good" in this case and should not be +subtracted away). There are generally not enough night sky lines to act +as the primary dispersion calibrator but just one can determine a possible +wavelength zero point shift. Measure the night sky line positions at the same +time the object lines are measured. Determine a zero point shift from +the night sky to be taken out of the object lines. +.NH +Method 2 +.PP +This method is similar to the correlation method in that a template +spectrum is used and the average shift relative to the template measures the +radial velocity. This has the advantage of not requiring the user to +do a lot of calculations (the averaging of the line shifts is done by +\fRidentify\fR) but is otherwise no better than method 1. +The template spectrum must have the same features as the object spectrum. +.IP (1) +Determine a dispersion solution for the template spectrum either from +the lines in the spectrum or from an arc calibration. +.IP (2) +Mark the features to be correlated in the template spectrum. +.IP (3) +Transfer the template dispersion solution and line positions to an object +spectrum using one of the methods described earlier. Then for the +current feature point the cursor near the same feature in the object +spectrum and type \fIs\fR. The mean shift in pixels, wavelength, and +fractional wavelength (like a radial velocity without the factor of +the speed of light) for the object is determined and printed. A new +dispersion solution is determined but you may ignore this. +.IP (4) +When doing additional object spectra remember to start over again with +the template spectrum (using \fI:read template\fR) and not the solution +from the last object spectrum. +.IP (5) +This procedure assumes that the dispersion solution between the template +and object are the same. Checks for zero point shifts with night sky +lines, as discussed earlier, should be made if possible. The systematic +centering bias, however, is accounted for by using the same lines from +the template radial velocity standard. +.IP (6) +One possible source of error is attempting to use very weak lines. The +recentering may find the wrong lines and affect the results. The protections +against this are the \fIthreshold\fR parameter (in Version 2.4 IRAF) and +setting the centering error radius to be relatively small. +.NH +Method 3 +.PP +This method uses only strong emission lines and works with linearized +data without an \fBidentify\fR dispersion solution. \fBIdentify\fR has +a failing when used with linearized data; it does not know about the +wavelength parameters in the image header. This will eventually be +fixed. However, if you have already linearized your spectra and wish +to use them instead of the nonlinear spectra the following method will +work. The recipe involves measuring the positions of emission lines in +pixels which must then be converted to wavelength using the header +information. The strongest emission lines are found automatically +using the \fIy\fR cursor key. The number of emission lines to be +identified is set by the \fImaxfeatures\fR parameter. The emission +line positions are then written to a data file using the \fI:features +file\fR colon command. This may be done interactively and takes only a +few moments per spectrum. If done interactively the images may be +chained by specifying an image template. The only trick required is +than when proceeding to the next spectrum the previous features are +deleted using the cursor key combination \fIa\fR and \fId\fR (all +delete). +.PP +For a large number of images, on the order of hundreds, this may be automated +as follows. A file containing the cursor commands is prepared. +The cursor command format consists of the x and y positions, the window +(usually window 1), and the key stroke or colon command. Because each new +image form an image template does not restart the cursor command file the +commands would have to be repeated for each image in the list. Thus, a CL +loop calling the +task each time with only one image is preferable. Besides redirecting +the cursor input from a command file we must also redirect the standard +input for the response to the database save query, the standard output +to discard the status line information, and, possibly, the graphics +to a metacode file which can then be reviewed later. The following +steps indicate what is to be done. +.IP (1) +Prepare a file containing the images to be measured (one per line). +This can usually be done using the sections command to expand a template +and directing the output into a file. +.IP (2) +Prepare the a cursor command file (let's call it cmdfile) containing the +following two lines. +.nf + 1 1 1 y + 1 1 1 :fe positions.dat +.fi +.IP (3) +Enter the following commands. +.nf + list="file" + while (fscan (list, s1) != EOF) { + print ("no") | identify (s1, maxfeatures=2, cursor="cmdfile", + >"dev$null", >G "plotfile") + } +.fi +.LP +Note that these commands could be put in a CL script and executed using the +command + + on> cl <script.cl + +.PP +The commands do the following. The first command initializes the image list +for the loop. The second command is the loop to be run until the end of +the image file is reached. The command in the loop directs the string +"no" to the standard input of identify which will be the response to the +database save query. The identify command uses the image name obtained +from the list by the fscan procedure, sets the maximum number of features +to be found to be 2 (this can be set using \fBeparam\fR instead), the cursor +input is taken from the cursor command file, the standard output is +discarded to the null device, and the STDGRAPH output is redirected to +a plot file. If the plot file redirection is not used then the graphs +will appear on the specified graphics device (usually the graphics terminal). +The plot file can then be disposed of using the \fBgkimosaic\fR task to either +the graphics terminal or a hardcopy device. diff --git a/noao/onedspec/doc/sys/sensfunc.ms b/noao/onedspec/doc/sys/sensfunc.ms new file mode 100644 index 00000000..67b6532d --- /dev/null +++ b/noao/onedspec/doc/sys/sensfunc.ms @@ -0,0 +1,83 @@ +.EQ +delim $$ +.EN +.OM +.TO +IRAF ONEDSPEC Users +.FR +Frank Valdes +.SU +SENSFUNC Corrections +.LP +This memorandum describes the meaning of the corrections +computed by the \fBonedspec\fR task \fBsensfunc\fR. +The basic equation is + +.EQ (1) +I( lambda )~=~I sub obs ( lambda )~10 sup {0.4~(s( lambda )~+ +~A~e( lambda )~+~roman {fudge~terms})} +.EN + +where $I sub obs$ is the observed spectrum corrected to counts per second, +$I$ is the flux calibrated spectrum, $s( lambda )$ is the sensitivity +correction needed to produce +flux calibrated intensities, $A$ is the air mass at the time of the +observation, $e( lambda )$ is a standard extinction function, and, +finally, additional terms appropriately called \fIfudge\fR terms. Expressed +as a magnitude correction this equation is + +.EQ (2) +DELTA m( lambda )~=s( lambda )~+~A~e( lambda )~+~roman {fudge~terms} +.EN + +In \fBsensfunc\fR the standard extinction function is applied so that ideally +the $DELTA m$ curves (defining the sensitivity function) obtained from +observations of different stars and at different air masses are identical. +However, at times this is not the case because the observations were taken +through non-constant or nonstandard extinction. + +There are two types of fudge terms used in \fBsensfunc\fR, called \fIfudge\fR +and \fIgrey\fR. The \fIfudge\fR correction is a separate constant, +independent of wavelength or air mass, applied to each observation to shift +the sensitivity curves to the same level on average. This is done to +determine the shape of the sensitivity curve only. +The fudge correction for each observation is obtained by determining +the average magnitude shift over all wavelenths relative to the observation +with the smallest sensitivity correction. A composite sensitivity curve +is then determined from the average of all the fudged observations. +The fudge terms are not incorporated in the sensitivity or extinction +corrections applied to calibrate the spectra. Thus, after applying the +sensitivity and extinction corrections to the standard star spectra there +will be absolute flux scale errors due to the observing conditions. + +If the observer believes that there is an actual calibratible error in +the standard extinction then \fBsensfunc\fR can be used to determine a +correction which is a linear function of the air mass. This is done by +relating the fudge values (the magnitude shifts needed to bring observations +to the same sensitivity level) to the air mass of the observations. +The \fIgrey\fR term is obtained by the least square fit to + +.EQ (3) +f sub i~=~G~DELTA A sub i~=~G~A sub i~+~C +.EN + +where the $f sub i$ are the fudge values relative to the observation with +the smallest sensitivity correction and the $DELTA A sub i$ are the +air mass differences relative to this same observation. The slope constant +$G$ is what is refered to as the \fIgrey\fR term. The constant term, +related to the air mass of the reference observation to which the other +spectra are shifted, is absorbed in the sensitivity function. +The modified equation (2) is + +.EQ (4) +DELTA m( lambda )~=~s ( lambda ) + A~(e( lambda )~+~G) +.EN + +It is important to realize that equation (3) can lead to erroneous results +if there is no real relation to the air mass or the air mass range is +too small. In other words applying the grey term correction will produce +some number for $G$ but it may be worse than no correction. A plot of +the individual fudge constants, $f sub i$, and the air mass or +air mass differences would be useful to evaluate the validity of the +grey correction. The actual magnitude of the correction is not $G$ +but $DELTA A~G$ where $DELTA A$ is the range of observed air mass. diff --git a/noao/onedspec/doc/sys/specwcs.ms b/noao/onedspec/doc/sys/specwcs.ms new file mode 100644 index 00000000..a9d90a41 --- /dev/null +++ b/noao/onedspec/doc/sys/specwcs.ms @@ -0,0 +1,612 @@ +.EQ +delim $$ +gsize 10 +.EN +.nr PS 11 +.nr VS 13 +.de V1 +.ft CW +.ps -2 +.nf +.. +.de V2 +.fi +.ft R +.ps +2 +.. +.ND March 1993 +.TL +The IRAF/NOAO Spectral World Coordinate Systems +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +.DY + +.AB +The image formats and world coordinate systems for dispersion calibrated +spectra used in the IRAF/NOAO spectroscopy packages are described; in +particular, the image header keywords defining the coordinates are given. +These keywords appear both as part of the IRAF image structure and map +directly to FITS format. The types of spectra include multidimensional +images with one or more spatial axes and a linear or log-linear dispersion +axis and special \fIequispec\fR and \fImultispec\fR formats having multiple +independent one dimensional spectra in a single multidimensional image. +The \fImultispec\fR format also includes general nonlinear dispersion +coordinate systems using polynomial, spline, sampled table, and look-up +table functions. +.AE + +.NH +Types of Spectral Data +.LP +Spectra are stored as one, two, or three dimensional images with one axis +being the dispersion axis. A pixel value is the flux over +some interval of wavelength and position. The simplest example of a +spectrum is a one dimensional image which has pixel values as a +function of wavelength. +.LP +There are two types of higher dimensional spectral image formats. One type +has spatial axes for the other dimensions and the dispersion axis may be +along any of the image axes. Typically this type of format is used for +long slit (two dimensional) and Fabry-Perot (three dimensional) spectra. +This type of spectra is referred to as \fIspatial\fR spectra and the +world coordinate system (WCS) format is called \fIndspec\fR. +The details of the world coordinate systems are discussed later. +.LP +The second type of higher dimensional spectral image consists of multiple, +independent, one dimensional spectra stored in the higher dimensions with +the first image axis being the dispersion axis; i.e. each line is a +spectrum. This format allows associating many spectra and related +parameters in a single data object. This type of spectra is referred to +as \fImultispec\fR and the there are two coordinate system formats, +\fIequispec\fR and \fImultispec\fR. The \fIequispec\fR format applies +to the common case where all spectra have the same linear dispersion +relation. The \fImultispec\fR format applies to the general case of spectra +with differing dispersion relations or non-linear dispersion functions. +These multi-spectrum formats are important since maintaining large numbers +of spectra as individual one dimensional images is very unwieldy for the +user and inefficient for the software. +.LP +Examples of multispec spectral images are spectra extracted from a +multi-fiber or multi-aperture spectrograph or orders from an echelle +spectrum. The second axis is some arbitrary indexing of the spectra, +called \fIapertures\fR, and the third dimension is used for +associated quantities. The IRAF \fBapextract\fR package may produce +multiple spectra from a CCD image in successive image lines with an +optimally weighted spectrum, a simple aperture sum spectrum, a background +spectrum, and sigma spectrum as the associated quantities along the third +dimension of the image. +.LP +Many \fBonedspec\fR package tasks which are designed to operate on +individual one dimensional spectra may operate on spatial spectra by +summing a number of neighboring spectra across the dispersion axis. This +eliminates the need to "extract" one dimensional spectra from the natural +format of this type of data in order to use tasks oriented towards the +display and analysis of one dimensional spectra. The dispersion axis is +either given in the image header by the keyword DISPAXIS or the package +\fIdispaxis\fR parameter. The summing factors across the +dispersion are specified by the \fInsum\fR package parameter. +.LP +One dimensional spectra, whether from multispec spatial spectra, have +several associated quantities which may appear in the image header as part +of the coordinate system description. The primary identification of a +spectrum is an integer aperture number. This number must be unique within +a single image. There is also an integer beam number used for various +purposes such as discriminating object, sky, and arc spectra in +multi-fiber/multi-aperture data or to identifying the order number in +echelle data. For spectra summed from spatial spectra the aperture number +is the central line, column, or band. In 3D images the aperture index +wraps around the lowest non-dispersion axis. Since most one dimensional +spectra are derived from an integration over one or more spatial axes, two +additional aperture parameters record the aperture limits. These limits +refer to the original pixel limits along the spatial axis. This +information is primarily for record keeping but in some cases it is used +for spatial interpolation during dispersion calibration. These values are +set either by the \fBapextract\fR tasks or when summing neighboring vectors +in spatial spectra. +.LP +An important task to be aware of for manipulating spectra between image +formats is \fBscopy\fR. This task allows selecting spectra from multispec +images and grouping them in various ways and also "extracts" apertures from +long slit and 3D spectra simply and without resort to the more general +\fBapextract\fR package. +.NH +World Coordinate Systems +.LP +IRAF images have three types of coordinate systems. The pixel array +coordinates of an image or image section, i.e. the lines and +columns, are called the \fIlogical\fR coordinates. The logical coordinates of +individual pixels change as sections of the image are used or extracted. +Pixel coordinates are tied to the data, i.e. are fixed to features +in the image, are called \fIphysical\fR coordinates. Initially the logical +and physical coordinates are the equivalent but differ when image sections +or other tasks which modify the sampling of the pixels are applied. +.LP +The last type of coordinate system is called the \fIworld\fR coordinate +system. Like the physical coordinates, the world coordinates are tied to +the features in the image and remain unchanged when sections of the image +are used or extracted. If a world coordinate system is not defined for an +image, the physical coordinate system is considered to be the world +coordinate system. In spectral images the world coordinate system includes +dispersion coordinates such as wavelengths. In many tasks outside the +spectroscopy packages, for example the \fBplot\fR, \fBtv\fR and +\fBimages\fR packages, one may select the type of coordinate system to be +used. To make plots and get coordinates in dispersion units for spectra +with these tasks one selects the "world" system. The spectral tasks always +use world coordinates. +.LP +The coordinate systems are defined in the image headers using a set of +reserved keywords which are set, changed, and updated by various tasks. +Some of the keywords consist of simple single values following the FITS +convention. Others, the WAT keywords, encode long strings of information, +one for each coordinate axis and one applying to all axes, into a set of +sequential keywords. The values of these keywords must then be pasted +together to recover the string. The long strings contain multiple pieces +called WCS \fIattributes\fR. In general the WCS keywords should be left to +IRAF tasks to modify. However, if one wants modify them directly some +tasks which may be used are \fBhedit\fR, \fBhfix\fR, \fBwcsedit\fR, +\fBwcsreset\fR, \fBspecshift\fR, \fBdopcor\fR, and \fBsapertures\fR. The +first two are useful for the simple keywords, the two "wcs" tasks are +useful for the linear ndspec and equispec formats, the next two are for the +common cases of shifting the coordinate zero point or applying a doppler +correction, and the last one is the one to use for the more complex +multispec format attributes. +.NH +Physical Coordinate System +.LP +The physical coordinate system is used by the spectral tasks when there is +no dispersion coordinate information (such as before dispersion +calibration), to map the physical dispersion axis to the logical dispersion +axis, and in the multispec world coordinate system dispersion functions +which are defined in terms of physical coordinates. +.LP +The transformation between logical and physical coordinates is defined by +the header keywords LTVi, LTMi_j (where i and j are axis numbers) through +the vector equation + +.EQ I + l vec~=~|m| cdot p vec + v vec +.EN + +where $l vec$ is a logical coordinate vector, $p vec$ is a physical +coordinate vector, $v vec$ is the origin translation vector specified by +the LTV keywords and $|m|$ is the scale/rotation matrix +specified by the LTM keywords. For spectra rotation terms (nondiagonal +matrix elements) generally do not make sense (in fact many tasks will not +work if there is a rotation) so the transformations along each axis are +given by the linear equation + +.EQ I + l sub i~=~LTMi_i cdot p sub i + LTVi. +.EN + +If all the LTM/LTV keywords are missing they are assumed to have zero +values except that the diagonal matrix terms, LTMi_i, are assumed to be 1. +Note that if some of the keywords are present then a missing LTMi_i will +take the value zero which generally causes an arithmetic or matrix +inversion error in the IRAF tasks. +.LP +The dimensional mapping between logical and physical axes is given by the +keywords WCSDIM and WAXMAP01. The WCSDIM keyword gives the dimensionality +of the physical and world coordinate system. There must be coordinate +information for that many axes in the header (though some may be missing +and take their default values). If the WCSDIM keyword is missing it is +assumed to be the same as the logical image dimensionality. +.LP +The syntax of the WAXMAP keyword are pairs of integer values, +one for each physical axis. The first number of each pair indicates which +current \fIlogical\fR axis corresponds to the original \fIphysical\fR axis +(in order) or zero if that axis is missing. When the first number is zero +the second number gives the offset to the element of the original axis +which is missing. As an example consider a three dimensional image in +which the second plane is extracted (an IRAF image section of [*,2,*]). +The keyword would then appear as WAXMAP01 = '1 0 0 1 2 0'. If this keyword +is missing the mapping is 1:1; i.e. the dimensionality and order of the +axes are the same. +.LP +The dimensional mapping is important because the dispersion axis for +the nspec spatial spectra as specified by the DISPAXIS keyword or task +parameter, or the axis definitions for the equispec and or multispec +formats are always in terms of the original physical axes. +.NH +Linear Spectral World Coordinate Systems +.LP +When there is a linear or logarithmic relation between pixels and +dispersion coordinates which is the same for all spectra the WCS header +format is simple and uses the FITS convention (with the CD matrix keywords +proposed by Hanisch and Wells 1992) for the logical pixel to world +coordinate transformation. This format applies to one, two, and three +dimensional data. The higher dimensional data may have either linear +spatial axes or the equispec format where each one dimensional spectrum +stored along the lines of the image has the same dispersion. +.LP +The FITS image header keywords describing the spectral world coordinates +are CTYPEi, CRPIXi, CRVALi, and CDi_j where i and j are axis numbers. As +with the physical coordinate transformation the nondiagonal or rotation +terms are not expected in the spectral WCS and may cause problems if they +are not zero. The CTYPEi keywords will have the value LINEAR to identify +the type of of coordinate system. The transformation between dispersion +coordinate, $w sub i$, and logical pixel coordinate, $l sub i$, along axis i is given by + +.EQ I + w sub i~=~CRVALi + CDi_i cdot (l sub i - CRPIXi) +.EN + +If the keywords are missing then the values are assumed to be zero except +for the diagonal elements of the scale/rotation matrix, the CDi_i, which +are assumed to be 1. If only some of the keywords are present then any +missing CDi_i keywords will take the value 0 which will cause IRAF tasks to +fail with arithmetic or matrix inversion errors. If the CTYPEi keyword is +missing it is assumed to be "LINEAR". +.LP +If the pixel sampling is logarithmic in the dispersion coordinate, as +required for radial velocity cross-correlations, the WCS coordinate values +are logarithmic and $w sub i$ (above) is the logarithm of the dispersion +coordinate. The spectral tasks (though not other tasks) will recognize +this case and automatically apply the anti-log. The two types of pixel +sampling are identified by the value of the keyword DC-FLAG. A value of 0 +defines a linear sampling of the dispersion and a value of 1 defines a +logarithmic sampling of the dispersion. Thus, in all cases the spectral +tasks will display and analyze the spectra in the same dispersion units +regardless of the pixel sampling. +.LP +Other keywords which may be present are DISPAXIS for 2 and 3 dimensional +spatial spectra, and the WCS attributes "system", "wtype", "label", and +"units". The system attribute will usually have the value "world" for +spatial spectra and "equispec" for equispec spectra. The wtype attribute +will have the value "linear". Currently the label will be either "Pixel" +or "Wavelength" and the units will be "Angstroms" for dispersion corrected +spectra. In the future there will be more generality in the units +for dispersion calibrated spectra. +.LP +Figure 1 shows the WCS keywords for a two dimensional long slit spectrum. +The coordinate system is defined to be a generic "world" system and the +wtype attributes and CTYPE keywords define the axes to be linear. The +other attributes define a label and unit for the second axis, which is the +dispersion axis as indicated by the DISPAXIS keyword. The LTM/LTV keywords +in this example show that a subsection of the original image has been +extracted with a factor of 2 block averaging along the dispersion axis. +The dispersion coordinates are given in terms of the \fIlogical\fR pixel +coordinates by the FITS keywords as defined previously. + +.DS +.ce +Figure 1: Long Slit Spectrum + +.V1 +WAT0_001= 'system=world' +WAT1_001= 'wtype=linear' +WAT2_001= 'wtype=linear label=Wavelength units=Angstroms' +WCSDIM = 2 +DISPAXIS= 2 +DC-FLAG = 0 + +CTYPE1 = 'LINEAR ' +LTV1 = -10. +LTM1_1 = 1. +CRPIX1 = -9. +CRVAL1 = 19.5743865966797 +CD1_1 = 1.01503419876099 + +CTYPE2 = 'LINEAR ' +LTV2 = -49.5 +LTM2_2 = 0.5 +CRPIX2 = -49. +CRVAL2 = 4204.462890625 +CD2_2 = 12.3337936401367 +.V2 +.DE + +Figure 2 shows the WCS keywords for a three dimensional image where each +line is an independent spectrum or associated data but where all spectra +have the same linear dispersion. This type of coordinate system has the +system name "equispec". The ancillary information about each aperture is +found in the APNUM keywords. These give the aperture number, beam number, +and extraction limits. In this example the LTM/LTV keywords have their +default values; i.e. the logical and physical coordinates are the same. + +.DS +.ce +Figure 2: Equispec Spectrum + +.V1 +WAT0_001= 'system=equispec' +WAT1_001= 'wtype=linear label=Wavelength units=Angstroms' +WAT2_001= 'wtype=linear' +WAT3_001= 'wtype=linear' +WCSDIM = 3 +DC-FLAG = 0 +APNUM1 = '41 3 7.37 13.48' +APNUM2 = '15 1 28.04 34.15' +APNUM3 = '33 2 43.20 49.32' + +CTYPE1 = 'LINEAR ' +LTM1_1 = 1. +CRPIX1 = 1. +CRVAL1 = 4204.463 +CD1_1 = 6.16689700000001 + +CTYPE2 = 'LINEAR ' +LTM2_2 = 1. +CD2_2 = 1. + +CTYPE3 = 'LINEAR ' +LTM3_3 = 1. +CD3_3 = 1. +.V2 +.DE +.NH +Multispec Spectral World Coordinate System +.LP +The \fImultispec\fR spectral world coordinate system applies only to one +dimensional spectra; i.e. there is no analog for the spatial type spectra. +It is used either when there are multiple 1D spectra with differing +dispersion functions in a single image or when the dispersion functions are +nonlinear. +.LP +The multispec coordinate system is always two dimensional though there may +be an independent third axis. The two axes are coupled and they both have +axis type "multispec". When the image is one dimensional the physical line +is given by the dimensional reduction keyword WAXMAP. The second, line +axis, has world coordinates of aperture number. The aperture numbers are +integer values and need not be in any particular order but do need to be +unique. This aspect of the WCS is not of particular user interest but +applications use the inverse world to physical transformation to select a +spectrum line given a specified aperture. +.LP +The dispersion functions are specified by attribute strings with the +identifier \fIspecN\fR where N is the \fIphysical\fR image line. The +attribute strings contain a series of numeric fields. The fields are +indicated symbolically as follows. + +.EQ I + specN~=~ap~beam~dtype~w1~dw~nw~z~aplow~aphigh~[functions sub i ] +.EN + +where there are zero or more functions having the following fields, + +.EQ I + function sub i~=~ wt sub i~w0 sub i~ftype sub i~[parameters]~[coefficients] +.EN + +The first nine fields in the attribute are common to all the dispersion +functions. The first field of the WCS attribute is the aperture number, +the second field is the beam number, and the third field is the dispersion +type with the same function as DC-FLAG in the \fInspec\fR and +\fIequispec\fR formats. A value of -1 indicates the coordinates are not +dispersion coordinates (the spectrum is not dispersion calibrated), a value +of 0 indicates linear dispersion sampling, a value of 1 indicates +log-linear dispersion sampling, and a value of 2 indicates a nonlinear +dispersion. +.LP +The next two fields are the dispersion coordinate of the first +\fIphysical\fR pixel and the average dispersion interval per \fIphysical\fR +pixel. For linear and log-linear dispersion types the dispersion +parameters are exact while for the nonlinear dispersion functions they are +approximate. The next field is the number of valid pixels, hence it is +possible to have spectra with varying lengths in the same image. In that +case the image is as big as the biggest spectrum and the number of pixels +selects the actual data in each image line. The next (seventh) field is a +doppler factor. This doppler factor is applied to all dispersion +coordinates by multiplying by $1/(1+z)$ (assuming wavelength dispersion +units). Thus a value of 0 is no doppler correction. The last two fields +are extraction aperture limits as discussed previously. +.LP +Following these fields are zero or more function descriptions. For linear +or log-linear dispersion coordinate systems there are no function fields. +For the nonlinear dispersion systems the function fields specify a weight, +a zero point offset, the type of dispersion function, and the parameters +and coefficients describing it. The function type codes, $ftype sub i$, +are 1 for a chebyshev polynomial, 2 for a legendre polynomial, 3 for a +cubic spline, 4 for a linear spline, 5 for a pixel coordinate array, and 6 +for a sampled coordinate array. The number of fields before the next +function and the number of functions are determined from the parameters of +the preceding function until the end of the attribute is reached. +.LP +The equation below shows how the final wavelength is computed based on +the $nfunc$ individual dispersion functions $W sub i (p)$. Note that this +is completely general in that different function types may be combined. +However, in practice when multiple functions are used they are generally of +the same type and represent a calibration before and after the actual +object observation with the weights based on the relative time difference +between the calibration dispersion functions and the object observation. + +.EQ I +w~=~sum from i=1 to nfunc {wt sub i cdot (w0 sub i + W sub i (p)) / (1 + z)} +.EN + +The multispec coordinate systems define a transformation between physical +pixel, $p$, and world coordinates, $w$. Generally there is an intermediate +coordinate system used. The following equations define these coordinates. +The first one shows the transformation between logical, $l$, and physical, +$p$, coordinates based on the LTM/LTV keywords. The polynomial functions +are defined in terms of a normalized coordinate, $n$, as shown in the +second equation. The normalized coordinates run between -1 and 1 over the +range of physical coordinates, $p sub min$ and $p sub max$ which are +parameters of the function, upon which the coefficients were defined. The +spline functions map the physical range into an index over the number of +evenly divided spline pieces, $npieces$, which is a parameter of the +function. This mapping is shown in the third and fourth equations where +$s$ is the continuous spline coordinate and $j$ is the nearest integer less +than or equal to $s$. + +.EQ I + p mark~=~(l - LTV1) / LTM1_1 +.EN +.EQ I + n lineup~=~(p - p sub middle ) / (2 cdot p sub range ) +.EN +.EQ I + lineup~=~(p - (p sub max + p sub min )/2) / (2 cdot (p sub max - p sub min )) +.EN +.EQ I + s lineup~=~(p - p sub min ) / (p sub max - p sub min ) cdot npieces +.EN +.EQ I + j lineup~=~roman "int" (s) +.EN +.NH 2 +Linear and Log Linear Dispersion Function +.LP +The linear and log-linear dispersion functions are described by a +wavelength at the first \fIphysical\fR pixel and a wavelength increment per +\fIphysical\fR pixel. A doppler correction may also be applied. The +equations below show the two forms. Note that the coordinates returned are +always wavelength even though the pixel sampling and the dispersion +parameters may be log-linear. + +.EQ I + w mark~=~(w1 + dw cdot (p - 1)) / (1 + z) +.EN +.EQ I + w lineup~=~10 sup {(w1 + dw cdot (p - 1)) / (1 + z)} +.EN + +Figure 3 shows an example from a multispec image with +independent linear dispersion coordinates. This is a linearized echelle +spectrum where each order (identified by the beam number) is stored as a +separate image line. + +.DS +.ce +Figure 3: Echelle Spectrum with Linear Dispersion Function + +.V1 +WAT0_001= 'system=multispec' +WAT1_001= 'wtype=multispec label=Wavelength units=Angstroms' +WAT2_001= 'wtype=multispec spec1 = "1 113 0 4955.44287109375 0.05... +WAT2_002= '5 256 0. 23.22 31.27" spec2 = "2 112 0 4999.0810546875... +WAT2_003= '58854293 256 0. 46.09 58.44" spec3 = "3 111 0 5043.505... +WAT2_004= '928358078002 256 0. 69.28 77.89" +WCSDIM = 2 + +CTYPE1 = 'MULTISPE' +LTM1_1 = 1. +CD1_1 = 1. + +CTYPE2 = 'MULTISPE' +LTM2_2 = 1. +CD2_2 = 1. +.V2 +.DE +.NH 2 +Chebyshev Polynomial Dispersion Function +.LP +The parameters for the chebyshev polynomial dispersion function are the +$order$ (number of coefficients) and the normalizing range of physical +coordinates, $p sub min$ and $p sub max$, over which the function is +defined and which are used to compute $n$. Following the parameters are +the $order$ coefficients, $c sub i$. The equation below shows how to +evaluate the function using an iterative definition where $x sub 1 = 1$, +$x sub 2 = n$, and $x sub i = 2 cdot n cdot x sub {i-1} - x sub {i-2}$. + +.EQ I + W~=~sum from i=1 to order {c sub i cdot x sub i} +.EN +.NH 2 +Legendre Polynomial Dispersion Function +.LP +The parameters for the legendre polynomial dispersion function are the +order (number of coefficients) and the normalizing range of physical +coordinates, pmin and pmax, over which the function is defined +and which are used to compute n. Following the parameters are the +order coefficients, c sub i. The equation below shows how to evaluate the +function using an iterative definition where $x sub 1 = 1$, $x sub 2 = n$, and +$x sub i = ((2i-3) cdot n cdot x sub {i-1} - (i-2) cdot x sub {i-2}) / (i-1)$. + +.EQ I + W~=~sum from i=1 to order {c sub i cdot x sub i} +.EN +.LP +Figure 4 shows an example from a multispec image with independent nonlinear +dispersion coordinates. This is again from an echelle spectrum. Note that +the IRAF \fBechelle\fR package determines a two dimensional dispersion +function, in this case a bidimensional legendre polynomial, with the +independent variables being the order number and the extracted pixel +coordinate. To assign and store this function in the image is simply a +matter of collapsing the two dimensional dispersion function by fixing the +order number and combining all the terms with the same order. + +.DS +.ce +Figure 4: Echelle Spectrum with Legendre Polynomial Function + +.V1 +WAT0_001= 'system=multispec' +WAT1_001= 'wtype=multispec label=Wavelength units=Angstroms' +WAT2_001= 'wtype=multispec spec1 = "1 113 2 4955.442888635351 0.05... +WAT2_002= '83 256 0. 23.22 31.27 1. 0. 2 4 1. 256. 4963.0163112090... +WAT2_003= '976664 -0.3191636898579552 -0.8169352858733255" spec2 =... +WAT2_004= '9.081188912082 0.06387049476832223 256 0. 46.09 58.44 1... +WAT2_005= '56. 5007.401409453303 8.555959076467951 -0.176732458267... +WAT2_006= '09935064388" spec3 = "3 111 2 5043.505764869474 0.07097... +WAT2_007= '256 0. 69.28 77.89 1. 0. 2 4 1. 256. 5052.586239197408 ... +WAT2_008= '271 -0.03173489817897474 -7.190562320405975E-4" +WCSDIM = 2 + +CTYPE1 = 'MULTISPE' +LTM1_1 = 1. +CD1_1 = 1. + +CTYPE2 = 'MULTISPE' +LTM2_2 = 1. +CD2_2 = 1. +.V2 +.DE +.NH 2 +Linear Spline Dispersion Function +.LP +The parameters for the linear spline dispersion function are the number of +spline pieces, $npieces$, and the range of physical coordinates, $p sub min$ +and $p sub max$, over which the function is defined and which are used to +compute the spline coordinate $s$. Following the parameters are the +$npieces+1$ coefficients, $c sub i$. The two coefficients used in a linear +combination are selected based on the spline coordinate, where $a$ and $b$ +are the fractions of the interval in the spline piece between the spline +knots, $a=(j+1)-s$, $b=s-j$, and $x sub 0 =a$, and $x sub 1 =b$. + +.EQ I + W~=~sum from i=0 to 1 {c sub (i+j) cdot x sub i} +.EN +.NH 2 +Cubic Spline Dispersion Function +.LP +The parameters for the cubic spline dispersion function are the number of +spline pieces, $npieces$, and the range of physical coordinates, $p sub min$ +and $p sub max$, over which the function is defined and which are used +to compute the spline coordinate $s$. Following the parameters are the +$npieces+3$ coefficients, $c sub i$. The four coefficients used are +selected based on the spline coordinate. The fractions of the interval +between the integer spline knots are given by $a$ and $b$, $a=(j+1)-s$, +b=$s-j$, and $x sub 0 =a sup 3$, $x sub 1 =(1+3 cdot a cdot (1+a cdot b))$, +$x sub 2 =(1+3 cdot b cdot (1+a cdot b))$, and $x sub 3 =b sup 3$. + +.EQ I + W~=~sum from i=0 to 3 {c sub (i+j) cdot x sub i} +.EN +.NH 2 +Pixel Array Dispersion Function +.LP +The parameters for the pixel array dispersion function consists of just the +number of coordinates $ncoords$. Following this are the wavelengths at +integer physical pixel coordinates starting with 1. To evaluate a +wavelength at some physical coordinate, not necessarily an integer, a +linear interpolation is used between the nearest integer physical coordinates +and the desired physical coordinate where $a$ and $b$ are the usual +fractional intervals $k= roman "int" (p)$, $a=(k+1)-p$, $b=p-k$, +and $x sub 0 =a$, and $x sub 1 =b$. + +.EQ I + W~=~sum from i=0 to 1 {c sub (i+j) cdot x sub i} +.EN +.NH 2 +Sampled Array Dispersion Function +.LP +The parameters for the sampled array dispersion function consists of +the number of coordinate pairs, $ncoords$, and a dummy field. +Following these are the physical coordinate and wavelength pairs +which are in increasing order. The nearest physical coordinates to the +desired physical coordinate are located and a linear interpolation +is computed between the two sample points. diff --git a/noao/onedspec/doc/telluric.hlp b/noao/onedspec/doc/telluric.hlp new file mode 100644 index 00000000..f0bfe597 --- /dev/null +++ b/noao/onedspec/doc/telluric.hlp @@ -0,0 +1,350 @@ +.help telluric Mar97 noao.onedspec +.ih +NAME +telluric -- remove telluric features from 1D spectra +.ih +SUMMARY +Telluric calibration spectra are shifted and scaled to best divide out +telluric features from data spectra. This may be done non-interactively to +minimize the RMS in some region or regions of the data spectra and +interactively with a graphically search. +.ih +USAGE +telluric input output cal +.ih +PARAMETERS +.ls input +List of input data images containing one dimensional spectra to be +corrected. All spectra in each image are corrected. The spectra need not +be wavelength calibrated. +.le +.ls output +List of output corrected images. The list must either match the input list +or be an empty list. If an empty list is specified the input spectra will +be replaced by the corrected spectra. The input spectra will also be +replaced if the input and output image names are the same. Any other image +name must be for a new image otherwise a warning message will be given and +the task will proceed to the next input image. +.le +.ls cal +List of telluric calibration images. If a single image is specified it +will apply to all the input images. Otherwise the list of calibration +images must match the list of input images. +.le +.ls ignoreaps = no +Ignore aperture numbers between the input spectra and the calibration +spectra? If "no" then the calibration image must contain a spectrum +with the same aperture number as each spectrum in the input image. +Otherwise the first spectrum in the calibration image will be used +for all spectra in the input image. +.le +.ls xcorr = yes +Cross-correlate each input spectrum with the calibration spectrum to +determine an shift for the calibration spectrum? Only regions specified by +the sample regions parameter will be used in the cross-correlation. +.le +.ls tweakrms = yes +Search for the minimum RMS in the corrected spectrum by adjusting the +shifts and scales between the input spectrum and the calibration spectrum? +The RMS is minimized in the specified sample regions. +.le +.ls interactive = yes +Enter an interactive graphical mode to search for the best shift +and scale between the input spectra and calibration spectra? This +is done after the optional automatic cross-correlation and RMS minimization +step. A query is made for each input spectrum so that the interactive +step may be skipped during the execution of the task. +.le +.ls sample = "*" +Sample regions to use for cross-correlation, automatic RMS minimization, +and RMS values. The sample regions are specified by a list of comma +separated ranges. The ranges are colon separate coordinate values. +For dispersion calibrated spectra the coordinate values are in the +dispersion units otherwise they are in pixel coordinates. The string "*" +selects the entire spectrum. The sample regions may be changed +interactively either with the cursor or with a colon command. +.le +.ls threshold = 0. +Since the calibration consists of division by the scaled calibration data +it is possible for totally saturated lines to have zero or negative values. +The task will quit if detects negative or zero calibration values. The +\fIthreshold\fR allows applying a minimum threshold to the calibration +values so the task may continue. +.le +.ls lag = 10 +The cross-correlation lag to use when \fIxcorr\fR = yes. The lag +is given in pixels. This is the distance to either side of the +initial shift over which the cross-correlation profile is computed. +If a value of zero is given then the cross-correlation step is not done. +.le +.ls shift = 0., dshift = 1. +The initial shift and shift step in pixels. This initializes the shift +search parameters for the first spectrum. If \fIdshift\fR is zero then +there will be no search for a new shift and the 'x' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls scale = 1., dscale = 0.2 +The initial scale and scale step. This initializes the scale +search parameters for the first spectrum. If \fIdscale\fR is zero then +there will be no search for a new scale and the 'y' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls offset = 1. +The interactive search displays three candidate corrected spectra which +have been normalized to a mean of one. The offset is added and subtracted +to separate the three candidates. The value may be changed interactively. +.le +.ls smooth = 1 +The displayed candidate corrected spectra are smoothed by a moving +boxcar average with a box size specified by this parameter. The smoothing +only applies to the displayed spectra and does not affect the measured +RMS or the output corrected spectra. The value may be changed interactively. +.le +.ls cursor = "" +Input cursor for the interactive graphics. A null value selects the +graphics cursor otherwise a file of cursor values may be specified. +.le +.ls airmass +Query parameter for the airmass. If the airmass is not in the image +header under the keyword AIRMASS the user is queried for the airmass. +This parameter should not be specified on the command line. +.le +.ls answer +Query parameter for responding to the interactive question. This parameter +should not be specified on the command line. +.le +.ls interp = poly5 +The \fBpackage\fR parameter specifying the interpolation function for shifting +the calibration spectra to match the input spectra. +.le +.ih +DESCRIPTION +Input one dimensional spectra are corrected to remove telluric features by +dividing by shifted and scaled calibration spectra. The calibration +spectra are generally of hot, nearly featureless stars; hence this procedure +is sometimes referred to as a B-star correction. The shifting +allows for possible small shifts or errors in the dispersion zeropoints. +The intensity scaling allows for differences in the airmass and variations +in the abundance of the telluric species. The intensity scaling +uses Beer's law which is the approximation that the change in absorption +with abundance is an exponential relation. + +The following describes the correction. Let J(x_i) be the calibration +spectrum at a set of pixels x_i. An interpolation function is fit to this +spectrum to give J(x). The shifted and scaled calibration function +is then + +.nf + (1) J'(x) = max (threshold, J(x+dx)) ** (A / A_cal * scale) +.fi + +where dx is the pixel shift parameter, A is the airmass of the input +spectrum, A_cal is the airmass of the calibration spectrum, and +scale is the scale parameter. The operator "**" is exponentiation. +The max operation limits the calibration spectrum to be greater +than or equal to the specified threshold value. If the calibration +value is ever less than or equal to zero then the task will quit +with a warning error. + +The output corrected spectrum is then computed as + +.nf + (2) I'(x_i) = I(x_i) / (J'(x_i) / <J'>) +.fi + +where I' is the corrected spectrum, I is the input spectrum, and <J'> is +the mean of the shifted and scaled calibration spectrum to keep the output +intensities comparable to the input spectrum. The value of <J'> is +printed in the output as the "normalization". If the spectra are +dispersion calibrated, possibly with different dispersion parameters, then +the x values in (2) from the input spectrum are converted to matching +pixels in the calibration spectrum using the dispersion functions of the +two spectra. + +The purpose of this task is to determine the best values of the +shift and scale parameters dx and scale. There +are automatic and interactive methods provided. The automatic +methods are cross-correlation of the calibration and input spectra +to find a shift and an iterative search for the in both +shift and scale that minimizes the RMS of I' in some region. +The automatic methods are performed first, if selected, followed +by the interactive, graphical step. The following describes +the steps in the order in which they occur. + +The initial values of the shift and scale are set by the parameters +\fIshift\fR and \fIscale\fR for the first spectrum. After that the values +determined for the previous spectrum, those actually applied to correcting +that spectrum, are used as the initial values for the next spectrum. The +search steps and sample regions are also initialized by task parameters but +may be modified during the interactive step and the modified values apply +to subsequent spectra. + +If the \fIxcorr\fR parameter is yes and the \fIlag\fR parameter is +not zero the calibration spectrum is cross-correlated against the input +spectrum. Each spectrum is prepared as follows. A large scale continuum +is fit by a quadratic chebyshev using 5 iterations of sigma clipping with a +clipping factor of 3 sigma below the fit and 1 sigma above the fit and +rejecting the deviant points along with one pixel on either side. This +attempts to eliminate the effects of absorption lines. The continuum fit +is subtracted from the spectrum and the spectrum is extended and tapered by +a cosine function of length given by the \fIlag\fR parameter. + +The prepared spectra are then cross-correlated by shifting the calibration +spectrum plus and minus the specified \fIlag\fR amount about the current +shift value. Only the regions in the input spectrum specified by the +sample regions parameter are used in the correlation. This produces a +correlation profile whose peak defines the relative shift between the two +spectra. The current shift value is updated. This method assumes the +common telluric features dominate within the specified sample regions. The +lag size should be roughly the profile widths of the telluric features. + +If the \fItweakrms\fR parameter is yes and \fIdshift\fR is greater than +zero trial corrections at the current shift value and plus and minus one +shift step with the scale value fixed at its current value are made and the +RMS in the sample regions computed. If the RMS is smallest at the current +shift value the shift step is divided in half otherwise the current shift +value is set to the shift with the lowest RMS. The process is then +repeated with the new shift and shift step values. This continues until +either the shift step is less than 0.01 pixels or the shift is more than +two pixels from the initial shift. In the latter case the final shift is +reset to the original shift. + +The scale factor is then varied if \fIdscale\fR is greater than zero by the +scale step at a fixed shift in the same way as above to search for a +smaller RMS in the sample regions. This search terminates when the scale +step is less than 0.01 or if the scale value has departed by 100% of the +initial value. In the latter case the scale value is left unchanged. + +The search over the shifts and scales is repeated a second time after which +the tweak algorithm terminates. + +After the optional cross-correlation and tweak steps the interactive search +mode may be entered. This occurs if \fIinteractive\fR = yes. A query is +asking whether to search interactively. The answers may be "no", "yes", +"NO", or "YES". The lower case answers apply to the current spectrum and +the upper case answers apply to all subsequent spectra. This means that if +an answer of "NO" or "YES" is given then there will be no further queries +for the remaining input spectra. + +If the interactive step is selected a graph of three candidate corrections +for the input spectrum is displayed. There also may be a graph of the +calibration or input spectrum shown for reference. Initially the +calibration spectrum is displayed. The additional graph may be toggled off +and on and between the input and calibration spectra with the 'c' and 'd' +keys. The three candidate corrected spectra will be with the current shift +and scale in the middle and plus or minus one step in either the shift or +scale. Initially the spectra will be at different scale values. +Information about the current shift and scale and the step used is given in +the graph title. + +One may toggle between shift steps and scale steps with the 'x' (for shift) +or 'y' (for scale) keys. The RMS in the title is the RMS within the +currently defined sample regions. If one of the step values is zero then a +display of different values of that parameter will not be selected. The +step size will need to be set with a colon command to search in that +parameter. + +If 'x' is typed when the three spectra are at different shifts then the +nearest spectrum to the y cursor at the x cursor position will be +selected. If the central spectrum is selected the step size is divided in +half otherwise the current shift is changed and the selected spectrum +becomes the middle spectrum. Three new spectra are then shown. The same +applies if 'y' is typed when the three spectra are at different scales. +This allows an interactive search similar to the iterative tweakrms method +described previously except the user can use whatever criteria is desired +to search for the best scale and shift. + +There are additional keystrokes and colon commands to set or change sample +regions, reset the current shift, scale, and step sizes, expand the step +size in the current mode, adjust the offsets between the spectra, and +get help. The 'w' key and GTOOLS colon commands are available to window +the graphs. Any changes in the x limits apply to both graphs while y limit +adjustments apply to the graph pointed to by the cursor. + +Two other commands require a short explanation. The 'a' key may +be used to run the tweakrms algorithm starting from the current +shift, scale, and steps and the current sample regions. This allows +one to graphically set or reset the sample regions before doing +the RMS minimization. The ":smooth" command and associated +\fIsmooth\fR task parameter allow the corrected spectra to be +displayed with a boxcar smoothing to better see faint features in +noise. It is important to realize that the smoothing is only +done on the displayed spectra. The telluric correction and computed RMS +are done in the unsmoothed data. + +After the interactive step is quit with 'q' or if the interactive +step is not done then the final output spectrum is computed and +written to the output image. A brief log output is printed for +each spectrum. +.ih +CURSOR KEYS AND COLON COMMANDS +.nf +? - print help +a - automatic RMS minimization within sample regions +c - toggle calibration spectrum display +d - toggle data spectrum display +e - expand (double) the step for the current selection +q - quit +r - redraw the graphs +s - add or reset sample regions +w - window commands (see :/help for additional information) +x - graph and select from corrected shifted candidates +y - graph and select from corrected scaled candidates + +:help - print help +:shift [value] - print or reset the current shift +:scale [value] - print or reset the current scale +:dshift [value] - print or reset the current shift step +:dscale [value] - print or reset the current scale step +:offset [value] - print or reset the current offset between spectra +:sample [value] - print or reset the sample regions +:smooth [value] - print or reset the smoothing box size +.fi +.ih +EXAMPLES +1. To interactively search for a best correction with the default +cross-correlation and tweak steps: + +.nf + cl> telluric spec001.ms telspec001.ms spec005.ms +.fi + +2. To search only for a scale factor: + +.nf + cl> telluric spec001.ms telspec001.ms spec005.ms xcorr- dshift=0. +.fi + +3. To processes a set of spectra non-interactively with the same calibration +spectrum and to replace the input spectra with the corrected spectra and +log the processing: + +.nf + cl> telluric spec* "" calspec inter- > log +.fi + +4. To apply the simplest scaling by the ratio of the airmasses alone: + +.nf + cl> telluric spec* tel//spec* calspec inter- xcorr- tweak- inter- \ + >>> scale=1. shift=0. +.fi +.ih +REVISIONS +.ls TELLURIC V2.12.3 +The normalization is printed. +.le +.ls TELLURIC V2.11.2 +Threshold parameter added. +.le +.ls TELLURIC V2.11 +This task is new in this version. +.le +.ih +SEE ALSO +skytweak +.endhelp diff --git a/noao/onedspec/doc/telluric.key b/noao/onedspec/doc/telluric.key new file mode 100644 index 00000000..11a42cc3 --- /dev/null +++ b/noao/onedspec/doc/telluric.key @@ -0,0 +1,35 @@ + TELLURIC COMMAND SUMMARY + +? - print help +a - automatic RMS minimization within sample regions +c - toggle calibration spectrum display +d - toggle data spectrum display +e - expand (double) the step for the current selection +q - quit +r - redraw the graphs +s - add or reset sample regions +w - window commands (see :/help for additional information) +x - graph and select from corrected shifted candidates +y - graph and select from corrected scaled candidates + +:help - print help +:shift [value] - print or reset the current shift +:scale [value] - print or reset the current scale +:dshift [value] - print or reset the current shift step +:dscale [value] - print or reset the current scale step +:offset [value] - print or reset the current offset between spectra +:sample [value] - print or reset the sample regions +:smooth [value] - print or reset the smoothing box size + + +The stacked display shows three corrected candidate spectra. The center +one is for the current shift and scale and the other two are one step +higher or lower in the shift or scale. The current values and the +step is shown in the title. Toggle between the shift and scale candidates +with 'x' or 'y'. Select the best spectrum with the cursor and typing +'x' or 'y'. Selecting the middle spectrum with 'x' in the shift display +divides the shift step in half. Selecting one of the other spectra +changes the current shift. Selecting the middle spectrum with 'y' +in the scale display divides the scale step in half. Selecting one of +the other spectra changes the current scale. When 'q' is typed the +final shift and scale will be that of the middle spectrum. diff --git a/noao/onedspec/doc/wspectext.hlp b/noao/onedspec/doc/wspectext.hlp new file mode 100644 index 00000000..9840b7b4 --- /dev/null +++ b/noao/onedspec/doc/wspectext.hlp @@ -0,0 +1,96 @@ +.help wspectext Oct93 onedspec +.ih +NAME +wspectext -- convert 1D image spectra to an ascii text spectra +.ih +USAGE +wspectext input output +.ih +PARAMETERS +.ls input +Input list of 1D image spectra to be converted. If the image is +not one dimensional an warning will be given and the image will be skipped. +.le +.ls output +Output list of ascii text spectra filenames. The list must match the +input list. +.le +.ls header = yes +This parameter determines whether or not a descriptive header precedes the +wavelength and flux values written to the text file. When \fIheader = +no\fR, only a two column list of wavelengths and fluxes is output. +.le +.ls wformat = "" +The wavelength coordinate output format. If it is undefined the formatting +option stored with the WCS in the image header is used. If the WCS +formatting option is not defined then a free format is used. See +\fBlistpixels\fR for a description of the format syntax. +.le +.ih +DESCRIPTION +IRAF one dimensional spectra are converted to ascii text files. The +text files consist of an optional FITS type header followed by a two +column list of wavelengths and flux values. The format of the wavelengths +can be set but the flux values are given in free format. This task +is a combination of \fBwtextimage\fR and \fBlistpixels\fR. The output +of this task may be converted back to an image spectrum with the +task \fBrspectext\fR. + +Spectra which are not in 1D images such as multispec format or long slit +may first be converted to 1D images using \fBscopy\fR with format="onedspec". +.ih +EXAMPLES +1. Write a text file with a header. + +.nf + cl> wspectext spec001 text001 header+ wformat="%0.2f" + cl> type text001 + BITPIX = 8 / 8-bit ASCII characters + NAXIS = 1 / Number of Image Dimensions + NAXIS1 = 100 / Length of axis + ORIGIN = 'NOAO-IRAF: WTEXTIMAGE' / + IRAF-MAX= 0. / Max image pixel (out of date) + IRAF-MIN= 0. / Min image pixel (out of date) + IRAF-B/P= 32 / Image bits per pixel + IRAFTYPE= 'REAL FLOATING ' / Image datatype + OBJECT = 'TITLE ' / + FILENAME= 'TEST ' / IRAF filename + FORMAT = '5G14.7 ' / Text line format + APNUM1 = '1 1 ' + DC-FLAG = 0 + WCSDIM = 1 + CTYPE1 = 'LINEAR ' + CRVAL1 = 4000. + CRPIX1 = 1. + CDELT1 = 10.1010101010101 + CD1_1 = 10.1010101010101 + LTM1_1 = 1. + WAT0_001= 'system=equispec ' + WAT1_001= 'wtype=linear label=Wavelength units=Angstroms ' + END + + 4000.00 1000. + 4010.10 1005.54 + 4020.20 1011.05 + ... +.fi + +2. Write a simple text file with two columns of wavelength and flux. + +.nf + cl> wspectext spec001 text002 header- wformat="%0.2f" + cl> type text002 + 4000.00 1000. + 4010.10 1005.54 + 4020.20 1011.05 + ... +.fi +.ih +REVISIONS +.ls WSPECTEXT V2.10.3 +This is a new task with this version. +.le +.ih +SEE ALSO +rspectext, wtextimage, listpixels, scopy, imspec +.endhelp |