diff options
Diffstat (limited to 'noao/onedspec/doc/refspectra.hlp')
| -rw-r--r-- | noao/onedspec/doc/refspectra.hlp | 413 |
1 files changed, 413 insertions, 0 deletions
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 |