KickJava   Java API By Example, From Geeks To Geeks.

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


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.stat.descriptive.StatisticalSummary;
20
21 /**
22  * An interface for Student's t-tests.
23  * <p>
24  * Tests can be:<ul>
25  * <li>One-sample or two-sample</li>
26  * <li>One-sided or two-sided</li>
27  * <li>Paired or unpaired (for two-sample tests)</li>
28  * <li>Homoscedastic (equal variance assumption) or heteroscedastic
29  * (for two sample tests)</li>
30  * <li>Fixed significance level (boolean-valued) or returning p-values.
31  * </li></ul>
32  * <p>
33  * Test statistics are available for all tests. Methods including "Test" in
34  * in their names perform tests, all other methods return t-statistics. Among
35  * the "Test" methods, <code>double-</code>valued methods return p-values;
36  * <code>boolean-</code>valued methods perform fixed significance level tests.
37  * Significance levels are always specified as numbers between 0 and 0.5
38  * (e.g. tests at the 95% level use <code>alpha=0.05</code>).
39  * <p>
40  * Input to tests can be either <code>double[]</code> arrays or
41  * {@link StatisticalSummary} instances.
42  *
43  *
44  * @version $Revision$ $Date: 2005-04-16 22:12:15 -0700 (Sat, 16 Apr 2005) $
45  */
46 public interface TTest {
47     /**
48      * Computes a paired, 2-sample t-statistic based on the data in the input
49      * arrays. The t-statistic returned is equivalent to what would be returned by
50      * computing the one-sample t-statistic {@link #t(double, double[])}, with
51      * <code>mu = 0</code> and the sample array consisting of the (signed)
52      * differences between corresponding entries in <code>sample1</code> and
53      * <code>sample2.</code>
54      * <p>
55      * <strong>Preconditions</strong>: <ul>
56      * <li>The input arrays must have the same length and their common length
57      * must be at least 2.
58      * </li></ul>
59      *
60      * @param sample1 array of sample data values
61      * @param sample2 array of sample data values
62      * @return t statistic
63      * @throws IllegalArgumentException if the precondition is not met
64      * @throws MathException if the statistic can not be computed do to a
65      * convergence or other numerical error.
66      */
67     public abstract double pairedT(double[] sample1, double[] sample2)
68         throws IllegalArgumentException JavaDoc, MathException;
69     /**
70      * Returns the <i>observed significance level</i>, or
71      * <i> p-value</i>, associated with a paired, two-sample, two-tailed t-test
72      * based on the data in the input arrays.
73      * <p>
74      * The number returned is the smallest significance level
75      * at which one can reject the null hypothesis that the mean of the paired
76      * differences is 0 in favor of the two-sided alternative that the mean paired
77      * difference is not equal to 0. For a one-sided test, divide the returned
78      * value by 2.
79      * <p>
80      * This test is equivalent to a one-sample t-test computed using
81      * {@link #tTest(double, double[])} with <code>mu = 0</code> and the sample
82      * array consisting of the signed differences between corresponding elements of
83      * <code>sample1</code> and <code>sample2.</code>
84      * <p>
85      * <strong>Usage Note:</strong><br>
86      * The validity of the p-value depends on the assumptions of the parametric
87      * t-test procedure, as discussed
88      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
89      * here</a>
90      * <p>
91      * <strong>Preconditions</strong>: <ul>
92      * <li>The input array lengths must be the same and their common length must
93      * be at least 2.
94      * </li></ul>
95      *
96      * @param sample1 array of sample data values
97      * @param sample2 array of sample data values
98      * @return p-value for t-test
99      * @throws IllegalArgumentException if the precondition is not met
100      * @throws MathException if an error occurs computing the p-value
101      */
102     public abstract double pairedTTest(double[] sample1, double[] sample2)
103         throws IllegalArgumentException JavaDoc, MathException;
104     /**
105      * Performs a paired t-test evaluating the null hypothesis that the
106      * mean of the paired differences between <code>sample1</code> and
107      * <code>sample2</code> is 0 in favor of the two-sided alternative that the
108      * mean paired difference is not equal to 0, with significance level
109      * <code>alpha</code>.
110      * <p>
111      * Returns <code>true</code> iff the null hypothesis can be rejected with
112      * confidence <code>1 - alpha</code>. To perform a 1-sided test, use
113      * <code>alpha * 2</code>
114      * <p>
115      * <strong>Usage Note:</strong><br>
116      * The validity of the test depends on the assumptions of the parametric
117      * t-test procedure, as discussed
118      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
119      * here</a>
120      * <p>
121      * <strong>Preconditions</strong>: <ul>
122      * <li>The input array lengths must be the same and their common length
123      * must be at least 2.
124      * </li>
125      * <li> <code> 0 < alpha < 0.5 </code>
126      * </li></ul>
127      *
128      * @param sample1 array of sample data values
129      * @param sample2 array of sample data values
130      * @param alpha significance level of the test
131      * @return true if the null hypothesis can be rejected with
132      * confidence 1 - alpha
133      * @throws IllegalArgumentException if the preconditions are not met
134      * @throws MathException if an error occurs performing the test
135      */
136     public abstract boolean pairedTTest(
137         double[] sample1,
138         double[] sample2,
139         double alpha)
140         throws IllegalArgumentException JavaDoc, MathException;
141     /**
142      * Computes a <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula">
143      * t statistic </a> given observed values and a comparison constant.
144      * <p>
145      * This statistic can be used to perform a one sample t-test for the mean.
146      * <p>
147      * <strong>Preconditions</strong>: <ul>
148      * <li>The observed array length must be at least 2.
149      * </li></ul>
150      *
151      * @param mu comparison constant
152      * @param observed array of values
153      * @return t statistic
154      * @throws IllegalArgumentException if input array length is less than 2
155      */
156     public abstract double t(double mu, double[] observed)
157         throws IllegalArgumentException JavaDoc;
158     /**
159      * Computes a <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula">
160      * t statistic </a> to use in comparing the mean of the dataset described by
161      * <code>sampleStats</code> to <code>mu</code>.
162      * <p>
163      * This statistic can be used to perform a one sample t-test for the mean.
164      * <p>
165      * <strong>Preconditions</strong>: <ul>
166      * <li><code>observed.getN() > = 2</code>.
167      * </li></ul>
168      *
169      * @param mu comparison constant
170      * @param sampleStats DescriptiveStatistics holding sample summary statitstics
171      * @return t statistic
172      * @throws IllegalArgumentException if the precondition is not met
173      */
174     public abstract double t(double mu, StatisticalSummary sampleStats)
175         throws IllegalArgumentException JavaDoc;
176     /**
177      * Computes a 2-sample t statistic, under the hypothesis of equal
178      * subpopulation variances. To compute a t-statistic without the
179      * equal variances hypothesis, use {@link #t(double[], double[])}.
180      * <p>
181      * This statistic can be used to perform a (homoscedastic) two-sample
182      * t-test to compare sample means.
183      * <p>
184      * The t-statisitc is
185      * <p>
186      * &nbsp;&nbsp;<code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code>
187      * <p>
188      * where <strong><code>n1</code></strong> is the size of first sample;
189      * <strong><code> n2</code></strong> is the size of second sample;
190      * <strong><code> m1</code></strong> is the mean of first sample;
191      * <strong><code> m2</code></strong> is the mean of second sample</li>
192      * </ul>
193      * and <strong><code>var</code></strong> is the pooled variance estimate:
194      * <p>
195      * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code>
196      * <p>
197      * with <strong><code>var1<code></strong> the variance of the first sample and
198      * <strong><code>var2</code></strong> the variance of the second sample.
199      * <p>
200      * <strong>Preconditions</strong>: <ul>
201      * <li>The observed array lengths must both be at least 2.
202      * </li></ul>
203      *
204      * @param sample1 array of sample data values
205      * @param sample2 array of sample data values
206      * @return t statistic
207      * @throws IllegalArgumentException if the precondition is not met
208      */
209     public abstract double homoscedasticT(double[] sample1, double[] sample2)
210         throws IllegalArgumentException JavaDoc;
211     /**
212      * Computes a 2-sample t statistic, without the hypothesis of equal
213      * subpopulation variances. To compute a t-statistic assuming equal
214      * variances, use {@link #homoscedasticT(double[], double[])}.
215      * <p>
216      * This statistic can be used to perform a two-sample t-test to compare
217      * sample means.
218      * <p>
219      * The t-statisitc is
220      * <p>
221      * &nbsp;&nbsp; <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code>
222      * <p>
223      * where <strong><code>n1</code></strong> is the size of the first sample
224      * <strong><code> n2</code></strong> is the size of the second sample;
225      * <strong><code> m1</code></strong> is the mean of the first sample;
226      * <strong><code> m2</code></strong> is the mean of the second sample;
227      * <strong><code> var1</code></strong> is the variance of the first sample;
228      * <strong><code> var2</code></strong> is 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 abstract double t(double[] sample1, double[] sample2)
240         throws IllegalArgumentException JavaDoc;
241     /**
242      * Computes a 2-sample t statistic </a>, comparing the means of the datasets
243      * described by two {@link StatisticalSummary} instances, without the
244      * assumption of equal subpopulation variances. Use
245      * {@link #homoscedasticT(StatisticalSummary, StatisticalSummary)} to
246      * compute a t-statistic under the equal variances assumption.
247      * <p>
248      * This statistic can be used to perform a two-sample t-test to compare
249      * sample means.
250      * <p>
251       * The returned t-statisitc is
252      * <p>
253      * &nbsp;&nbsp; <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code>
254      * <p>
255      * where <strong><code>n1</code></strong> is the size of the first sample;
256      * <strong><code> n2</code></strong> is the size of the second sample;
257      * <strong><code> m1</code></strong> is the mean of the first sample;
258      * <strong><code> m2</code></strong> is the mean of the second sample
259      * <strong><code> var1</code></strong> is the variance of the first sample;
260      * <strong><code> var2</code></strong> is the variance of the second sample
261      * <p>
262      * <strong>Preconditions</strong>: <ul>
263      * <li>The datasets described by the two Univariates must each contain
264      * at least 2 observations.
265      * </li></ul>
266      *
267      * @param sampleStats1 StatisticalSummary describing data from the first sample
268      * @param sampleStats2 StatisticalSummary describing data from the second sample
269      * @return t statistic
270      * @throws IllegalArgumentException if the precondition is not met
271      */
272     public abstract double t(
273         StatisticalSummary sampleStats1,
274         StatisticalSummary sampleStats2)
275         throws IllegalArgumentException JavaDoc;
276     /**
277      * Computes a 2-sample t statistic, comparing the means of the datasets
278      * described by two {@link StatisticalSummary} instances, under the
279      * assumption of equal subpopulation variances. To compute a t-statistic
280      * without the equal variances assumption, use
281      * {@link #t(StatisticalSummary, StatisticalSummary)}.
282      * <p>
283      * This statistic can be used to perform a (homoscedastic) two-sample
284      * t-test to compare sample means.
285      * <p>
286      * The t-statisitc returned is
287      * <p>
288      * &nbsp;&nbsp;<code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code>
289      * <p>
290      * where <strong><code>n1</code></strong> is the size of first sample;
291      * <strong><code> n2</code></strong> is the size of second sample;
292      * <strong><code> m1</code></strong> is the mean of first sample;
293      * <strong><code> m2</code></strong> is the mean of second sample
294      * and <strong><code>var</code></strong> is the pooled variance estimate:
295      * <p>
296      * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code>
297      * <p>
298      * with <strong><code>var1<code></strong> the variance of the first sample and
299      * <strong><code>var2</code></strong> the variance of the second sample.
300      * <p>
301      * <strong>Preconditions</strong>: <ul>
302      * <li>The datasets described by the two Univariates must each contain
303      * at least 2 observations.
304      * </li></ul>
305      *
306      * @param sampleStats1 StatisticalSummary describing data from the first sample
307      * @param sampleStats2 StatisticalSummary describing data from the second sample
308      * @return t statistic
309      * @throws IllegalArgumentException if the precondition is not met
310      */
311     public abstract double homoscedasticT(
312         StatisticalSummary sampleStats1,
313         StatisticalSummary sampleStats2)
314         throws IllegalArgumentException JavaDoc;
315     /**
316      * Returns the <i>observed significance level</i>, or
317      * <i>p-value</i>, associated with a one-sample, two-tailed t-test
318      * comparing the mean of the input array with the constant <code>mu</code>.
319      * <p>
320      * The number returned is the smallest significance level
321      * at which one can reject the null hypothesis that the mean equals
322      * <code>mu</code> in favor of the two-sided alternative that the mean
323      * is different from <code>mu</code>. For a one-sided test, divide the
324      * returned value by 2.
325      * <p>
326      * <strong>Usage Note:</strong><br>
327      * The validity of the test depends on the assumptions of the parametric
328      * t-test procedure, as discussed
329      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a>
330      * <p>
331      * <strong>Preconditions</strong>: <ul>
332      * <li>The observed array length must be at least 2.
333      * </li></ul>
334      *
335      * @param mu constant value to compare sample mean against
336      * @param sample array of sample data values
337      * @return p-value
338      * @throws IllegalArgumentException if the precondition is not met
339      * @throws MathException if an error occurs computing the p-value
340      */
341     public abstract double tTest(double mu, double[] sample)
342         throws IllegalArgumentException JavaDoc, MathException;
343     /**
344      * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
345      * two-sided t-test</a> evaluating the null hypothesis that the mean of the population from
346      * which <code>sample</code> is drawn equals <code>mu</code>.
347      * <p>
348      * Returns <code>true</code> iff the null hypothesis can be
349      * rejected with confidence <code>1 - alpha</code>. To
350      * perform a 1-sided test, use <code>alpha * 2</code>
351      * <p>
352      * <strong>Examples:</strong><br><ol>
353      * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at
354      * the 95% level, use <br><code>tTest(mu, sample, 0.05) </code>
355      * </li>
356      * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code>
357      * at the 99% level, first verify that the measured sample mean is less
358      * than <code>mu</code> and then use
359      * <br><code>tTest(mu, sample, 0.02) </code>
360      * </li></ol>
361      * <p>
362      * <strong>Usage Note:</strong><br>
363      * The validity of the test depends on the assumptions of the one-sample
364      * parametric t-test procedure, as discussed
365      * <a HREF="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a>
366      * <p>
367      * <strong>Preconditions</strong>: <ul>
368      * <li>The observed array length must be at least 2.
369      * </li></ul>
370      *
371      * @param mu constant value to compare sample mean against
372      * @param sample array of sample data values
373      * @param alpha significance level of the test
374      * @return p-value
375      * @throws IllegalArgumentException if the precondition is not met
376      * @throws MathException if an error computing the p-value
377      */
378     public abstract boolean tTest(double mu, double[] sample, double alpha)
379         throws IllegalArgumentException JavaDoc, MathException;
380     /**
381      * Returns the <i>observed significance level</i>, or
382      * <i>p-value</i>, associated with a one-sample, two-tailed t-test
383      * comparing the mean of the dataset described by <code>sampleStats</code>
384      * 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">
396      * here</a>
397      * <p>
398      * <strong>Preconditions</strong>: <ul>
399      * <li>The sample must contain at least 2 observations.
400      * </li></ul>
401      *
402      * @param mu constant value to compare sample mean against
403      * @param sampleStats StatisticalSummary describing sample data
404      * @return p-value
405      * @throws IllegalArgumentException if the precondition is not met
406      * @throws MathException if an error occurs computing the p-value
407      */
408     public abstract double tTest(double mu, StatisticalSummary sampleStats)
409         throws IllegalArgumentException JavaDoc, MathException;
410     /**
411      * Performs a <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
412      * two-sided t-test</a> evaluating the null hypothesis that the mean of the
413      * population from which the dataset described by <code>stats</code> is
414      * drawn equals <code>mu</code>.
415      * <p>
416      * Returns <code>true</code> iff the null hypothesis can be rejected with
417      * confidence <code>1 - alpha</code>. To perform a 1-sided test, use
418      * <code>alpha * 2.</code>
419      * <p>
420      * <strong>Examples:</strong><br><ol>
421      * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at
422      * the 95% level, use <br><code>tTest(mu, sampleStats, 0.05) </code>
423      * </li>
424      * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code>
425      * at the 99% level, first verify that the measured sample mean is less
426      * than <code>mu</code> and then use
427      * <br><code>tTest(mu, sampleStats, 0.02) </code>
428      * </li></ol>
429      * <p>
430      * <strong>Usage Note:</strong><br>
431      * The validity of the test depends on the assumptions of the one-sample
432      * parametric t-test procedure, as discussed
433      * <a HREF="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a>
434      * <p>
435      * <strong>Preconditions</strong>: <ul>
436      * <li>The sample must include at least 2 observations.
437      * </li></ul>
438      *
439      * @param mu constant value to compare sample mean against
440      * @param sampleStats StatisticalSummary describing sample data values
441      * @param alpha significance level of the test
442      * @return p-value
443      * @throws IllegalArgumentException if the precondition is not met
444      * @throws MathException if an error occurs computing the p-value
445      */
446     public abstract boolean tTest(
447         double mu,
448         StatisticalSummary sampleStats,
449         double alpha)
450         throws IllegalArgumentException JavaDoc, MathException;
451     /**
452      * Returns the <i>observed significance level</i>, or
453      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
454      * comparing the means of the input arrays.
455      * <p>
456      * The number returned is the smallest significance level
457      * at which one can reject the null hypothesis that the two means are
458      * equal in favor of the two-sided alternative that they are different.
459      * For a one-sided test, divide the returned value by 2.
460      * <p>
461      * The test does not assume that the underlying popuation variances are
462      * equal and it uses approximated degrees of freedom computed from the
463      * sample data to compute the p-value. The t-statistic used is as defined in
464      * {@link #t(double[], double[])} and the Welch-Satterthwaite approximation
465      * to the degrees of freedom is used,
466      * as described
467      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
468      * here.</a> To perform the test under the assumption of equal subpopulation
469      * variances, use {@link #homoscedasticTTest(double[], double[])}.
470      * <p>
471      * <strong>Usage Note:</strong><br>
472      * The validity of the p-value 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 observed array lengths must both be at least 2.
479      * </li></ul>
480      *
481      * @param sample1 array of sample data values
482      * @param sample2 array of sample data values
483      * @return p-value for t-test
484      * @throws IllegalArgumentException if the precondition is not met
485      * @throws MathException if an error occurs computing the p-value
486      */
487     public abstract double tTest(double[] sample1, double[] sample2)
488         throws IllegalArgumentException JavaDoc, MathException;
489     /**
490      * Returns the <i>observed significance level</i>, or
491      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
492      * comparing the means of the input arrays, under the assumption that
493      * the two samples are drawn from subpopulations with equal variances.
494      * To perform the test without the equal variances assumption, use
495      * {@link #tTest(double[], double[])}.
496      * <p>
497      * The number returned is the smallest significance level
498      * at which one can reject the null hypothesis that the two means are
499      * equal in favor of the two-sided alternative that they are different.
500      * For a one-sided test, divide the returned value by 2.
501      * <p>
502      * A pooled variance estimate is used to compute the t-statistic. See
503      * {@link #homoscedasticT(double[], double[])}. The sum of the sample sizes
504      * minus 2 is used as the degrees of freedom.
505      * <p>
506      * <strong>Usage Note:</strong><br>
507      * The validity of the p-value depends on the assumptions of the parametric
508      * t-test procedure, as discussed
509      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
510      * here</a>
511      * <p>
512      * <strong>Preconditions</strong>: <ul>
513      * <li>The observed array lengths must both be at least 2.
514      * </li></ul>
515      *
516      * @param sample1 array of sample data values
517      * @param sample2 array of sample data values
518      * @return p-value for t-test
519      * @throws IllegalArgumentException if the precondition is not met
520      * @throws MathException if an error occurs computing the p-value
521      */
522     public abstract double homoscedasticTTest(
523         double[] sample1,
524         double[] sample2)
525         throws IllegalArgumentException JavaDoc, MathException;
526     /**
527      * Performs a
528      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
529      * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code>
530      * and <code>sample2</code> are drawn from populations with the same mean,
531      * with significance level <code>alpha</code>. This test does not assume
532      * that the subpopulation variances are equal. To perform the test assuming
533      * equal variances, use
534      * {@link #homoscedasticTTest(double[], double[], double)}.
535      * <p>
536      * Returns <code>true</code> iff the null hypothesis that the means are
537      * equal can be rejected with confidence <code>1 - alpha</code>. To
538      * perform a 1-sided test, use <code>alpha * 2</code>
539      * <p>
540      * See {@link #t(double[], double[])} for the formula used to compute the
541      * t-statistic. Degrees of freedom are approximated using the
542      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
543      * Welch-Satterthwaite approximation.</a>
544     
545      * <p>
546      * <strong>Examples:</strong><br><ol>
547      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
548      * the 95% level, use
549      * <br><code>tTest(sample1, sample2, 0.05). </code>
550      * </li>
551      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code>,
552      * at the 99% level, first verify that the measured mean of <code>sample 1</code>
553      * is less than the mean of <code>sample 2</code> and then use
554      * <br><code>tTest(sample1, sample2, 0.02) </code>
555      * </li></ol>
556      * <p>
557      * <strong>Usage Note:</strong><br>
558      * The validity of the test depends on the assumptions of the parametric
559      * t-test procedure, as discussed
560      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
561      * here</a>
562      * <p>
563      * <strong>Preconditions</strong>: <ul>
564      * <li>The observed array lengths must both be at least 2.
565      * </li>
566      * <li> <code> 0 < alpha < 0.5 </code>
567      * </li></ul>
568      *
569      * @param sample1 array of sample data values
570      * @param sample2 array of sample data values
571      * @param alpha significance level of the test
572      * @return true if the null hypothesis can be rejected with
573      * confidence 1 - alpha
574      * @throws IllegalArgumentException if the preconditions are not met
575      * @throws MathException if an error occurs performing the test
576      */
577     public abstract boolean tTest(
578         double[] sample1,
579         double[] sample2,
580         double alpha)
581         throws IllegalArgumentException JavaDoc, MathException;
582     /**
583      * Performs a
584      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
585      * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code>
586      * and <code>sample2</code> are drawn from populations with the same mean,
587      * with significance level <code>alpha</code>, assuming that the
588      * subpopulation variances are equal. Use
589      * {@link #tTest(double[], double[], double)} to perform the test without
590      * the assumption of equal variances.
591      * <p>
592      * Returns <code>true</code> iff the null hypothesis that the means are
593      * equal can be rejected with confidence <code>1 - alpha</code>. To
594      * perform a 1-sided test, use <code>alpha * 2.</code> To perform the test
595      * without the assumption of equal subpopulation variances, use
596      * {@link #tTest(double[], double[], double)}.
597      * <p>
598      * A pooled variance estimate is used to compute the t-statistic. See
599      * {@link #t(double[], double[])} for the formula. The sum of the sample
600      * sizes minus 2 is used as the degrees of freedom.
601      * <p>
602      * <strong>Examples:</strong><br><ol>
603      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
604      * the 95% level, use <br><code>tTest(sample1, sample2, 0.05). </code>
605      * </li>
606      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2, </code>
607      * at the 99% level, first verify that the measured mean of
608      * <code>sample 1</code> is less than the mean of <code>sample 2</code>
609      * and then use
610      * <br><code>tTest(sample1, sample2, 0.02) </code>
611      * </li></ol>
612      * <p>
613      * <strong>Usage Note:</strong><br>
614      * The validity of the test depends on the assumptions of the parametric
615      * t-test procedure, as discussed
616      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
617      * here</a>
618      * <p>
619      * <strong>Preconditions</strong>: <ul>
620      * <li>The observed array lengths must both be at least 2.
621      * </li>
622      * <li> <code> 0 < alpha < 0.5 </code>
623      * </li></ul>
624      *
625      * @param sample1 array of sample data values
626      * @param sample2 array of sample data values
627      * @param alpha significance level of the test
628      * @return true if the null hypothesis can be rejected with
629      * confidence 1 - alpha
630      * @throws IllegalArgumentException if the preconditions are not met
631      * @throws MathException if an error occurs performing the test
632      */
633     public abstract boolean homoscedasticTTest(
634         double[] sample1,
635         double[] sample2,
636         double alpha)
637         throws IllegalArgumentException JavaDoc, MathException;
638     /**
639      * Returns the <i>observed significance level</i>, or
640      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
641      * comparing the means of the datasets described by two StatisticalSummary
642      * instances.
643      * <p>
644      * The number returned is the smallest significance level
645      * at which one can reject the null hypothesis that the two means are
646      * equal in favor of the two-sided alternative that they are different.
647      * For a one-sided test, divide the returned value by 2.
648      * <p>
649      * The test does not assume that the underlying popuation variances are
650      * equal and it uses approximated degrees of freedom computed from the
651      * sample data to compute the p-value. To perform the test assuming
652      * equal variances, use
653      * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}.
654      * <p>
655      * <strong>Usage Note:</strong><br>
656      * The validity of the p-value depends on the assumptions of the parametric
657      * t-test procedure, as discussed
658      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
659      * here</a>
660      * <p>
661      * <strong>Preconditions</strong>: <ul>
662      * <li>The datasets described by the two Univariates must each contain
663      * at least 2 observations.
664      * </li></ul>
665      *
666      * @param sampleStats1 StatisticalSummary describing data from the first sample
667      * @param sampleStats2 StatisticalSummary describing data from the second sample
668      * @return p-value for t-test
669      * @throws IllegalArgumentException if the precondition is not met
670      * @throws MathException if an error occurs computing the p-value
671      */
672     public abstract double tTest(
673         StatisticalSummary sampleStats1,
674         StatisticalSummary sampleStats2)
675         throws IllegalArgumentException JavaDoc, MathException;
676     /**
677      * Returns the <i>observed significance level</i>, or
678      * <i>p-value</i>, associated with a two-sample, two-tailed t-test
679      * comparing the means of the datasets described by two StatisticalSummary
680      * instances, under the hypothesis of equal subpopulation variances. To
681      * perform a test without the equal variances assumption, use
682      * {@link #tTest(StatisticalSummary, StatisticalSummary)}.
683      * <p>
684      * The number returned is the smallest significance level
685      * at which one can reject the null hypothesis that the two means are
686      * equal in favor of the two-sided alternative that they are different.
687      * For a one-sided test, divide the returned value by 2.
688      * <p>
689      * See {@link #homoscedasticT(double[], double[])} for the formula used to
690      * compute the t-statistic. The sum of the sample sizes minus 2 is used as
691      * the degrees of freedom.
692      * <p>
693      * <strong>Usage Note:</strong><br>
694      * The validity of the p-value depends on the assumptions of the parametric
695      * t-test procedure, as discussed
696      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a>
697      * <p>
698      * <strong>Preconditions</strong>: <ul>
699      * <li>The datasets described by the two Univariates must each contain
700      * at least 2 observations.
701      * </li></ul>
702      *
703      * @param sampleStats1 StatisticalSummary describing data from the first sample
704      * @param sampleStats2 StatisticalSummary describing data from the second sample
705      * @return p-value for t-test
706      * @throws IllegalArgumentException if the precondition is not met
707      * @throws MathException if an error occurs computing the p-value
708      */
709     public abstract double homoscedasticTTest(
710         StatisticalSummary sampleStats1,
711         StatisticalSummary sampleStats2)
712         throws IllegalArgumentException JavaDoc, MathException;
713     /**
714      * Performs a
715      * <a HREF="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm">
716      * two-sided t-test</a> evaluating the null hypothesis that
717      * <code>sampleStats1</code> and <code>sampleStats2</code> describe
718      * datasets drawn from populations with the same mean, with significance
719      * level <code>alpha</code>. This test does not assume that the
720      * subpopulation variances are equal. To perform the test under the equal
721      * variances assumption, use
722      * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}.
723      * <p>
724      * Returns <code>true</code> iff the null hypothesis that the means are
725      * equal can be rejected with confidence <code>1 - alpha</code>. To
726      * perform a 1-sided test, use <code>alpha * 2</code>
727      * <p>
728      * See {@link #t(double[], double[])} for the formula used to compute the
729      * t-statistic. Degrees of freedom are approximated using the
730      * <a HREF="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm">
731      * Welch-Satterthwaite approximation.</a>
732      * <p>
733      * <strong>Examples:</strong><br><ol>
734      * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at
735      * the 95%, use
736      * <br><code>tTest(sampleStats1, sampleStats2, 0.05) </code>
737      * </li>
738      * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code>
739      * at the 99% level, first verify that the measured mean of
740      * <code>sample 1</code> is less than the mean of <code>sample 2</code>
741      * and then use
742      * <br><code>tTest(sampleStats1, sampleStats2, 0.02) </code>
743      * </li></ol>
744      * <p>
745      * <strong>Usage Note:</strong><br>
746      * The validity of the test depends on the assumptions of the parametric
747      * t-test procedure, as discussed
748      * <a HREF="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">
749      * here</a>
750      * <p>
751      * <strong>Preconditions</strong>: <ul>
752      * <li>The datasets described by the two Univariates must each contain
753      * at least 2 observations.
754      * </li>
755      * <li> <code> 0 < alpha < 0.5 </code>
756      * </li></ul>
757      *
758      * @param sampleStats1 StatisticalSummary describing sample data values
759      * @param sampleStats2 StatisticalSummary describing sample data values
760      * @param alpha significance level of the test
761      * @return true if the null hypothesis can be rejected with
762      * confidence 1 - alpha
763      * @throws IllegalArgumentException if the preconditions are not met
764      * @throws MathException if an error occurs performing the test
765      */
766     public abstract boolean tTest(
767         StatisticalSummary sampleStats1,
768         StatisticalSummary sampleStats2,
769         double alpha)
770         throws IllegalArgumentException JavaDoc, MathException;
771 }
Popular Tags