    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017    package org.apache.commons.math.stat.inference;
    018
    019    import org.apache.commons.math.MathException;
    020
    021    /**
    022     * An interface for Chi-Square tests for unknown distributions.
    023     * <p>Two samples tests are used when the distribution is unknown <i>a priori</i>
    024     * but provided by one sample. We compare the second sample against the first.</p>
    025     *
    026     * @version $Revision: 811685 $ $Date: 2009-09-05 19:36:48 +0200 (sam. 05 sept. 2009) $
    027     * @since 1.2
    028     */
    029    public interface UnknownDistributionChiSquareTest extends ChiSquareTest {
    030
    031        /**
    032         * <p>Computes a
    033         * <a href="http://www.itl.nist.gov/div898/software/dataplot/refman1/auxillar/chi2samp.htm">
    034         * Chi-Square two sample test statistic</a> comparing bin frequency counts
    035         * in <code>observed1</code> and <code>observed2</code>.  The
    036         * sums of frequency counts in the two samples are not required to be the
    037         * same.  The formula used to compute the test statistic is</p>
    038         * <code>
    039         * &sum;[(K * observed1[i] - observed2[i]/K)<sup>2</sup> / (observed1[i] + observed2[i])]
    040         * </code> where
    041         * <br/><code>K = &sqrt;[&sum(observed2 / &sum;(observed1)]</code>
    042         * </p>
    043         * <p>This statistic can be used to perform a Chi-Square test evaluating the null hypothesis that
    044         * both observed counts follow the same distribution.</p>
    045         * <p>
    046         * <strong>Preconditions</strong>: <ul>
    047         * <li>Observed counts must be non-negative.
    048         * </li>
    049         * <li>Observed counts for a specific bin must not both be zero.
    050         * </li>
    051         * <li>Observed counts for a specific sample must not all be 0.
    052         * </li>
    053         * <li>The arrays <code>observed1</code> and <code>observed2</code> must have the same length and
    054         * their common length must be at least 2.
    055         * </li></ul></p><p>
    056         * If any of the preconditions are not met, an
    057         * <code>IllegalArgumentException</code> is thrown.</p>
    058         *
    059         * @param observed1 array of observed frequency counts of the first data set
    060         * @param observed2 array of observed frequency counts of the second data set
    061         * @return chiSquare statistic
    062         * @throws IllegalArgumentException if preconditions are not met
    063         */
    064        double chiSquareDataSetsComparison(long[] observed1, long[] observed2)
    065            throws IllegalArgumentException;
    066
    067        /**
    068         * <p>Returns the <i>observed significance level</i>, or <a href=
    069         * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
    070         * p-value</a>, associated with a Chi-Square two sample test comparing
    071         * bin frequency counts in <code>observed1</code> and
    072         * <code>observed2</code>.
    073         * </p>
    074         * <p>The number returned is the smallest significance level at which one
    075         * can reject the null hypothesis that the observed counts conform to the
    076         * same distribution.
    077         * </p>
    078         * <p>See {@link #chiSquareDataSetsComparison(long[], long[])} for details
    079         * on the formula used to compute the test statistic. The degrees of
    080         * of freedom used to perform the test is one less than the common length
    081         * of the input observed count arrays.
    082         * </p>
    083         * <strong>Preconditions</strong>: <ul>
    084         * <li>Observed counts must be non-negative.
    085         * </li>
    086         * <li>Observed counts for a specific bin must not both be zero.
    087         * </li>
    088         * <li>Observed counts for a specific sample must not all be 0.
    089         * </li>
    090         * <li>The arrays <code>observed1</code> and <code>observed2</code> must
    091         * have the same length and
    092         * their common length must be at least 2.
    093         * </li></ul><p>
    094         * If any of the preconditions are not met, an
    095         * <code>IllegalArgumentException</code> is thrown.</p>
    096         *
    097         * @param observed1 array of observed frequency counts of the first data set
    098         * @param observed2 array of observed frequency counts of the second data set
    099         * @return p-value
    100         * @throws IllegalArgumentException if preconditions are not met
    101         * @throws MathException if an error occurs computing the p-value
    102         */
    103        double chiSquareTestDataSetsComparison(long[] observed1, long[] observed2)
    104          throws IllegalArgumentException, MathException;
    105
    106        /**
    107         * <p>Performs a Chi-Square two sample test comparing two binned data
    108         * sets. The test evaluates the null hypothesis that the two lists of
    109         * observed counts conform to the same frequency distribution, with
    110         * significance level <code>alpha</code>.  Returns true iff the null
    111         * hypothesis can be rejected with 100 * (1 - alpha) percent confidence.
    112         * </p>
    113         * <p>See {@link #chiSquareDataSetsComparison(long[], long[])} for
    114         * details on the formula used to compute the Chisquare statistic used
    115         * in the test. The degrees of of freedom used to perform the test is
    116         * one less than the common length of the input observed count arrays.
    117         * </p>
    118         * <strong>Preconditions</strong>: <ul>
    119         * <li>Observed counts must be non-negative.
    120         * </li>
    121         * <li>Observed counts for a specific bin must not both be zero.
    122         * </li>
    123         * <li>Observed counts for a specific sample must not all be 0.
    124         * </li>
    125         * <li>The arrays <code>observed1</code> and <code>observed2</code> must
    126         * have the same length and their common length must be at least 2.
    127         * </li>
    128         * <li> <code> 0 < alpha < 0.5 </code>
    129         * </li></ul><p>
    130         * If any of the preconditions are not met, an
    131         * <code>IllegalArgumentException</code> is thrown.</p>
    132         *
    133         * @param observed1 array of observed frequency counts of the first data set
    134         * @param observed2 array of observed frequency counts of the second data set
    135         * @param alpha significance level of the test
    136         * @return true iff null hypothesis can be rejected with confidence
    137         * 1 - alpha
    138         * @throws IllegalArgumentException if preconditions are not met
    139         * @throws MathException if an error occurs performing the test
    140         */
    141        boolean chiSquareTestDataSetsComparison(long[] observed1, long[] observed2, double alpha)
    142          throws IllegalArgumentException, MathException;
    143
    144    }