Indentifier   sap_shift

 Purpose       To normalise a single scan to a given detector by
               comparing overlapping wavelength regions.

 Synopsis      status = sap_shift (struc_in, struc_out, det)


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

               struc_in  I    struct   Input structure (AAR)
                                         Data tag "det" is requiired.

               struc_out O    struct   Output structure (AAR)
                                       (unchanged if fatal error)

               det       I    int      Detector number of the "good" detector

 Returns       status:  0 if OK   1 if fatal error

 Description   The flux values for the "good" dector will remain unchanged.
               Flux values (and stdev) for the other detectors will
               each be multiplied by a computed constant to adjust it to
               the good dector.  This computed constant is ratio between
               the weighted means in the overlap region.  This process
               will ripple through all detectors until they have all
               been corrected.

               The standard output of the LWS OLP - and to a certain extent
               the SWS - is sub-divided into scans each containing the
               data from individual detectors which have overlapping
               wavelength portions when the full range of the instrument
               is used.  Although the best effort has been made in OLP
               to ensure that the variation in response between detectors
               has been accounted for, there will inevitably be some
               residual discontinuity at the boundaries between detectors.
               This utility will allow the user to select a given detector
               as more trustworthy than the rest and normalise all detector
               data to that detector.  The input spectrum may or may not
               have been averaged across scans and/or MASKed or TIPPEXed
               before this operation.


 Comment
               If any stdev values are not positive then all flux
               values will be weighted equally but the stdev values
               will be adjusted properly by the multiplication factor.

               If any detector has no overlap area or has a mean
               value of 0.0, it will not be adjusted.

               This version does only multiplicative correction.
               Additive corrections are planned for version 2.
               Also, aligning by scan (rather than by detector)
               may be added.

 Examples

               In the following example, the output is returned in an AAR
               structure named AAR_SHIFTED. To normalize AAR_ORIG so that all
               the other detectors are normalized to detector 5:

                      stat = sap_shift (AAR_ORIG, AAR_SHIFTED, 5)

 Dependencies   CALLS: kwd_notset, sap_error, update_history
                CALLED FROM: IA, GUI

 Category      ISAP

 Filename      sap_shift.pro

 Author        R. Narron (IPAC)

 Version       1.0

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

               0.1  950906 --> R. Narron (IPAC)  Prototype
               0.2  951010 --> R. Narron (IPAC)  New AAR definition
               1.0  951027 --> R. Narron (IPAC)  New parameter checking
                                                 Fix det 0 bug

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