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