From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/onedspec/doc/aidpars.hlp | 563 +++++++ noao/onedspec/doc/autoidentify.hlp | 370 +++++ noao/onedspec/doc/bplot.hlp | 201 +++ noao/onedspec/doc/calibrate.hlp | 195 +++ noao/onedspec/doc/continuum.hlp | 263 ++++ noao/onedspec/doc/deredden.hlp | 201 +++ noao/onedspec/doc/dispcor.hlp | 497 +++++++ noao/onedspec/doc/disptrans.hlp | 193 +++ noao/onedspec/doc/dopcor.hlp | 184 +++ noao/onedspec/doc/fitprofs.hlp | 403 +++++ noao/onedspec/doc/identify.hlp | 810 ++++++++++ noao/onedspec/doc/lcalib.hlp | 125 ++ noao/onedspec/doc/mkspec.hlp | 86 ++ noao/onedspec/doc/names.hlp | 67 + noao/onedspec/doc/ndprep.hlp | 115 ++ noao/onedspec/doc/odcombine.hlp | 480 ++++++ noao/onedspec/doc/onedspec.hlp | 293 ++++ noao/onedspec/doc/refspectra.hlp | 413 ++++++ noao/onedspec/doc/reidentify.hlp | 516 +++++++ noao/onedspec/doc/rspectext.hlp | 138 ++ noao/onedspec/doc/sapertures.hlp | 217 +++ noao/onedspec/doc/sarith.hlp | 571 +++++++ noao/onedspec/doc/sbands.hlp | 209 +++ noao/onedspec/doc/scombine.hlp | 765 ++++++++++ noao/onedspec/doc/scoords.hlp | 83 ++ noao/onedspec/doc/scopy.hlp | 541 +++++++ noao/onedspec/doc/sensfunc.hlp | 447 ++++++ noao/onedspec/doc/sfit.hlp | 262 ++++ noao/onedspec/doc/sflip.hlp | 114 ++ noao/onedspec/doc/sinterp.hlp | 146 ++ noao/onedspec/doc/skytweak.hlp | 311 ++++ noao/onedspec/doc/skytweak.key | 35 + noao/onedspec/doc/slist.hlp | 142 ++ noao/onedspec/doc/specplot.hlp | 387 +++++ noao/onedspec/doc/specshift.hlp | 67 + noao/onedspec/doc/specwcs.hlp | 586 ++++++++ noao/onedspec/doc/splot.hlp | 1118 ++++++++++++++ noao/onedspec/doc/standard.hlp | 551 +++++++ noao/onedspec/doc/sys/1and2dspec.hlp | 66 + noao/onedspec/doc/sys/Headers.hlp | 189 +++ noao/onedspec/doc/sys/Onedspec.hlp | 2219 ++++++++++++++++++++++++++++ noao/onedspec/doc/sys/Review.hlp | 512 +++++++ noao/onedspec/doc/sys/TODO | 28 + noao/onedspec/doc/sys/coincor.ms | 46 + noao/onedspec/doc/sys/identify.ms | 347 +++++ noao/onedspec/doc/sys/onedproto.ms | 1673 +++++++++++++++++++++ noao/onedspec/doc/sys/onedv210.ms | 680 +++++++++ noao/onedspec/doc/sys/revisions.v3.ms | 382 +++++ noao/onedspec/doc/sys/revisions.v31.ms | 329 +++++ noao/onedspec/doc/sys/revisions.v31.ms.bak | 307 ++++ noao/onedspec/doc/sys/rvidentify.ms | 304 ++++ noao/onedspec/doc/sys/sensfunc.ms | 83 ++ noao/onedspec/doc/sys/specwcs.ms | 612 ++++++++ noao/onedspec/doc/telluric.hlp | 350 +++++ noao/onedspec/doc/telluric.key | 35 + noao/onedspec/doc/wspectext.hlp | 96 ++ 56 files changed, 20923 insertions(+) create mode 100644 noao/onedspec/doc/aidpars.hlp create mode 100644 noao/onedspec/doc/autoidentify.hlp create mode 100644 noao/onedspec/doc/bplot.hlp create mode 100644 noao/onedspec/doc/calibrate.hlp create mode 100644 noao/onedspec/doc/continuum.hlp create mode 100644 noao/onedspec/doc/deredden.hlp create mode 100644 noao/onedspec/doc/dispcor.hlp create mode 100644 noao/onedspec/doc/disptrans.hlp create mode 100644 noao/onedspec/doc/dopcor.hlp create mode 100644 noao/onedspec/doc/fitprofs.hlp create mode 100644 noao/onedspec/doc/identify.hlp create mode 100644 noao/onedspec/doc/lcalib.hlp create mode 100644 noao/onedspec/doc/mkspec.hlp create mode 100644 noao/onedspec/doc/names.hlp create mode 100644 noao/onedspec/doc/ndprep.hlp create mode 100644 noao/onedspec/doc/odcombine.hlp create mode 100644 noao/onedspec/doc/onedspec.hlp create mode 100644 noao/onedspec/doc/refspectra.hlp create mode 100644 noao/onedspec/doc/reidentify.hlp create mode 100644 noao/onedspec/doc/rspectext.hlp create mode 100644 noao/onedspec/doc/sapertures.hlp create mode 100644 noao/onedspec/doc/sarith.hlp create mode 100644 noao/onedspec/doc/sbands.hlp create mode 100644 noao/onedspec/doc/scombine.hlp create mode 100644 noao/onedspec/doc/scoords.hlp create mode 100644 noao/onedspec/doc/scopy.hlp create mode 100644 noao/onedspec/doc/sensfunc.hlp create mode 100644 noao/onedspec/doc/sfit.hlp create mode 100644 noao/onedspec/doc/sflip.hlp create mode 100644 noao/onedspec/doc/sinterp.hlp create mode 100644 noao/onedspec/doc/skytweak.hlp create mode 100644 noao/onedspec/doc/skytweak.key create mode 100644 noao/onedspec/doc/slist.hlp create mode 100644 noao/onedspec/doc/specplot.hlp create mode 100644 noao/onedspec/doc/specshift.hlp create mode 100644 noao/onedspec/doc/specwcs.hlp create mode 100644 noao/onedspec/doc/splot.hlp create mode 100644 noao/onedspec/doc/standard.hlp create mode 100644 noao/onedspec/doc/sys/1and2dspec.hlp create mode 100644 noao/onedspec/doc/sys/Headers.hlp create mode 100644 noao/onedspec/doc/sys/Onedspec.hlp create mode 100644 noao/onedspec/doc/sys/Review.hlp create mode 100644 noao/onedspec/doc/sys/TODO create mode 100644 noao/onedspec/doc/sys/coincor.ms create mode 100644 noao/onedspec/doc/sys/identify.ms create mode 100644 noao/onedspec/doc/sys/onedproto.ms create mode 100644 noao/onedspec/doc/sys/onedv210.ms create mode 100644 noao/onedspec/doc/sys/revisions.v3.ms create mode 100644 noao/onedspec/doc/sys/revisions.v31.ms create mode 100644 noao/onedspec/doc/sys/revisions.v31.ms.bak create mode 100644 noao/onedspec/doc/sys/rvidentify.ms create mode 100644 noao/onedspec/doc/sys/sensfunc.ms create mode 100644 noao/onedspec/doc/sys/specwcs.ms create mode 100644 noao/onedspec/doc/telluric.hlp create mode 100644 noao/onedspec/doc/telluric.key create mode 100644 noao/onedspec/doc/wspectext.hlp (limited to 'noao/onedspec/doc') 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 " +is included where 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 ", where 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 ", where 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 = +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 ", where 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|@|!) +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|@|!) +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|@|!) +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 .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 + + 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. + +.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 + +.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|@|!) +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|@|!) +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|@|!) +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. @. +.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 @ 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. !. + +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 , +as approximated by the median or average with the lowest and highest value +excluded, is given as: + +.nf + sigma = ((rn / g) ** 2 + / g + (s * ) ** 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 + + cl> scoords spec coords.dat label=Wavelength units=Angstroms + cl> listpix spec wcs=world + 4000. 124. + 4010.123 543 + +.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 = +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 @ where 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 Show spectrum parameters (file optional) +:vshow Show verbose parameters (file optional) +:step Set or show step +:fraction Set or show autolayout fraction +:label Set or show label type + (none|imtitle|imname|index|user) + +:move[index] Move spectrum to new index position +:shift[index|*] Shift spectra by adding to index +:w0[index|*] Set or show zero point wavelength +:wpc[index|*] Set or show wavelength per channel +:velocity[index|*] Set or show radial velocity (km/s) +:redshift[index|*] Set or show redshift +:offset[index|*] Set or show intensity offset +:scale[index|*] Set or show intensity scale +:xlpos[index|*] Set or show X label position +:ylpos[index|*] Set or show Y label position +:ptype[index|*] Set or show plotting type +:color[index|*] Set or show color (1-9) +:ulabel[index|*] Set or show user labels +:units[index|*] Change coordinate units + +:/title Set the title of the graph +:/xlabel Set the X label of the graph +:/ylabel Set the Y label of the graph +:/xwindow Set the X graph range + (use INDEF for autoscaling) +:/ywindow 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 +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 +Show or change dispersion axis for 2D images. +.le +.ls :nsum +Show or change summing for 2D images. +.le +.ls :units +Change the coordinate units in the plot. See below for more information. +.le +.ls :# +Add comment to logfile. +.le +.ls Labels: +.ls :label