View Javadoc

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: 670469 $ $Date: 2008-06-23 04:01:38 -0400 (Mon, 23 Jun 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       * &sum;[(K * observed1[i] - observed2[i]/K)<sup>2</sup> / (observed1[i] + observed2[i])]
40       * </code> where 
41       * <br/><code>K = &sqrt;[&sum(observed2 / &sum;(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 }