1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.math.stat.inference;
18
19 import org.apache.commons.math.MathException;
20
21 /**
22 * An interface for Chi-Square tests for unknown distributions.
23 * <p>Two samples tests are used when the distribution is unknown <i>a priori</i>
24 * but provided by one sample. We compare the second sample against the first.</p>
25 *
26 * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
27 * @since 1.2
28 */
29 public interface UnknownDistributionChiSquareTest extends ChiSquareTest {
30
31 /**
32 * <p>Computes a
33 * <a href="http://www.itl.nist.gov/div898/software/dataplot/refman1/auxillar/chi2samp.htm">
34 * Chi-Square two sample test statistic</a> comparing bin frequency counts
35 * in <code>observed1</code> and <code>observed2</code>. The
36 * sums of frequency counts in the two samples are not required to be the
37 * same. The formula used to compute the test statistic is</p>
38 * <code>
39 * ∑[(K * observed1[i] - observed2[i]/K)<sup>2</sup> / (observed1[i] + observed2[i])]
40 * </code> where
41 * <br/><code>K = &sqrt;[&sum(observed2 / ∑(observed1)]</code>
42 * </p>
43 * <p>This statistic can be used to perform a Chi-Square test evaluating the null hypothesis that
44 * both observed counts follow the same distribution.</p>
45 * <p>
46 * <strong>Preconditions</strong>: <ul>
47 * <li>Observed counts must be non-negative.
48 * </li>
49 * <li>Observed counts for a specific bin must not both be zero.
50 * </li>
51 * <li>Observed counts for a specific sample must not all be 0.
52 * </li>
53 * <li>The arrays <code>observed1</code> and <code>observed2</code> must have the same length and
54 * their common length must be at least 2.
55 * </li></ul></p><p>
56 * If any of the preconditions are not met, an
57 * <code>IllegalArgumentException</code> is thrown.</p>
58 *
59 * @param observed1 array of observed frequency counts of the first data set
60 * @param observed2 array of observed frequency counts of the second data set
61 * @return chiSquare statistic
62 * @throws IllegalArgumentException if preconditions are not met
63 */
64 double chiSquareDataSetsComparison(long[] observed1, long[] observed2)
65 throws IllegalArgumentException;
66
67 /**
68 * <p>Returns the <i>observed significance level</i>, or <a href=
69 * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
70 * p-value</a>, associated with a Chi-Square two sample test comparing
71 * bin frequency counts in <code>observed1</code> and
72 * <code>observed2</code>.
73 * </p>
74 * <p>The number returned is the smallest significance level at which one
75 * can reject the null hypothesis that the observed counts conform to the
76 * same distribution.
77 * </p>
78 * <p>See {@link #chiSquareDataSetsComparison(long[], long[])} for details
79 * on the formula used to compute the test statistic. The degrees of
80 * of freedom used to perform the test is one less than the common length
81 * of the input observed count arrays.
82 * </p>
83 * <strong>Preconditions</strong>: <ul>
84 * <li>Observed counts must be non-negative.
85 * </li>
86 * <li>Observed counts for a specific bin must not both be zero.
87 * </li>
88 * <li>Observed counts for a specific sample must not all be 0.
89 * </li>
90 * <li>The arrays <code>observed1</code> and <code>observed2</code> must
91 * have the same length and
92 * their common length must be at least 2.
93 * </li></ul><p>
94 * If any of the preconditions are not met, an
95 * <code>IllegalArgumentException</code> is thrown.</p>
96 *
97 * @param observed1 array of observed frequency counts of the first data set
98 * @param observed2 array of observed frequency counts of the second data set
99 * @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 }