## Name

MPFTEST

## 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 F value

## Major Topics

Curve and Surface Fitting, Statistics

## Calling Sequence

PROB = MPFTEST(F, DOF1, DOF2, [/SIGMA, /CLEVEL, /SLEVEL ])

## Description

The function MPFTEST() computes the probability for a value drawn

from the F-distribution to equal or exceed the given value of F.

This can be used for confidence testing of a measured value obeying

the F-distribution (i.e., for testing the ratio of variances, or

equivalently for the addition of parameters to a fitted model).

P_F(X > F; DOF1, DOF2) = 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.

For the ratio of variance test, the two variances, VAR1 and VAR2,

should be distributed according to the chi-squared distribution

with degrees of freedom DOF1 and DOF2 respectively. The F-value is

computed as:

F = (VAR1/DOF1) / (VAR2/DOF2)

and then the probability is computed as:

PROB = MPFTEST(F, DOF1, DOF2, ... )

For the test of additional parameters in least squares fitting, the

user should perform two separate fits, and have two chi-squared

values. One fit should be the "original" fit with no additional

parameters, and one fit should be the "new" fit with M additional

parameters.

CHI1 - chi-squared value for original fit

DOF1 - number of degrees of freedom of CHI1 (number of data

points minus number of original parameters)

CHI2 - chi-squared value for new fit

DOF2 - number of degrees of freedom of CHI2

Note that according to this formalism, the number of degrees of

freedom in the "new" fit, DOF2, should be less than the number of

degrees of freedom in the "original" fit, DOF1 (DOF2 < DOF1); and

also CHI2 < CHI1.

With the above definition, the F value is computed as:

F = ( (CHI1-CHI2)/(DOF1-DOF2) ) / (CHI2/DOF2)

where DOF1-DOF2 is equal to M, and then the F-test probability is

computed as:

PROB = MPFTEST(F, DOF1-DOF2, DOF2, ... )

Note that this formalism assumes that the addition of the M

parameters is a small peturbation to the overall fit. If the

additional parameters dramatically changes the character of the

model, then the first "ratio of variance" test is more appropriate,

where F = (CHI1/DOF1) / (CHI2/DOF2).

## Inputs

F - ratio of variances as defined above.

DOF1 - number of degrees of freedom in first variance component.

DOF2 - number of degrees of freedom in second variance component.

## 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.

## Example

chi1 = 62.3D & dof1 = 42d

chi2 = 54.6D & dof2 = 40d

f = ((chi1-chi2)/(dof1-dof2)) / (chi2/dof2)

print, mpftest(f, dof1-dof2, dof2)

This is a test for addition of parameters. The "original"

chi-squared value was 62.3 with 42 degrees of freedom, and the

"new" chi-squared value was 54.6 with 40 degrees of freedom.

These values reflect the addition of 2 parameters and the

reduction of the chi-squared value by 7.7. The significance of

this set of circumstances is 0.071464757.

## 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

Added documentation, 30 Dec 2001, CM

Documentation corrections (thanks W. Landsman), 17 Jan 2002, CM

Example docs were corrected (Thanks M. Perez-Torres), 17 Feb 2002,

CM

Example corrected again (sigh...), 13 Feb 2003, CM

Convert to IDL 5 array syntax (!), 16 Jul 2006, CM

Move STRICTARR compile option inside each function/procedure, 9 Oct 2006

Usage message with /CONTINUE, 23 Sep 2009, CM