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: 811786 $ $Date: 2009-09-06 05:36:08 -0400 (Sun, 06 Sep 2009) $
033     */
034    public interface OneWayAnova {
035    
036        /**
037         * Computes the ANOVA F-value for a collection of <code>double[]</code>
038         * arrays.
039         *
040         * <p><strong>Preconditions</strong>: <ul>
041         * <li>The categoryData <code>Collection</code> must contain
042         * <code>double[]</code> arrays.</li>
043         * <li> There must be at least two <code>double[]</code> arrays in the
044         * <code>categoryData</code> collection and each of these arrays must
045         * contain at least two values.</li></ul></p>
046         *
047         * @param categoryData <code>Collection</code> of <code>double[]</code>
048         * arrays each containing data for one category
049         * @return Fvalue
050         * @throws IllegalArgumentException if the preconditions are not met
051         * @throws MathException if the statistic can not be computed do to a
052         *         convergence or other numerical error.
053         */
054        double anovaFValue(Collection<double[]> categoryData)
055            throws IllegalArgumentException, MathException;
056    
057        /**
058         * Computes the ANOVA P-value for a collection of <code>double[]</code>
059         * arrays.
060         *
061         * <p><strong>Preconditions</strong>: <ul>
062         * <li>The categoryData <code>Collection</code> must contain
063         * <code>double[]</code> arrays.</li>
064         * <li> There must be at least two <code>double[]</code> arrays in the
065         * <code>categoryData</code> collection and each of these arrays must
066         * contain at least two values.</li></ul></p>
067         *
068         * @param categoryData <code>Collection</code> of <code>double[]</code>
069         * arrays each containing data for one category
070         * @return Pvalue
071         * @throws IllegalArgumentException if the preconditions are not met
072         * @throws MathException if the statistic can not be computed do to a
073         *         convergence or other numerical error.
074         */
075        double anovaPValue(Collection<double[]> categoryData)
076            throws IllegalArgumentException, MathException;
077    
078        /**
079         * Performs an ANOVA test, evaluating the null hypothesis that there
080         * is no difference among the means of the data categories.
081         *
082         * <p><strong>Preconditions</strong>: <ul>
083         * <li>The categoryData <code>Collection</code> must contain
084         * <code>double[]</code> arrays.</li>
085         * <li> There must be at least two <code>double[]</code> arrays in the
086         * <code>categoryData</code> collection and each of these arrays must
087         * contain at least two values.</li>
088         * <li>alpha must be strictly greater than 0 and less than or equal to 0.5.
089         * </li></ul></p>
090         *
091         * @param categoryData <code>Collection</code> of <code>double[]</code>
092         * arrays each containing data for one category
093         * @param alpha significance level of the test
094         * @return true if the null hypothesis can be rejected with
095         * confidence 1 - alpha
096         * @throws IllegalArgumentException if the preconditions are not met
097         * @throws MathException if the statistic can not be computed do to a
098         *         convergence or other numerical error.
099         */
100        boolean anovaTest(Collection<double[]> categoryData, double alpha)
101            throws IllegalArgumentException, MathException;
102    
103    }