Identifier     vel_prof

 Purpose        Convert a Spectrum (AAR) from wavelength to velocity space
                with respect to given (rest) wavelength(s).

 Synopsis       aar_out = vel_prof( AAR, stat [,ref_wave=ref_wave] [,z=z] 
                          [,v=v] [,plot=plot] [stamps=stamps] [,_extra=e])

 Arguments      Name      I/O  Type      Description
                -----------------------------------------------------
                AAR        I   struct    The input spectrum to be converted.
                stat       O   0 or 1    error status, o=ok, 1=fatal  
                ref_wave   I   int(arr)  The reference wavelength (rest
                                         wavelength if z is specified). For 
                                         each line in the AAR (identified by
                                         the line tag) a reference wavelength
                                         has to be given. If this keyword is 
                                         not set then the routine analyses the
                                         AAR, displays which lines in which 
                                         wavelength regions are present and
                                         asks the user for a ref wave for each
                                         line.
                z          I   float     The redshift of the source, i.e.
                                         (lambda-lambda_0)/lambda0.
                                         If specified the program 
                                         assumes ref_wave to be a rest 
                                         wavelength (lambda_0).
                v          I   float     c*z
                                         If specified the program 
                                         assumes ref_wave to be a rest 
                                         wavelength (lambda_0).
                plot       I   0 or 1    If set, the lines are plotted in
                                         velocity space.
                stamps     I   0 or 1    Same as /plot, but up to 6 lines are
                                         plotted into the same plot window
                                         (!p.multi = [0,2,3]).
                                         This can help to look for systematic
                                         deviations in the velocities.
                _extra     I             Any keyword(s) that is (/are) 
                                         accepted by IDLs PLOT routine.
                
                
 Returns        A copy of AAR but with wave of each line set to km/s units
                with respect to the given reference wavelengths.

 Description    If not keyword_set(ref_wave) then analyse the AAR, print out 
                the line numbers and their wavelength regions and ask the 
                user for reference values. If keyword_set(z) then transform
                ref_wave according to 
                       ref_wave = ref_wave*(1+z).
                Compute velocities for each line:
                       v = (wave/ref_wave - 1)*c.
                If keyword_set(plot or stamps) then plot immedialtely line
                by line in the respective plotmode.


 Comment        Needs a properly filled line tag in the AAR. At least for
                SWS AOT1s this condition is currently not fulfilled.
                Seems to be reasonable only for AOTs in single line scan
                mode, i.e if there is only one spectral line per scan. If more
                than one line is present in a scan, you can specify a ref 
                wave only
                for one of them. This is because the line numbering in the
                LINE tag of the AAR is associated with a scan and not with 
                real lines (which is only reasonable). 

                Currently, if ref_wave is not given, the user is interactively
                asked to enter the reference wavelengths. THIS IS NOT SUITABLE
                FOR THE GUI! 
                

 Example        IDL> aar_vel = vel_prof( AAR, stat, refwave=[17.035,28.219],
                               z=0.01, /ynozero, xstyle=1 )
                IDL> index1 = where(aar_vel.data.line eq 1)
                IDL> plot,aar_vel.data(index1).wave,aar_vel.data(index1).flux

                In this example an AAR containing two (H2) lines is converted
                according to the given rest wavelengths and redshift. In the
                subsequent plot the line profile of line 1 is plotted in 
                velocity space, i.e. the wave unit is km/s and the line should
                be centered at v = 0 km/s.

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

 Category       ISAP

 Filename       vel_prof.pro

 Author         E. Sturm (--> ES)

 Version        0.2

 History        0.1   15-02-96  ES     first draft of requirements
                0.2   19-02-96  ES     first version

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, Max-Planck-Institut fuer extraterrestrische Physik (MPE);
                    Garching, Germany                                       ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;