REBIN AND DEFINE SCALE: 

This routine allows a user to define a new wavelength grid, and to 
rebin the prime AAR onto this grid. Here we explain the various rebin options
and then give a detailed description of the rebinning algorithm. (We will refer
to (wavelength, flux), or (x, y) interchangable.)

Masked data: If there are any masked data, they will be ignored during the
rebinning but retained in the ouput AAR (If the user wishes, these can be
unmasked afterwards from the main GUI window.)

Rebinning data separately or together: The rebinning can be performed across
scans, detectors, lines, and scan-directions under the user's control. Scan,
detector, line, and scan-direction buttons will appear under the label "Rebin
Across...." in the top left corner of the gui window. Buttons will appear for
only those tags found in the prime AAR which have two or more values. (Thus for
some AARs, no buttons will appear.)

Depending on the AOT type, some of the scan, detector, line, and scan-direction
buttons will be preselected for the user's convenience.  The user may override
these selections.  When any of these buttons is selected, then the rebinning
will be performed across the data ignoring the corresponding tags. When the 
buttons are not selected, data will be rebinned separately.

An Example: Suppose the selected data has three scans for each of ten detectors
and only one value for the lines and scan-directions tags. Then only the scan
and detector buttons will appear and the user has four different ways to rebin
this data.  First, if both buttons are not turned on, then thirty rebinned
spectra will appear corresponding to each scan from each detector.  Second, if
only the scan button is selected, then the scans corresponding to each detector
is rebinned together such that ten spectra (one for each detector) are
produced. Third, if only the detector button is pressed, then for each scan,
all the detector data will be rebinned together; hence, only three spectra
results corresponding to each scan. Fianlly, when the both button are turned
on, then only one spectrum appears because all the scan and detector data are
rebinned together.


Defining the x-scale: This can be done in four different ways: 

Start/End/No. of Steps (log grid option available) :  equidistant 
with a given start and end wavelength and a given number 
of steps

Start/Step Width/No. of Steps:  equidistant with a given start 
wavelength, a step width (in microns) and a number of steps

Start/Resolution/No. of Steps:  consistent with a given 
resolution, a start wavelength and a number of steps

Start/Resolution/End:  consistent with a given resolution and a 
start and end wavelength

Resolution is defined as lambda/delta-lambda.

One or two lists of the wavelengths found in the input data are shown under the
define scale option so that the user may easily select (by clicking) a new
starting or stopping wavelength for the grid.

epsilon is used to eliminate multiple x-values as discussed below. 

   
Plotting: Finally, on the gui_rebin, a user has the advantage of viewing the 
data before and after rebin.  These two displays also come with all the 
flexibilities such as Set Plotstyle, Replot, Unzoom, Hard Copy, Freeze 
Ranges and etc.  In the end, the user has the choice to quit without 
saving rebin or to exit which delivers the result to the main gui.

The Algorithm: 

First, the reference 
x-array is created as defined by the user with one of the options stated 
above.  

Next, the "chk_multix" routine is performed.  This checks if any array
of x values contains multiple points at the same value.  Here, the "same"
value means value +- epsilon.  If so, this routine computes mean of the 
corresponding y values and stdev values at the mean of the duplicated 
points in data x-array and modify data x-array, y-array, and stdev-array 
accordingly.  In addition, this routine remembers the number of multiple 
points used for each of the modified y-array elements.  This information 
will be used later to rebin the data as the weight of each flux value.  
This is intended as a pre-binning operation to simplify interpolation and 
rebinning of a spectrum.  

Finally, the rebin is performed conserving flux via approximate 
trapezoidal intergration method.  This is outlined as follows.  

Let xarr and yarr be the wavelength and flux array of the prime AAR, and 
refarr the user-definded wavelength array.

1.  The middle point array is generated from the user-defined wavelength 
    scale according to
	xmid(i) = (refarr(i+1) + refarr(i)) / 2.

2.  Using all the xarr values ranging from the xmid(i-1) to xmid(i) and 
    the corresponding yarr values, this routine computes the new flux at 
    refarr(i) as the total integral via the simple trapezoidal rule.  
    That is,

Sum of ( (yarr(k) + yarr(k-1)) * (xarr(k) - xarr(k-1)) * w_av(k) / 2 )
--------------------------------------------------------------------------  
             Sum of ( w_av(k) )

    where w_av is (weight(k-1) + weight(k))/2

    for all k such that xmid(i-1) <= xarr(k) <= xmid(i).  Because of the 
    boundary, the first k in this range will not be applied to this formula.
    The weight(k) is the product of the {chk_multix} routine explained 
    above; it is a number equal to or greater than one, and it shows how 
    many data points were used in calculating this modified yarr(k).

3.  For the edges at the xmid(i-1) and xmid(i), there are two case.  
    First, if a data point coincidentally exists at either of these points, 
    then its corresponding flux is used to compute the integration.  If 
    not (which is the usual case), then the fluxes at these points are 
    linearly interpolated from the two nearest points to each side of them.

4.  For the first element, refarr(0), all the points at xarr within the 
    range, refarr(0) to xmid(0) are used.  Note that "(0)" designated the 
    first element in the array.  

5.  If there are no points inside a bin, the value for that bin is found 
    by linearly interpolating between the nearest two data point on either
    side of the bin: call these: (x_lo, y_lo), (x_hi, y_hi): 

                                   xarr(i) - x_lo
yarr(i) = y_lo + (y_hi - y_lo)   -----------------
                                    x_hi  - x_lo

6.  New "STDEV" values are computed as the error in the mean. Specifically:

                  sum { weight_i [F_i - M]^2 } / 
 STDEV= SQRT (   -----------------------------------    )
                sum { weight_i } (sum { weight_i } -1)

   Please refer to {sap_rebin} for more details.