Java > Open Source Codes > org > apache > commons > math > stat > inference > TTestImpl


1 /*
2  * Copyright 2004-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.math.stat.inference;
17
18 import org.apache.commons.math.MathException;
19 import org.apache.commons.math.distribution.DistributionFactory;
20 import org.apache.commons.math.distribution.TDistribution;
21 import org.apache.commons.math.stat.StatUtils;
22 import org.apache.commons.math.stat.descriptive.StatisticalSummary;
23
24 /**
25  * Implements t-test statistics defined in the {@link TTest} interface.
26  * <p>
27  * Uses commons-math {@link org.apache.commons.math.distribution.TDistribution}
28  * implementation to estimate exact p-values.
29  *
30  * @version $Revision$ $Date: 2005-05-01 22:14:49 -0700 (Sun, 01 May 2005) $
31  */
32 public class TTestImpl implements TTest {
33
34     /** Cached DistributionFactory used to create TDistribution instances */
35     private DistributionFactory distributionFactory = null;
36     
37     /**
38      * Default constructor.
39      */
40     public TTestImpl() {
41         super();
42     }
43     
44     /**
45      * Computes a paired, 2-sample t-statistic based on the data in the input
46      * arrays. The t-statistic returned is equivalent to what would be returned by
47      * computing the one-sample t-statistic {@link #t(double, double[])}, with
48      * <code>mu = 0</code> and the sample array consisting of the (signed)
49      * differences between corresponding entries in <code>sample1</code> and
50      * <code>sample2.</code>
51      * <p>
52      * <strong>Preconditions</strong>: <ul>
53      * <li>The input arrays must have the same length and their common length
54      * must be at least 2.
55      * </li></ul>
56      *
57      * @param sample1 array of sample data values
58      * @param sample2 array of sample data values
59      * @return t statistic
60      * @throws IllegalArgumentException if the precondition is not met
61      * @throws MathException if the statistic can not be computed do to a
62      * convergence or other numerical error.
63      */
64     public double pairedT(double[] sample1, double[] sample2)
65         throws IllegalArgumentException , MathException {
66         if ((sample1 == null) || (sample2 == null ||
67                 Math.min(sample1.length, sample2.length) < 2)) {
68             throw new IllegalArgumentException ("insufficient data for t statistic");
69         }
70         double meanDifference = StatUtils.meanDifference(sample1, sample2);
71         return t(meanDifference, 0,
72                 StatUtils.varianceDifference(sample1, sample2, meanDifference),
73                 (double) sample1.length);
74     }
75
76      /**
77      * Returns the <i>observed significance level</i>, or
78      * <i> p-value</i>, associated with a paired, two-sample, two-tailed t-test
79      * based on the data in the input arrays.
80      * <p>
81      * The number returned is the smallest significance level
82      * at which one can reject the null hypothesis that the mean of the paired
83      * differences is 0 in favor of the two-sided alternative that the mean paired
84      * difference is not equal to 0. For a one-sided test, divide the returned
85      * value by 2.
86      * <p>
87      * This test is equivalent to a one-sample t-test computed using
88      * {@link #tTest(double, double[])} with <code>mu = 0</code> and the sample
89      * array consisting of the signed differences between corresponding elements of
90      * <code>sample1</code> and <code>sample2.</code>
91      * <p>
92      * <strong>Usage Note:</strong><br>
93      * The validity of the p-value depends on the assumptions of the parametric
94      * t-test procedure, as discussed
95      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
96      * here</a>
97      * <p>
98      * <strong>Preconditions</strong>: <ul>
99      * <li>The input array lengths must be the same and their common length must
100      * be at least 2.
101      * </li></ul>
102      *
103      * @param sample1 array of sample data values
104      * @param sample2 array of sample data values
105      * @return p-value for t-test
106      * @throws IllegalArgumentException if the precondition is not met
107      * @throws MathException if an error occurs computing the p-value
108      */
109     public double pairedTTest(double[] sample1, double[] sample2)
110         throws IllegalArgumentException , MathException {
111         double meanDifference = StatUtils.meanDifference(sample1, sample2);
112         return tTest(meanDifference, 0,
113                 StatUtils.varianceDifference(sample1, sample2, meanDifference),
114                 (double) sample1.length);
115     }
116
117      /**
118      * Performs a paired t-test evaluating the null hypothesis that the
119      * mean of the paired differences between <code>sample1</code> and
120      * <code>sample2</code> is 0 in favor of the two-sided alternative that the
121      * mean paired difference is not equal to 0, with significance level
122      * <code>alpha</code>.
123      * <p>
124      * Returns <code>true</code> iff the null hypothesis can be rejected with
125      * confidence <code>1 - alpha</code>. To perform a 1-sided test, use
126      * <code>alpha * 2</code>
127      * <p>
128      * <strong>Usage Note:</strong><br>
129      * The validity of the test depends on the assumptions of the parametric
130      * t-test procedure, as discussed
131      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
132      * here</a>
133      * <p>
134      * <strong>Preconditions</strong>: <ul>
135      * <li>The input array lengths must be the same and their common length
136      * must be at least 2.
137      * </li>
138      * <li> <code> 0 < alpha < 0.5 </code>
139      * </li></ul>
140      *
141      * @param sample1 array of sample data values
142      * @param sample2 array of sample data values
143      * @param alpha significance level of the test
144      * @return true if the null hypothesis can be rejected with
145      * confidence 1 - alpha
146      * @throws IllegalArgumentException if the preconditions are not met
147      * @throws MathException if an error occurs performing the test
148      */
149     public boolean pairedTTest(double[] sample1, double[] sample2, double alpha)
150         throws IllegalArgumentException , MathException {
151         if ((alpha <= 0) || (alpha > 0.5)) {
152             throw new IllegalArgumentException ("bad significance level: " + alpha);
153         }
154         return (pairedTTest(sample1, sample2) < alpha);
155     }
156
157     /**
158      * Computes a <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula">
159      * t statistic </a> given observed values and a comparison constant.
160      * <p>
161      * This statistic can be used to perform a one sample t-test for the mean.
162      * <p>
163      * <strong>Preconditions</strong>: <ul>
164      * <li>The observed array length must be at least 2.
165      * </li></ul>
166      *
167      * @param mu comparison constant
168      * @param observed array of values
169      * @return t statistic
170      * @throws IllegalArgumentException if input array length is less than 2
171      */
172     public double t(double mu, double[] observed)
173     throws IllegalArgumentException {
174         if ((observed == null) || (observed.length < 2)) {
175             throw new IllegalArgumentException ("insufficient data for t statistic");
176         }
177         return t(StatUtils.mean(observed), mu, StatUtils.variance(observed),
178                 observed.length);
179     }
180
181     /**
182      * Computes a <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula">
183      * t statistic </a> to use in comparing the mean of the dataset described by
184      * <code>sampleStats</code> to <code>mu</code>.
185      * <p>
186      * This statistic can be used to perform a one sample t-test for the mean.
187      * <p>
188      * <strong>Preconditions</strong>: <ul>
189      * <li><code>observed.getN() > = 2</code>.
190      * </li></ul>
191      *
192      * @param mu comparison constant
193      * @param sampleStats DescriptiveStatistics holding sample summary statitstics
194      * @return t statistic
195      * @throws IllegalArgumentException if the precondition is not met
196      */
197     public double t(double mu, StatisticalSummary sampleStats)
198     throws IllegalArgumentException {
199         if ((sampleStats == null) || (sampleStats.getN() < 2)) {
200             throw new IllegalArgumentException ("insufficient data for t statistic");
201         }
202         return t(sampleStats.getMean(), mu, sampleStats.getVariance(),
203                 sampleStats.getN());
204     }
205
206     /**
207      * Computes a 2-sample t statistic, under the hypothesis of equal
208      * subpopulation variances. To compute a t-statistic without the
209      * equal variances hypothesis, use {@link #t(double[], double[])}.
210      * <p>
211      * This statistic can be used to perform a (homoscedastic) two-sample
212      * t-test to compare sample means.
213      * <p>
214      * The t-statisitc is
215      * <p>
216      * &nbsp;&nbsp;<code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code>
217      * <p>
218      * where <strong><code>n1</code></strong> is the size of first sample;
219      * <strong><code> n2</code></strong> is the size of second sample;
220      * <strong><code> m1</code></strong> is the mean of first sample;
221      * <strong><code> m2</code></strong> is the mean of second sample</li>
222      * </ul>
223      * and <strong><code>var</code></strong> is the pooled variance estimate:
224      * <p>
225      * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code>
226      * <p>
227      * with <strong><code>var1<code></strong> the variance of the first sample and
228      * <strong><code>var2</code></strong> the variance of the second sample.
229      * <p>
230      * <strong>Preconditions</strong>: <ul>
231      * <li>The observed array lengths must both be at least 2.
232      * </li></ul>
233      *
234      * @param sample1 array of sample data values
235      * @param sample2 array of sample data values
236      * @return t statistic
237      * @throws IllegalArgumentException if the precondition is not met
238      */
239     public double homoscedasticT(double[] sample1, double[] sample2)
240     throws IllegalArgumentException {
241         if ((sample1 == null) || (sample2 == null ||
242                 Math.min(sample1.length, sample2.length) < 2)) {
243             throw new IllegalArgumentException ("insufficient data for t statistic");
244         }
245         return homoscedasticT(StatUtils.mean(sample1), StatUtils.mean(sample2),
246                 StatUtils.variance(sample1), StatUtils.variance(sample2),
247                 (double) sample1.length, (double) sample2.length);
248     }
249     
250     /**
251      * Computes a 2-sample t statistic, without the hypothesis of equal
252      * subpopulation variances. To compute a t-statistic assuming equal
253      * variances, use {@link #homoscedasticT(double[], double[])}.
254      * <p>
255      * This statistic can be used to perform a two-sample t-test to compare
256      * sample means.
257      * <p>
258      * The t-statisitc is
259      * <p>
260      * &nbsp;&nbsp; <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code>
261      * <p>
262      * where <strong><code>n1</code></strong> is the size of the first sample
263      * <strong><code> n2</code></strong> is the size of the second sample;
264      * <strong><code> m1</code></strong> is the mean of the first sample;
265      * <strong><code> m2</code></strong> is the mean of the second sample;
266      * <strong><code> var1</code></strong> is the variance of the first sample;
267      * <strong><code> var2</code></strong> is the variance of the second sample;
268      * <p>
269      * <strong>Preconditions</strong>: <ul>
270      * <li>The observed array lengths must both be at least 2.
271      * </li></ul>
272      *
273      * @param sample1 array of sample data values
274      * @param sample2 array of sample data values
275      * @return t statistic
276      * @throws IllegalArgumentException if the precondition is not met
277      */
278     public double t(double[] sample1, double[] sample2)
279     throws IllegalArgumentException {
280         if ((sample1 == null) || (sample2 == null ||
281                 Math.min(sample1.length, sample2.length) < 2)) {
282             throw new IllegalArgumentException ("insufficient data for t statistic");
283         }
284         return t(StatUtils.mean(sample1), StatUtils.mean(sample2),
285                 StatUtils.variance(sample1), StatUtils.variance(sample2),
286                 (double) sample1.length, (double) sample2.length);
287     }
288
289     /**
290      * Computes a 2-sample t statistic </a>, comparing the means of the datasets
291      * described by two {@link StatisticalSummary} instances, without the
292      * assumption of equal subpopulation variances. Use
293      * {@link #homoscedasticT(StatisticalSummary, StatisticalSummary)} to
294      * compute a t-statistic under the equal variances assumption.
295      * <p>
296      * This statistic can be used to perform a two-sample t-test to compare
297      * sample means.
298      * <p>
299       * The returned t-statisitc is
300      * <p>
301      * &nbsp;&nbsp; <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code>
302      * <p>
303      * where <strong><code>n1</code></strong> is the size of the first sample;
304      * <strong><code> n2</code></strong> is the size of the second sample;
305      * <strong><code> m1</code></strong> is the mean of the first sample;
306      * <strong><code> m2</code></strong> is the mean of the second sample
307      * <strong><code> var1</code></strong> is the variance of the first sample;
308      * <strong><code> var2</code></strong> is the variance of the second sample
309      * <p>
310      * <strong>Preconditions</strong>: <ul>
311      * <li>The datasets described by the two Univariates must each contain
312      * at least 2 observations.
313      * </li></ul>
314      *
315      * @param sampleStats1 StatisticalSummary describing data from the first sample
316      * @param sampleStats2 StatisticalSummary describing data from the second sample
317      * @return t statistic
318      * @throws IllegalArgumentException if the precondition is not met
319      */
320     public double t(StatisticalSummary sampleStats1,
321             StatisticalSummary sampleStats2)
322     throws IllegalArgumentException {
323         if ((sampleStats1 == null) ||
324                 (sampleStats2 == null ||
325                         Math.min(sampleStats1.getN(), sampleStats2.getN()) < 2)) {
326             throw new IllegalArgumentException ("insufficient data for t statistic");
327         }
328         return t(sampleStats1.getMean(), sampleStats2.getMean(),
329                 sampleStats1.getVariance(), sampleStats2.getVariance(),
330                 (double) sampleStats1.getN(), (double) sampleStats2.getN());
331     }
332     
333     /**
334      * Computes a 2-sample t statistic, comparing the means of the datasets
335      * described by two {@link StatisticalSummary} instances, under the
336      * assumption of equal subpopulation variances. To compute a t-statistic
337      * without the equal variances assumption, use
338      * {@link #t(StatisticalSummary, StatisticalSummary)}.
339      * <p>
340      * This statistic can be used to perform a (homoscedastic) two-sample
341      * t-test to compare sample means.
342      * <p>
343      * The t-statisitc returned is
344      * <p>
345      * &nbsp;&nbsp;<code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code>
346      * <p>
347      * where <strong><code>n1</code></strong> is the size of first sample;
348      * <strong><code> n2</code></strong> is the size of second sample;
349      * <strong><code> m1</code></strong> is the mean of first sample;
350      * <strong><code> m2</code></strong> is the mean of second sample
351      * and <strong><code>var</code></strong> is the pooled variance estimate:
352      * <p>
353      * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code>
354      * <p>
355      * with <strong><code>var1<code></strong> the variance of the first sample and
356      * <strong><code>var2</code></strong> the variance of the second sample.
357      * <p>
358      * <strong>Preconditions</strong>: <ul>
359      * <li>The datasets described by the two Univariates must each contain
360      * at least 2 observations.
361      * </li></ul>
362      *
363      * @param sampleStats1 StatisticalSummary describing data from the first sample
364      * @param sampleStats2 StatisticalSummary describing data from the second sample
365      * @return t statistic
366      * @throws IllegalArgumentException if the precondition is not met
367      */
368     public double homoscedasticT(StatisticalSummary sampleStats1,
369             StatisticalSummary sampleStats2)
370     throws IllegalArgumentException {
371         if ((sampleStats1 == null) ||
372                 (sampleStats2 == null ||
373                         Math.min(sampleStats1.getN(), sampleStats2.getN()) < 2)) {
374             throw new IllegalArgumentException ("insufficient data for t statistic");
375         }
376         return homoscedasticT(sampleStats1.getMean(), sampleStats2.getMean(),
377                 sampleStats1.getVariance(), sampleStats2.getVariance(),
378                 (double) sampleStats1.getN(), (double) sampleStats2.getN());
379     }
380
381      /**
382      * Returns the <i>observed significance level</i>, or
383      * <i>p-value</i>, associated with a one-sample, two-tailed t-test
384      * comparing the mean of the input array with the constant <code>mu</code>.
385      * <p>
386      * The number returned is the smallest significance level
387      * at which one can reject the null hypothesis that the mean equals
388      * <code>mu</code> in favor of the two-sided alternative that the mean
389      * is different from <code>mu</code>. For a one-sided test, divide the
390      * returned value by 2.
391      * <p>
392      * <strong>Usage Note:</strong><br>
393      * The validity of the test depends on the assumptions of the parametric
394      * t-test procedure, as discussed
395      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a>
396      * <p>
397      * <strong>Preconditions</strong>: <ul>
398      * <li>The observed array length must be at least 2.
399      * </li></ul>
400      *
401      * @param mu constant value to compare sample mean against
402      * @param sample array of sample data values
403      * @return p-value
404      * @throws IllegalArgumentException if the precondition is not met
405      * @throws MathException if an error occurs computing the p-value
406      */
407     public double tTest(double mu, double[] sample)
408     throws IllegalArgumentException , MathException {
409         if ((sample == null) || (sample.length < 2)) {
410             throw new IllegalArgumentException ("insufficient data for t statistic");
411         }
412         return tTest( StatUtils.mean(sample), mu, StatUtils.variance(sample),
413                 sample.length);
414     }
415
416     /**
417      * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
418      * two-sided t-test</a> evaluating the null hypothesis that the mean of the population from
419      * which <code>sample</code> is drawn equals <code>mu</code>.
420      * <p>
421      * Returns <code>true</code> iff the null hypothesis can be
422      * rejected with confidence <code>1 - alpha</code>. To
423      * perform a 1-sided test, use <code>alpha * 2</code>
424      * <p>
425      * <strong>Examples:</strong><br><ol>
426      * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at
427      * the 95% level, use <br><code>tTest(mu, sample, 0.05) </code>
428      * </li>
429      * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code>
430      * at the 99% level, first verify that the measured sample mean is less
431      * than <code>mu</code> and then use
432      * <br><code>tTest(mu, sample, 0.02) </code>
433      * </li></ol>
434      * <p>
435      * <strong>Usage Note:</strong><br>
436      * The validity of the test depends on the assumptions of the one-sample
437      * parametric t-test procedure, as discussed
438      * <a HREF="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a>
439      * <p>
440      * <strong>Preconditions</strong>: <ul>
441      * <li>The observed array length must be at least 2.
442      * </li></ul>
443      *
444      * @param mu constant value to compare sample mean against
445      * @param sample array of sample data values
446      * @param alpha significance level of the test
447      * @return p-value
448      * @throws IllegalArgumentException if the precondition is not met
449      * @throws MathException if an error computing the p-value
450      */
451     public boolean tTest(double mu, double[] sample, double alpha)
452     throws IllegalArgumentException , MathException {
453         if ((alpha <= 0) || (alpha > 0.5)) {
454             throw new IllegalArgumentException ("bad significance level: " + alpha);
455         }
456         return (tTest(mu, sample) < alpha);
457     }
458
459     /**
460      * Returns the <i>observed significance level</i>, or
461      * <i>p-value</i>, associated with a one-sample, two-tailed t-test
462      * comparing the mean of the dataset described by <code>sampleStats</code>
463      * with the constant <code>mu</code>.
464      * <p>
465      * The number returned is the smallest significance level
466      * at which one can reject the null hypothesis that the mean equals
467      * <code>mu</code> in favor of the two-sided alternative that the mean
468      * is different from <code>mu</code>. For a one-sided test, divide the
469      * returned value by 2.
470      * <p>
471      * <strong>Usage Note:</strong><br>
472      * The validity of the test depends on the assumptions of the parametric
473      * t-test procedure, as discussed
474      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
475      * here</a>
476      * <p>
477      * <strong>Preconditions</strong>: <ul>
478      * <li>The sample must contain at least 2 observations.
479      * </li></ul>
480      *
481      * @param mu constant value to compare sample mean against
482      * @param sampleStats StatisticalSummary describing sample data
483      * @return p-value
484      * @throws IllegalArgumentException if the precondition is not met
485      * @throws MathException if an error occurs computing the p-value
486      */
487     public double tTest(double mu, StatisticalSummary sampleStats)
488     throws IllegalArgumentException , MathException {
489         if ((sampleStats == null) || (sampleStats.getN() < 2)) {
490             throw new IllegalArgumentException ("insufficient data for t statistic");
491         }
492         return tTest(sampleStats.getMean(), mu, sampleStats.getVariance(),
493                 sampleStats.getN());
494     }
495
496      /**
497      * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
498      * two-sided t-test</a> evaluating the null hypothesis that the mean of the
499      * population from which the dataset described by <code>stats</code> is
500      * drawn equals <code>mu</code>.
501      * <p>
502      * Returns <code>true</code> iff the null hypothesis can be rejected with
503      * confidence <code>1 - alpha</code>. To perform a 1-sided test, use
504      * <code>alpha * 2.</code>
505      * <p>
506      * <strong>Examples:</strong><br><ol>
507      * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at
508      * the 95% level, use <br><code>tTest(mu, sampleStats, 0.05) </code>
509      * </li>
510      * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code>
511      * at the 99% level, first verify that the measured sample mean is less
512      * than <code>mu</code> and then use
513      * <br><code>tTest(mu, sampleStats, 0.02) </code>
514      * </li></ol>
515      * <p>
516      * <strong>Usage Note:</strong><br>
517      * The validity of the test depends on the assumptions of the one-sample
518      * parametric t-test procedure, as discussed
519      * <a HREF="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a>
520      * <p>
521      * <strong>Preconditions</strong>: <ul>
522      * <li>The sample must include at least 2 observations.
523      * </li></ul>
524      *
525      * @param mu constant value to compare sample mean against
526      * @param sampleStats StatisticalSummary describing sample data values
527      * @param alpha significance level of the test
528      * @return p-value
529      * @throws IllegalArgumentException if the precondition is not met
530      * @throws MathException if an error occurs computing the p-value
531      */
532     public boolean tTest( double mu, StatisticalSummary sampleStats,
533             double alpha)
534     throws IllegalArgumentException , MathException {
535         if ((alpha <= 0) || (alpha > 0.5)) {
536             throw new IllegalArgumentException ("bad significance level: " + alpha);
537         }
538         return (tTest(mu, sampleStats) < alpha);
539     }
540
541     /**
542      * Returns the <i>observed significance level</i>, or
543      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
544      * comparing the means of the input arrays.
545      * <p>
546      * The number returned is the smallest significance level
547      * at which one can reject the null hypothesis that the two means are
548      * equal in favor of the two-sided alternative that they are different.
549      * For a one-sided test, divide the returned value by 2.
550      * <p>
551      * The test does not assume that the underlying popuation variances are
552      * equal and it uses approximated degrees of freedom computed from the
553      * sample data to compute the p-value. The t-statistic used is as defined in
554      * {@link #t(double[], double[])} and the Welch-Satterthwaite approximation
555      * to the degrees of freedom is used,
556      * as described
557      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
558      * here.</a> To perform the test under the assumption of equal subpopulation
559      * variances, use {@link #homoscedasticTTest(double[], double[])}.
560      * <p>
561      * <strong>Usage Note:</strong><br>
562      * The validity of the p-value depends on the assumptions of the parametric
563      * t-test procedure, as discussed
564      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
565      * here</a>
566      * <p>
567      * <strong>Preconditions</strong>: <ul>
568      * <li>The observed array lengths must both be at least 2.
569      * </li></ul>
570      *
571      * @param sample1 array of sample data values
572      * @param sample2 array of sample data values
573      * @return p-value for t-test
574      * @throws IllegalArgumentException if the precondition is not met
575      * @throws MathException if an error occurs computing the p-value
576      */
577     public double tTest(double[] sample1, double[] sample2)
578     throws IllegalArgumentException , MathException {
579         if ((sample1 == null) || (sample2 == null ||
580                 Math.min(sample1.length, sample2.length) < 2)) {
581             throw new IllegalArgumentException ("insufficient data");
582         }
583         return tTest(StatUtils.mean(sample1), StatUtils.mean(sample2),
584                 StatUtils.variance(sample1), StatUtils.variance(sample2),
585                 (double) sample1.length, (double) sample2.length);
586     }
587     
588     /**
589      * Returns the <i>observed significance level</i>, or
590      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
591      * comparing the means of the input arrays, under the assumption that
592      * the two samples are drawn from subpopulations with equal variances.
593      * To perform the test without the equal variances assumption, use
594      * {@link #tTest(double[], double[])}.
595      * <p>
596      * The number returned is the smallest significance level
597      * at which one can reject the null hypothesis that the two means are
598      * equal in favor of the two-sided alternative that they are different.
599      * For a one-sided test, divide the returned value by 2.
600      * <p>
601      * A pooled variance estimate is used to compute the t-statistic. See
602      * {@link #homoscedasticT(double[], double[])}. The sum of the sample sizes
603      * minus 2 is used as the degrees of freedom.
604      * <p>
605      * <strong>Usage Note:</strong><br>
606      * The validity of the p-value depends on the assumptions of the parametric
607      * t-test procedure, as discussed
608      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
609      * here</a>
610      * <p>
611      * <strong>Preconditions</strong>: <ul>
612      * <li>The observed array lengths must both be at least 2.
613      * </li></ul>
614      *
615      * @param sample1 array of sample data values
616      * @param sample2 array of sample data values
617      * @return p-value for t-test
618      * @throws IllegalArgumentException if the precondition is not met
619      * @throws MathException if an error occurs computing the p-value
620      */
621     public double homoscedasticTTest(double[] sample1, double[] sample2)
622     throws IllegalArgumentException , MathException {
623         if ((sample1 == null) || (sample2 == null ||
624                 Math.min(sample1.length, sample2.length) < 2)) {
625             throw new IllegalArgumentException ("insufficient data");
626         }
627         return homoscedasticTTest(StatUtils.mean(sample1),
628                 StatUtils.mean(sample2), StatUtils.variance(sample1),
629                 StatUtils.variance(sample2), (double) sample1.length,
630                 (double) sample2.length);
631     }
632     
633
634      /**
635      * Performs a
636      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
637      * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code>
638      * and <code>sample2</code> are drawn from populations with the same mean,
639      * with significance level <code>alpha</code>. This test does not assume
640      * that the subpopulation variances are equal. To perform the test assuming
641      * equal variances, use
642      * {@link #homoscedasticTTest(double[], double[], double)}.
643      * <p>
644      * Returns <code>true</code> iff the null hypothesis that the means are
645      * equal can be rejected with confidence <code>1 - alpha</code>. To
646      * perform a 1-sided test, use <code>alpha / 2</code>
647      * <p>
648      * See {@link #t(double[], double[])} for the formula used to compute the
649      * t-statistic. Degrees of freedom are approximated using the
650      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
651      * Welch-Satterthwaite approximation.</a>
652       
653      * <p>
654      * <strong>Examples:</strong><br><ol>
655      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
656      * the 95% level, use
657      * <br><code>tTest(sample1, sample2, 0.05). </code>
658      * </li>
659      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code> at
660      * the 99% level, first verify that the measured mean of <code>sample 1</code>
661      * is less than the mean of <code>sample 2</code> and then use
662      * <br><code>tTest(sample1, sample2, 0.02) </code>
663      * </li></ol>
664      * <p>
665      * <strong>Usage Note:</strong><br>
666      * The validity of the test depends on the assumptions of the parametric
667      * t-test procedure, as discussed
668      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
669      * here</a>
670      * <p>
671      * <strong>Preconditions</strong>: <ul>
672      * <li>The observed array lengths must both be at least 2.
673      * </li>
674      * <li> <code> 0 < alpha < 0.5 </code>
675      * </li></ul>
676      *
677      * @param sample1 array of sample data values
678      * @param sample2 array of sample data values
679      * @param alpha significance level of the test
680      * @return true if the null hypothesis can be rejected with
681      * confidence 1 - alpha
682      * @throws IllegalArgumentException if the preconditions are not met
683      * @throws MathException if an error occurs performing the test
684      */
685     public boolean tTest(double[] sample1, double[] sample2,
686             double alpha)
687     throws IllegalArgumentException , MathException {
688         if ((alpha <= 0) || (alpha > 0.5)) {
689             throw new IllegalArgumentException ("bad significance level: " + alpha);
690         }
691         return (tTest(sample1, sample2) < alpha);
692     }
693     
694     /**
695      * Performs a
696      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
697      * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code>
698      * and <code>sample2</code> are drawn from populations with the same mean,
699      * with significance level <code>alpha</code>, assuming that the
700      * subpopulation variances are equal. Use
701      * {@link #tTest(double[], double[], double)} to perform the test without
702      * the assumption of equal variances.
703      * <p>
704      * Returns <code>true</code> iff the null hypothesis that the means are
705      * equal can be rejected with confidence <code>1 - alpha</code>. To
706      * perform a 1-sided test, use <code>alpha * 2.</code> To perform the test
707      * without the assumption of equal subpopulation variances, use
708      * {@link #tTest(double[], double[], double)}.
709      * <p>
710      * A pooled variance estimate is used to compute the t-statistic. See
711      * {@link #t(double[], double[])} for the formula. The sum of the sample
712      * sizes minus 2 is used as the degrees of freedom.
713      * <p>
714      * <strong>Examples:</strong><br><ol>
715      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
716      * the 95% level, use <br><code>tTest(sample1, sample2, 0.05). </code>
717      * </li>
718      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2, </code>
719      * at the 99% level, first verify that the measured mean of
720      * <code>sample 1</code> is less than the mean of <code>sample 2</code>
721      * and then use
722      * <br><code>tTest(sample1, sample2, 0.02) </code>
723      * </li></ol>
724      * <p>
725      * <strong>Usage Note:</strong><br>
726      * The validity of the test depends on the assumptions of the parametric
727      * t-test procedure, as discussed
728      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
729      * here</a>
730      * <p>
731      * <strong>Preconditions</strong>: <ul>
732      * <li>The observed array lengths must both be at least 2.
733      * </li>
734      * <li> <code> 0 < alpha < 0.5 </code>
735      * </li></ul>
736      *
737      * @param sample1 array of sample data values
738      * @param sample2 array of sample data values
739      * @param alpha significance level of the test
740      * @return true if the null hypothesis can be rejected with
741      * confidence 1 - alpha
742      * @throws IllegalArgumentException if the preconditions are not met
743      * @throws MathException if an error occurs performing the test
744      */
745     public boolean homoscedasticTTest(double[] sample1, double[] sample2,
746             double alpha)
747     throws IllegalArgumentException , MathException {
748         if ((alpha <= 0) || (alpha > 0.5)) {
749             throw new IllegalArgumentException ("bad significance level: " + alpha);
750         }
751         return (homoscedasticTTest(sample1, sample2) < alpha);
752     }
753
754      /**
755      * Returns the <i>observed significance level</i>, or
756      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
757      * comparing the means of the datasets described by two StatisticalSummary
758      * instances.
759      * <p>
760      * The number returned is the smallest significance level
761      * at which one can reject the null hypothesis that the two means are
762      * equal in favor of the two-sided alternative that they are different.
763      * For a one-sided test, divide the returned value by 2.
764      * <p>
765      * The test does not assume that the underlying popuation variances are
766      * equal and it uses approximated degrees of freedom computed from the
767      * sample data to compute the p-value. To perform the test assuming
768      * equal variances, use
769      * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}.
770      * <p>
771      * <strong>Usage Note:</strong><br>
772      * The validity of the p-value depends on the assumptions of the parametric
773      * t-test procedure, as discussed
774      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
775      * here</a>
776      * <p>
777      * <strong>Preconditions</strong>: <ul>
778      * <li>The datasets described by the two Univariates must each contain
779      * at least 2 observations.
780      * </li></ul>
781      *
782      * @param sampleStats1 StatisticalSummary describing data from the first sample
783      * @param sampleStats2 StatisticalSummary describing data from the second sample
784      * @return p-value for t-test
785      * @throws IllegalArgumentException if the precondition is not met
786      * @throws MathException if an error occurs computing the p-value
787      */
788     public double tTest(StatisticalSummary sampleStats1, StatisticalSummary sampleStats2)
789     throws IllegalArgumentException , MathException {
790         if ((sampleStats1 == null) || (sampleStats2 == null ||
791                 Math.min(sampleStats1.getN(), sampleStats2.getN()) < 2)) {
792             throw new IllegalArgumentException ("insufficient data for t statistic");
793         }
794         return tTest(sampleStats1.getMean(), sampleStats2.getMean(), sampleStats1.getVariance(),
795                 sampleStats2.getVariance(), (double) sampleStats1.getN(),
796                 (double) sampleStats2.getN());
797     }
798     
799     /**
800      * Returns the <i>observed significance level</i>, or
801      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
802      * comparing the means of the datasets described by two StatisticalSummary
803      * instances, under the hypothesis of equal subpopulation variances. To
804      * perform a test without the equal variances assumption, use
805      * {@link #tTest(StatisticalSummary, StatisticalSummary)}.
806      * <p>
807      * The number returned is the smallest significance level
808      * at which one can reject the null hypothesis that the two means are
809      * equal in favor of the two-sided alternative that they are different.
810      * For a one-sided test, divide the returned value by 2.
811      * <p>
812      * See {@link #homoscedasticT(double[], double[])} for the formula used to
813      * compute the t-statistic. The sum of the sample sizes minus 2 is used as
814      * the degrees of freedom.
815      * <p>
816      * <strong>Usage Note:</strong><br>
817      * The validity of the p-value depends on the assumptions of the parametric
818      * t-test procedure, as discussed
819      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a>
820      * <p>
821      * <strong>Preconditions</strong>: <ul>
822      * <li>The datasets described by the two Univariates must each contain
823      * at least 2 observations.
824      * </li></ul>
825      *
826      * @param sampleStats1 StatisticalSummary describing data from the first sample
827      * @param sampleStats2 StatisticalSummary describing data from the second sample
828      * @return p-value for t-test
829      * @throws IllegalArgumentException if the precondition is not met
830      * @throws MathException if an error occurs computing the p-value
831      */
832     public double homoscedasticTTest(StatisticalSummary sampleStats1,
833             StatisticalSummary sampleStats2)
834     throws IllegalArgumentException , MathException {
835         if ((sampleStats1 == null) || (sampleStats2 == null ||
836                 Math.min(sampleStats1.getN(), sampleStats2.getN()) < 2)) {
837             throw new IllegalArgumentException ("insufficient data for t statistic");
838         }
839         return homoscedasticTTest(sampleStats1.getMean(),
840                 sampleStats2.getMean(), sampleStats1.getVariance(),
841                 sampleStats2.getVariance(), (double) sampleStats1.getN(),
842                 (double) sampleStats2.getN());
843     }
844
845     /**
846      * Performs a
847      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
848      * two-sided t-test</a> evaluating the null hypothesis that
849      * <code>sampleStats1</code> and <code>sampleStats2</code> describe
850      * datasets drawn from populations with the same mean, with significance
851      * level <code>alpha</code>. This test does not assume that the
852      * subpopulation variances are equal. To perform the test under the equal
853      * variances assumption, use
854      * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}.
855      * <p>
856      * Returns <code>true</code> iff the null hypothesis that the means are
857      * equal can be rejected with confidence <code>1 - alpha</code>. To
858      * perform a 1-sided test, use <code>alpha * 2</code>
859      * <p>
860      * See {@link #t(double[], double[])} for the formula used to compute the
861      * t-statistic. Degrees of freedom are approximated using the
862      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
863      * Welch-Satterthwaite approximation.</a>
864      * <p>
865      * <strong>Examples:</strong><br><ol>
866      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
867      * the 95%, use
868      * <br><code>tTest(sampleStats1, sampleStats2, 0.05) </code>
869      * </li>
870      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code>
871      * at the 99% level, first verify that the measured mean of
872      * <code>sample 1</code> is less than the mean of <code>sample 2</code>
873      * and then use
874      * <br><code>tTest(sampleStats1, sampleStats2, 0.02) </code>
875      * </li></ol>
876      * <p>
877