Identifier     bin_struct

 Purpose        Modify an AAR structure after its data has been 
                rebinned


 Synopsis       struc_out = bin_struct( struc_in, resx, resy, sigy
                                      [,resdet=resdet] [,rescnt = rescnt]
                                      [,resdir = resdir] 
                                      [,resline = resline] )


 Arguments      Name      I/O Type       Description
                -----------------------------------------------------
                struc_in   I  AAR        input structure (spectrum)
                resx       I  Fltarr     resampled x-scale (wavelength)
                resy       I  Fltarr     resampled y-scale (flux)
                sigy       I  Fltarr     sigma array for yarr
                resdet     I  Intarr     optional detector array for
                                         this spectrum
                rescnt     I  Intarr     optional scnt array for 
                                         this spectrum
                resdir     I  Intarr     optional sdir array for
                                         this spectrum
                resline    I  Intarr     optional line array for
                                         this spectrum
                struc_out  O  AAR        the rebinned structure (spectrum)


 Returns        the rebinned AAR structure (spectrum)


 Description    Create the new structure (new length and new data
                with resx, resy, and sigy arrays using the header
                from input sructure "struc_in". Other data tags are
                added when it makes sense. Please see examples below.


 Comment        Since rebinning of some tags like time or detector ID 
                is not meaningful after data from multiple detectors 
                or scans have been combined, they do not exist in output
                structure. However, if the options passed to bin_struct
                indicate that certain data tags in input AAR retain their
                identity, they will be added to the output structure.
                These tags ared  det, sdir, scnt.

                The flag and the status word may be used for some 
                indications TBD. 

                History part of the header will be updated TBD.

 Example        1.  aar1 = sap_rebin (aar, ref = resx) will generate
                    ouput AAR data tags : wave, flux, stdev

                2.  aar1 = sap_rebin (aar, ref = resx, det='all') 
                    ouput AAR data tags : wave, flux, stdev, det 
                    (resampled output arrays of individual detector)

                3.  aar1 = sap_rebin (aar, ref = resx, scnt = 1) 
                    ouput AAR data tags : wave, flux, stdev, scnt 

                4.  aar1 = sap_rebin (aar, ref = resx, sdir = 0) 
                    ouput AAR data tags : wave, flux, stdev, sdir 

                5.  aar1 = sap_rebin (aar, ref = resx, sdir = 0,
                                      det=[13,14]) 
                    ouput AAR data tags : wave, flux, stdev, sdir, det 
                    (resampled output arrays of detectors 13, 14)

 Dependencies   CALLS:  KWD_NOTSET, REDO_HDR
                CALLED FROM: SAP_REBIN

 Category       ISAP 

 Filename       bin_struct.pro

 Author         Iffat Khan (irk@ipac.caltech.edu)

 Version        1.1

 History            27.07.95  definition of requirements - first draft   E. Sturm  
                    01.09.95  revision of requirements                   J. Mazz
                0.1 01.08.95  Design and Code                            I. Khan
                0.1 20.09.95  Include "FLAG" tag in output structure     I. Khan
                0.2 09.11.95  Include Parameter validation via           I. Khan
                              KWD_NOTSET. Also regenerate secondary  
                              header for the output aar.
                0.3 10.11.95  Include "Dependencies" in the header       I. Khan
                0.4 10.11.95  removed bug creating history routine crash I. Khan
                1.1 28-02-96  include "line" tag in      --> irk@ipac
                              rebinned structure with "scnt" option
                2.0 29-04-96  exclude "line" tag in output AAR     --> irk@ipac

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