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: 811685 $ $Date: 2009-09-05 19:36:48 +0200 (sam. 05 sept. 2009) $ 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 } 145
