Indentifier   glue

 Purpose       To join spectra or mini-spectra into a single spectrum
               by averaging the overlapping portions of the spectra.

 Synopsis      status = glue (struc_in, struc_out
                     [, struc_in2 = struc_in2] [, epsilon = epsilon] )


 Arguments     Name      I/O  Type     Description
               ---------------------------------------------------------

               struc_in I    struct   Input structure (AAR)

               struc_out O    struct   Output structure (AAR)
                                        (unchanged if fatal error)
                                        Data points will be sorted
                                        in wave order.  Only data tags
                                        wave, flux, stdev, flag will
                                        be in the data part of struc_out.

               struc_in2 I   struct    Optional second input structure (AAR)
                                       (see struc_in for details)

               epsilon   i    float    Optional epsilon to determine
                                       if two wave values are the "same"
                                       Default is 1.e-5

 Returns       0 if OK   1 if fatal error

 Description   This utility is capable of joining individual detector
               spectra within one AAR structure of two AAR structures.
               Points where wave is within epsilon will be combined with
               a weighted average. Stdev will be correctly propogated.
               See documentation for chk_multix for information
               about how points are combined.

 Comment
               There is no check tha the data has been rebinned.
               (differing wave values in the overlap areas.

               This program calls chk_multix which provides
               no mechanism for maintaining corresponding values
               for tags other than wave, flux, and stdev.

 Examples

               In the following examples, the output is returned in
               an AAR structure named AAR_GLUED.

               To glue all of the mini-spectra in AAR_ORIG together:

                      stat = glue (AAR_ORIG,  AAR_GLUED)

               To glue all of the mini-spectra in AAR_ORIG together with
               a tollerance of 1.0E-3 for combining points:

                      stat = glue (AAR_ORIG,  AAR_GLUED, epsilon=1.0E-3)

               To glue AAR_ADDON together with AAR_ORIG and produce AAR_GLUED:

                      stat = glue (AAR_ORIG, AAR_ADDON,  AAR_GLUED)

 Dependencies  CALLS: chk_multix, kwd_notset, redo_hdr, sap_ckunits, 
                      sap_error, update_history
               CALLED FROM: IA, GUI

 Category      ISAP

 Filename      glue.pro

 Author        R. Narron (IPAC)

 Version       1.6

 History       definition of requirements - rewrite of E. Sturm's
               first draft by B. Swinyard 7/8/95

               0.1  950809 --> R. Narron (IPAC)  Prototype
               0.2  951010 --> R. Narron  New AAR definition
               1.0  951027 --> R. Narron  New parameter checking
               1.1  951106 --> R. Narron  Update FITS header
               1.2  951120 --> R. Narron  Always set type="YAAAR"
               1.3  951201 --> R. Narron  Exclude all "mask" points
               1.4  951206 --> R. Narron  Add-in "mask" points later
               1.5  951207 --> R. Narron  change chk_units call to sap_ckunits
               1.6  960716 --> RN added status return from chk_multix

 Copyright (C) 1995, California Institute of Technology.
 U.S. Government Sponsorship under NASA Contract NAS7-918 is acknowledged.
******************************************************************************