/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.math.stat.inference;
import org.apache.commons.math.MathException;
/**
* An interface for Chi-Square tests.
* This interface handles only known distributions. If the distribution is
* unknown and should be provided by a sample, then the {@link UnknownDistributionChiSquareTest
* UnknownDistributionChiSquareTest} extended interface should be used instead.
* @version $Revision: 811685 $ $Date: 2009-09-05 19:36:48 +0200 (sam. 05 sept. 2009) $
*/
public interface ChiSquareTest {
/**
* 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.
*
* @param observed array of observed frequency counts
* @param expected array of expected frequency counts
* @return chiSquare statistic
* @throws IllegalArgumentException if preconditions are not met
*/
double chiSquare(double[] expected, long[] observed)
throws IllegalArgumentException;
/**
* 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.
*
* @param observed array of observed frequency counts
* @param expected array of expected frequency counts
* @return p-value
* @throws IllegalArgumentException if preconditions are not met
* @throws MathException if an error occurs computing the p-value
*/
double chiSquareTest(double[] expected, long[] observed)
throws 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.
*
* @param observed array of observed frequency counts
* @param expected array of expected frequency counts
* @param alpha significance level of the test
* @return true iff null hypothesis can be rejected with confidence
* 1 - alpha
* @throws IllegalArgumentException if preconditions are not met
* @throws MathException if an error occurs performing the test
*/
boolean chiSquareTest(double[] expected, long[] observed, double alpha)
throws IllegalArgumentException, MathException;
/**
* 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.
*
* @param counts array representation of 2-way table
* @return chiSquare statistic
* @throws IllegalArgumentException if preconditions are not met
*/
double chiSquare(long[][] counts)
throws IllegalArgumentException;
/**
* 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.
*
* @param counts array representation of 2-way table
* @return p-value
* @throws IllegalArgumentException if preconditions are not met
* @throws MathException if an error occurs computing the p-value
*/
double chiSquareTest(long[][] counts)
throws IllegalArgumentException, MathException;
/**
* 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.
*
* @param counts array representation of 2-way table
* @param alpha significance level of the test
* @return true iff null hypothesis can be rejected with confidence
* 1 - alpha
* @throws IllegalArgumentException if preconditions are not met
* @throws MathException if an error occurs performing the test
*/
boolean chiSquareTest(long[][] counts, double alpha)
throws IllegalArgumentException, MathException;
}