----- file created by makedoc on: Fri May 31 15:22:23 2013

----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/respower.pro -----

  NAME:
 	RESPOWER
  PURPOSE:
 	to compute the resolving power E/DE from the dispersion in a plane
       (usually the exit slit plane).
  CATEGORY:
        SHADOW's utilities
  CALLING SEQUENCE:
 	respower,'myfile',col_E, col_D
  INPUTS:
 	myfile  name of the file with data (between quotes) 
                (it can also be a structure like idl_var)
       col_E:  the SHADOW column with the energy information: 
                   11: Energy in eV
                   19: Wavelength in A
       col_D:  the SHADOW column with the legth in the dispersion direction (1 or 3)
  KEYWORD PARAMETERS:
 		ERANGE=[emin,emax] range of the energy variable for the TOP plot
 		ZRANGE=[Zmin,Zmax]              Z
 		E2RANGE=[emin,emax] range of the energy variable for the BOTTOM plot
 		Z2RANGE=[Zmin,Zmax]              Z
               NBINS              number of bins for the histogram
 		HLIMIT             the normalized heigh at which the histogram 
                                  limits taken for calculating the resolving power. 
                                  Default: 0.1
 		TITLE='top_title' title to be written at the top
 		NOPLOT = When set, inhibits the graph.

  OUTPUTS:
 	a plot
  OPTIONAL OUTPUT PARAMETERS:
 	resolvingPower: Set this keyword to a named variable to receive the Resolving Power
       deltaEmin: Set this keyword to a named variable to receive the minimum DE 
                  (at zero exist slit opening)
       Pendent: Set this keyword to a named variable to receive P

                Note that for any exit slit aperture  DE = deltaE + DZ/P
  COMMON BLOCKS:
 	None.
  SIDE EFFECTS:
 	None.
  RESTRICTIONS:
 	None.
  PROCEDURE:
 	Compute the dispersion plot (Z vs DE, top graph) then calculate the dispersion
       band by 
         i) Removing the regression line (bottom: plot with regression removed)
        ii) Calculate Z histogram
       iii) Calculate the histogram limits at HLIMIT height (bottom plot), 
        iv) Plot these limits in the upper graphic to define the dispersion band,
         v) compute related parameters:
          The "pendent" P from the regression fit gives the disperion DZ/DE
          The "origin" is the Eo value at the upper boundary of the dispersion band
          The Resolving Power is  Eo/P 
          The "Delta" value is the DE corresponding to the histogram limits, or 
              equivalently, the DE at zero slit opening
       
          The energy bandwith at a given slit opening Z is DE= Delta+ Z/P

  MODIFICATION HISTORY:
 	by M. Sanchez del Rio. ESRF. Grenoble, around 1995
 	2013/03/18 srio@esrf.eu documented, extracted some parameters
 

