stat procs

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Dec 20 11:48:26 2005.


List of Routines


Routine Descriptions

CHAUVENET

[Next Routine] [List of Routines]
 NAME:
       CHAUVENET
     
 PURPOSE:
       Given the residuals of a fit, this routine returns the indices
       of points that pass Chauvenet's criterion.  You can also return
       the number of points that passed, the indices of the points
       that failed, the number of points that failed, and a byte mask
       where 1B represents a passing point and 0B represents a failing
       point.
     
 EXPLANATION:
       Chauvenet's criterion states that a datum should be discarded if 
       less than half an event is expected to be further from the mean of 
       the data set than the suspect datum.  You should only use this
       criterion if the data are normally distributed.  Many authorities
       believe Chauvenet's criterion should never be applied a second
       time.  Not me.
     
 CALLING SEQUENCE:
       RESULT = CHAUVENET(X [,NPASS][,REJECT=reject][,
                          NREJECTS=nrejects][,MASK=mask][,/ITERATE])
     
 INPUTS:
       residuals : The residuals of a fit to data.
     
 OUTPUTS:
       The indices of the data that passed Chauvenet's criterion.

 OPTIONAL OUTPUTS:
       NPASS : The number of data that passed Chauvenet's criterion.

 KEYWORDS:
       /ITERATE : Iterate until there are no data that fail
                  Chauvenet's criterion.

       REJECT : The indices of data that failed Chauvenet's criterion.

       NREJECTS: The number of data that failed Chauvenet's criterion.

       MASK : A byte mask which is set to 1B where a datum passed
              Chauvenet's criterion and 0B where a datum failed.

 RESTRICTIONS:
       Only works for IDL versions 5.4 and above!!!
       (Uses COMPLEMENT keyword for WHERE function.)

 PROCEDURES CALLED:
      INVERF 

 EXAMPLE:
       RESIDUALS is an array with the difference between DATA and
       a fit to these data.  Find the indices of 

       IDL> passed = chauvenet(RESIDUALS,NPASS,REJECT=failed)

       Plot the data points and highlight the data that failed:

       IDL> plot, DATA, ps=3
       IDL> oplot, DATA[failed], ps=4

 NOTES:
       See Taylor's Intro to Error Analysis pp 142-144 OR
       Bevington & Robinson's Data Reduction & Error Analysis for the
       Physical Sciences p 58.

       Any non-finite values are ignored... rather than throwing
       them out, the user should think about why they have non-
       finite values and deal with them on their own terms.

       If the data you are testing are not drawn from a Gaussian
       parent distribution, then you have no business using this
       routine!

 MODIFICATION HISTORY:
       Written by Tim Robishaw, Berkeley  Dec 13, 2001

(See /dzd2/heiles/idl/gen/stat/chauvenet.pro)


GAUSSDIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       GAUSSDIST
     
 PURPOSE:
       Creates Gaussian distribution(s) with the width, center and
       height as specified.  
     
 CALLING SEQUENCE:
       RESULT = GAUSSDIST(X, ZRO, CEN, WID, HGT)
     
 INPUTS:
       X : Vector of abscissa values.

       ZRO : The zero offset of the Gaussian distribution. A scalar.

       CEN : Array (or scalar) of centers of Gaussian components.

       WID : Array (or scalar) of widths of Gaussian components.

       HGT : Array (or scalar) of heights of Gaussian components.

 OUTPUTS:
       Returns the Gaussian distribution of the input parameters.

 EXAMPLE:
  Plot two Gaussians:
    IDL> plot, gaussdist(findgen(2000)/100., 0, [10,15], [6,3], [6,3])

 MODIFICATION HISTORY:
       Written Tim Robishaw, Berkeley 01 Dec 2001.

(See /dzd2/heiles/idl/gen/stat/gaussdist.pro)


GAUSSNOISE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       GAUSSNOISE
     
 PURPOSE:
       Creates pseudo-random Gaussian distribution with specified
       mean and standard deviation.
     
 CALLING SEQUENCE:
       RESULT = GAUSSNOISE(DIMENSION, MEAN, SIGMA)
     
 INPUTS:
       DIMENSION - Number of elements for desired noise distribution. 
       MEAN - Mean of desired distribution.
       SIGMA - Standard deviation of desired distribution.

 KEYWORDS:
       /DOUBLE - Return distribution in double-precision floating-point.

 OUTPUTS:
       Returns pseudo-random Gaussian distribution with specified
       mean and standard deviation.

 EXAMPLE:
    IDL> plot, gaussnoise(1024, 10.0, 0.07)

 MODIFICATION HISTORY:
   15 Jul 2003  Written by Tim Robishaw, Berkeley

(See /dzd2/heiles/idl/gen/stat/gaussnoise.pro)


INVERF -- INVERSE ERROR FUNCTION

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
INVERF -- inverse error function
     
 PURPOSE:
       Returns the inverse error function for a given probabality.
       
     
 CALLING SEQUENCE:
       RESULT = INVERF(X)
     
 INPUTS:
       X : Number representing the integrated Gaussian probability 
           distribution between -N standard deviations and +N standard
           deviations.
     
 OUTPUTS:
       Returns the inverse error function of X.  This is the number of
       standard deviations that the error function needs to be integrated 
       over in order to yield the value X.

 KEYWORDS:
       None.

 COMMON BLOCKS:
       None.

 RESTRICTIONS:
       The error function is normalized to unity, so it is meaningless
       to ask for the inverse error function of a value larger than
       one or less than zero.  If you do, the function will stop and 
       tell you to contemplate your mistake.

       To check behavior visually:
         IDL> x = dindgen(10001)/10000.
         IDL> plot, x, abs(x-errorf(inverf(x))), /ylog, yr=[1d-9,1d-1]
         IDL> oplot, !x.crange, 4.5d-4*[1,1], lines=1

       Hasting's approximation (see NOTES below) is accurate to
       4.5d-4, and we see this is indeed the case.

       Alternatively, check how large x can become before
       inverf(errorf(x)) fails, i.e. the difference between
       x and inverf(errorf(x)) becomes larger than 4.5d-4:

         IDL> x = dindgen(10001)/10000.*6
         IDL> plot, x, abs(x-inverf(errorf(x))), /ylog, yr=[1d-9,1d-1]
         IDL> oplot, !x.crange, 4.5d-4*[1,1], lines=1

       So, if x is double precision, inverf(errorf(x)) is accurate
       up to x=5.34.  If x is floating precision, it is accurate up to
       x=3.11.  This makes plenty of sense, since beyond this limit out in 
       the wings of the normal distribution, the error function is exactly 
       one to machine precision. So the inverse error function can't be
       expected to differentiate between the error function of 7 and the
       error function of 200!

 NOTES:
       Using notation from Abramowitz & Stegun, page 931, we see:

         erf(x) = 2*P(x*sqrt(2)) - 1
         P(x*sqrt(2)) = 1 - Q(x*sqrt(2))

       Given Q(x*sqrt(2))=p, we can use Hasting's approximation 
       for digital computers (Abramowitz & Stegun, page 933) to get:

         x*sqrt(2) = t - (c0+c1*t+c2*t^2)/(1+d1*t+d2*t^2+d3*t^3) + e(p)

       where |e(p)| < 4.5d-4 and the constants appear in the code below.

 MODIFICATION HISTORY:
       Written Tim Robishaw, Berkeley  22 Feb 2002
       Stole idea from Carl Heiles.
       Added machine precision considerations. TR 23 Feb 2002

(See /dzd2/heiles/idl/gen/stat/inverf.pro)


P_CHISQ -- CALCULATE THE CHI SQUARE PDF GIVEN CHISQ AND NU.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
p_chisq -- CALCULATE the CHI SQuare pdf GIVEN CHISQ AND NU.
CALCULATE CHI SQ PROB DIST GIVEN CHISQ AND NU.
CALLIING SEQUENCE:
	PCHISQ= P_CHIS1Q( CHISQ, NU)

INPUTS:
	CHISQ, the value of chisquared
	NU, the degrees of freedom

OUTPUTS: 
	P_CHISQ, the probability of finding chisq given nu.

COMMENTS:

	for nu le 30, uses the exact formula. however, factors of this
formula go to infinity for large nu, so we revert to a logarithmic
approximation for large nu.

(See /dzd2/heiles/idl/gen/stat/p_chisq.pro)


THETA_RANDOM -- GENERATE RANDOM NUMBERS DISTRIBUTED ACCORDING TO SIN THETA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
theta_random -- generate random numbers distributed according to sin theta.

PURPOSE: generate random numbers distributed according to sin theta.
CALLING SYNTAX:
	theta_random, nr, theta_random, seed=seed, pi_over2=pi_over2

INPUT:
	nr, nr of random theta's to generate.
KEYWORDS:
	seed--the usual
	pi_over2--restricts theta range to 0 --> pi/2 instead of 0 --> pi.
OUTPUT:
	theta_random, the set of random theta's.

(See /dzd2/heiles/idl/gen/stat/theta_random.pro)


WT_AVG

[Previous Routine] [List of Routines]
 NAME:
       WT_AVG

 PURPOSE:
       To take a simple weighted average of data.

 CALLING SEQUENCE:
       Result = WT_AVG(data, weight [, dimension] [, /SIGMA] [, /DOUBLE] [,
       WT_SIGMA=variable]

 INPUTS:
       data - an array of data.
       weight - an array of weights. If the /SIGMA keyword is set, these
                values are assumed to be the uncertainties in each datum.

 OPTIONAL INPUTS:
       dimension - the dimension over which to average.

 KEYWORD PARAMETERS:
       /SIGMA: set this keyword when inputing the uncertaintied in each 
               datum. The weight will then be set to 1/sigma^2.
       /DOUBLE: return the result in double precision.
       WT_SIGMA - set this keyword to a named variable that will contain
                  uncertainty of the weighted mean.

 COMMON BLOCKS:
       None.

 EXAMPLE:
       The example from Bevington:

       IDL> d = [fltarr(40)+1.022,fltarr(10)+1.018]
       IDL> s = [fltarr(40)+0.01,fltarr(10)+0.004]
       IDL> print, wt_avg(d,s,/SIGMA,WT_SIGMA=wt_sigma)
             1.01956
       IDL> print, wt_sigma
         0.000987730

 MODIFICATION HISTORY:
   17 Jun 2004  Written by Tim Robishaw, Berkeley

(See /dzd2/heiles/idl/gen/stat/wt_avg.pro)