ChiSquareTest


1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.stat.inference;
17  
18  import org.apache.commons.math.MathException;
19  
20  /**
21   * An interface for Chi-Square tests.
22   *
23   * @version $Revision$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $ 
24   */
25  public interface ChiSquareTest {
26       
27       /**
28       * Computes the <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda35f.htm">
29       * Chi-Square statistic</a> comparing <code>observed</code> and <code>expected</code> 
30       * freqeuncy counts. 
31       * <p>
32       * This statistic can be used to perform a Chi-Square test evaluating the null hypothesis that
33       *  the observed counts follow the expected distribution.
34       * <p>
35       * <strong>Preconditions</strong>: <ul>
36       * <li>Expected counts must all be positive.  
37       * </li>
38       * <li>Observed counts must all be >= 0.   
39       * </li>
40       * <li>The observed and expected arrays must have the same length and
41       * their common length must be at least 2.  
42       * </li></ul><p>
43       * If any of the preconditions are not met, an 
44       * <code>IllegalArgumentException</code> is thrown.
45       *
46       * @param observed array of observed frequency counts
47       * @param expected array of expected frequency counts
48       * @return chiSquare statistic
49       * @throws IllegalArgumentException if preconditions are not met
50       */
51      double chiSquare(double[] expected, long[] observed) 
52          throws IllegalArgumentException  ;
53      
54      /**
55       * Returns the <i>observed significance level</i>, or <a HREF=
56       * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
57       * p-value</a>, associated with a 
58       * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda35f.htm">
59       * Chi-square goodness of fit test</a> comparing the <code>observed</code> 
60       * frequency counts to those in the <code>expected</code> array.
61       * <p>
62       * The number returned is the smallest significance level at which one can reject 
63       * the null hypothesis that the observed counts conform to the frequency distribution 
64       * described by the expected counts. 
65       * <p>
66       * <strong>Preconditions</strong>: <ul>
67       * <li>Expected counts must all be positive.  
68       * </li>
69       * <li>Observed counts must all be >= 0.   
70       * </li>
71       * <li>The observed and expected arrays must have the same length and
72       * their common length must be at least 2.  
73       * </li></ul><p>
74       * If any of the preconditions are not met, an 
75       * <code>IllegalArgumentException</code> is thrown.
76       *
77       * @param observed array of observed frequency counts
78       * @param expected array of expected frequency counts
79       * @return p-value
80       * @throws IllegalArgumentException if preconditions are not met
81       * @throws MathException if an error occurs computing the p-value
82       */
83      double chiSquareTest(double[] expected, long[] observed) 
84          throws IllegalArgumentException  , MathException;
85      
86      /**
87       * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda35f.htm">
88       * Chi-square goodness of fit test</a> evaluating the null hypothesis that the observed counts 
89       * conform to the frequency distribution described by the expected counts, with 
90       * significance level <code>alpha</code>.  Returns true iff the null hypothesis can be rejected
91       * with 100 * (1 - alpha) percent confidence.
92       * <p>
93       * <strong>Example:</strong><br>
94       * To test the hypothesis that <code>observed</code> follows 
95       * <code>expected</code> at the 99% level, use <p>
96       * <code>chiSquareTest(expected, observed, 0.01) </code>
97       * <p>
98       * <strong>Preconditions</strong>: <ul>
99       * <li>Expected counts must all be positive.  
100      * </li>
101      * <li>Observed counts must all be >= 0.   
102      * </li>
103      * <li>The observed and expected arrays must have the same length and
104      * their common length must be at least 2.  
105      * <li> <code> 0 < alpha < 0.5 </code>
106      * </li></ul><p>
107      * If any of the preconditions are not met, an 
108      * <code>IllegalArgumentException</code> is thrown.
109      *
110      * @param observed array of observed frequency counts
111      * @param expected array of expected frequency counts
112      * @param alpha significance level of the test
113      * @return true iff null hypothesis can be rejected with confidence
114      * 1 - alpha
115      * @throws IllegalArgumentException if preconditions are not met
116      * @throws MathException if an error occurs performing the test
117      */
118     boolean chiSquareTest(double[] expected, long[] observed, double alpha) 
119         throws IllegalArgumentException  , MathException;
120     
121     /**
122      *  Computes the Chi-Square statistic associated with a 
123      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section4/prc45.htm">
124      *  chi-square test of independence</a> based on the input <code>counts</code>
125      *  array, viewed as a two-way table.  
126      * <p>
127      * The rows of the 2-way table are <code>count[0], ... , count[count.length - 1] </code>
128      * <p>
129      * <strong>Preconditions</strong>: <ul>
130      * <li>All counts must be >= 0.  
131      * </li>
132      * <li>The count array must be rectangular (i.e. all count[i] subarrays must have the same length). 
133      * </li>
134      * <li>The 2-way table represented by <code>counts</code> must have at least 2 columns and
135      *        at least 2 rows.
136      * </li>
137      * </li></ul><p>
138      * If any of the preconditions are not met, an 
139      * <code>IllegalArgumentException</code> is thrown.
140      *
141      * @param counts array representation of 2-way table
142      * @return chiSquare statistic
143      * @throws IllegalArgumentException if preconditions are not met
144      */
145     double chiSquare(long[][] counts) 
146     throws IllegalArgumentException  ;
147     
148     /**
149      * Returns the <i>observed significance level</i>, or <a HREF=
150      * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
151      * p-value</a>, associated with a 
152      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section4/prc45.htm">
153      * chi-square test of independence</a> based on the input <code>counts</code>
154      * array, viewed as a two-way table.  
155      * <p>
156      * The rows of the 2-way table are <code>count[0], ... , count[count.length - 1] </code>
157      * <p>
158      * <strong>Preconditions</strong>: <ul>
159      * <li>All counts must be >= 0.  
160      * </li>
161      * <li>The count array must be rectangular (i.e. all count[i] subarrays must have the same length). 
162      * </li>
163      * <li>The 2-way table represented by <code>counts</code> must have at least 2 columns and
164      *        at least 2 rows.
165      * </li>
166      * </li></ul><p>
167      * If any of the preconditions are not met, an 
168      * <code>IllegalArgumentException</code> is thrown.
169      *
170      * @param counts array representation of 2-way table
171      * @return p-value
172      * @throws IllegalArgumentException if preconditions are not met
173      * @throws MathException if an error occurs computing the p-value
174      */
175     double chiSquareTest(long[][] counts) 
176     throws IllegalArgumentException  , MathException;
177     
178     /**
179      * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section4/prc45.htm">
180      * chi-square test of independence</a> evaluating the null hypothesis that the classifications 
181      * represented by the counts in the columns of the input 2-way table are independent of the rows,
182      * with significance level <code>alpha</code>.  Returns true iff the null hypothesis can be rejected
183      * with 100 * (1 - alpha) percent confidence.
184      * <p>
185      * The rows of the 2-way table are <code>count[0], ... , count[count.length - 1] </code>
186      * <p>
187      * <strong>Example:</strong><br>
188      * To test the null hypothesis that the counts in <code>count[0], ... , count[count.length - 1] </code>
189      *  all correspond to the same underlying probability distribution at the 99% level, use <p>
190      * <code>chiSquareTest(counts, 0.01) </code>
191      * <p>
192      * <strong>Preconditions</strong>: <ul>
193      * <li>All counts must be >= 0.  
194      * </li>
195      * <li>The count array must be rectangular (i.e. all count[i] subarrays must have the same length). 
196      * </li>
197      * <li>The 2-way table represented by <code>counts</code> must have at least 2 columns and
198      *        at least 2 rows.
199      * </li>
200      * </li></ul><p>
201      * If any of the preconditions are not met, an 
202      * <code>IllegalArgumentException</code> is thrown.
203      *
204      * @param counts array representation of 2-way table
205      * @param alpha significance level of the test
206      * @return true iff null hypothesis can be rejected with confidence
207      * 1 - alpha
208      * @throws IllegalArgumentException if preconditions are not met
209      * @throws MathException if an error occurs performing the test
210      */
211     boolean chiSquareTest(long[][] counts, double alpha) 
212     throws IllegalArgumentException  , MathException;
213 }
214
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags