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 */
017package org.apache.commons.math3.stat.inference;
018
019import java.util.Collection;
020import org.apache.commons.math3.exception.ConvergenceException;
021import org.apache.commons.math3.exception.DimensionMismatchException;
022import org.apache.commons.math3.exception.MaxCountExceededException;
023import org.apache.commons.math3.exception.NoDataException;
024import org.apache.commons.math3.exception.NotPositiveException;
025import org.apache.commons.math3.exception.NotStrictlyPositiveException;
026import org.apache.commons.math3.exception.NullArgumentException;
027import org.apache.commons.math3.exception.NumberIsTooSmallException;
028import org.apache.commons.math3.exception.OutOfRangeException;
029import org.apache.commons.math3.exception.ZeroException;
030import 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 */
039public 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}