Identifier     avgsig    

 Purpose        Calculate the statistcal parameter of an array (mean, sigma)

 Synopsis       stat_struc = avgsig (xarr,[sarr],/disp)
                             

 Arguments      Name      I/O       Type           Description
                -----------------------------------------------------
                xarr      I    any except string   input array 
                sarr      I    any except string   input sigma array 

 Returns        structure stat_struc with tags .mean and .sigma


 Description    Calculate the mean and standard deviation, or uncertainty
                in the mean of the data points in the input array (xarr). 
                The following statistics are computed depending on the
                logic of the input parameters provided:

                1. Input data array without sigma array or dispersion keyword:
                   >stat_struc = avg_sig(x)
                    stat_struc.mean = sum(x_i)/n   
                           Unweighed sample mean of x is computed,
                           assuming equal uncertainties in the data points.
                           Equation (2-7) of Bevington.
                    stat_struc.sigma = s/sqrt(n), where 
                           s=sqrt{sum(x_i-mean)^2/(n-i)} is the sample
                           standard deviation of the data around their mean.
                           Uncertainty in the determination of the unweighted
                           sample mean of x is computed.
                           Equation (5-13) of Bevington.
  
                2. Input data array without sigma array, but with dispersion
                   keyword:
                   >stat_struc = avg_sig(x,/disp)
                    stat_struc.mean = sum(x_i)/n   
                           Unweighed sample mean of x is computed,
                           assuming equal uncertainties in the data points.
                           Equation (2-7) of Bevington.
                   stat_struc.sigma = s = sqrt{sum(x_i-mean)^2/(n-1)}
                           Sample standard deviation [dispersion] of the 
                           data around their mean is computed.
                           Equation (2-10) of Bevington.

                3. Input data array and weights, without dispersion keyword:
                   >stat_struc = avg_sig(x,sig)
                   stat_struc.mean = sum(x_i/sig_i^2)/sum(1./sig_i^2)
                           Weigthed mean is computed accounting for unequal 
                           uncertainties sig_i in the data points x_i.
                           Equation (5-14) of Bevington.
                   stat_struc.sigma = sqrt{sum(1./sig_i^2)}
                           Uncertainty in the weighted mean is computed, 
                           ignoring the dispersion [spread] of the data 
                           points around their mean.
                           Equation (5-15) of Bevington.

                4. Input data array and weights, with dispersion keyword:
                   >stat_struc = avg_sig(x,sig,/disp)
                   stat_struc.mean = sum(x_i/sig_i^2)/sum(1./sig_i^2)
                           Weigthed mean is computed accounting for unequal 
                           uncertainties sig_i in the data points x_i.
                           Equation (5-14) of Bevington.
                   stat_struc.sigma = sqrt{sum[(x_i-mean)^2/sig_i^2]
                                 /[(n-1)*sum(1./sig_i^2)]}
                           Uncertainty in the weighted mean is computed, 
                           accounting for the dispersion [spread] of the data 
                           points around their mean.
                           Last two equations on bottom of p. 73 of Bevington.

 Comment        See Bevington, P. R., 1969, Data Propagation and Error 
                Analysis for the Physical Sciences (McGraw-Hill).
               

 Example        stat_struc = avg_sig(flux)  OR
                stat_struc = avg_sig(flux, /disp) OR
                stat_struc = avg_sig(flux, stdev) OR
                stat_struc = avg_sig(flux, stdev, /disp) OR

 Dependencies   CALLS: acknowledge
                CALLED FROM: inter_pol

 Category       ISAP

 Filename       avgsig.pro 

 Author         I. R. Khan       

 Version        1.0

 History        Aug 25, 1995   1.0    ---> irk

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, California Institute of Technology.  ;
U.S. Government Sponsorship under NASA Contract NAS7-918 ;
is acknowledged.                                         ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;