Identifier   spect_form

 Purpose      convert the flux data in an aar to new units

 Synopsis     outaar = spect_form(inaar,unit,inunit=inunit,nostdev=nostdev
                       [,stat=stat]) 

 Arguments    Name   I/O  Type:     Description:
              -------------------------------------------------------------
              inaar   I   AAR       structure with input flux
              unit    I   string    output flux unit 
                                    (e.g. 'jy', 'w/cm^2/um') 
              inunit  I   strarr(2) optional input units: If there is no
                                    specification of the input units in the
                                    header of inaar, the default units 'um'
                                    and 'jy' are normally assumed. Inunit 
                                    will overwrite this default values.
                                    The order is (wave,flux)
              nostdev I   switch    if set, standard deviations of flux are
                                    NOT converted (e.g. if the errors are not
                                    known)
              stat   I/O  int       error status, 0 if ok, 1 if fatal

 Returns      aar with flux and (optional) stdev data converted to new units
 
 Description  Routine reads the input flux density unit from inaar header.
              If absent from header, the default unit 'jy' (Jansky) is used.
              The desired output flux unit is specified by giving an
              ASCII string. 
              Checks whether input/output units are one of the allowed set.
              The flux unit can be one of the following:
              ['jy', 'w/cm^2/um', 'w/m^2/um', 'w/cm^2/hz',
               'erg/s/cm^2/um', 'erg/s/m^2/um', 'erg/s/cm^2/hz'].
              An additional '/sr' (indicating surface brightness) may be 
              appended to all these units.
              The routine looks up the correct conversion from input to
              output units from a matrix of short conversion algorithms and
              converts the data to the desired units.
              The actual conversion may depend on the wavelength units
              (e.g. when going from jy to w/cm^2/um).
              The new units are written into the FITS header keyword of the
              output aar. 

 Comment      If a new flux unit is to be added, then the sections 'define 
              valid values for flux units' and 'define the conversion factors'
              have to be modified.
              If a new wavelength unit is to be added, then the section
              'prepare mixed cases' (item 1), 3) and possibly 5a)) is to
              be modified. 
              'microns' is treated as 'um'

 Example      outarr = spect_form(saar.header,'w/cm^2/um')
              converts the flux scale from the input unit (e.g. Jy) to
              W/cm^2/um.

 Dependencies  CALLS:  get_hdrkey, sap_error, update_history, write_hdrkey
               CALLED FROM: GUI, IA

 Category     ISAP

 Filename     spect_form.pro
 
 Author       E. Sturm (ES)

 Version      1.3

 History      definition of requirements - 27.7.95  D. Rigopoulou/E.Wieprecht
              0.1  6-Oct-95    ES  first version, based on routines from
                                   Iffat Khan (IPAC)
              1.0  30-11-95    ES  V1 delivery
              1.1  04-01-96    ES  flux unit now also written to TUNIT3
                                   (stdev). New call to write_fits_key
                   29-01-96    ES  replaced read_fits_key with get_hdrkey,
                                   write_fits_key with write_hdrkey
                   20-02-96    ES  changed conversion factor for mixed cases
                                   from 10^-12 to 10^-16; added second index
                                   to convin and convout computation in 5b).
              1.2  09-07-96    ES  stat added
              1.3  26-07-96    ES  treat 'microns' (LWS) as 'um'
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, Max-Planck-Institut fuer extraterrestrische Physik (MPE);
                    Garching, Germany                                       ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;