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

    java.lang.Object
      org.apache.commons.math.stat.inference.ChiSquareTestImpl

All Implemented Interfaces:
  ChiSquareTest, UnknownDistributionChiSquareTest

    public class ChiSquareTestImpl

extends java.lang.Object
implements UnknownDistributionChiSquareTest

Implements Chi-Square test statistics defined in the `UnknownDistributionChiSquareTest` interface.

Version:
  $Revision: 811833 $ $Date: 2009-09-06 12:27:50 -0400 (Sun, 06 Sep 2009) $

Field Summary
`private ChiSquaredDistribution` `distribution` Distribution used to compute inference statistics.

Constructor Summary
`ChiSquareTestImpl()` Construct a ChiSquareTestImpl
`ChiSquareTestImpl(ChiSquaredDistribution x)` Create a test instance using the given distribution for computing inference statistics.

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.
`private void` `checkNonNegative(long[] in)` Check all entries of the input array are >= 0.
`private void` `checkNonNegative(long[][] in)` Check all entries of the input array are >= 0.
`private void` `checkPositive(double[] in)` Check all entries of the input array are > 0.
`private void` `checkRectangular(long[][] in)` Throws IllegalArgumentException if the input array is not rectangular.
`double` `chiSquare(double[] expected, long[] observed)` Computes the Chi-Square statistic comparing `observed` and `expected` frequency 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` `chiSquareDataSetsComparison(long[] observed1, long[] observed2)` Computes a Chi-Square two sample test statistic comparing bin frequency counts in `observed1` and `observed2`.
`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`.
`double` `chiSquareTestDataSetsComparison(long[] observed1, long[] observed2)` Returns the observed significance level, or p-value, associated with a Chi-Square two sample test comparing bin frequency counts in `observed1` and `observed2`.
`boolean` `chiSquareTestDataSetsComparison(long[] observed1, long[] observed2, double alpha)` Performs a Chi-Square two sample test comparing two binned data sets.
`void` `setDistribution(ChiSquaredDistribution value)` Modify the distribution used to compute inference statistics.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### distribution

    private ChiSquaredDistribution distribution

  Distribution used to compute inference statistics.

Constructor Detail

### ChiSquareTestImpl

    public ChiSquareTestImpl()

  Construct a ChiSquareTestImpl

### ChiSquareTestImpl

    public ChiSquareTestImpl(ChiSquaredDistribution x)

  Create a test instance using the given distribution for computing inference statistics.

  Parameters:
    `x` - distribution used to compute inference statistics.
  Since:
    1.2

Method Detail

### chiSquare

    public double chiSquare(double[] expected,
                            long[] observed)
                     throws java.lang.IllegalArgumentException

  Computes the Chi-Square statistic comparing `observed` and `expected` frequency 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:

  - Expected counts must all be positive.
  - Observed counts must all be >= 0.
  - The observed and expected arrays must have the same length and their common length must be at least 2.

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

  Note: This implementation rescales the `expected` array if necessary to ensure that the sum of the expected and observed counts are equal.

  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

  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:

  - Expected counts must all be positive.
  - Observed counts must all be >= 0.
  - The observed and expected arrays must have the same length and their common length must be at least 2.

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

  Note: This implementation rescales the `expected` array if necessary to ensure that the sum of the expected and observed counts are equal.

  Specified by:
    `chiSquareTest` in interface `ChiSquareTest`
  Parameters:
    `observed` - array of observed frequency counts
    `expected` - array of expected 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

  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:

  - Expected counts must all be positive.
  - Observed counts must all be >= 0.
  - The observed and expected arrays must have the same length and their common length must be at least 2.
  - `0 < alpha < 0.5`

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

  Note: This implementation rescales the `expected` array if necessary to ensure that the sum of the expected and observed counts are equal.

  Specified by:
    `chiSquareTest` in interface `ChiSquareTest`
  Parameters:
    `observed` - array of observed frequency counts
    `expected` - array of expected 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:

  - All counts must be >= 0.
  - The count array must be rectangular (i.e. all count[i] subarrays must have the same length).
  - The 2-way table represented by `counts` must have at least 2 columns and at least 2 rows.

  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:

  - All counts must be >= 0.
  - The count array must be rectangular (i.e. all count[i] subarrays must have the same length).
  - The 2-way table represented by `counts` must have at least 2 columns and at least 2 rows.

  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:

  - All counts must be >= 0.
  - The count array must be rectangular (i.e. all count[i] subarrays must have the same length).
  - The 2-way table represented by `counts` must have at least 2 columns and at least 2 rows.

  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

### chiSquareDataSetsComparison

    public double chiSquareDataSetsComparison(long[] observed1,
                                              long[] observed2)
                                       throws java.lang.IllegalArgumentException

  Description copied from interface: `UnknownDistributionChiSquareTest`

  Computes a Chi-Square two sample test statistic comparing bin frequency counts in `observed1` and `observed2`. The sums of frequency counts in the two samples are not required to be the same. The formula used to compute the test statistic is

  `∑[(K * observed1[i] - observed2[i]/K)2 / (observed1[i] + observed2[i])]` where
  `K = &sqrt;[&sum(observed2 / ∑(observed1)]`

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

  Preconditions:

  - Observed counts must be non-negative.
  - Observed counts for a specific bin must not both be zero.
  - Observed counts for a specific sample must not all be 0.
  - The arrays `observed1` and `observed2` must have the same length and their common length must be at least 2.

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

  Specified by:
    `chiSquareDataSetsComparison` in interface `UnknownDistributionChiSquareTest`
  Parameters:
    `observed1` - array of observed frequency counts of the first data set
    `observed2` - array of observed frequency counts of the second data set
  Returns:
    chi-square test statistic
  Throws:
    `java.lang.IllegalArgumentException` - if preconditions are not met
  Since:
    1.2

### chiSquareTestDataSetsComparison

    public double chiSquareTestDataSetsComparison(long[] observed1,
                                                  long[] observed2)
                                           throws java.lang.IllegalArgumentException,
                                                  MathException

  Description copied from interface: `UnknownDistributionChiSquareTest`

  Returns the observed significance level, or p-value, associated with a Chi-Square two sample test comparing bin frequency counts in `observed1` and `observed2`.

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

  See `UnknownDistributionChiSquareTest.chiSquareDataSetsComparison(long[], long[])` for details on the formula used to compute the test statistic. The degrees of of freedom used to perform the test is one less than the common length of the input observed count arrays.

  Preconditions:
  - Observed counts must be non-negative.
  - Observed counts for a specific bin must not both be zero.
  - Observed counts for a specific sample must not all be 0.
  - The arrays `observed1` and `observed2` must have the same length and their common length must be at least 2.

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

  Specified by:
    `chiSquareTestDataSetsComparison` in interface `UnknownDistributionChiSquareTest`
  Parameters:
    `observed1` - array of observed frequency counts of the first data set
    `observed2` - array of observed frequency counts of the second data set
  Returns:
    p-value
  Throws:
    `java.lang.IllegalArgumentException` - if preconditions are not met
    `MathException` - if an error occurs computing the p-value
  Since:
    1.2

### chiSquareTestDataSetsComparison

    public boolean chiSquareTestDataSetsComparison(long[] observed1,
                                                   long[] observed2,
                                                   double alpha)
                                            throws java.lang.IllegalArgumentException,
                                                   MathException

  Description copied from interface: `UnknownDistributionChiSquareTest`

  Performs a Chi-Square two sample test comparing two binned data sets. The test evaluates the null hypothesis that the two lists of observed counts conform to the same frequency distribution, with significance level `alpha`. Returns true iff the null hypothesis can be rejected with 100 * (1 - alpha) percent confidence.

  See `UnknownDistributionChiSquareTest.chiSquareDataSetsComparison(long[], long[])` for details on the formula used to compute the Chisquare statistic used in the test. The degrees of of freedom used to perform the test is one less than the common length of the input observed count arrays.

  Preconditions:
  - Observed counts must be non-negative.
  - Observed counts for a specific bin must not both be zero.
  - Observed counts for a specific sample must not all be 0.
  - The arrays `observed1` and `observed2` must have the same length and their common length must be at least 2.
  - `0 < alpha < 0.5`

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

  Specified by:
    `chiSquareTestDataSetsComparison` in interface `UnknownDistributionChiSquareTest`
  Parameters:
    `observed1` - array of observed frequency counts of the first data set
    `observed2` - array of observed frequency counts of the second data set
    `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
  Since:
    1.2

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

### checkRectangular

    private void checkRectangular(long[][] in)

  Throws IllegalArgumentException if the input array is not rectangular.

  Parameters:
    `in` - array to be tested
  Throws:
    `java.lang.NullPointerException` - if input array is null
    `java.lang.IllegalArgumentException` - if input array is not rectangular

### checkPositive

    private void checkPositive(double[] in)
                        throws java.lang.IllegalArgumentException

  Check all entries of the input array are > 0.

  Parameters:
    `in` - array to be tested
  Throws:
    `java.lang.IllegalArgumentException` - if one entry is not positive

### checkNonNegative

    private void checkNonNegative(long[] in)
                           throws java.lang.IllegalArgumentException

  Check all entries of the input array are >= 0.

  Parameters:
    `in` - array to be tested
  Throws:
    `java.lang.IllegalArgumentException` - if one entry is negative

### checkNonNegative

    private void checkNonNegative(long[][] in)
                           throws java.lang.IllegalArgumentException

  Check all entries of the input array are >= 0.

  Parameters:
    `in` - array to be tested
  Throws:
    `java.lang.IllegalArgumentException` - if one entry is negative

### setDistribution

    public void setDistribution(ChiSquaredDistribution value)

  Modify the distribution used to compute inference statistics.

  Parameters:
    `value` - the new distribution
  Since:
    1.2

Copyright (c) 2003-2011 Apache Software Foundation