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 * ∑[(K * observed1[i] - observed2[i]/K)<sup>2</sup> / (observed1[i] + observed2[i])]
040 * </code> where
041 * <br/><code>K = &sqrt;[&sum(observed2 / ∑(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 }