NAME:
       A_CORRELATE

 PURPOSE:
       This function computes the autocorrelation Px(L) or autocovariance
       Rx(L) of a sample population X as a function of the lag (L).

 CATEGORY:
       Statistics.

 CALLING SEQUENCE:
       Result = A_correlate(X, Lag)

 INPUTS:
       X:    An n-element vector of type integer, float or double.

     LAG:    A scalar or n-element vector, in the interval [-(n-2), (n-2)],
             of type integer that specifies the absolute distance(s) between
             indexed elements of X.

 KEYWORD PARAMETERS:
       COVARIANCE:    If set to a non-zero value, the sample autocovariance
                      is computed.

       DOUBLE:        If set to a non-zero value, computations are done in
                      double precision arithmetic.

 EXAMPLE
       Define an n-element sample population.
         x = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57]

       Compute the autocorrelation of X for LAG = -3, 0, 1, 3, 4, 8
         lag = [-3, 0, 1, 3, 4, 8]
         result = a_correlate(x, lag)

       The result should be:
         [0.0146185, 1.00000, 0.810879, 0.0146185, -0.325279, -0.151684]

 PROCEDURE:
       See computational formula published in IDL manual.

 REFERENCE:
       INTRODUCTION TO STATISTICAL TIME SERIES
       Wayne A. Fuller
       ISBN 0-471-28715-6

 MODIFICATION HISTORY:
       Written by:  GGS, RSI, October 1994
       Modified:    GGS, RSI, August 1995
                    Corrected a condition which excluded the last term of the
                    time-series.
       Modified:    GGS, RSI, April 1996
                    Simplified AUTO_COV function. Added DOUBLE keyword.
                    Modified keyword checking and use of double precision.
   CT, RSI, September 2002: Rewrote for speed, per W. Biagiotti suggestions.
                    Now handles large vectors and complex inputs.
   CT, RSI, July 2003: Add note about using the mean over entire series.

 NAME:
	ADAPT_HIST_EQUAL

 PURPOSE:
	Perform Adaptive Histogram Equalization (AHE), a form of
	automatic image contrast enhancement, using a method described
	by Pizer, et. al. Adaptive Histogram Equalization involves
	applying contrast enhancement based on the local region
	surrounding each pixel.  That is, each pixel is mapped to an
	intensity proportional to its rank in its surrounding
	neighborhood.  This routine implements what Pizer calls
	"Contrast Limited Adaptive Histogram Equalization", or CLAHE.

 CATEGORY:
	Image processing.

 CALLING SEQUENCE:
	Result = ADAPT_HIST_EQUAL(Image [, NREGIONS=nregions] [, CLIP=clip])

 INPUTS:
	Image:  A 2-dimensional array of byte type.  Other types of
		images may be used, but they are converted to byte type before
		use.  For proper operation, be sure that the range of pixels
		lies between 0 and 255.

 KEYWORD PARAMETERS:
	CLIP:	If non-zero, clip the histogram to limit its slope to "CLIP",
		thereby limiting contrast.  For example, if CLIP is 3, the
		slope of the histogram is limited to 3. By default, the slope
		and/or contrast is not limited.  Noise overenhancement in
		nearly homogeneous regions is reduced by setting this
		parameter to values larger than 1.0.
	NREGIONS: Set this keyword to the size of the overlapped tiles, as a
		fraction of the largest	dimension of the image size.  The
		default is 12, which makes each tile 1/12 the size of the
		largest image dimension.
   TOP: 	Set this keyword to the maximum value to scale the output
		array. The default is 255.
   FCN:	The desired cumulative probability distribution
   		function in the form of a 256 element vector.  If
   		omitted, a linear ramp, which yields equal probability
   		bins results.  This function is later normalized, so
   		its magnitude doesn't matter.  It should be
   		monotonically increasing. 

 OUTPUTS:
	The result of the function is a byte image with the same
	dimensions as the input parameter.

 CALLS: ***
	AHMHISTOGRAM
 RESTRICTIONS:
	Works only on byte images.

 PROCEDURE:
	The procedure described by Pizer, et.al., "Adaptive Histogram
	Equalization and Its Variations", Computer Vision, Graphics,
	and Image Processing, 39:355-368, is followed.  This method has
	the advantages of being automatic, reproducible, locally
	adaptive, and usually produces superior images when compared
	with interactive contrast enhancement.

	The image is split into overlapping regions, each of size
	MaxDimension / NREGIONS.  The distribution histogram for each
	region is computed.  Then, for each pixel, its histogram
	equalized value is computed from the four overlapping regions
	that cover the pixel, normalized for the pixel's distance from
	each region's center.

 EXAMPLE:
	A = Read_Tiff('xyz.tif') ; Read an image
	TVSCL, Adapt_Hist_Equal(A)   ;Contrast enhance and display.

  To perform adaptive histogram "equalization", with a logarithmic
  cumulative distribution (i.e. more pixels with lower values):
       y = alog(findgen(256)+1)   ;a log shaped curve
       TVSCL, Adapt_Hist_Equal(A, FCN = y)

  The following example does adaptive histogram "equalization", with
  a gaussian probability (not cumulative) distribution.  This results
  in most of the pixels having an intensity near the midrange:
	x = findgen(256)/255.	   ;Ramp from 0 to 1.
	y=exp(-((x-.5)/.2)^2)      ;Gaussian centered at middle, full
				   ;width at 1/2 max ~ 0.4
		;Form cumulative distribution, transform and display:
       TVSCL, Adapt_Hist_Equal(A, FCN = TOTAL(y, /CUMULATIVE))

 MODIFICATION HISTORY:
	DMS, RSI	July, 1999.

 NAME:
	AMOEBA

 PURPOSE:
	Multidimensional minimization of a function FUNC(X), where
	X is an N-dimensional vector, using the downhill simplex
	method of Nelder and Mead, 1965, Computer Journal, Vol 7, pp 308-313.

	This routine is based on the AMOEBA routine, Numerical
	Recipes in C: The Art of Scientific Computing (Second Edition), Page
	411, and is used by permission.

 CATEGORY:
	Function minimization/maximization. Simplex method.

 CALLING SEQUENCE:
	Result = AMOEBA(Ftol, ....)
 INPUTS:
    FTOL:  the fractional tolerance to be achieved in the function
	value.  e.g. the fractional decrease in the function value in the
	terminating step.  This should never be less than the
	machine's single or double precision.
 KEYWORD PARAMETERS:
    FUNCTION_NAME: a string containing the name of the function to
	be minimized.  If omitted, the function FUNC is minimized.
	This function must accept an Ndim vector as its only parameter and
	return a scalar single or double precision floating point value as its
	result. 
    FUNCTION_VALUE: (output) on exit, an Ndim+1 element vector
	containing the function values at the simplex points.  The first
	element contains the function minimum. 
    NCALLS: (output) the of times the function was evaluated. 
    NMAX: the maximum number of function evaluations allowed
	before terminating.  Default = 5000.
    P0: Initial starting point, an Ndim element vector.  The starting
	point must be specified using either the keyword SIMPLEX, or P0 and
	SCALE.  P0 may be either single or double precision floating.
	For example, in a 3-dimensional problem, if the initial guess
	is the point [0,0,0], and it is known that the function's
	minimum value occurs in the interval: -10 <
	X(0) < 10, -100 < X(1) < 100, -200 < X(2) < 200, specify: P0=[0,0,0],
	SCALE=[10, 100, 200]. 
    SCALE: a scalar or Ndim element vector contaiing the problem's
	characteristic length scale for each dimension.
	SCALE is used with P0 to form an initial (Ndim+1) point simplex.
	If all dimensions have the same	scale, specify a scalar.
    SIMPLEX: (output and/or optional input) On input, if P0 and SCALE
	are not set, SIMPLEX contains the Ndim+1 vertices, each of
	Ndim elements, of starting simplex, in either single or double
	precision floating point, in an (Ndim, Ndim+1) array. On output,
	SIMPLEX contains the simplex, of dimensions (Ndim, Ndim+1), enclosing
	the function minimum.  The first point, Simplex(*,0), corresponds to
	the function's minimum.

 OUTPUTS:
   Result: If the minimum is found, an Ndim vector, corresponding to
	the Function's minimum value is returned.  If a function minimum
	within the given tolerance, is NOT found in the given number of
	evaluations, a scalar value of -1 is returned.

 CALLS: ***
	AMOTRY
 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	None.

 PROCEDURE:
	This procedure implements the Simplex method, described in
	Numerical Recipes, Section 10.4.  See also the POWELL procedure.

	Advantages:  requires only function evaluations, not
	derivatives, may be more reliable than the POWELL method.
	Disadvantages: not as efficient as Powell's method, and usually
	requires more function evaluations.

	Results are performed in the mode (single or double precision)
	returned by the user-supplied function.  The mode of the inputs P0,
	SCALE, or SIMPLEX, should match that returned by the function. The
	mode of the input vector supplied to the user-written function, is
	determined by P0, SCALE, or SIMPLEX.

 EXAMPLE:
	Use Amoeba to find the slope and intercept of a straight line fitting
	a given set of points minimizing the maximum error:

	The function to be minimized returns the maximum error,
	given p(0) = intercept, and p(1) = slope:
 FUNCTION FUNC, p
 COMMON FUNC_XY, x, y
 RETURN, MAX(ABS(y - (p(0) + p(1) * x)))
 END

	Put the data points into a common block so they are accessible to the
	function: 
 COMMON FUNC_XY, x, y
	Define the data points:
   x = findgen(17)*5
   y = [ 12.0,  24.3,  39.6,  51.0,  66.5,  78.4,  92.7, 107.8, 120.0, $
        135.5, 147.5, 161.0, 175.4, 187.4, 202.5, 215.4, 229.9]

	Call the function.  Fractional tolerance = 1 part in 10^5, 
	Initial guess = [0,0], and the minimum should be found within
	a distance of 100 of that point: 
   r = AMOEBA(1.0e-5, SCALE=1.0e2, P0 = [0, 0], FUNCTION_VALUE=fval)

	Check for convergence:
   if n_elements(r) eq 1 then message,'AMOEBA failed to converge'
	Print results.
   print, 'Intercept, Slope:', r, 'Function value (max error): ', fval(0)
Intercept, Slope:      11.4100      2.72800
Function value:       1.33000

 MODIFICATION HISTORY:
	DMS, May, 1996.	Written.

 NAME:
	ANNOTATE

 PURPOSE:
	This procedure is a general purpose drawing program/widget to
	annotate displays. Drawing objects include text, lines, arrows,
	polygons, rectangles, circles, and ellipses.

 CATEGORY:
	Widgets.  Will also work with plain windows.

 CALLING SEQUENCE:
	ANNOTATE

 INPUTS:
	No required inputs.

 KEYWORD PARAMETERS:
	COLOR_INDICES:	an array of color indices from which the user
			can choose colors. For example, to allow the user
			to choose 10 colors, spread evenly over the
			available indices, set the keyword as folows:
			COLOR_INDICES = INDGEN(10) * (!D.TABLE_SIZE-1) / 9
	DRAWABLE:	the widget ID of the draw widget for the annotations.
			This is mutually exclusive with WINDOW.
	LOAD_FILE:	the name of an annotation format file to load after
			initialization.
	TEK_COLORS:	if set, the Tektronix color table is loaded
			starting at color index TEK_COLORS(0), with
			TEK_COLORS(1) color indices. The Tektronix color
			table contains up to 32 distinct colors suitable
			for graphics.
	WINDOW:		the window index number of the window to receive the
			annotations.

 OUTPUTS:
	This procedure has no explicit outputs. Menu choices exist to
	write TIFF, PNG, or PostScript bitmap files. Encapsulated
	or standalone PostScript files may also be created.

 CALLS: ***
	ANNOTATE_EVENT, ANNOTATE_PS, ANN_ADD_OBJECT, ANN_B_BUTTON, ANN_CLOSEST
	ANN_CLOSEST_OBJ, ANN_DRAW_EVENT, ANN_DRAW_OBJECT, ANN_GET_NUM, ANN_GET_NUM_EVENT
	ANN_LOAD_OBJ, ANN_MAKE_DRAW_BUTTON, ANN_MOVE_RESIZE, ANN_REFRESH_LIST
	ANN_RESET_MODE, ANN_SET_CONTROLS, ANN_XFER_FILE, ARROW, CW_BGROUP, CW_CLR_INDEX
	CW_CONFIRM, CW_CONF_EVENT, CW_PDMENU, FILEPATH, REVERSE, SPLINE_P, TEK_COLOR
	XDISPLAYFILE, XMANAGER, XMGR_FAKE
 SIDE EFFECTS:
	Annotations are made in the designated window or draw widget.

 RESTRICTIONS:
	This is a simple drawing program.

 PROCEDURE:
	If neither TEK_COLORS or COLOR_INDICES are specified, the default
	is to load 10 colors, evenly distributed over those available.

	If neither WINDOW or DRAWABLE are specified, the current window
	is used.

 EXAMPLE:
	TVSCL, HANNING(300,200)	;Output an image in the current window
	ANNOTATE		;Annotate it

 MODIFICATION HISTORY:
	DMS, RSI, July, 1993.  Original version.
   CT, RSI, August 2003: Remove EXECUTE to allow use in
        IDL Virtual Machine. No functional or UI changes.

 NAME:
   ARRAY_INDICES

 PURPOSE:
   Given an input array, this function converts one-dimensional
   subscripts back into the corresponding multi-dimensional subscripts.


 CALLING SEQUENCE:
   Result = ARRAY_INDICES(Array, Index)


 RETURN VALUE:
   If Index is a scalar, then the Result will be a vector containing
   the M multi-dimensional subscripts. If Index is a vector containing
   N elements, then the Result will be a (M x N) array, with each row
   containing the multi-dimensional subscripts corresponding to that Index.


 INPUTS:
   Array: An array of any type, whose dimensions should be used in
       converting the subscripts. If DIMENSIONS is set then Array
       should be a vector containing the dimensions.

   Index: A scalar or vector containing the subscript(s) to be converted.


 KEYWORD PARAMETERS:
   DIMENSIONS: If this keyword is set, then Array is assumed to be
       a vector containing the dimensions.
   Tip: This keyword is useful when you don't have the actual Array,
       and want to avoid allocating the array just to find the indices.


 CALLED BY:
	H5_BROWSER
 EXAMPLE:
   Simple example.
       seed = 111
       array = RANDOMU(seed, 10, 10)
       mx = MAX(array, location)
       ind = ARRAY_INDICES(array, location)
       print, ind, array[ind[0],ind[1]], $
           format = '(%"Value at [%d, %d] is %f")'

   Example using DIMENSIONS.
   This will give the same results as the first example.
       dims = SIZE(array, /DIMENSIONS)
       ind = ARRAY_INDICES(dims, location, /DIMENSIONS)


 MODIFICATION HISTORY:
   Written by:  CT, RSI, October 2002
   Modified: CT, RSI, July 2004: Added DIMENSIONS keyword.

 NAME:				ARROW
 PURPOSE:	Draw a vector(s) with an arrow head
 CATEGORY:	Graphics
 CALLING SEQUENCE:
	ARROW, x0, y0, x1, y1
 INPUTS:
	(x0, y0) = coordinates of beginning of vector(s).  May be arrays
		or scalars. Coordinates are in DEVICE coordinates
		unless otherwise specified.
	(x1, y1) = coordinates of endpoint (head) of vector.
		x0, y0, x1, y1 must all have the same number of elements.
 KEYWORD PARAMETERS:
	DATA - if set, implies that coordinates are in data coords.
	NORMALIZED - if set, coordinates are specified in normalized coords.
	HSIZE = size of arrowhead.  Default = 1/64th the width of the device,
		(!D.X_SIZE / 64.).
		If the size is positive, it is assumed to be in device
		coordinate units.  If it is NEGATIVE, then the head length
		is set to the vector length * abs(hsize), giving heads
		proportional in size to the bodies.  The size is defined as
		the length of each of the lines (separated by 60 degrees)
		that make the head.
	COLOR = drawing color.  Default = highest color index.
	HTHICK = thickness of heads.  Default = 1.0.
	SOLID = if set, make a solid arrow, using polygon fills, looks better
		for thick arrows.
	THICK = thickness of body.    Default = 1.0.

 OUTPUTS:
	No explicit outputs.
 CALLED BY:
	ANNOTATE
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
	Straightforward.
	Examples:
  		Draw an arrow from (100,150) to (300,350) in DEVICE units.
	ARROW, 100, 150,  300, 350

		Draw a sine wave with arrows from the line Y=0 to
		sin(x/4).
	X = FINDGEN(50)
	Y = SIN(x/4)		;Make sin wave
	PLOT, X, Y
	ARROW, X, REPLICATE(0,50), X, Y, /DATA
 MODIFICATION HISTORY:
	DMS, Feb, 1992.
	DMS, Sept, 1992.  Added /SOLID.

 NAME:
       ASCII_TEMPLATE

 PURPOSE:
       Generate a template that defines an ASCII file format.

 CATEGORY:
       Input/Output.

 CALLING SEQUENCE:
       template = ASCII_TEMPLATE( [file] )

 INPUTS:
       file              - Name of file to base the template on.
                           Default = use DIALOG_PICKFILE to get the file.

 INPUT KEYWORD PARAMETERS:
       browse_lines      - Number of lines to read in at a time via the
                           GUI's browse button.  Default = 50.

 OUTPUT KEYWORD PARAMETERS:
       cancel            - Boolean indicating if the user canceled
                           out of the interface (1B = canceled).

 OUTPUTS:
       The function returns a template (structure) defining ASCII files
       of the input file's format.  Such templates may be used as inputs
       to function READ_ASCII.  (0 is returned if the user canceled.)

 CALLS: ***
	AT_1_EVENT, AT_2_EVENT, AT_3_EVENT, AT_BUILD_TEMPL, AT_BUILD_TEMPLATE
	AT_CHECK_FILE, AT_DEFAULT_DELIMIT, AT_DELETE_TEMPLATE, AT_DISPLAY_TEXT
	AT_GET_LINES, AT_LIST_TO_STR, AT_NUM_FIELDS, AT_REMOVE_TABS, AT_RESIZE_TABLE
	AT_SAMPLE_RECORD, AT_SET_LIST, AT_SET_STATE, AT_STR_TO_LIST, AT_STR_TO_VAL
	AT_UPDATE, AT_WHICH_FIELD, AT_WIDGET, AT_WIDGET_CLEANUP, AT_WIDGET_EVENT
	QUERY_ASCII, XMANAGER
 CALLED BY:
	IDLitUIAsciiTemplate, IMPORT_ASCII
 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       None.

 RESTRICTIONS:
       See DESCRIPTION.

 DESCRIPTION:
       This routine presents a graphical user interface (GUI) that assists
       the user in defining a template.

       ASCII files handled by this routine consist of an optional header
       of a fixed number of lines, followed by columnar data.  Files may
       also contain comments, which exist between a user-specified comment
       string and the corresponding end-of-line.

       One or more rows of data constitute a "record."  Each data element
       within a record is considered to be in a different column, or "field."
       Adjacent fields may be "grouped" into multi-column fields.
       The data in one field must be of, or promotable to, a single
       type (e.g., FLOAT).

 EXAMPLES:
       ; Generating a template to be used later, maybe on a set of files.
       template = ASCII_TEMPLATE()

       ; Same as above, but immediately specifying which file to use.
       template = ASCII_TEMPLATE(file)

       ; Same as above, but returning flag if the user canceled.
       template = ASCII_TEMPLATE(file, CANCEL=cancel)

       ; Generating and using a template in place for reading data.
       data = READ_ASCII(file, TEMPLATE=ASCII_TEMPLATE(file))

 DEVELOPMENT NOTES:
       - see ???,!!!,xxx in the code
       - errors preserving state when switch pages with 'back/next'
       - make NaN default missing value as in reader ?

 MODIFICATION HISTORY:
       AL & RPM, 8/96 - Written.