STACK

*NAME:

     stack

*PURPOSE:

     To coadd selected Copernicus scans.

*CALLING SEQUENCE:

     stack,file,scan,wave,counts,nys,scatter,back,out=out,bkgnd=bkgnd,/tempcor,$
        /inspect,/batch,resltn=resltn,vrad=vrad,vlsr=vlsr,u3scan=u3scan

*PARAMETERS:

     file    (req) (i) (0) (s)
             Name of file containing the Copernicus scans

     scan    (req) (i) (1) (i)
             Vector containing the scan numbers to be coadded

     wave    (opt) (o) (1) (f)
             Wavelengths for coadded spectrum

     counts  (opt) (o) (1) (f)
             Counts for coadded spectrum
 
     nys     (opt) (o) (1) (i)
             Number of scans coadded per datum

     scatter (opt) (o) (1) (f)
             Scatter per datum

     back    (opt) (o) (1) (i)
             Coadded background

     out     (key) (i) 
             Name of output file

     bkgnd   (key) (i)
             Background subtraction option.  0=no background, 1=background
             from original FITS table (file), 2=background interpolated from
             a table.  Default is 1.

     tempcor (key) (i)
             If set, a temperature correction will be performed.

     batch   (key) (i)
             If set, no plots will appear on the screen and the user will
             not be prompted or allowed to reject portions of scans.  A 
             postscript file of the results will be generated.  Without
             this keyword, the user has the option of writing a postscript
             file after viewing the plot on the screen.

     resltn  (key) (i)
             Resolution of output wavelengths.  Defaults for each tube are:
             u1: .01, v1: .02, u2: .1, v2: .2, v3: .1  (angstroms)

    NOTE:  Velocity corrections not currently applied.  Ignore VRAD and VLSR.

     vrad    (key) (i) (0) 
             Radial velocity.  If not given, the value in the FITS header
             will be used.

     vlsr    (key) (i) (0)
             Velocity, local standard of rest.  If not given, the value in
             the FITS header will be used.

     inspect (key) (i) (0) (i)
             If set, the plots of each scan will be displayed and the user
             may reject all or part of that scan, as desired.

     u3scan  (key) (i) (1) (i)
             U3 scans corresponding to U1 scans to be stacked.  They'll be
             overplotted (scaled) in INSPECT mode so the user can see if there
             were any glitches or not.

*EXAMPLES:

           file='fornax$dkb100:[pep]c002.pep'
           scan=[659,664,672,677]

     Stack scans 659, 664, 672, and 677 from file C002.PEP, return vectors 
     to the user, and write results to file TEST.FIT:

           stack,file,scan,w,c,n,s,b,out='test.fit'

     Same as above, but use backgrounds from the table and not the raw file:

           stack,file,scan,w,c,n,s,b,out='test.fit',bkgnd=2
     
*SUBROUTINES CALLED:

     iuefhrd   Reads FITS header of input file
     iue3drd   Reads data from FITS file
     ifitswrt  Writes output FITS file
     setwgt    Allows user to interactively discard scans or regions thereof
     swtest    Data rejection and correction subroutine (widgets)
     within    Range testing
     tabinv    Locates index of items in a vector
     iueterp   Interpolates data to new wavelength grid
     nsplot    Stacked plot of counts, nys, sigma vs wavelengths
     addpar    Adds items to FITS header
     dateconv  converts date to fits format (if output file requested)

*SYSTEM VARIABLES USED:

     none

*FILES USED:

     Input FITS file containing original data
     Output FITS file containing stacked data if user selects that option
     backs.fit - Table of backgrounds in FITS primary array file
     tempcor.dat - Temperature data in ASCII format (if user selects 
                   that option)

*PROCEDURE:

     The user must have selected the scans to coadd ahead of time.  

     If the temperature or background tables need to be read, they
     are read.  Then the scalar fields for each scan are read.  The
     final wavelength vector is constructed.  Then the scans are read
     and any desired corrections (temperature or background) are applied.
     The data for each scan is saved, so that a sigma vector (a measure
     of the deviance from the coadded spectrum) can be calculated.  The
     data are plotted, and, if desired, a FITS file containing the results
     is written.  Note that the plot may be directed to a postscript file.

*MODIFICATION HISTORY:

     20 Jun 95 LLT Wrote (based on ASTACK by LLT and RWT)
      7 Jul 95 LLT inspect keyword
     15 Aug 95 LLT change annotation on plot
     19 Sep 95 LLT read corrected FITS files
     20 Sep 95 LLT add CATCH to skip scans with non-monotonic wavelengths
     20 Feb 96 RWT point to new files in fornax$dkb100:[pep]
     08 Mar 96 RWT replace backs_0.pix with call to FITS file backs.fit
                   to make stack more portable
     13 Mar 96 RWT subtract background from counts if bkgnd > 0
                   (apparently inadvertently left out in a previous version)
     25 Mar 96 RWT set plot y-axis scale to be min and max of individual
                   scans (not min and max of mean spectrum)
     01 May 96 RWT use !copr.arch & !copr.dat for file locations
     08 Aug 96 RWT add precautionary comments to output FITS file header
     19 Aug 96 RWT add more keywords to FITS headers
     23 Aug 96 RWT call copplot instead of nsplot
     23 Oct 96 RWT add object name to plot & limit scan list to 33
     07 Nov 96 RWT remove scan numbers from plot & add end time
     09 Dec 96 RWT move fiducial in upper left corner