path: root/noao/onedspec/doc/refspectra.hlp

.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