Indentifier   normal

 Purpose       To normalise a defined portion of an input spectrum to
               a constant value or to another spectrum.

 Synopsis    status = normal (struc_in, struc_out, wave1 , wave2 
             [, struc_ref=struc_ref] [, n_const=n_const] [, /nowgt]
             [, wave1_ref=wave1_ref] [, wave2_ref=wave2_ref] )


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

               struc_in  I    struct   Input structure (AAR)

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

               wave1     I    flt      Lower boundary of "defined portion"
                                       of the struc_in spectra.
                                       (same units as struc_in.wave)

               wave2     I    flt      Upper boundary of "defined portion"
                                       of the struc_in spectra.
                                       (same units as struc_in.wave)

               struc_ref I    struct   Optional spectrum to normalise to
                                        (wave, flux, and stder must be in
                                         same units as struc_in.)

               wave1_ref I    flt      Optional (defaults to wave1)
                                       Lower boundary of "defined portion"
                                       of the struc_ref spectra.
                                       (same units as struc_ref.wave)

               wave2_ref I    flt      Optional (defaults to wave2)
                                       Upper boundary of "defined portion"
                                       of the struc_ref spectra.
                                       (same units as struc_ref.wave)

               n_const   I    flt      Optional normalisation constant
                                       (same units as struc_in.wave)

               nowgt     I   int      When computing average value(s)
                                       don't weight by 1/(stdev^2)

               COMBINATIONS:

                        - exactly ONE of struc_ref or n_const must be specified

                        - wave1_ref and wave2_ref may only be specified
                           if struc_ref is specified


 Returns       0 if OK   1 if fatal error

 Description   A spectrum will be multiplied by a constant such that
               the mean within a specified wavelength range will
               be either (1) equal to a specified value or, (2) equal
               to the mean value of a wavelength range of a
               reference spectrum. Errors are correctly propagated
               (multiplied by the same scale factor).

 Comment       This version does only multiplicative correction.
               Additive corrections are planned for version 2.


 Examples

               In both of the following examples, the output is returned in
               an AAR structure named AAR_NORM

               To normalize AAR_ORIG so that the portion between 10 and 20 
               microns (if AAR_ORIG is in microns) has an average value of
               35.3, do the following:

                  stat =normal(AAR_ORIG, AAR_NORM, 10.0, 20.0, n_const=35.3)

               To normalize AAR_ORIG so that the portion between 10 and 20 
               microns (if AAR_ORIG is in microns) has the same average value
               as AAR_REF has in the same range, do the following:

                  stat=normal(AAR_ORIG, AAR_NORM, 10.0,20.0,struc_ref=AAR_REF)


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

 Category      ISAP

 Filename      normal.pro

 Author        R. Narron (IPAC)

 Version       1.1

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

               0.1  950831 --> R. Narron (IPAC)  Prototype
               0.2  951010 --> R. Narron (IPAC)  New AAR definition
               1.0  951027 --> R. Narron (IPAC)  New parameter checking
               1.1  951207 --> R. Narron  change chk_units call to sap_ckunits

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