----- file created by makedoc on: Thu Nov  5 15:14:56 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/histo1.pro -----

 NAME:
	HISTO1 
 PURPOSE:
	an IDL implementation of the HISTO1 SHADOW's utility
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:
	histo1, shadow_in, col, shadow_out, keyword_parameters
 INPUTS:
	shadow_in   IDL structure with SHADOW data
	col   column to analyze (see doc in PLOTXY for a column description)
 OPTIONAL INPUTS:
	shadow_out  name of the IDL-SHADOW structure where store the file
 KEYWORD PARAMETERS:
	XRANGE = [min,max], limits of the histogram. 
	YRANGE = [min,max], heigth limits of the histogram. 
	NBINS = number of bins (def = 25)
	NOLOST = consider losses
		0 all rays (default option)
		1 exclude losses 
		2 consider only losses 
	REF = include reflectivity
		0 no (default)
		1 yes (A**2 as weight=column 23)
               n (21<n<34, n=column to weight (see PLOTXY for col description))
	GAUSSFIT = makes a gaussian fit of the histo
		0  No (default)
		1  Gauss+2nd degree polynomial (using gauss_fit routine)
		2  Gaussian: using (fit_voigt(...,/Gaussian) routine)
		3  PseudoVoigt: using (fit_voigt() routine)
		4  Lorentzian: using (fit_voigt(...,/Lorentzian) routine)
       TITLE = top title
       XTITLE = title in X column
       YTITLE = title in Y column
	[XY]STYLE = Same effect as in plot. 
		Default: 1 if [XY]RANGE is set, otherwise 0.
	MULFAC = A multiplicative factor to change the X scales.
       OVER   = overplots the previous histogram when set to 1
       WRITE  = when set to 1 writes the histogram in the file HISTO1

		NOTE : the abscissas points correspond to the 
		starting position of each bin (as in IDL histogram()),
		and not to the central position of the bin. 

		IF WRITE=2, the starting position of each bin 
		is in the bin's center.
	CALFWHM = if set to 1 then calculates the fwhm of the histogram
	FWHM_VAL = fwhm_val stores the FWHM value of the histogram in
	          an IDL varianle
	FWHM_FIT = fwhm_fit stores the FWHM value of the gauss fit 
	           in an IDL varianle
	IDL_VAR = idl_var srores the histogram in an IDL variable
	SAVE = a named variable where to save the histogram (if
		defined as a single element) or to accumulate the 
		histogram in sucessive runs. (see note in /WRITE).
	CM = set this keyword to center the histogram abscissas at the
               CenterOfMass of the data.
	X0 = a numerical value to be deduced from the X array (useful 
		when one wants to plot vs. E-Eo, for example).
	PUBLISH = flag to supress graphic output not suitable for publication, 
		i.e. username, date, time, filepath, etc.
		When flag is present and non-zero, output is supressed.
       GROUP The parent id for the caller widget (used to positioning
               error and information windows).
       NSPLIT: an integer to be used for statistical calculations of 
               fwhm, etc. by splitting the rays in NSPLIT groups
       FWHM_MEAN: mean value of fwhm, when NSPLIT is used. 
       FWHM_ERROR: RMS error of the fwhm, when NSPLIT is used. 

	OUTPUTS:
	an histogram on the screen.
 OPTIONAL OUTPUT PARAMETERS:
	shadow_out  name of the IDL-SHADOW structure where store the file
 COMMON BLOCKS:
	Calls histogramw
 SIDE EFFECTS:
 	None.
 RESTRICTIONS:
 	None.
 KNOWN BUGS:
	It has been found that the routine (or idl) gives bad results
	when plotting vs col 11 using very small interval (very high
	resolution). A temporal solution of this problem is to use the X0
	keyword.
 PROCEDURE:
	Similar to SHADOW's original.
 EXAMPLES:
	1) Simplest run:
		histo1,'begin.dat',1
	2) Save variable:
		histoall = 1
		histo1,'begin.dat',1,xrange=[-1,1],save=histoall
		plotfile,histoall,psym=10 ; to check if it contains data
		histo1,'begin2.dat',1,xrange=[-1,1],save=histoall ;add
							; a new histogram
		(xrange must be defined to force histo1 to produce the
		same gridding for the X values)

 MODOFICATION HISTORY:
	M. Sanchez del Rio. ESRF. Grenoble May 1991
       11-12-91 MSR output for Sigma in fit option
       01-09-92 MSR  change input type.
       03-09-92 MSR  introduce new columns. Few changes
       02-10-92 MSR  added GETPHASE to correct phases for stokes parameters
       06-10-92 MSR  added YRANGE and WRITE OPTIONS
       19-04-93 MSR  changes GAUSSFIT by GAUSS_FIT
       14-05-93 MSR  allows using either gaussfit or gauss_fit
       29-07-93 MSR  adds CALFWHM,FWHM_VAL and FWHM_FIT
       13-06-95 MSR  used getshcol, and allows external ref array.
		      Use the histosh function.
	26-06-96 MSR Adds save option. Speeds-up printing of time, date...
	02-04-97 MSR Adds X0 keyword. Cosmetics.
	03-03-98 MSR Adds PUBLISH keyword. Adapts to xsh_histo1 interface.
	07-04-98 MSR uses column_name to display it. 
	13-06-01 MSR sets the minimum for the plot different from zero
		for the default case. Useful for negative values, like S3
	16-10-06 MSR changes fitting routines. Added lorentzian
	14-06-06 srio@esrf.eu adapted it to ne histogramw *some problems
		affecting a shift of one bin removed*  Added WRITE=2
	08-09-08 srio@esrf.eu added CM and MULFAC keywords.
	08-09-12 srio@esrf.eu added [XY]STYLE keywords.
	08-10-24 srio@esrf.eu bug fixed when save with different dimensions
	2009-01-12 srio@esrf.eu added NSPLIT and intensity info.
	2009-06-12 srio@esrf.eu documented NSPLIT etc. Fixed bug when Ref=0


