STScI Logo

refspectra noao.onedspec


NAME · USAGE · PARAMETERS · DESCRIPTION · KEYWORDS · EXAMPLES
REVISIONS · SEE_ALSO

NAME

refspectra -- Assign reference spectra

USAGE

refspectra input [records]

PARAMETERS

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.

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 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.

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:

           REFSPEC1='d1.0001'  or

           REFSPEC1='d5.0001 0.756'
           REFSPEC2='d5.0002 0.244'

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.

    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.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 acceptible.
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.

SEE ALSO

identify, reidentify, dispcor, setjd, setairmass


Source Code · Search Form · STSDAS