Initial commit

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