path: root/noao/onedspec/doc/sys/Onedspec.hlp

.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