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