Initial commit

1 files changed, 2219 insertions, 0 deletions

diff --git a/noao/onedspec/doc/sys/Onedspec.hlp b/noao/onedspec/doc/sys/Onedspec.hlp
new file mode 100644
index 00000000..85a3f20e
--- /dev/null
+++ b/noao/onedspec/doc/sys/Onedspec.hlp
@@ -0,0 +1,2219 @@
+.help spbasic
+.sh
+One Dimensional Package - Basic Operators
+
+.sh
+INTRODUCTION
+
+     The IRAF One Dimensional Package is intended to provide the basic
+tools required to reduce, analyze, and display data having a
+single dimension. This primarily refers to spectra, but may have
+applicability to time series photometry, or any other
+source of data which can be considered a simple vector.
+All such data will be referred to as spectra in the following discussion.
+Furthermore, the spectrum vector is assumed to be equally spaced
+along the independent variable (wavelength, channel, frequency,
+wavenumber,...). For the purposes of discussion, the independent
+variable will be referred to as wavelength but may be any of the
+possible physical transformations.
+
+     Spectra are to be stored as 2 dimensional IRAF floating point images
+having a single line
+and are therefore limited to lengths smaller than or equal to the
+largest representable positive integer. For 32 bit machines, this
+is about 2 billion points, so that disk space will likely be the
+operational limit.  The precision and dynamic range  for each pixel
+will be determined by the local machine.
+The second dimension of the spectrum is spatial, and therefore
+represents a special case of the long slit spectroscopic mode.
+
+     Each spectrum will, by default, be stored as a separate image
+file.  Alternatively, an association
+can be declared for a related set of spectra
+through a "data group" mechanism. A data group can be defined to
+contain any number of related spectra so that an operation can
+be specified for the group. For example, one can group a single
+night of IIDS spectra into a group labeled JAN28, and then
+wavelength linearize JAN28. This helps minimize
+the user interaction which would otherwise be repetitive, and
+also reduces the user bookkeeping required.
+
+     Data input to the package is provided through the DATAIO
+package. Tape readers will be provided for FITS, IIDS and IRS mountain
+formats, Text ("card-image"),  REDUCER and PDS. The descriptor fields
+included in these formats will be mapped into standard IRAF
+image header fields when possible. Special fields will be
+added to the image header to represent instrument
+related parameters.
+
+     Data output to tape (for visitor take home) will be
+either in FITS or text format.
+
+     A variety of graphics display options will be provided
+for both interactive use and for hardcopy generation.
+Scale expansion and contraction, labeling, multiple spectra
+plots, and axis limit specification are to be included in the
+options.
+
+     Specific reduction scripts will be provided to efficiently
+process raw data from the Kitt Peak instruments IIDS and IRS.
+
+
+.sh
+SCOPE OF SPECIFICATIONS
+
+This paper specifies the command format, parameters, and
+operations for the Basic contents of the One Dimensional
+Spectral Package. The Basic functions are those comprising the
+minimum set to reduce a large variety of spectra.
+More complicated operators and analysis functions
+are described in a companion paper on Intermediate Functions.
+Major projects in spectral analysis will be considered at
+a later date in the Advanced function set.
+
+The primary functions within the Basic operator set are:
+
+.ls 4 Transport
+Primarily magtape readers for the common tape formats. Included
+are FITS, IIDS/IRS, REDUCER, PDS, and Card-image formats.
+Tape writers will be initially limited to FITS and Card-image.
+.le
+.ls 4 Mathematical
+Add, subtract, multiply, divide spectra by spectra or constants.
+Apply functional operators such as log, exp, sqrt, sin, cos.
+Weighted sums and averages of spectra.
+.le
+.ls 4 Reduction operators
+Line identification, dispersion solution, flux calibration,
+coincidence correction, atmospheric extinction correction,
+flat fielding.
+.le
+.ls 4 Plotting
+Terminal package to expand, overplot, annotate plots. Hard
+copy package for printer/plotters.
+.le
+.ls 4 Utilities
+Header examination and modification. List, copy, delete spectra.
+Define, add, delete entries in a data group.
+.le
+.ls 4 Artificial spectra
+Generate ramps, Gaussian and Voigt lines, noise.
+.le
+
+These functions will be considered in detail in the following
+discussion.
+
+.ks
+A summary of the commands is given below:
+
+.nf
+rfits       -- Convert FITS data files to IRAF data files
+riids       -- Convert IIDS mountain tape format to IRAF data files
+rreducer    -- Convert Reducer format tape to IRAF data files
+rpds        -- Convert a PDS format tape to IRAF data files
+rtext       -- Convert a card-image text file to an IRAF image file
+wfits       -- Convert IRAF data files to FITS data format
+wtext       -- Convert an IRAF image file to a card-image text file
+.sp 1
+coin_cor    -- Correct specified spectra for photon coincidence
+line_list   -- Create a new line list, or modify an existing one
+mlinid      -- Manually identify line features in a spectrum
+alinid      -- Automatically locate spectral features in a spectrum
+disp_sol    -- Determine the dispersion relation for a set of spectra
+disp_cor    -- Linearize spectra having dispersion relation coefficients
+cr_flat     -- Create a flat field spectrum
+flt_field   -- Correct spectra for pixel-to-pixel variations
+std_star    -- Define the standard stars to be used for solving the 
+               extinction and system sensitivity functions
+crext_func  -- Create an extinction function from a set of observations
+crsens_func -- Create system sensitivity function
+ext_cor     -- Extinction correct specified spectra
+sens_cor    -- Correct the specified spectra for system sensitivity
+.fi
+.ju
+.ke
+
+.bp
+.sh
+TRANSPORT - INPUT
+
+Although the primary data input source for the near future
+will be magtape, direct links from other computers will
+be a likely source of input. The IRAF DATAIO package
+treats magtape as simple bit streams so that alternate
+input devices (e.g. disk, ethernet, phone lines) can also
+be accommodated with no programming modifications.
+
+This section describes the different formats to be made
+available in the initial release of the Spectroscopic
+package. Additional formats may be added if needed.
+
+In general, the following information will be copied to
+the standard image header: length of spectrum, title, 
+abscissa units, brightness units, reference pixel
+abscissa value and increment, right ascension and declination
+of telescope.
+
+Non-standard header parameters include but are not limited to:
+integration time, UT and LST of the observation, airmass (or 
+zenith distance), processing history, and comments.
+
+.sh
+FITS
+.ih
+NAME
+rfits -- Convert FITS data files to IRAF data files
+.ih
+USAGE
+rfits [source, filename, files]
+.ih
+DESCRIPTION
+FITS data is read from the specified source.
+The FITS header may optionally be printed on the standard
+output as either a full listing or a short description.  Image data may
+optionally be converted to an IRAF image of specified data type.
+
+Eventually all data from the mountain will be in FITS format,
+with the exception of time-critical data transfer projects
+and special applications. The IRAF FITS reader will
+copy the data to disk for most applications.
+
+.ih
+PARAMETERS
+.ls 4 fits_source
+The FITS data source.  If the data source is a disk file or an explicit tape file
+specification of the form mt*[n] where n is a file number then only that file
+is converted.  If the general tape device name is given, i.e. mta, mtb800, etc,
+then the files specified by the files parameter will be read from the tape.
+.le
+.ls filename
+The IRAF file which will receive the FITS data if the make_image parameter
+switch set.  For tape files specified by the files parameter the filename
+will be used as a prefix and the file number will be appended.   Otherwise,
+the file will be named as specified.  Thus,
+reading files 1 and 3 from a FITS tape with a filename of data will produce
+the files data1 and data3.  It is legal to use a null filename.  However,
+converting a source without a file number and with a null filename will cause
+a default file fits to be created.
+.le
+.ls files
+The files to be read from a tape are specified by the files string.  The
+string can consist of any sequence of file numbers separated by
+at least one of whitespace, comma, or dash.
+A dash specifies a range of files.  For example the string
+
+1 2, 3 - 5,8-6
+
+will convert the files 1 through 8.
+.le
+.ls print_header
+If this switch is set header information is printed on the standard output
+output. (default = yes)
+.le
+.ls short_header
+This switch controls the format of the header information printed when the
+print_header switch is set.
+When the short_header switch is set only the output filename,
+the FITS OBJECT string, and the image dimensions are printed.
+Otherwise, the output filename is followed by the full FITS header.
+(default = yes)
+.le
+.ls bytes_per_record
+The FITS standard record size is 2880 bytes which is the default for this
+parameter.  However, non-standard FITS tapes with different record sizes can
+be read by setting the appropriate size.
+.le
+.ls make_image
+This switch determines whether FITS image data is converted to an IRAF image
+file.  This switch is set to no to obtain just header information with the
+print_header switch. (default = yes)
+.le
+.ls data_type
+The IRAF image file may be of a different data type than the FITS image data.
+The data type may be specified as s for short, l for long, and r for real.
+The user must beware of truncation problems if an inappropriate data type is
+specified.  If the FITS keywords BSCALE and BZERO are found then the image
+data is scaled appropriately.  In this case the real data type may be most
+appropriate.
+.le
+.sh
+For spectroscopic applications, the parameter data_type would be
+specified as r for real, and the filename would probably be assigned
+as the "group" name as well. (see section on data groups.)
+
+
+.sh
+IIDS/IRS
+.ih
+NAME
+riids -- Convert IIDS mountain tape format to IRAF data files
+.ih
+USAGE
+riids [source, filename, form, records]
+.ih
+DESCRIPTION
+IIDS/IRS mountain format data is read from the specified source.
+The header may be printed
+on the standard output either in short form, label only, or a long
+form containing telescope and time information, processing flags,
+and wavelength solution values.
+
+Either raw or "mountain reduced" tapes can be specified with the
+parameter form.
+
+The IIDS format is destined for extinction. A FITS format will
+replace the current tape format, but an interim period will exist
+for which this tape reader must exist.
+.ih
+PARAMETERS
+.ls 4 iids_source
+The data source, either magtape or a data stream (e.g. disk file).
+The current IIDS tape format produces tapes having only a single
+file. If the source is a magtape, the general tape specification
+mt*[n], should either have n specified as 1, or [n] should not be present.
+.le
+.ls 4 filename
+The IRAF file which will contain the data if the make_image parameter
+is set. The filename will be used as a prefix and the record number
+will be used as the suffix. Thus reading records 1 through 100 from
+an IIDS tape with a file name of 'blue' will produce 100 files having
+names blue1, blue2, ..., blue100. A null filename will default to 'iids'.
+.le
+.ls 4 form
+This string parameter defines the tape to be either 'new' or 'red'.
+The 'new' designation refers to tapes made after January 1977, and
+'red' refers to mountain reduced tapes. (default = 'red')
+.le
+.ls 4 records
+The records specified by this string parameter will be copied to disk.
+The syntax is identical to that for the files parameter of the FITS reader.
+.le
+.ls 4 print_header
+If this switch is set, header information is printed on the standard
+output. (default = yes)
+.le
+.ls 4 short_header
+If this switch is set, only the filename and label information will be printed
+if the print_header switch is also set. If set to 'no', the long form
+will be printed. (default = yes)
+.le
+.ls 4 make_image
+See definition of this parameter under FITS.
+.le
+
+
+.sh
+REDUCER
+
+REDUCER tapes require several considerations beyond the
+previous simple formats. The spectra actually consist of
+many spectra having lengths of 4096 but slightly different
+spectral sampling. Thus, the reader can create many small
+independent spectra, or interpolate the data onto a common
+spectral scale to create a single large spectrum.
+The latter alternative seems to be more generally useful,
+unless the interpolation process introduces significant errors.
+Probably the initial reader will provide both options.
+   
+A second consideration is the 60 bit word length conversion.
+The IRAF images are limited to 32 bit reals on most 32 bit machines.
+Some loss of precision and dynamic range will result while reading REDUCER
+format data.
+   
+Also, there may be a considerable number (~100) of non-standard header
+elements. These can be handled in a normal fashion, and tools
+will be provided to extract or modify these elements as needed.
+New elements may be added as well.
+
+.ih
+NAME
+rreducer -- Convert Reducer format tape to IRAF data files
+.ih
+USAGE
+rreducer [source, filename, files]
+.ih
+DESCRIPTION
+REDUCER format data is read from the specified source.
+The header may be printed on the standard output either in short form
+consisting of the 80 character ID field, or a long form containing some
+selection (to be agreed upon) of the many header elements.
+
+Either a single long spectrum requiring interpolation
+to match the spectral characteristics of the first data block, or
+multiple short spectra having individual spectral parameters can
+be specified with the hidden parameter, interp.
+Interpolation is performed via a fifth order polynomial.
+
+Subsets of the spectrum can be selected with the blocks string
+parameter. This specifies which blocks in the file are to be extracted.
+
+.ih
+PARAMETERS
+.ls 4 reducer_source
+The data source, either magnetic tape or a data stream (e.g. disk
+file). See the definition of fits_source above for a description
+of how this parameter interacts with the files parameter.
+.le
+.ls 4 filename
+The filename which will contain the data.
+See the definition of this parameter under FITS.
+If no name is given, the default of 'reducer' will be used.
+.le
+.ls 4 files
+The files to be read from tape are given by the files string. See
+the description of this parameter under FITS.
+.le
+.ls 4 print_header
+If this switch is set header information will be printed on the
+standard output. (default = yes)
+.le
+.ls 4 short_header
+If this switch is set only the filename and the first 60 characters
+of the 80 character ID field will be printed if the print_header
+switch is also set. If set to no, the long form of the header
+will be printed, containing selected elements of the 100 word
+header record. (default = yes)
+.le
+.ls 4 make_image
+See the definition of this parameter under FITS.
+.le
+.ls 4 interp
+If this switch is set, a single long spectrum is produced. If
+set to no, multiple spectra will be generated, one for each
+header-data block. The resulting filenames will have suffixes
+of '.1' , '.2' ... '.n'. For example, if the given filename is
+fts and the tape file is 2, the resulting spectrum will be
+fts2 if interp is set to yes, but will be fts2.1, fts2.2, and
+fts2.3 if there are 3 header-data block sets and interp is set
+to no. (default = yes).
+.le
+.ls 4 blocks
+This string parameter allows selected extraction of the
+specified header-block sets, rather than the entire spectrum.
+Thus subsets of the spectrum may be extracted. The parameter
+specifies the starting block and ending block within a tape file.
+If an end-of-file is found prior to exhaustion of the
+specification, reading is terminated.
+For example, the string '12 19' specifies that the eight sets
+starting with the twelfth block are to be extracted to
+form the spectrum. (default = '1 32767', or all)
+.le
+
+
+.sh
+PDS
+
+Tapes from the new PDS 11/23 system will be either FITS or
+old format PDS 9 track tapes. This reader will accept the
+old format tapes which are based on the PDP 8 character set
+and either 10 or 12 bit format.
+
+.ih
+NAME
+rpds -- Convert a PDS format tape to IRAF data files
+.ih
+USAGE
+rpds [source, filename, files]
+.ih
+DESCRIPTION
+PDS format data is read from the specified source. The header
+may be printed on the standard output either in short form
+consisting of the 40 character ID field, filename, and size,
+or in long form including raster parameters and origin.
+
+Because PDS data is limited to no more than 12 bit data, the output image
+will be short integers if the number of lines ("scans") implies
+two dimensional data. If one dimensional data is implied, the
+output image will be converted to reals.
+.ih
+PARAMETERS
+.ls 4 pds_source
+The data source, either magtape or a data stream. See the definition
+of fits_source above for a description of how this parameter interacts
+with the files parameter.
+.le
+.ls 4 filename
+If no filename is given, the default of 'pds' will be used.
+.le
+.ls 4 files
+See the definition of this parameter under FITS.
+.le
+.ls 4 print_header
+If this switch is set, header information will be printed on the
+standard output. (default = yes).
+.le
+.ls 4 short_header
+If this switch is set, only the filename, size, and the 40 character ID
+field will be printed if the print_header switch is also set.
+If set to no, the long form of the header will be printed
+containing the full information block (delta X, delta Y, scan type,
+speed, origin, corner, travel). (default = yes)
+.le
+.ls 4 make_image
+See the definition of this parameter under FITS. (default = yes)
+.le
+.ls 4 data_type
+Specifies the IRAF image file output data type. Normally one
+dimensional PDS data (NSCANS=1) will be stored as real and
+two dimensional PDS data (NSCANS>1) will be stored as short.
+The data type may be specified as s (short), l (long), or r
+(real).
+.le
+
+
+.sh
+TEXT (Read Card-Image)
+
+Card-image tapes are probably the most portable form of data transport.
+Unlike FITS, there is no standard for internally documenting the
+contents of the text file. Header information is essentially
+lost. This makes card-image data transfer a relatively unattractive
+format.
+
+
+.ih
+NAME
+rtext -- Convert a card-image text file to an IRAF image file.
+.ih
+USAGE
+rtext [source, filename, files, ncols, nlines, label]
+.ih
+DESCRIPTION
+The card-image text file specified by the source parameter is 
+converted to an IRAF image file. The file is read in a free form
+mode (values separated by spaces) converting data along lines (1-ncols) first.
+No header information is stored except for the image size and
+the label.
+
+If additional header information is to be stored, the standard
+image header utility must be used.
+
+Pixel values exactly equal to some constant will be assumed to be blanks
+if the blank switch is set to yes. The flag value for blanks can be
+set with the blank_value parameter.
+
+.ih
+PARAMETERS
+.ls 4 text_source
+The input data source. See the definition of this parameter under FITS.
+.le
+.ls 4 filename
+The IRAF file which will contain the image data if the make_image
+switch is set. If no filename is given, the default of 'text'
+will be used.
+.le
+.ls 4 files
+See the definition of this parameter under FITS.
+.le
+.ls 4 ncols
+The number of columns of data which describe the image extent.
+.le
+.ls 4 nlines
+The number of lines (or 'rows') of data which describe the image extent.
+For one dimensional spectra, this parameter will be 1.
+.le
+.ls 4 label
+This string parameter becomes the image identification label.
+Up to 80 characters may be stored.
+.le
+.ls 4 print_header
+If this switch is set, header information consisting of the filename,
+image label, and image size will be printed on the standard output.
+(default = yes)
+.le
+.ls 4 make_image
+If this switch is set, an IRAF image will be created. (default = yes)
+.le
+.ls 4 data_type
+The IRAF image may be either s (short), l (long), or r (real).
+(default = r)
+.le
+.ls 4 card_length
+The number of columns on the "card" in the card-image file.
+(default = 80)
+.le
+.ls 4 blank_value
+The value used to flag blank pixels if the blank switch is set to yes.
+(default = -32767)
+.le
+.ls 4 blank
+If this switch is set to yes, any pixel having exactly the value
+specified by the parameter blank_value will be flagged as a blank
+pixel. If set to no, all pixel values are assumed to be valid.
+.le
+
+
+.bp
+.sh
+TRANSPORT - OUTPUT
+
+The primary format for take away tapes will eventually be FITS.
+Because many facilities currently cannot read FITS format,
+the card-image format will also be provided.
+
+.sh
+FITS
+.ih
+NAME
+wfits -- Convert IRAF data files to FITS data format
+.ih
+USAGE
+wfits [destination, filename, files]
+.ih
+DESCRIPTION
+Data is read from the specified filename(s) and written to the
+destination, usually a magnetic tape specification. 
+A short header consisting of the filename, size, and label
+may optionally be printed on the standard output.
+
+The data will be automatically scaled to either 16 or 32 bit integer format
+(BITPIX = 16 or 32) depending on the number of bits per pixel in the
+image data, unless the bitpix parameter is specified
+otherwise. The scaling parameters may be forced to
+exactly represent the original data (BSCALE = 1.0, BZERO = 0.0)
+by setting the scale switch to no.
+
+If only the header information is to be copied to the destination,
+the write_image parameter can be set to no. If this is the case,
+then the NAXIS FITS keyword will be assigned the value of 0;
+otherwise the value for
+NAXIS will be taken from the IRAF image header.
+
+Each non-standard header element will be written into the FITS file
+in a form to be determined. These elements may be entered as FITS
+COMMENT records, or perhaps added to the file as FITS "special
+records".
+
+Other keywords will be written following standard FITS specifications.
+A few special cases will be set as follows:
+
+.ls 4 NAXISn
+The NAXIS1, NAXIS2, ... NAXISn values will be taken from the
+image header
+.le
+.ls 4 OBJECT
+The first 60 characters of the image label will be used.
+.le
+.ls 4 BLANK
+Blank pixels will be written to tape having the IRAF value for
+indefinite appropriate to 8, 16, or 32 bit integers.
+.le
+.ls 4 ORIGIN = 'KPNO IRAF'
+.le
+
+.ih
+PARAMETERS
+.ls 4 fits_destination
+The data destination, usually a magnetic tape, but may be a disk
+file or STDOUT. If magtape,
+the tape should be specified with a file number of either 1
+or "eot". The file number refers to the file which will be written.
+Thus a file number of 2 would overwrite file 2. If the tape already
+has data written on it, the safest specification would be "eot".
+This forces the tape to be positioned between the double end-of-tape
+marks prior to writing.
+.le
+.ls 4 filename
+The IRAF filename providing the root for the source name. The files
+string, if given, will be used as the suffix for the file names
+to be written to tape. For example, if the filename is given as
+"image", and the files string is "1 -5", then files image1, image2,
+image3, image4, and image5 will be written to the destination
+in FITS format. If the files string is empty, only the specified
+filename will be converted.
+.le
+.ls 4 files
+See the definition of this parameter under the FITS reader.
+.le
+.ls 4 print_header
+If this switch is set, a short header will be printed on the
+standard output for each image converted. (default = yes)
+.le
+.ls 4 write_image
+If this switch is set to no, only header information will be
+written to the destination, but no image data.
+By using this parameter,
+one can generate a FITS tape containing header information only
+and may be used as a means for examining the IRAF image header
+or for generating a table of contents on a tape prior to writing
+the data. (default = yes)
+.le
+.ls 4 bitpix
+This parameter must be either 8, 16, or 32 to specify the
+allowable FITS pixel sizes.
+.le
+.ls 4 scale
+If this switch parameter is set to no, the FITS scaling
+parameters BSCALE and BZERO will be set to 1.0 and 0.0
+respectively. The data will be copied as it appears in the
+original data, with possible loss of dynamic range.
+Values exceeding the maximum value implied by the bitpix
+parameter will be set to the maximum representable value.
+(default = yes)
+.le
+
+
+.sh
+TEXT (Write Card-Image)
+
+Although this format is easily readable by the destination
+machine, there is no real standard for encoding information,
+neither the image data itself nor the descriptive parameters.
+
+.ih
+NAME
+wtext -- Convert an IRAF image file to a card-image text file
+.ih
+USAGE
+wtext [destination, filename, files]
+.ih
+DESCRIPTION
+Data is read from the specified filename(s) and written to
+the destination, usually a magnetic tape. The data will be
+blank padded, ASCII in a format consistent with the data type
+of the image pixels, (integer or floating point).
+A short header description, consisting of the filename
+being converted and the image label, may optionally be printed
+on the standard output.
+
+The column length of the "card" may be changed from the default
+of 80 using the card_length parameter, and the field width
+to be allocated for each data element may be changed from the
+default of 10 columns by setting the field_width parameter.
+
+If the data are integers, the equivalent of the FORTRAN format
+I<field_width> will be used;
+if the data are reals, the equivalent of the FORTRAN format
+1P<n>E<field_width>.3
+will be used, where n is the number of elements which can
+be output into one card length. For the default values of
+card_length = 80, and field_width = 10, n will be 8. (1P8E10.3).
+
+Several cards may be written as a single "block" for
+improving the efficiency on magtape. Reasonable efficiency (80 percent)
+is attained with a blocking factor of 50, but this value
+may be modified by changing the parameter blocking_factor.
+If the last block is unfilled, it will be truncated to the
+minimum number of card images required to flush the data.
+
+A legitimate value must be defined to represent blank pixels.
+The parameter blank_value is used to define this value and
+defaults to -32767.
+
+.ih
+PARAMETERS
+.ls 4 text_destination
+See the definition for fits_destination for a description of this
+parameter.
+.le
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 print_header
+If this switch is set, a short header is printed for each
+file converted. (default = yes)
+.le
+.ls 4 card_length
+The number of columns on the "card" to be generated. (default = 80)
+.le
+.ls 4 field_width
+The number of columns on the "card" to be allocated for each pixel value.
+(default = 10)
+.le
+.ls 4 blocking_factor
+The number of card images to be written as a single blocked record.
+(default = 50)
+.le
+.ls 4 blank_value
+The value to be assigned to blank pixels for the purpose of
+representing them on the card image. (default = -32767)
+.le
+.bp
+
+
+.sh
+MATHEMATICAL OPERATORS
+
+Because spectra are stored as IRAF images, the standard image
+calculator utility provides the basic arithmetic services.
+For example, to create a spectrum (called spavg) which is the average of two
+other spectra (sp1 and sp2), one can enter the command:
+.ls 8 cl>imcalc "spavg = (sp1 + sp2) / 2"
+.le
+
+Other arithmetic operations are performed in a similar fashion.
+The general form of the command string is
+output_image = expression where "expression" may consist of:
+.ls 8 1. Spectra or segments of spectra
+A segment of a spectrum is specified by the notation spectrum[x1:x2]
+where x1 and x2 are pixel indices along the spectrum. For example,
+to create a spectrum which is the difference of the first 100
+pixels of two other spectra, the following command would be used:
+.ls 16 cl> imcalc "spdiff = sp1[1:100] - sp2[1:100]"
+.le
+An option to specify wavelength delineated segments may be added
+if this appears generally feasible.
+.le
+.ls 8 2. Numeric constants
+.le
+.ls 8 3. Data group names
+If an operation is performed on a data group, the output
+will be a new data group containing spectra which have been
+individually treated by the specified calculation.
+For example, if JAN28 is a group containing 100 congruent spectra
+and response is the instrumental response as a function of
+wavelength as determined from a set of standards, then
+the after the following command is entered:
+.ls 16 cl> imcalc "JAN28X = JAN28 * response"
+.le
+
+a new data group will be generated containing 100 spectra which
+have been calibrated for the instrument response. The new spectra will
+be given names JAN28X1 through JAN28X100.
+.le
+.ls 8 4. Intrinsic functions
+.ks
+The following intrinsic functions are to be provided:
+
+.nf
+    abs      atan2    cos      int      min      sin       
+    acos     ceil     cosh     log      mod      sinh      
+    aimag    char     double   log10    nint     sqrt      
+    asin     complex  exp      long     real     tan       
+    atan     conjug   floor    max      short    tanh      
+.fi
+.ke
+.le
+
+Expression elements are to be
+separated by arithmetic and boolean operators (+,-,*,/,**,<,>,<=,=>,==,!,!=). 
+The boolean operators provide a means to generate masks.
+
+Rules governing operations on non-congruent spectra are not yet fully defined.
+.bp
+
+.sh
+REDUCTION OPERATORS
+
+Most of the reduction operators discussed in this section are
+intended for spectra of the IIDS/IRS class, although they
+are sufficiently general to accommodate data obtained with
+the CryoCam (either multi-aperture or long-slit mode), Echelle,
+Coude Feed, and photographic (PDS) instruments. Some 
+application to FTS data is also feasible.
+
+It is intended that many of these operators will never be
+directly executed by users, but that they will be driven by
+CL command scripts tuned for individual instruments.
+In some cases the scripts will be fairly elaborate and extensive
+to lead new users through the reduction phase along a reliable
+path.
+
+It will no doubt be necessary to either modify some
+of these operators, or create more specific operators for
+certain other instruments. These operators should be considered
+a sample of what will eventually be available in this package. 
+
+The basic path which most spectroscopic data follows is:
+
+.ls 4 1.
+Coincidence Correction.
+.ls
+Many detectors can respond to incoming photevents at a limited
+rate. Once an event occurs, the detector cannot respond for some
+instrument dependent period, or dead-time. If events occur during
+this period, they will not be counted. If the event rate
+does not greatly exceed the detector limits, the uncounted events
+can be corrected for statistically.
+
+For many detectors, the coincidence correction is a well
+determined function and can be applied to the raw data
+to produce a reasonably corrected spectrum.
+.le
+.le
+.ls 4 2.
+Wavelength linearization.
+.ls
+Few instruments produce spectra having pixel to pixel wavelength
+differences which are constant across the entire spectrum.
+For subsequent reduction and analysis purposes, it is
+desirable to rectify the spectra. This is done by mapping the spectrum
+from the non-linear wavelength coordinate to a linear one.
+It is also desirable to provide a means of forcing the mapping
+to a grid which is common to many observations, and in some cases,
+to observations acquired with other instruments as well.
+
+The processes required for the mapping are outlined below.
+
+.le
+.ls 4 a.
+Manually identify a small number of spectral features having
+known wavelengths thereby creating a table of wavelength as
+a function of pixel number.
+.le
+.ls 4 b.
+Compute estimated relationship between wavelength and pixel number
+.le
+.ls 4 c.
+Automatically locate many features found in a user definable line list.
+Optionally locate additional features from other spectra using an alternate
+line list. (This allows spectra from several different sources to be used
+for the wavelength calibration, such as arc lamps, night/day sky.)
+.le
+.ls 4 d.
+Compute improved relationship between wavelength and pixel number.
+.le
+.ls 4 e.
+Perform 2.c. and 2.d. for all other spectral entries in the wavelength
+calibration data group.
+.le
+.ls 4 f.
+Compute relationship for wavelength as a function of pixel number and time (or
+zenith distance, or some other flexure parameter) as deduced from 2.e.
+.le
+.ls 4 g.
+Apply inverse of wavelength function to a data group. This requires
+interpolation of the data at pixels having fixed steps in wavelength.
+The start wavelength and the step size must be user definable.
+The interpolation may be via a polynomial of a user specified order (typically
+1 to 5), or a more sophisticated interpolator. The linearization
+in wavelength may also be a simple rebinning of the data to exactly preserve
+photon statistics.
+.le
+.le
+.ls 4 3.
+Field flattening.
+.ls
+Pixel to pixel sensitivity variations and other small scale
+fluctuations are removed by dividing the object spectra by the spectrum of
+a continuum source. The latter spectrum should have a very high
+signal-to-noise ratio so as not to introduce additional uncertainties
+into the data.
+
+If the spectrum of the continuum source has much low frequency
+modulation,
+it may be necessary to filter these variations before the division is performed.
+Otherwise fluctuations not characteristic
+of the instrument response may be introduced, and may be difficult to remove
+during the subsequent flux calibration process.
+.le
+.le
+.ls 4 4.
+Sky Subtraction
+.ls
+Except for extremely bright sources, all spectra require that the
+spectrum of the night sky be removed. In some cases, sky will
+be the dominant contributor to the raw spectrum.
+Sky subtraction is a simple subtraction operation and can be
+accomplished with the image calculator tools.
+.le
+.le
+.ls 4 5.
+Extinction Correction
+.ls
+The effects of the Earth's atmosphere produce a wavelength dependent
+reduction of flux across the spectrum. The extinction function
+is approximately known from extensive photometric measurements
+obtained at the observatory over a period of many years. But on
+any given night this function may deviate from the average, sometimes
+significantly. If the spectroscopic observer has acquired the necessary
+data, it is possible to solve for the extinction function directly.
+
+Therefore, it should be possible for the user to either derive the
+extinction function, input a user-defined function, or use the
+standard average function and subsequently correct spectra for the
+effects of the atmosphere as described by that function and the effective
+observing airmass. (Note that because  exposures may be quite long, the
+effective airmass must be calculated as a function
+of position on the sky.)
+.le
+.le
+.ls 4 6.
+Flux Calibration (Correction for Instrument Response)
+.ls
+By observing objects having known wavelength dependent flux
+distributions, it is possible to determine the sensitivity
+variations of the instrument as a function of wavelength.
+Usually several standards are observed for each group of data
+and these must be averaged together after corrections for
+"grey shift" variations (wavelength independent flux reductions
+such as those introduced by thin clouds).
+
+Although the actual flux of the standards is generally known only
+for a limited selection of wavelengths, the instrument response
+usually varies smoothly between those wavelengths and a smooth
+interpolator generally provides satisfactory calibration values
+at intermediate wavelengths.
+
+In some cases, the system sensitivity response may be known
+from other observations, and the user will be allowed to directly
+enter the sensitivity function.
+.le
+.le
+
+The above reduction path is primarily tuned to IIDS/IRS style data.
+Other instruments may require additional or alternate steps.
+It may be necessary for multiaperture Cryocam spectra, for example,
+to undergo an additional hole to hole sensitivity correction
+based on the total sky flux through each hole.
+
+The tasks performing the procedures outlined above will be described
+in more detail in the following discussion.
+
+.sh
+COINCIDENCE CORRECTION
+.ih
+NAME
+coin_cor -- Correct specified spectra for photon coincidence
+.ih
+USAGE
+coin_cor [filename, files, destination, dead_time]
+.ih
+DESCRIPTION
+The spectra specified by the root filename and the files parameter
+are corrected for photon counting losses due to detector dead-time.
+The corrected spectra are written to filenames having the root
+specified by the destination.
+
+The correction, if typical of photomultiplier discriminators,
+is usually of the form:
+
+.br
+         Co(i) = C(i) exp[C(i) dt],
+.br
+         dt = t/T,
+.br
+
+where Co(i) is the corrected count at pixel i, C(i) is the raw count,
+t is the detector/discriminator dead-time, and T is the
+exposure time at pixel i.
+
+Clearly, the correction factor can become extremely large when the
+count rate, C(i)/T, is large compared with the dead-time, t.
+The above formula cannot be expected to
+exactly remove the effects of undetected photo-events when
+large corrections are required.
+
+The exposure time will be read from the image header.
+If no value exists, or if the value is less than or equal to
+zero, a request from standard input will be issued for this parameter.
+
+Because each detector may have unique coincidence properties,
+this routine may be package dependent.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 destination
+The IRAF filename providing the root for the name of the result
+spectra. The files parameter, if specified, will be used for the
+suffix. If the filename parameter is actually a data group name,
+the destination name will be used to create a new data group
+containing spectra having IRAF filenames with the destination
+group name as a root and a suffix starting with 1 and incremented for
+each converted spectrum.
+.le
+.ls 4 dead_time
+The value of this parameter, in seconds, represents the detector
+dead-time.
+.le
+.ls 4 print_header
+If this switch is set, a short header will be printed on the
+standard output for each spectrum corrected. (default = yes)
+.le
+.ls 4 exposure
+This parameter should be entered into the image header. If not
+present or not realistic, a request is made from standard input.
+.le
+
+.sh
+WAVELENGTH LINEARIZATION
+
+A package of routines is required to perform the operations
+leading to linearized data. These include:
+.ls 4 1. Spectral line list definition and editing facility
+.le
+.ls 4 2. Manual line identifier using graphics cursor.
+.le
+.ls 4 3. Automatic line identifier using preliminary identifications
+from manual identifier and locating lines from the predefined list.
+.le
+.ls 4 4. Computation of dispersion relationship as a function of
+pixel coordinate and a flexure parameter, probably zenith distance.
+.le
+.ls 4 5. Linearization of spectra according to dispersion relation.
+Correction can be to either a linear or logarithmic dispersion in
+the pixel coordinate.
+.le
+
+Perhaps the most critical aspect of determining the dispersion
+relation is the algorithm for locating spectral line centers.
+A variety of techniques are available, and some testing will
+be required before adopting a standard scheme. Probably several
+algorithms will be available and switch selectable at the command
+level.
+
+.sh
+LINE LIST PREPARATION
+.ih
+NAME
+line_list -- Create a new line list, or modify an existing one
+.ih
+USAGE
+line_list [filename, option]
+.ih
+DESCRIPTION
+The line list specified by the IRAF filename parameter will be
+either created, listed, or modified according to the option
+given. The IRAF database facility will be used to manage the
+line list file.
+
+Each entry within the list will contain an identification tag (e.g. HeII)
+a reference value (e.g. wavelength, frequency, wavenumber), and a weighting
+value such as 1.0 or 2.0 to be used later in the least-squares fitting.
+An optional descriptive header may be associated with the line list.
+(e.g. "HeII arc from 3500 to 11,000A")
+
+Either the header, entry identifier or value may be changed
+if the modify option is specified. Deletion or addition of
+entries is also possible with the appropriate option flags
+specifications.
+.ih
+PARAMETERS
+
+.ls 4 filename
+The IRAF filename to be assigned to the line list. The list will
+referenced by this name thereafter.
+.le
+.ls 4 option
+This string parameter determines the action of the line list task.
+If no option is specified, the default action is to list the
+specified line list on the standard output if the line list
+exists; if it does not exist, a new line list will be created
+with the given name.
+.ls 4 = create
+The identifications and values for the line list are read from
+the standard input on a record by record basis. Each input
+record contains data for one line according to the format:
+.br
+.ls 4 identification value
+.le
+.le
+.ls 4 = header
+A descriptive header is read from the standard input.
+.le
+.ls 4 = list (default)
+The line list is listed on the standard output.
+.le
+.ls 4 = add
+Additional entries to the list are read from the standard input.
+.le
+.ls 4 = delete
+The entries defined by the values read from the standard input
+are deleted from the line list. The entries deleted will be those
+having values nearest the entered value, unless the absolute
+difference from the listed value is too large. For example, one
+can enter 5015 to delete the helium line at 5015.675, but entering
+5014 would result in an error message that no match could be found.
+.le
+.ls 4 = id
+The entries defined by values entered as for delete will be modified.
+Input is expected in the format:
+.br
+approxvalue  newidentifier
+.le
+.ls 4 = value
+As for option = id except that the input format contains
+the newvalue instead of the newidentifier.
+.le
+.ls 4 = weight
+As for option = id except that the nput format contains the newweight
+instead of the newidentifier.
+.le
+.le
+
+.sh
+MANUAL LINE IDENTIFICATION
+
+This routine provides the option of manually identifying the locations
+of spectral features by either setting a graphics cursor interactively,
+or by entering a list of feature positions.
+
+The primary uses for this routine are to identify features of known
+wavelength in preparation for a dispersion solution, and also to
+identify features in linearized spectra for velocity measurements.
+
+.ih
+NAME
+mlinid -- Manually identify line features in a spectrum
+.ih
+USAGE
+mlinid [filename, files]
+.ih
+DESCRIPTION
+A list file is created for each of
+the spectra specified by the IRAF filename parameter and files string
+containing the locations of spectral features and their associated
+reference value (e.g. wavelength, frequency, wavenumber).
+If invoked as an interactive task from a graphics terminal,
+the spectra will be displayed and cursor input requested to ascertain
+the approximate position of the feature. An improved position will
+be obtained via one of the line centering algorithms, and
+a request will be made for the reference value of the feature.
+The requests continue until EOF is detected.
+The name of the created list file is added to the spectral image
+header.
+
+Positions of features are given in the coordinate system defined
+by the standard image header entries CRPIX and CDELT
+defining the reference pixel and the
+pixel to pixel distance. For raw spectra these values simply define
+the pixel position of the feature. For dispersion corrected spectra
+these values define the position of the feature in wavelength units.
+
+If invoked as a background task, or from a non-graphics terminal,
+additional requests for the cursor x-coordinate  and intensity
+will be made from the standard input.
+
+The procedure is repeated for all specified spectra.
+
+Because the dispersion solution may be a function of an additional
+instrument dependent parameter (e.g. zenith distance),
+the driving package script can indicate the header entry to be
+used as the second parameter. Values for this parameter, if present,
+will be written to the output list file.
+.ih
+PARAMETERS
+
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 cur (x,y)
+This is a list structured parameter of type "graphics cursor".
+The list contains the approximate values of the pixel
+coordinate for the spectral features to be identified
+and the intensity value of the continuum at the feature. If the
+task is invoked from a graphics terminal in an interactive mode,
+values for this parameter will be read from the terminal's
+graphics cursor.
+.le
+.ls 4 value
+This is a list structured parameter containing the reference values
+for the spectral features to be identified. If the task is invoked in
+an interactive mode, the user will be prompted for these values.
+.le
+.ls 4 center_option
+This string parameter controls which algorithm is to be used during
+the improved centering phase of the process. (default = cg)
+.ls 4 = cg
+This specifies a center of gravity algorithm defined as the
+first moment of the intensity above the continuum level
+across the spectral feature.
+The integrals are evaluated using the trapezoidal rule and
+the intensity will be weighted by the square root of the intensity
+if the switch parameter cgweight is set to yes. The integral
+is evaluated from the approximate position defined by x cursor position
+plus and minus the number of pixels specified by the parameter
+cgextent.
+.ls 4 cgweight
+This switch defines whether a weighted moment is used in the
+center of gravity centering algorithm. (default = yes)
+.le
+.ls 4 cgextent
+This integer parameter defines the limits of the integrals in the
+center of gravity centering algorithm. The integral extends from
+the approximate position minus the extent to the approximate position
+plus the extent in units of pixels. (default = 5).
+.le
+.le
+.ls 4 = parabola
+This specifies that the centering algorithm is to be a parabolic
+fit to the central 3 pixels. The improved center is taken as the
+center of the parabola. The central 3 pixels are defined as the
+most extreme local pixel plus and minus one pixel. The most extreme
+local pixel is that pixel nearest the approximate center having the
+greatest deviation from the local average value of the spectrum. The
+extent of "local" is taken as plus and minus the parameter parextent.
+.ls 4 parextent
+This integer parameter defines the extent in units of pixels
+of the search for a local extreme pixel. (default = 3)
+.le
+.le
+.ls 4 = gauss
+(This algorithm will not be implemented in the initial system release.)
+This specifies that the centering algorithm is to be a Gaussian
+fit to the region near the approximate center. The fit is
+made to a region specified by the parameter gextent. Because
+this is a three parameter non-linear least-squares fit
+(center, width, peak intensity), it is likely to
+be slow. It may also produce poor results with noisy data
+although centering on high signal to noise data should be
+excellent.
+.ls 4 gextent
+This integer parameter specifies the extent in pixels of the Gaussian fit.
+It may be necessary to include a significant region of continuum.
+(default = 9)
+.le
+.le
+.ls 4 = none
+If this option is chosen, no improvement to the approximate center
+will be made. This may be useful for asymmetric and weak features
+where the other techniques can be systematically incorrect.
+.le
+.ls 4 second_order
+This string parameter defines the name of the image header entry to be
+used as the second order correction parameter in the dispersion
+solution. Values for this parameter, if present, are read from the image header
+and written to the output list file. Examples of values are zenith_distance,
+sidereal_time, instr_temp. (default = none)
+.le
+
+.sh
+AUTOMATIC LINE IDENTIFICATION
+
+This task allows a user to locate a set of spectral features defined
+in a previously prepared list.
+
+.ih
+NAME
+alinid -- Automatically locate spectral features in a spectrum
+.ih
+USAGE
+alinid [filename, files, mfilename, mfiles, list]
+.ih
+DESCRIPTION
+A list file is created for each of the spectra specified by the
+IRAF filename and files parameters. The file will contain
+the positions of the features defined in the line list file
+specified by the list parameter. The name of the list file
+will be added to the spectral image header.
+
+A preliminary estimate of the
+relationship of feature position as a function of feature
+wavelength is obtained from the list file(s) created by the
+task MLINID and defined by the parameters mfilename and mfiles. 
+A single preliminary estimate may be applied to a number of
+spectra by specifying a null mfiles string. Otherwise,
+a one-to-one correspondence is assumed between preliminary
+list files and spectra. If the entry for mfilename is also null,
+the linear dispersion relation for the pixel coordinate contained
+in the image header will be used. This provides the option
+of locating features in linearized spectra.
+
+The initial position estimate is improved using one of the centering
+algorithms defined by the center_option parameter and then
+written to a list file. Also written to the list file will be
+the feature's reference value (e.g. wavelength), weight,
+identification string, and the acceptability of the line.
+Acceptibility is noted as either accepted, set, deleted, or not
+found (see below).
+
+If the task is invoked from a graphics terminal as an interactive
+task, the interact switches may be set to yes.
+Then each spectrum will
+be displayed in segments expanded about each feature with the
+automatically defined center marked. The user can then accept
+the given position, mark a new center, or declare the line
+unacceptable.
+
+If the display switch is set, the spectrum is displayed
+and the features marked.
+
+If the task is invoked as a background task, or if the
+user terminal is non-graphics, then the display and interact
+switches cannot assume values of yes.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS
+.le
+.ls 4 files
+See the definition of this parameter under RFITS
+.le
+.ls 4 mfilename
+The root for the spectra names used to define the preliminary
+relationship between spectral feature coordinate and reference
+value. The mfiles string parameter is used to define the
+suffix of the spectral name. If this parameter is null, the
+preliminary relationship is assumed to be linear and defined
+by the standard image header entries CRPIX and CDELT.
+.le
+.ls 4 mfiles
+This string parameter serves the same purpose for mfilename
+as the files parameter serves for filename. Note that if this
+parameter is null, the single spectrum defined by mfilename
+is used to define the preliminary relationship for all
+spectra defined by filename and files.
+.le
+.ls 4 list
+This parameter specifies the IRAF file name containing the
+spectral line list to be scanned for features. (See the
+task LINE_LIST)
+.le
+.ls 4 interact
+If this switch is set to yes and the task is invoked interactively
+from a graphics terminal, the spectrum will be displayed on the
+terminal. Each feature will be marked with its computed center
+and the user can type one of the following single keystrokes:
+.ls 4 a
+to accept the displayed position
+.le
+.ls 4 s
+to set the cursor to the desired position
+.le
+.ls 4 d
+to delete the displayed feature from the line list during this
+invocation of the task
+.le
+.ls 4 b
+to reset the operational mode to a "batch" environment where
+no display or interaction is desired
+.le
+.ls 4 p
+to reset the operational mode to a "passive" environment where
+the spectra are displayed and marked, but no interaction is desired
+.le
+.le
+.ls 4 display
+If this switch is set to yes, and the task is invoked from
+a graphics terminal, the spectrum will be displayed and the
+identified lines marked for the user's inspection. No
+interaction is allowed unless the interact switch is also set to yes.
+(default = yes)
+.le
+.ls 4 center_option
+See the description of this parameter under MLINID.
+.le
+.ls 4 second_order
+See the description of this parameter under MLINID.
+.le
+
+.sh
+DISPERSION SOLUTION
+
+After several spectral features have been identified, either
+manually with MLINID or automatically with ALINID, the relationship
+between feature reference value and pixel coordinate can be calculated.
+The dispersion relation may require a second order correction
+to account for variations as a function of some additional
+parameter, such as zenith distance or time of day.
+
+.ih
+NAME
+disp_sol -- Determine the dispersion relation for a set of spectra.
+.ih
+USAGE
+disp_sol [filename, files, order, global]
+.ih
+DESCRIPTION
+The list files containing the postions and reference values for
+features in the specified spectra are combined to solve for the
+dispersion relation by a polynomial least-squares fit to the lists.
+The solution can include a second order
+correction parameter which is also contained in the list file.
+
+The solution takes the form of a polynomial in the pixel
+coordinate having the specified order. The second order
+is also fit by a polynomial. (The choice of a polynomial
+applies to the initial release. Additional forms, selectable by
+parameter, of the solution may be available later.)
+The polynomial coefficients are stored in the spectral image header
+if the store_coeffs switch is set to yes and the spectrum does not already
+contain a solution. If a solution already exists, the user is
+asked for confirmation to overwrite the solution, unless the overwrite
+switch is set to yes.
+
+If filename is the name of a data group, all line list files for
+spectra in that data group are combined into the solution.
+
+If invoked as an interactive task from a graphics terminal,
+a representation of the solution will be displayed and the user
+will be allowed to alter the weights of the line entries.
+If invoked from a non-graphics terminal, the representation
+will be in a tabular format (also available at a graphics terminal)
+for inspection and alteration. If invoked as a background task,
+an attempt will be made to reject discrepant points.
+
+The solution is made using all available line lists combined
+into a single data set if the global switch is set to yes.
+If global is set to no, each spectrum is treated as an
+independent data set.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 order
+The order of the polynomial for a least-squares fit to the
+dispersion solution. If the specified order exceeds the number
+of free parameters, the order will be reset to the maximum
+allowable. (default = 1 --> linear).
+.le
+.ls 4 global
+This switch determines if the data from all the specified spectra are
+to be treated as a single large data set. This is appropriate if the
+data represent a single congruent "setup". But if the data represent
+several different configurations, such as for multiaperture data,
+the global switch should be set to no. Note that if global is no, then
+no second order parameter solution is possible.
+.le
+.ls second_order
+This parameter specifies the order for the fit to the second
+order parameter. The limit described for the order parameter
+applies. (default = 0 --> no second parameter solution).
+.le
+.ls 4 interact
+If this switch is set to yes and the task is invoked interactively
+from a graphics terminal, the residuals of the solution will be displayed
+on the terminal. The user can type one of the following keystrokes:
+.ls 4 a
+to accept the current solution. The parameters of the fit
+are written into the headers of the spectra contributing to the fit.
+.le
+.ls 4 e
+to exit without saving the solution
+.le
+.ls 4 w
+to reset the weight of the point near the cursor positioned by the user.
+The user is then prompted for the new weight which may be set to zero
+to delete the point from the solution.
+.le
+.ls 4 t
+to display the solution parameters in tabular form
+.le
+.ls 4 o
+to specify a new order for the solution
+.le
+.ls 4 s
+to specify a new order for the second order parameter solution
+.le
+.ls 4 b
+to revert to batch mode to process the remainder of the solutions.
+This is only meaningful if the global switch is set to no.
+.le
+.ls 4 p
+to revert to passive mode as for ALINID. This is only meaningful
+if the global switch is set to no
+.le
+.le
+.ls 4 store_coeffs
+If this switch is set to yes, the dispersion solution polynomial
+coefficients will be written into the image header as special
+header elements. Otherwise, the solution is discarded. (default = yes)
+.le
+.ls 4 overwrite
+If this switch is set to yes, any existing dispersion solution contained
+in the image header will be overwritten without any request for confirmation
+from the user. If set to no, the user is asked if overwriting of the solution
+is acceptable. If no prior solution exists, this switch has no meaning.
+(default = no)
+.le
+
+.sh
+DISPERSION CORRECTION
+
+After the dispersion relation has been determined, the spectra
+are usually re-binned to create spectra having a linear
+relationship with wavelength. Although this is not always
+done, nor is it always desirable, subsequent processing
+is often simplified greatly by having to deal with only
+linearized data.
+
+.ih
+NAME
+disp_cor -- Linearize spectra having dispersion relation coefficients
+.ih
+USAGE
+disp_cor [filename, files, destination, option]
+.ih
+DESCRIPTION
+The spectra specified by the root filename and the files parameter
+are corrected for deviations from a linear wavelength relationship.
+The corrected spectra are written to filenames having the root
+specified by the destination parameter.
+
+The correction is performed by solving for the inverse relationship
+of pixel number as a function of equal increments in the wavelength.
+The new starting wavelength and increment are optionally specified
+by the parameters start and increment. If not specified, the current
+wavelength of the first pixel will be taken as the starting wavelength
+and the increment will be chosen to exactly fill the length of the
+current spectrum. The spectrum will be padded with INDEF on either
+end if the specified parameters request a larger spectral window than
+actually exists.
+
+The actual re-binning can be performed using one of several algorithms.
+The most efficient minimally smoothing algorithm to be available in the
+initial release is the fifth order polynomial interpolation.
+The most efficient count preserving algorithm is the simple partial-pixel
+summer.
+
+The interpolation can be either linear in wavelength or in the logarithm
+of wavelength. The latter is useful for subsequent radial velocity
+analyses. The choice is specified by the logarithm switch.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS
+.le
+.ls 4 destination
+See the definition of this parameter under COIN_COR.
+.le
+.ls 4 option
+This parameter specifies the algorithm to be used for the
+re-binning operation. The initial release will contain the
+following options:
+.ls 4 = linear
+to use a linear interpolation
+.le
+.ls 4 = poly
+to use a fifth order polynomial
+.le
+.ls 4 = sinc
+to use a sinc function interpolator
+.le
+.ls 4 = sum
+to use partial pixel summation
+.le
+.le
+.ls 4 start
+This parameter specifies the wavelength at which the corrected
+spectrum is to begin. The wavelength of the first pixel will
+be assigned this value. This parameter, combined with the increment
+parameter, allows data taken on different nights
+or with different instruments to be forced to be congruent.
+(default = value at first pixel)
+.le
+.ls 4 increment
+This parameter specifies the pixel to pixel wavelength (or logarithm of
+wavelength) increment
+that is to be used during the linearization process.
+(default = [wavelength at last pixel minus wavelength at first pixel]
+divided by [number of points in spectrum - 1])
+.le
+.ls 4 logarithm
+If this switch is set to yes, the linearization occurs with equal
+increments in the logarithm of wavelength. Otherwise, equal
+increments of wavelength are used. (default = no)
+.le
+.ls 4 print_header
+See the definition of this parameter for COIN_COR.
+.le
+
+.sh
+FIELD FLATTENING
+
+Most detectors exhibit variations in sensitivity across the field
+of interest. These are removed by dividing all observations by
+the spectrum of a smooth continuous source, such as an incandescant
+lamp. In order that these lamps, which usually have a low color
+temperature, produce sufficient energy in the blue and ultraviolet,
+they are often enclosed in a quartz rather than a glass bulb.
+Thus, the field flattening operation is often referred to as
+"quartz division".
+
+The operation is of marginal value unless the continuum source is
+observed properly. First, a very high signal-to-noise ratio per
+pixel is required. For certain detectors and applications this
+may not be possible in a reasonable amount of time. Second, the
+continuum source should not have any significant variations
+across small regions of the spectrum (high frequency "bumps").
+Otherwise the division will add these variations into the spectrum.
+
+There are basically two aspects to flat fielding spectra. The first
+is the removal of pixel-to-pixel sensitivity variations. The second
+is a more global pattern due to non-uniform iillumination and
+spatial and wavelength sensitivity variations across the detector.
+
+The very high frequency pixel-to-pixel variations are easily handled
+by a straightforward division of the observations by the continuum
+spectrum.
+
+The second problem is usually postponed in one-dimensional data
+reductions and included in the
+solution for the system sensitivity by observing standard stars.
+This aspect of the problem is adequately handled in this fashion
+and no special operators are provided in this package.
+
+If the continuum source exhibits large low frequency variations
+across the spectrum, it may be desirable to filter these.
+This is most easily done by fitting a moderately high order
+polynomial through the spectrum, and then dividing the polynomial
+representation into the original continuum spectrum. The result
+is a flat spectrum having an average value of unity and
+containing only the pixel-to-pixel sensitivity variations.
+
+Finally, it should be noted that the field flattening operation
+is most properly performed prior to the wavelength linearization
+of the spectra because the linearization process can smooth
+pixel-to-pixel variations.
+
+Flat fielding consists of two logical operations. The first
+is the solution for a continuum spectrum with the low frequency
+variations removed (CR_FLAT). It is assumed that multiple observations
+of the continuum source have been already averaged (using the
+image calculator program, for example).
+
+The second operation is the actual field flattening of the object
+spectra (FLT_FIELD).
+
+.ih
+NAME
+cr_flat -- Create a flat field spectrum
+.ih
+USAGE
+cr_flat [filename, destination]
+.ih
+DESCRIPTION
+The continuum spectrum specified by filename is corrected for
+low frequency spectral variations. Several algorithms may be
+available. The initial release will contain only a polynomial
+fitting technique. A fourier filtering algorithm may be added
+at a later date.
+
+The spectrum is fit by a polynomial in the pixel coordinate
+and the polynomial is divided into the original spectrum.
+Discrepant pixels may be rejected and the solution re-iterated.
+
+If invoked as an interactive task from a graphics terminal, the
+resultant spectrum is displayed and the user may alter the
+solution parameters if the interact switch is set to yes.
+If invoked from a non-graphics terminal, sufficient information
+concerning the fit is written to the terminal to allow
+the user to judge the quality of the fit and then alter the
+solution parameters.
+
+If invoked as a background task, or if the interact switch is set
+to no, default parameters will be assumed.
+
+The parameters of the fit are added to the image header for
+the corrected spectra.
+.ih
+PARAMETERS
+.ls 4 filename
+The IRAF filename containing the spectrum of the continuum
+source. If this is a data group name, then all spectra
+in the group will be corrected.
+.le
+.ls 4 destination
+The IRAF filename into which the resultant corrected
+spectrum is written. If the source filename is a data group,
+then the destination will be a new data group containing
+the names of the corrected spectra. The names will be
+assigned using the destination as a root name, and the
+ordinal of the spectrum in the list as a suffix.
+.le
+.ls 4 option
+This string parameter specifies the algorithm to be used
+in the correction process. Currently only option = poly
+is recognized.
+.le
+.ls 4 order
+This integer parameter specifies the initial order of the
+polynomial fit. (default = 8)
+.le
+.ls 4 reject
+This parameter specifies the number of standard deviations
+beyond which pixels are to be rejected. If the task
+is interactive, pixel rejection is performed only on command.
+If invoked as a background task, rejection is iterated 
+until no further pixels are rejected, or until the iteration
+count has been attained (see parameter niter). (default = 2.2)
+.le
+.ls 4 niter
+This integer parameter specifies the number of iterations
+to be performed in background mode. It may be set to 0 to
+specify no pixel rejection. (default = 2).
+.le
+.ls 4 interact
+If this switch is set to yes and the task is invoked as
+an interactive task, the user can alter the fit parameters
+order, reject, and niter. If at a graphics terminal, the resultant
+spectrum is displayed and the user can command the operation
+with the following single keystrokes:
+.ls 4 a
+to accept the solution
+.le
+.ls 4 o
+to change the order of the fit
+.le
+.ls 4 r
+to reset the reject parameter
+.le
+.ls 4 n
+to reset the niter parameter
+.le
+.ls 4 b
+to reset the operational mode to a batch environment
+.le
+.ls 4 p
+to reset the operational mode to a passive environment
+.le
+.le
+
+If at a non-graphics terminal, the fit parameters are
+written to the terminal so that the user may assess the quality
+of the fit. A request for one of the interactive commands
+is then issued and the user may proceed as if on a graphics
+terminal.
+.le
+
+.ih
+NAME
+flt_field -- Correct spectra for pixel-to-pixel variations
+.ih
+USAGE
+flt_field [filename, files, flatname, destination]
+.ih
+DESCRIPTION
+The spectra specified by the IRAF filename parameter and the files
+string are divided by the flat field spectra specified by
+the parameter flatname. If filename and flatname are data group names,
+the division is performed on a one-for-one basis.
+
+This operation is little more than a simple division. An image
+header entry is added indicating that flattening by the
+appropriate spectrum has been performed.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 flatname
+This string parameter sepcifies the name of the flat field
+spectrum, or spectra if a data group name.
+It is not necessary that the flat field spectra be corrected
+for low frequency spectral variations.
+It is required that the spectra be congruent with the spectra
+to be flattened; that is, all spectra must have the same
+length, reference pixel, and pixel-to-pixel increment.
+.le
+.ls 4 destination
+See the definition of this parameter under COIN_COR.
+.le
+.ls 4 print_header
+See the definition of this parameter under COIN_COR.
+.le
+
+.sh
+EXTINCTION CORRECTION/FLUX CALIBRATION
+
+At each wavelength (lambda) along the spectrum, the observed
+flux (fobs) must be corrected for extinction (k) due to the
+Earth's atmosphere and the system sensitivity (S) to obtain
+a true flux (f) above the atmosphere.
+.sp 1
+fobs(lambda) = f(lambda) * exp{-z[k(lambda)+C]} * S(lambda)
+.sp 1
+where z is the path through the Earth's atmosphere during the
+observation and C is an optional "grey" opacity term.
+
+For most observations, the standard extinction function is adequate,
+but occasionally the additive term is beneficial. In rare cases,
+the observer has acquired sufficient high quality data to
+determine the extinction function across the spectral region
+of interest. And in other cases, the user may have a priori
+knowledge of the extinction function.
+
+Observations of standard stars are used to determine
+either the additive constant or a new extinction function,
+and the system sensitivity.
+The two operations, determining the extinction parameters
+and the system sensitivity curve, are therefore intimately
+related.
+
+The process breaks down into four basic operations:
+.ls 4 1.
+Define the standard stars and their observations. (STD_STAR)
+.le
+.ls 4 2.
+Define the extinction solution option and solve for the extinction
+additive term or complete function if necessary. (CREXT_FUNC)
+.le
+.ls 4 3.
+Determine the system sensitivity function. (CRSENS_FUNC)
+.le
+.ls 4 4.
+Remove the effects of the extinction and the system sensitivity
+from the observations. (EXT_COR, SENS_COR)
+.le
+
+These will be described below in more detail.
+
+.ih
+NAME
+std_star -- Define the standard stars to be used for solving the extinction and
+system sensitivity functions.
+.ih
+USAGE
+std_star [fnamelist, filelist, namelist, std_file]
+.ih
+DESCRIPTION
+The spectra defined by the list of filenames and associated files
+contained in the string list parameters fnamelist and filelist
+are compared with the standard flux measurements for the stars
+listed in the string list parameter namelist. The resultant
+table of ratios as a function of wavelength are saved in the
+IRAF file specified by the std_file parameter.
+
+All spectra must be wavelength linearized. The star names given
+in namelist must be in a form similar to that in the IIDS Reduction
+manual. If a star name cannot be matched to the standards contained
+in a calibration file, the user is prompted for additional
+information. The calibration file containing the list of reference
+flux values is specified by the calib_file parameter.
+.ih
+PARAMETERS
+.ls 4 fnamelist
+This is a list structured parameter containing the IRAF filenames
+associated with the spectra for each of the standard stars contained
+in the list of starnames defined by the list structured parameter
+namelist. Both these parameters must have the same number of elements.
+The filename specifications are defined as in RFITS.
+.le
+.ls 4 fileslist
+This is also a list structured parameter having the same number of
+elements as fnamelist although some may be null.
+The entries are defined as in RFITS.
+.le
+.ls 4 namelist
+This is also a list structured parameter having the same number
+of elements as fnamelist. All elements must exist and have a
+form to be decided on, but probably similar to that given in the IIDS
+Reduction manual, page 36. For example, a typical star name might
+be BD+8 2015, or HILTNER 102. Case will not be significant.
+.le
+.ls 4 std_file
+This string parameter defines the IRAF filename in which the
+results from the standard star observations are stored.
+This file will be used to contain further calibration information
+such as the extinction and sensitivity function for the
+current set of observations.
+.le
+.ls 4 calib_file
+This string parameter defines which of several calibration
+data files are to be accessed for the comparison of the
+observational data to the standard fluxes. Separate tools
+to examine, modify, and create these files are available
+in the utilities package. (default = onedspec$iids.cal)
+.le
+.ls 4 print_header
+If this parameter is set to yes, an informative header
+is listed on the standard output as the standard stars are processed
+(default = yes).
+.le
+
+.ih
+NAME
+crext_func -- Create an extinction function from a set of observations
+.ih
+USAGE
+crext_func [std_file, option]
+.ih
+DESCRIPTION
+The user may specify via the option parameter which of the four
+extinction solutions is to be used. These are:
+.sp 1
+.ls 4 1.
+Adopt standard extinction function (option = standard).
+.le
+.ls 4 2.
+Solve for an additive constant (option = additive).
+.le
+.ls 4 3.
+Solve for extinction function (option = new_function).
+.le
+.ls 4 4.
+Input a tabular extinction function consisting of extinction
+values at specified wavelengths (option = input).
+.le
+.sp 1
+If the first or last options are chosen, the std_file may be empty.
+If the second option is chosen, several observations at
+differing air masses must be included in the file specified by std_file.
+If the third option is chosen,
+at least two standard stars must be included in the list of observations.
+
+The derived extinction function is added to the IRAF file specified
+by the std_file parameter by creating a new spectrum containing the
+function and adding the spectrum name to the std_file.
+The new spectrum will adopt a name having a root from the
+name std_file and a suffix of ".ext". The spectrum is created by
+a spline interpolation through the extinction values.
+
+If invoked as an interactive task from a graphics terminal, the
+derived extinction function  is displayed. The user may interactively
+alter the derived extinction values using the graphics cursor.
+If invoked from a non-graphics terminal, the user may alter the
+values by specifying the wavelength and new extinction value
+from the standard input. Interaction may be suppressed by setting the
+interact switch to no.
+
+.ih
+PARAMETERS
+.ls 4 std_file
+See the definition of this parameter under STD_STAR.
+.le
+.ls 4 option
+This parameter specifies which aspects of the extinction solution
+are to be computed. See description section for CREXT_FUNC.
+.le
+.ls 4 interact
+If this switch is set the user may alter the derived extinction values.
+If invoked from a graphics terminal and interact is set to yes, the
+following single keystroke commands may be typed:
+.ls 4 a
+to accept the current solution
+.le
+.ls 4 m
+to modify the extinction value at the cursor wavelength position (cursor-x)
+to the cursor extinction value position (cursor-y).
+.le
+.ls 4 i
+to insert a new wavelength-extinction value pair at the current
+crosshair position.
+.le
+.ls 4 d
+to delete the wavelength-extinction value pair at the current
+cursor wavelength position.
+.le
+.le
+
+.ih
+NAME
+crsens_func -- Create system sensitivity function.
+.ih
+USAGE
+crsens_func [std_file, option]
+.ih
+DESCRIPTION
+The standard star data and extinction function contained in the
+IRAF file specified by the std_file parameter are used to
+compute the system sensitivity as a function of wavelength.
+The derived function is written to the file specified by
+std_file.
+
+There must be at least one standard star observation contained
+in the std_file, unless the parameter option = input.
+This allows the user to enter any function in the
+form of wavelength-sensitivity pairs.
+
+If option = shift, a "grey" shift is applied to all observations
+necessary to bring relatively faint values up to the brightest
+to account for possible cloud variations.
+
+If invoked as an interactive task from a graphics terminal,
+and the interact switch is set to yes, the sensitivity values
+from each standard are plotted with any "grey" shift correction
+added. The user may delete or add new points as desired using
+the cursor. If invoked from a non-graphics terminal, a tabular
+list of the solution is presented and additions or deletions
+may be entered through the standard input.
+
+The final function written to the std_file is simply the name of a new
+spectrum derived from a spline fit to the sensitivity
+if the spline switch is set to yes. If spline = no, a linear
+interpolation between sensitivity points will be used.
+The sensitivity spectrum name will be taken from the file name
+given to std_file and with the suffix ".sen".
+.ih
+PARAMETERS
+.ls 4 std_file
+See the definition of this parameter under STD_STAR.
+.le
+.ls 4 option
+This parameter can assume the following string values:
+.ls 4 = input
+to indicate that the sensitivity function is to be entered as
+wavelength-sensitivity pairs. 
+.le
+.ls 4 = shift
+to force a "grey" shift between all standard star spectra to
+account for clouds. This is actually a multiplicative factor
+across each of the affected spectra.
+.le
+.le
+.ls 4 spline
+This switch parameter determines if a spline fit is to be made
+between the sensitivity points (spline = yes), or a linear
+fit (spline = no). (default = yes).
+.le
+.ls 4 interact
+If invoked as an interactive task, the user may alter the sensitivity
+function values. If at a graphics terminal, the sensitivity curve
+is displayed first for each star in the solution. The user may
+add or delete values for any or all stars at a given wavelength.
+Subsequently, the derived average curve is displayed and the user
+may further modify the solution. The following keystrokes are
+available from the graphics terminal:
+.ls 4 a
+to accept the current displayed data (solution).
+.le
+.ls 4 d
+to delete the value at the cross-hairs. If several values
+are very close together, an expanded display is presented.
+.le
+.ls 4 i
+to insert the sensitivity value of the y-cursor at the wavelength position.
+.le
+.ls 4 c
+to "create" new sensitivity values at the wavelength position of the
+x-cursor. Normally sensitivity values are computed only at pre-defined
+wavelengths specified in the calib_file. Additional values
+may be computed by interpolation of the standard star fluxes
+from the calib_file. The name of the calib_file and the spectra
+in the current solution are taken from the std_file.
+.le
+.le
+
+.ih
+NAME
+ext_cor -- Extinction correct specified spectra
+.ih
+USAGE
+ext_cor [filename, files, std_file, destination]
+.ih
+DESCRIPTION
+The spectra specified by the filename and files parameters
+are corrected for atmospheric extinction according to the
+extinction correction function pointed to by the function
+name in std_file. The resulting new spectra are created with the
+root of the destination parameter and having suffixes of
+1 through n corresponding to the n spectra corrected.
+If filename is a data group name, a new data group will be created having
+the name given by the destination parameter.
+
+The correction has the form:
+.sp 1
+f(lambda) = fobs(lambda) / 10**{-z[a(lambda) + C]}
+.sp 1
+where:
+.ls 4 f(lambda) = the flux at wavelength lambda above the Earth's atmosphere.
+.le
+.ls 4 fobs(lambda) = the flux observed through the atmosphere
+.le
+.ls 4 z = the path length through the atmosphere is units of air masses
+(= 1 at the zenith)
+.le
+.ls 4 a(lambda) = the extinction function at wavelength lambda
+in magnitudes per airmass.
+.le
+.ls 4 C = the additive constant, if any, in magnitudes per airmass.
+.le
+.sp 1
+For each spectrum, the zenith distance must be present in the image header.
+This is assumed to be correct for the beginning of the observation.
+For short exposures, this is adequate for the correction, but for
+long exposures, an effective air mass must be calculated over the
+integration. To do so requires knowledge of the altitude and azimuth
+of the telescope (or equivalantly RA, Dec, and sidereal time).
+If these are not present, the approximate air mass calculation will be used
+based solely on the available zenith distance. If the zenith distance
+is not present, user input is requested.
+
+The air mass is calculated according to the following equation for a given
+telescope position (based on Allen p.125,133):
+.sp 1
+z = sqrt{[q sin (alt)]**2 + 2q + 1} - q sin(alt)
+.sp 1
+where:
+.ls 4 q
+= atmospheric scale height (approx = 750).
+.le
+.ls 4 alt
+= telescope altitude
+.le
+.sp 1
+If the telescope traverses a significant distance in elevation during
+the integration, an effective correction can be computed as:
+.sp 1
+f(lambda)a = f(lambda)obs*T / integral{10**[-z(t)(a(lambda) + c)]}dt
+.sp 1
+where the integral is over the integration time, T.
+
+This expression can then be evaluated numerically at each wavelength.
+Because this is a time-consuming operation, the switch effective_cor
+can be set to no and then a simplified correction scheme will be used.
+This will be to compute a midpoint airmass if sufficient information
+is available, or simply to use the header airmass otherwise.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 std_file
+See the definition of this parameter under STD_STAR.
+.le
+.ls 4 destination
+See the definition of this parameter under COIN_COR.
+.le
+.ls 4 effective_cor
+If this switch is set to yes, the procedure to compute an effective
+corrective term averaged over the integration time will be used.
+Although a slow process, this method is more accurate than
+simply using the correction at any given time of the integration
+such as the midpoint. If set to no, a midpoint zenith distance
+will be computed and used if sufficient header information
+exists. (default = no).
+.le
+.ls 4 print_header
+See the definition of this parameter for COIN_COR.
+.le
+
+.ih
+NAME
+sens_cor -- Correct the specified spectra for system sensitivity
+variations across the spectrum.
+.ih
+USAGE
+sens_cor [filename, files, std_file, destination]
+.ih
+DESCRIPTION
+The spectra specified by the filename and files parameters are
+corrected for instrumental sensitivity by the 
+function pointed to by the spectrum name contained in std_file.
+The resulting spectra are stored according to the destination parameter.
+Filename may be a data group name. If so, then destination will be
+a new data group containing the names of the corrected spectra.
+
+This correction is a simple vector multiplcation.
+.ih
+PARAMETERS
+.ls 4 filename
+See the definition of this parameter under RFITS.
+.le
+.ls 4 files
+See the definition of this parameter under RFITS.
+.le
+.ls 4 std_file
+See the definition of this parameter under STD_STAR.
+.le
+.ls 4 destination
+See the definition of this parameter under COIN_COR.
+.le
+.ls 4 print_header
+See the definition of this parameter under COIN_COR.
+.le
+.endhelp