org.apache.commons.math.stat.inference
Class ChiSquareTestImpl

java.lang.Object
  extended by org.apache.commons.math.stat.inference.ChiSquareTestImpl
All Implemented Interfaces:
ChiSquareTest

public class ChiSquareTestImpl
extends java.lang.Object
implements ChiSquareTest

Implements Chi-Square test statistics defined in the ChiSquareTest interface.

Version:
$Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $

Field Summary
private  DistributionFactory distributionFactory
          Cached DistributionFactory used to create ChiSquaredDistribution instances
 
Constructor Summary
ChiSquareTestImpl()
          Construct a ChiSquareTestImpl
 
Method Summary
private  void checkArray(long[][] in)
          Checks to make sure that the input long[][] array is rectangular, has at least 2 rows and 2 columns, and has all non-negative entries, throwing IllegalArgumentException if any of these checks fail.
 double chiSquare(double[] expected, long[] observed)
          Computes the Chi-Square statistic comparing observed and expected freqeuncy counts.
 double chiSquare(long[][] counts)
          Computes the Chi-Square statistic associated with a chi-square test of independence based on the input counts array, viewed as a two-way table.
 double chiSquareTest(double[] expected, long[] observed)
          Returns the observed significance level, or p-value, associated with a Chi-square goodness of fit test comparing the observed frequency counts to those in the expected array.
 boolean chiSquareTest(double[] expected, long[] observed, double alpha)
          Performs a Chi-square goodness of fit test evaluating the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts, with significance level alpha.
 double chiSquareTest(long[][] counts)
          Returns the observed significance level, or p-value, associated with a chi-square test of independence based on the input counts array, viewed as a two-way table.
 boolean chiSquareTest(long[][] counts, double alpha)
          Performs a chi-square test of independence evaluating the null hypothesis that the classifications represented by the counts in the columns of the input 2-way table are independent of the rows, with significance level alpha.
protected  DistributionFactory getDistributionFactory()
          Gets a DistributionFactory to use in creating ChiSquaredDistribution instances.
private  boolean isNonNegative(long[] in)
          Returns true iff all entries of the input array are >= 0.
private  boolean isNonNegative(long[][] in)
          Returns true iff all entries of (all subarrays of) the input array are >= 0.
private  boolean isPositive(double[] in)
          Returns true iff all entries of the input array are > 0.
private  boolean isRectangular(long[][] in)
          Returns true iff input array is rectangular.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

distributionFactory

private DistributionFactory distributionFactory
Cached DistributionFactory used to create ChiSquaredDistribution instances

Constructor Detail

ChiSquareTestImpl

public ChiSquareTestImpl()
Construct a ChiSquareTestImpl

Method Detail

chiSquare

public double chiSquare(double[] expected,
                        long[] observed)
                 throws java.lang.IllegalArgumentException
Description copied from interface: ChiSquareTest
Computes the Chi-Square statistic comparing observed and expected freqeuncy counts.

This statistic can be used to perform a Chi-Square test evaluating the null hypothesis that the observed counts follow the expected distribution.

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquare in interface ChiSquareTest
Parameters:
observed - array of observed frequency counts
expected - array of expected frequency counts
Returns:
chi-square test statistic
Throws:
java.lang.IllegalArgumentException - if preconditions are not met or length is less than 2

chiSquareTest

public double chiSquareTest(double[] expected,
                            long[] observed)
                     throws java.lang.IllegalArgumentException,
                            MathException
Description copied from interface: ChiSquareTest
Returns the observed significance level, or p-value, associated with a Chi-square goodness of fit test comparing the observed frequency counts to those in the expected array.

The number returned is the smallest significance level at which one can reject the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts.

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquareTest in interface ChiSquareTest
Parameters:
observed - array of observed frequency counts
expected - array of exptected frequency counts
Returns:
p-value
Throws:
java.lang.IllegalArgumentException - if preconditions are not met
MathException - if an error occurs computing the p-value

chiSquareTest

public boolean chiSquareTest(double[] expected,
                             long[] observed,
                             double alpha)
                      throws java.lang.IllegalArgumentException,
                             MathException
Description copied from interface: ChiSquareTest
Performs a Chi-square goodness of fit test evaluating the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts, with significance level alpha. Returns true iff the null hypothesis can be rejected with 100 * (1 - alpha) percent confidence.

Example:
To test the hypothesis that observed follows expected at the 99% level, use

chiSquareTest(expected, observed, 0.01)

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquareTest in interface ChiSquareTest
Parameters:
observed - array of observed frequency counts
expected - array of exptected frequency counts
alpha - significance level of the test
Returns:
true iff null hypothesis can be rejected with confidence 1 - alpha
Throws:
java.lang.IllegalArgumentException - if preconditions are not met
MathException - if an error occurs performing the test

chiSquare

public double chiSquare(long[][] counts)
                 throws java.lang.IllegalArgumentException
Description copied from interface: ChiSquareTest
Computes the Chi-Square statistic associated with a chi-square test of independence based on the input counts array, viewed as a two-way table.

The rows of the 2-way table are count[0], ... , count[count.length - 1]

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquare in interface ChiSquareTest
Parameters:
counts - array representation of 2-way table
Returns:
chi-square test statistic
Throws:
java.lang.IllegalArgumentException - if preconditions are not met

chiSquareTest

public double chiSquareTest(long[][] counts)
                     throws java.lang.IllegalArgumentException,
                            MathException
Description copied from interface: ChiSquareTest
Returns the observed significance level, or p-value, associated with a chi-square test of independence based on the input counts array, viewed as a two-way table.

The rows of the 2-way table are count[0], ... , count[count.length - 1]

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquareTest in interface ChiSquareTest
Parameters:
counts - array representation of 2-way table
Returns:
p-value
Throws:
java.lang.IllegalArgumentException - if preconditions are not met
MathException - if an error occurs computing the p-value

chiSquareTest

public boolean chiSquareTest(long[][] counts,
                             double alpha)
                      throws java.lang.IllegalArgumentException,
                             MathException
Description copied from interface: ChiSquareTest
Performs a chi-square test of independence evaluating the null hypothesis that the classifications represented by the counts in the columns of the input 2-way table are independent of the rows, with significance level alpha. Returns true iff the null hypothesis can be rejected with 100 * (1 - alpha) percent confidence.

The rows of the 2-way table are count[0], ... , count[count.length - 1]

Example:
To test the null hypothesis that the counts in count[0], ... , count[count.length - 1] all correspond to the same underlying probability distribution at the 99% level, use

chiSquareTest(counts, 0.01)

Preconditions:

If any of the preconditions are not met, an IllegalArgumentException is thrown.

Specified by:
chiSquareTest in interface ChiSquareTest
Parameters:
counts - array representation of 2-way table
alpha - significance level of the test
Returns:
true iff null hypothesis can be rejected with confidence 1 - alpha
Throws:
java.lang.IllegalArgumentException - if preconditions are not met
MathException - if an error occurs performing the test

checkArray

private void checkArray(long[][] in)
                 throws java.lang.IllegalArgumentException
Checks to make sure that the input long[][] array is rectangular, has at least 2 rows and 2 columns, and has all non-negative entries, throwing IllegalArgumentException if any of these checks fail.

Parameters:
in - input 2-way table to check
Throws:
java.lang.IllegalArgumentException - if the array is not valid

getDistributionFactory

protected DistributionFactory getDistributionFactory()
Gets a DistributionFactory to use in creating ChiSquaredDistribution instances.

Returns:
a DistributionFactory

isRectangular

private boolean isRectangular(long[][] in)
Returns true iff input array is rectangular.

Parameters:
in - array to be tested
Returns:
true if the array is rectangular
Throws:
java.lang.NullPointerException - if input array is null
java.lang.ArrayIndexOutOfBoundsException - if input array is empty

isPositive

private boolean isPositive(double[] in)
Returns true iff all entries of the input array are > 0. Returns true if the array is non-null, but empty

Parameters:
in - array to be tested
Returns:
true if all entries of the array are positive
Throws:
java.lang.NullPointerException - if input array is null

isNonNegative

private boolean isNonNegative(long[] in)
Returns true iff all entries of the input array are >= 0. Returns true if the array is non-null, but empty

Parameters:
in - array to be tested
Returns:
true if all entries of the array are non-negative
Throws:
java.lang.NullPointerException - if input array is null

isNonNegative

private boolean isNonNegative(long[][] in)
Returns true iff all entries of (all subarrays of) the input array are >= 0. Returns true if the array is non-null, but empty

Parameters:
in - array to be tested
Returns:
true if all entries of the array are non-negative
Throws:
java.lang.NullPointerException - if input array is null