Name

---

  MPCHITEST

Author

---

  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  craigm@lheamail.gsfc.nasa.gov
  UPDATED VERSIONs can be found on my WEB PAGE:
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

Purpose

---

  Compute the probability of a given chi-squared value

Major Topics

---

  Curve and Surface Fitting, Statistics

Calling Sequence

---

  PROB = MPCHITEST(CHI, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])

Description

---

  The function MPCHITEST() computes the probability for a value drawn
  from the chi-square distribution to equal or exceed the given value
  CHI. This can be used for confidence testing of a measured value
  obeying the chi-squared distribution.
    P_CHI(X > CHI; DOF) = PROB
  In specifying the returned probability level the user has three
  choices:
    * return the confidence level when the /CLEVEL keyword is passed;
      OR
    * return the significance level (i.e., 1 - confidence level) when
      the /SLEVEL keyword is passed (default); OR
    * return the "sigma" of the probability (i.e., compute the
      probability based on the normal distribution) when the /SIGMA
      keyword is passed.
  Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.

Inputs

---

  CHI - chi-squared value to be tested.
  DOF - scalar or vector number, giving the number of degrees of
        freedom in the chi-square distribution.

Returns

---

  Returns a scalar or vector of probabilities, as described above,
  and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.

Keyword Parameters

---

  SLEVEL - if set, then PROB describes the significance level
            (default).
  CLEVEL - if set, then PROB describes the confidence level.
  SIGMA - if set, then PROB is the number of "sigma" away from the
          mean in the normal distribution.

Examples

---

  print, mpchitest(1300d,1252d)
  Print the probability for a chi-squared value with 1252 degrees of
  freedom to exceed a value of 1300, as a confidence level.

References

---

  Algorithms taken from CEPHES special function library, by Stephen
  Moshier. (http://www.netlib.org/cephes/)

Modification History

---

  Completed, 1999, CM
  Documented, 16 Nov 2001, CM
  Reduced obtrusiveness of common block and math error handling, 18
    Nov 2001, CM
  Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
  Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
  Add usage message, 24 Nov 2006, CM
  Really add usage message, with /CONTINUE, 23 Sep 2009, CM