    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.math3.stat.inference;
    018
    019    import java.util.Collection;
    020    import org.apache.commons.math3.exception.ConvergenceException;
    021    import org.apache.commons.math3.exception.DimensionMismatchException;
    022    import org.apache.commons.math3.exception.MaxCountExceededException;
    023    import org.apache.commons.math3.exception.NoDataException;
    024    import org.apache.commons.math3.exception.NotPositiveException;
    025    import org.apache.commons.math3.exception.NotStrictlyPositiveException;
    026    import org.apache.commons.math3.exception.NullArgumentException;
    027    import org.apache.commons.math3.exception.NumberIsTooSmallException;
    028    import org.apache.commons.math3.exception.OutOfRangeException;
    029    import org.apache.commons.math3.exception.ZeroException;
    030    import org.apache.commons.math3.stat.descriptive.StatisticalSummary;
    031
    032    /**
    033     * A collection of static methods to create inference test instances or to
    034     * perform inference tests.
    035     *
    036     * @since 1.1
    037     * @version $Id: TestUtils.java 1422313 2012-12-15 18:53:41Z psteitz $
    038     */
    039    public class TestUtils  {
    040
    041        /** Singleton TTest instance. */
    042        private static final TTest T_TEST = new TTest();
    043
    044        /** Singleton ChiSquareTest instance. */
    045        private static final ChiSquareTest CHI_SQUARE_TEST = new ChiSquareTest();
    046
    047        /** Singleton OneWayAnova instance. */
    048        private static final OneWayAnova ONE_WAY_ANANOVA = new OneWayAnova();
    049
    050        /** Singleton G-Test instance. */
    051        private static final GTest G_TEST = new GTest();
    052
    053        /**
    054         * Prevent instantiation.
    055         */
    056        private TestUtils() {
    057            super();
    058        }
    059
    060        // CHECKSTYLE: stop JavadocMethodCheck
    061
    062        /**
    063         * @see org.apache.commons.math3.stat.inference.TTest#homoscedasticT(double[], double[])
    064         */
    065        public static double homoscedasticT(final double[] sample1, final double[] sample2)
    066            throws NullArgumentException, NumberIsTooSmallException {
    067            return T_TEST.homoscedasticT(sample1, sample2);
    068        }
    069
    070        /**
    071         * @see org.apache.commons.math3.stat.inference.TTest#homoscedasticT(org.apache.commons.math3.stat.descriptive.StatisticalSummary, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    072         */
    073        public static double homoscedasticT(final StatisticalSummary sampleStats1,
    074                                            final StatisticalSummary sampleStats2)
    075            throws NullArgumentException, NumberIsTooSmallException {
    076            return T_TEST.homoscedasticT(sampleStats1, sampleStats2);
    077        }
    078
    079        /**
    080         * @see org.apache.commons.math3.stat.inference.TTest#homoscedasticTTest(double[], double[], double)
    081         */
    082        public static boolean homoscedasticTTest(final double[] sample1, final double[] sample2,
    083                                                 final double alpha)
    084            throws NullArgumentException, NumberIsTooSmallException,
    085            OutOfRangeException, MaxCountExceededException {
    086            return T_TEST.homoscedasticTTest(sample1, sample2, alpha);
    087        }
    088
    089        /**
    090         * @see org.apache.commons.math3.stat.inference.TTest#homoscedasticTTest(double[], double[])
    091         */
    092        public static double homoscedasticTTest(final double[] sample1, final double[] sample2)
    093            throws NullArgumentException, NumberIsTooSmallException, MaxCountExceededException {
    094            return T_TEST.homoscedasticTTest(sample1, sample2);
    095        }
    096
    097        /**
    098         * @see org.apache.commons.math3.stat.inference.TTest#homoscedasticTTest(org.apache.commons.math3.stat.descriptive.StatisticalSummary, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    099         */
    100        public static double homoscedasticTTest(final StatisticalSummary sampleStats1,
    101                                                final StatisticalSummary sampleStats2)
    102            throws NullArgumentException, NumberIsTooSmallException, MaxCountExceededException {
    103            return T_TEST.homoscedasticTTest(sampleStats1, sampleStats2);
    104        }
    105
    106        /**
    107         * @see org.apache.commons.math3.stat.inference.TTest#pairedT(double[], double[])
    108         */
    109        public static double pairedT(final double[] sample1, final double[] sample2)
    110            throws NullArgumentException, NoDataException,
    111            DimensionMismatchException, NumberIsTooSmallException {
    112            return T_TEST.pairedT(sample1, sample2);
    113        }
    114
    115        /**
    116         * @see org.apache.commons.math3.stat.inference.TTest#pairedTTest(double[], double[], double)
    117         */
    118        public static boolean pairedTTest(final double[] sample1, final double[] sample2,
    119                                          final double alpha)
    120            throws NullArgumentException, NoDataException, DimensionMismatchException,
    121            NumberIsTooSmallException, OutOfRangeException, MaxCountExceededException {
    122            return T_TEST.pairedTTest(sample1, sample2, alpha);
    123        }
    124
    125        /**
    126         * @see org.apache.commons.math3.stat.inference.TTest#pairedTTest(double[], double[])
    127         */
    128        public static double pairedTTest(final double[] sample1, final double[] sample2)
    129            throws NullArgumentException, NoDataException, DimensionMismatchException,
    130            NumberIsTooSmallException, MaxCountExceededException {
    131            return T_TEST.pairedTTest(sample1, sample2);
    132        }
    133
    134        /**
    135         * @see org.apache.commons.math3.stat.inference.TTest#t(double, double[])
    136         */
    137        public static double t(final double mu, final double[] observed)
    138            throws NullArgumentException, NumberIsTooSmallException {
    139            return T_TEST.t(mu, observed);
    140        }
    141
    142        /**
    143         * @see org.apache.commons.math3.stat.inference.TTest#t(double, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    144         */
    145        public static double t(final double mu, final StatisticalSummary sampleStats)
    146            throws NullArgumentException, NumberIsTooSmallException {
    147            return T_TEST.t(mu, sampleStats);
    148        }
    149
    150        /**
    151         * @see org.apache.commons.math3.stat.inference.TTest#t(double[], double[])
    152         */
    153        public static double t(final double[] sample1, final double[] sample2)
    154            throws NullArgumentException, NumberIsTooSmallException {
    155            return T_TEST.t(sample1, sample2);
    156        }
    157
    158        /**
    159         * @see org.apache.commons.math3.stat.inference.TTest#t(org.apache.commons.math3.stat.descriptive.StatisticalSummary, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    160         */
    161        public static double t(final StatisticalSummary sampleStats1,
    162                               final StatisticalSummary sampleStats2)
    163            throws NullArgumentException, NumberIsTooSmallException {
    164            return T_TEST.t(sampleStats1, sampleStats2);
    165        }
    166
    167        /**
    168         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double, double[], double)
    169         */
    170        public static boolean tTest(final double mu, final double[] sample, final double alpha)
    171            throws NullArgumentException, NumberIsTooSmallException,
    172            OutOfRangeException, MaxCountExceededException {
    173            return T_TEST.tTest(mu, sample, alpha);
    174        }
    175
    176        /**
    177         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double, double[])
    178         */
    179        public static double tTest(final double mu, final double[] sample)
    180            throws NullArgumentException, NumberIsTooSmallException,
    181            MaxCountExceededException {
    182            return T_TEST.tTest(mu, sample);
    183        }
    184
    185        /**
    186         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double, org.apache.commons.math3.stat.descriptive.StatisticalSummary, double)
    187         */
    188        public static boolean tTest(final double mu, final StatisticalSummary sampleStats,
    189                                    final double alpha)
    190            throws NullArgumentException, NumberIsTooSmallException,
    191            OutOfRangeException, MaxCountExceededException {
    192            return T_TEST.tTest(mu, sampleStats, alpha);
    193        }
    194
    195        /**
    196         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    197         */
    198        public static double tTest(final double mu, final StatisticalSummary sampleStats)
    199            throws NullArgumentException, NumberIsTooSmallException,
    200            MaxCountExceededException {
    201            return T_TEST.tTest(mu, sampleStats);
    202        }
    203
    204        /**
    205         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double[], double[], double)
    206         */
    207        public static boolean tTest(final double[] sample1, final double[] sample2,
    208                                    final double alpha)
    209            throws NullArgumentException, NumberIsTooSmallException,
    210            OutOfRangeException, MaxCountExceededException {
    211            return T_TEST.tTest(sample1, sample2, alpha);
    212        }
    213
    214        /**
    215         * @see org.apache.commons.math3.stat.inference.TTest#tTest(double[], double[])
    216         */
    217        public static double tTest(final double[] sample1, final double[] sample2)
    218            throws NullArgumentException, NumberIsTooSmallException,
    219            MaxCountExceededException {
    220            return T_TEST.tTest(sample1, sample2);
    221        }
    222
    223        /**
    224         * @see org.apache.commons.math3.stat.inference.TTest#tTest(org.apache.commons.math3.stat.descriptive.StatisticalSummary, org.apache.commons.math3.stat.descriptive.StatisticalSummary, double)
    225         */
    226        public static boolean tTest(final StatisticalSummary sampleStats1,
    227                                    final StatisticalSummary sampleStats2,
    228                                    final double alpha)
    229            throws NullArgumentException, NumberIsTooSmallException,
    230            OutOfRangeException, MaxCountExceededException {
    231            return T_TEST.tTest(sampleStats1, sampleStats2, alpha);
    232        }
    233
    234        /**
    235         * @see org.apache.commons.math3.stat.inference.TTest#tTest(org.apache.commons.math3.stat.descriptive.StatisticalSummary, org.apache.commons.math3.stat.descriptive.StatisticalSummary)
    236         */
    237        public static double tTest(final StatisticalSummary sampleStats1,
    238                                   final StatisticalSummary sampleStats2)
    239            throws NullArgumentException, NumberIsTooSmallException,
    240            MaxCountExceededException {
    241            return T_TEST.tTest(sampleStats1, sampleStats2);
    242        }
    243
    244        /**
    245         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquare(double[], long[])
    246         */
    247        public static double chiSquare(final double[] expected, final long[] observed)
    248            throws NotPositiveException, NotStrictlyPositiveException,
    249            DimensionMismatchException {
    250            return CHI_SQUARE_TEST.chiSquare(expected, observed);
    251        }
    252
    253        /**
    254         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquare(long[][])
    255         */
    256        public static double chiSquare(final long[][] counts)
    257            throws NullArgumentException, NotPositiveException,
    258            DimensionMismatchException {
    259            return CHI_SQUARE_TEST.chiSquare(counts);
    260        }
    261
    262        /**
    263         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTest(double[], long[], double)
    264         */
    265        public static boolean chiSquareTest(final double[] expected, final long[] observed,
    266                                            final double alpha)
    267            throws NotPositiveException, NotStrictlyPositiveException,
    268            DimensionMismatchException, OutOfRangeException, MaxCountExceededException {
    269            return CHI_SQUARE_TEST.chiSquareTest(expected, observed, alpha);
    270        }
    271
    272        /**
    273         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTest(double[], long[])
    274         */
    275        public static double chiSquareTest(final double[] expected, final long[] observed)
    276            throws NotPositiveException, NotStrictlyPositiveException,
    277            DimensionMismatchException, MaxCountExceededException {
    278            return CHI_SQUARE_TEST.chiSquareTest(expected, observed);
    279        }
    280
    281        /**
    282         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTest(long[][], double)
    283         */
    284        public static boolean chiSquareTest(final long[][] counts, final double alpha)
    285            throws NullArgumentException, DimensionMismatchException,
    286            NotPositiveException, OutOfRangeException, MaxCountExceededException {
    287            return CHI_SQUARE_TEST.chiSquareTest(counts, alpha);
    288        }
    289
    290        /**
    291         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTest(long[][])
    292         */
    293        public static double chiSquareTest(final long[][] counts)
    294            throws NullArgumentException, DimensionMismatchException,
    295            NotPositiveException, MaxCountExceededException {
    296            return CHI_SQUARE_TEST.chiSquareTest(counts);
    297        }
    298
    299        /**
    300         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareDataSetsComparison(long[], long[])
    301         *
    302         * @since 1.2
    303         */
    304        public static double chiSquareDataSetsComparison(final long[] observed1,
    305                                                         final long[] observed2)
    306            throws DimensionMismatchException, NotPositiveException, ZeroException {
    307            return CHI_SQUARE_TEST.chiSquareDataSetsComparison(observed1, observed2);
    308        }
    309
    310        /**
    311         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTestDataSetsComparison(long[], long[])
    312         *
    313         * @since 1.2
    314         */
    315        public static double chiSquareTestDataSetsComparison(final long[] observed1,
    316                                                             final long[] observed2)
    317            throws DimensionMismatchException, NotPositiveException, ZeroException,
    318            MaxCountExceededException {
    319            return CHI_SQUARE_TEST.chiSquareTestDataSetsComparison(observed1, observed2);
    320        }
    321
    322        /**
    323         * @see org.apache.commons.math3.stat.inference.ChiSquareTest#chiSquareTestDataSetsComparison(long[], long[], double)
    324         *
    325         * @since 1.2
    326         */
    327        public static boolean chiSquareTestDataSetsComparison(final long[] observed1,
    328                                                              final long[] observed2,
    329                                                              final double alpha)
    330            throws DimensionMismatchException, NotPositiveException,
    331            ZeroException, OutOfRangeException, MaxCountExceededException {
    332            return CHI_SQUARE_TEST.chiSquareTestDataSetsComparison(observed1, observed2, alpha);
    333        }
    334
    335        /**
    336         * @see org.apache.commons.math3.stat.inference.OneWayAnova#anovaFValue(Collection)
    337         *
    338         * @since 1.2
    339         */
    340        public static double oneWayAnovaFValue(final Collection<double[]> categoryData)
    341            throws NullArgumentException, DimensionMismatchException {
    342            return ONE_WAY_ANANOVA.anovaFValue(categoryData);
    343        }
    344
    345        /**
    346         * @see org.apache.commons.math3.stat.inference.OneWayAnova#anovaPValue(Collection)
    347         *
    348         * @since 1.2
    349         */
    350        public static double oneWayAnovaPValue(final Collection<double[]> categoryData)
    351            throws NullArgumentException, DimensionMismatchException,
    352            ConvergenceException, MaxCountExceededException {
    353            return ONE_WAY_ANANOVA.anovaPValue(categoryData);
    354        }
    355
    356        /**
    357         * @see org.apache.commons.math3.stat.inference.OneWayAnova#anovaTest(Collection,double)
    358         *
    359         * @since 1.2
    360         */
    361        public static boolean oneWayAnovaTest(final Collection<double[]> categoryData,
    362                                              final double alpha)
    363            throws NullArgumentException, DimensionMismatchException,
    364            OutOfRangeException, ConvergenceException, MaxCountExceededException {
    365            return ONE_WAY_ANANOVA.anovaTest(categoryData, alpha);
    366        }
    367
    368         /**
    369         * @see org.apache.commons.math3.stat.inference.GTest#g(double[], long[])
    370         * @since 3.1
    371         */
    372        public static double g(final double[] expected, final long[] observed)
    373            throws NotPositiveException, NotStrictlyPositiveException,
    374            DimensionMismatchException {
    375            return G_TEST.g(expected, observed);
    376        }
    377
    378        /**
    379         * @see org.apache.commons.math3.stat.inference.GTest#gTest( double[],  long[] )
    380         * @since 3.1
    381         */
    382        public static double gTest(final double[] expected, final long[] observed)
    383            throws NotPositiveException, NotStrictlyPositiveException,
    384            DimensionMismatchException, MaxCountExceededException {
    385            return G_TEST.gTest(expected, observed);
    386        }
    387
    388        /**
    389         * @see org.apache.commons.math3.stat.inference.GTest#gTestIntrinsic(double[], long[] )
    390         * @since 3.1
    391         */
    392        public static double gTestIntrinsic(final double[] expected, final long[] observed)
    393            throws NotPositiveException, NotStrictlyPositiveException,
    394            DimensionMismatchException, MaxCountExceededException {
    395            return G_TEST.gTestIntrinsic(expected, observed);
    396        }
    397
    398         /**
    399         * @see org.apache.commons.math3.stat.inference.GTest#gTest( double[],long[],double)
    400         * @since 3.1
    401         */
    402        public static boolean gTest(final double[] expected, final long[] observed,
    403                                    final double alpha)
    404            throws NotPositiveException, NotStrictlyPositiveException,
    405            DimensionMismatchException, OutOfRangeException, MaxCountExceededException {
    406            return G_TEST.gTest(expected, observed, alpha);
    407        }
    408
    409        /**
    410         * @see org.apache.commons.math3.stat.inference.GTest#gDataSetsComparison(long[], long[])
    411         * @since 3.1
    412         */
    413        public static double gDataSetsComparison(final long[] observed1,
    414                                                      final long[] observed2)
    415            throws DimensionMismatchException, NotPositiveException, ZeroException {
    416            return G_TEST.gDataSetsComparison(observed1, observed2);
    417        }
    418
    419        /**
    420         * @see org.apache.commons.math3.stat.inference.GTest#rootLogLikelihoodRatio(long, long, long, long)
    421         * @since 3.1
    422         */
    423        public static double rootLogLikelihoodRatio(final long k11, final long k12, final long k21, final long k22)
    424            throws DimensionMismatchException, NotPositiveException, ZeroException {
    425            return G_TEST.rootLogLikelihoodRatio(k11, k12, k21, k22);
    426        }
    427
    428
    429        /**
    430         * @see org.apache.commons.math3.stat.inference.GTest#gTestDataSetsComparison(long[], long[])
    431         * @since 3.1
    432         */
    433        public static double gTestDataSetsComparison(final long[] observed1,
    434                                                            final long[] observed2)
    435            throws DimensionMismatchException, NotPositiveException, ZeroException,
    436            MaxCountExceededException {
    437            return G_TEST.gTestDataSetsComparison(observed1, observed2);
    438        }
    439
    440        /**
    441         * @see org.apache.commons.math3.stat.inference.GTest#gTestDataSetsComparison(long[],long[],double)
    442         * @since 3.1
    443         */
    444        public static boolean gTestDataSetsComparison(final long[] observed1,
    445                                                      final long[] observed2,
    446                                                      final double alpha)
    447            throws DimensionMismatchException, NotPositiveException,
    448            ZeroException, OutOfRangeException, MaxCountExceededException {
    449            return G_TEST.gTestDataSetsComparison(observed1, observed2, alpha);
    450        }
    451
    452        // CHECKSTYLE: resume JavadocMethodCheck
    453
    454    }