refspectra input [records]
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.
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 recformat parameter.
references = *.imh
List of reference spectra to be assigned or a "reference spectra assignment
table" (see DESCRIPTION section).
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.
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.
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.
select = interp
Selection method for assigning reference spectra. The methods are:
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.
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.
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).
match
Match each input spectrum with the reference spectrum list in order.
This overrides any aperture or group values.
nearest
Select the nearest spectrum in the reference list based on the sort and
group parameters.
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.
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.
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.
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.
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.
confirm = yes
Confirm reference spectrum assignments? If yes 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.
assign = yes
Assign the reference spectrum by entering it in the image header?
The input spectra are only modified if this parameter is yes.
This parameter may be set to no to get a list of assignments
without actually entering the assignments in the image headers.
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.
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.
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+
REVISIONS
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 irs/iids packages.
identify, reidentify, dispcor, setjd, setairmass,