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    import java.util.Collection;
021    
022    /**
023     * An interface for one-way ANOVA (analysis of variance). 
024     *
025     * <p> Tests for differences between two or more categories of univariate data
026     * (for example, the body mass index of accountants, lawyers, doctors and
027     * computer programmers).  When two categories are given, this is equivalent to
028     * the {@link org.apache.commons.math.stat.inference.TTest}.
029     * </p>
030     *
031     * @since 1.2
032     * @version $Revision: 670469 $ $Date: 2008-06-23 04:01:38 -0400 (Mon, 23 Jun 2008) $ 
033     */
034    public interface OneWayAnova {
035        /**
036         * Computes the ANOVA F-value for a collection of <code>double[]</code>
037         * arrays.
038         * 
039         * <p><strong>Preconditions</strong>: <ul>
040         * <li>The categoryData <code>Collection</code> must contain
041         * <code>double[]</code> arrays.</li>
042         * <li> There must be at least two <code>double[]</code> arrays in the
043         * <code>categoryData</code> collection and each of these arrays must
044         * contain at least two values.</li></ul></p>
045         *
046         * @param categoryData <code>Collection</code> of <code>double[]</code>
047         * arrays each containing data for one category
048         * @return Fvalue
049         * @throws IllegalArgumentException if the preconditions are not met
050         * @throws MathException if the statistic can not be computed do to a
051         *         convergence or other numerical error.
052         */
053        public double anovaFValue(Collection<double[]> categoryData)
054            throws IllegalArgumentException, MathException;
055    
056        /**
057         * Computes the ANOVA P-value for a collection of <code>double[]</code>
058         * arrays.
059         *
060         * <p><strong>Preconditions</strong>: <ul>
061         * <li>The categoryData <code>Collection</code> must contain
062         * <code>double[]</code> arrays.</li>
063         * <li> There must be at least two <code>double[]</code> arrays in the
064         * <code>categoryData</code> collection and each of these arrays must
065         * contain at least two values.</li></ul></p>
066         *
067         * @param categoryData <code>Collection</code> of <code>double[]</code>
068         * arrays each containing data for one category
069         * @return Pvalue
070         * @throws IllegalArgumentException if the preconditions are not met
071         * @throws MathException if the statistic can not be computed do to a
072         *         convergence or other numerical error.
073         */
074        public double anovaPValue(Collection<double[]> categoryData)
075            throws IllegalArgumentException, MathException;
076    
077        /**
078         * Performs an ANOVA test, evaluating the null hypothesis that there
079         * is no difference among the means of the data categories.
080         * 
081         * <p><strong>Preconditions</strong>: <ul>
082         * <li>The categoryData <code>Collection</code> must contain
083         * <code>double[]</code> arrays.</li>
084         * <li> There must be at least two <code>double[]</code> arrays in the
085         * <code>categoryData</code> collection and each of these arrays must
086         * contain at least two values.</li>
087         * <li>alpha must be strictly greater than 0 and less than or equal to 0.5.
088         * </li></ul></p>
089         *
090         * @param categoryData <code>Collection</code> of <code>double[]</code>
091         * arrays each containing data for one category
092         * @param alpha significance level of the test
093         * @return true if the null hypothesis can be rejected with 
094         * confidence 1 - alpha
095         * @throws IllegalArgumentException if the preconditions are not met
096         * @throws MathException if the statistic can not be computed do to a
097         *         convergence or other numerical error.
098        */
099        public boolean anovaTest(Collection<double[]> categoryData, double alpha)
100            throws IllegalArgumentException, MathException;
101    
102    }