refspectra -- Assign reference spectra
refspectra input [records]
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 hedit 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 iids/irs packages. The input spectra may be restricted to a particular set of aperture numbers by the parameter apertures ; 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 override is no then input spectra which have existing reference spectra assignments (which includes the reference spectra) are skipped.
The reference spectra parameter references 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:
spec1 spec2,spec3,spec4 spec5 spec6,spec7 spect8,spec9 spec10 spec11 spec12 spec13 spec14 spec15
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 ignoreaps 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 select . 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 setjd 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 sort parameter. A null string "" or the word "null" may be used to select no sort parameter. Parameters which are times, as indicated by the time 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 setjd or a middle UT time may be computed with the task setairmass .
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 setjd or setairmass 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.
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:
REFSPEC1='d1.0001' or REFSPEC1='d5.0001 0.756' REFSPEC2='d5.0002 0.244'
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.
cl> setjd *.imh jd=jd ljd=ljd cl> refspec *.imh sort=jd group=ljd select=interp
2. Specifically assign reference spectra to input spectra.
cl> refspectra spec1,spec3 refe=spec2,spec4 select=match
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.
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
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.
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)?
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.
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
8. Assign reference spectra using the "average" option and the reference assignment table with data with record number extensions. First edit the file reftable:
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
9. Assign a reference spectrum for aperture 1 to the object spectra for apertures 2 thru 5.
cl> refspec spec 2-5 recfor+ refer=arc.*.imh refaps=1 ignoreaps+
identify, reidentify, dispcor, setjd, setairmass