diff options
Diffstat (limited to 'src/main/java/org/apache/commons/math/stat/inference/TTest.java')
| -rw-r--r-- | src/main/java/org/apache/commons/math/stat/inference/TTest.java | 771 |
1 files changed, 771 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/math/stat/inference/TTest.java b/src/main/java/org/apache/commons/math/stat/inference/TTest.java new file mode 100644 index 0000000..0ccb0c0 --- /dev/null +++ b/src/main/java/org/apache/commons/math/stat/inference/TTest.java @@ -0,0 +1,771 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.math.stat.inference; + +import org.apache.commons.math.MathException; +import org.apache.commons.math.stat.descriptive.StatisticalSummary; + +/** + * An interface for Student's t-tests. + * <p> + * Tests can be:<ul> + * <li>One-sample or two-sample</li> + * <li>One-sided or two-sided</li> + * <li>Paired or unpaired (for two-sample tests)</li> + * <li>Homoscedastic (equal variance assumption) or heteroscedastic + * (for two sample tests)</li> + * <li>Fixed significance level (boolean-valued) or returning p-values. + * </li></ul></p> + * <p> + * Test statistics are available for all tests. Methods including "Test" in + * in their names perform tests, all other methods return t-statistics. Among + * the "Test" methods, <code>double-</code>valued methods return p-values; + * <code>boolean-</code>valued methods perform fixed significance level tests. + * Significance levels are always specified as numbers between 0 and 0.5 + * (e.g. tests at the 95% level use <code>alpha=0.05</code>).</p> + * <p> + * Input to tests can be either <code>double[]</code> arrays or + * {@link StatisticalSummary} instances.</p> + * + * + * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $ + */ +public interface TTest { + /** + * Computes a paired, 2-sample t-statistic based on the data in the input + * arrays. The t-statistic returned is equivalent to what would be returned by + * computing the one-sample t-statistic {@link #t(double, double[])}, with + * <code>mu = 0</code> and the sample array consisting of the (signed) + * differences between corresponding entries in <code>sample1</code> and + * <code>sample2.</code> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The input arrays must have the same length and their common length + * must be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if the statistic can not be computed do to a + * convergence or other numerical error. + */ + double pairedT(double[] sample1, double[] sample2) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i> p-value</i>, associated with a paired, two-sample, two-tailed t-test + * based on the data in the input arrays. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the mean of the paired + * differences is 0 in favor of the two-sided alternative that the mean paired + * difference is not equal to 0. For a one-sided test, divide the returned + * value by 2.</p> + * <p> + * This test is equivalent to a one-sample t-test computed using + * {@link #tTest(double, double[])} with <code>mu = 0</code> and the sample + * array consisting of the signed differences between corresponding elements of + * <code>sample1</code> and <code>sample2.</code></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the p-value depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The input array lengths must be the same and their common length must + * be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return p-value for t-test + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double pairedTTest(double[] sample1, double[] sample2) + throws IllegalArgumentException, MathException; + /** + * Performs a paired t-test evaluating the null hypothesis that the + * mean of the paired differences between <code>sample1</code> and + * <code>sample2</code> is 0 in favor of the two-sided alternative that the + * mean paired difference is not equal to 0, with significance level + * <code>alpha</code>. + * <p> + * Returns <code>true</code> iff the null hypothesis can be rejected with + * confidence <code>1 - alpha</code>. To perform a 1-sided test, use + * <code>alpha * 2</code></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The input array lengths must be the same and their common length + * must be at least 2. + * </li> + * <li> <code> 0 < alpha < 0.5 </code> + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @param alpha significance level of the test + * @return true if the null hypothesis can be rejected with + * confidence 1 - alpha + * @throws IllegalArgumentException if the preconditions are not met + * @throws MathException if an error occurs performing the test + */ + boolean pairedTTest( + double[] sample1, + double[] sample2, + double alpha) + throws IllegalArgumentException, MathException; + /** + * Computes a <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula"> + * t statistic </a> given observed values and a comparison constant. + * <p> + * This statistic can be used to perform a one sample t-test for the mean. + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array length must be at least 2. + * </li></ul></p> + * + * @param mu comparison constant + * @param observed array of values + * @return t statistic + * @throws IllegalArgumentException if input array length is less than 2 + */ + double t(double mu, double[] observed) + throws IllegalArgumentException; + /** + * Computes a <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm#formula"> + * t statistic </a> to use in comparing the mean of the dataset described by + * <code>sampleStats</code> to <code>mu</code>. + * <p> + * This statistic can be used to perform a one sample t-test for the mean. + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li><code>observed.getN() > = 2</code>. + * </li></ul></p> + * + * @param mu comparison constant + * @param sampleStats DescriptiveStatistics holding sample summary statitstics + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + */ + double t(double mu, StatisticalSummary sampleStats) + throws IllegalArgumentException; + /** + * Computes a 2-sample t statistic, under the hypothesis of equal + * subpopulation variances. To compute a t-statistic without the + * equal variances hypothesis, use {@link #t(double[], double[])}. + * <p> + * This statistic can be used to perform a (homoscedastic) two-sample + * t-test to compare sample means.</p> + * <p> + * The t-statisitc is</p> + * <p> + * <code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code> + * </p><p> + * where <strong><code>n1</code></strong> is the size of first sample; + * <strong><code> n2</code></strong> is the size of second sample; + * <strong><code> m1</code></strong> is the mean of first sample; + * <strong><code> m2</code></strong> is the mean of second sample</li> + * </ul> + * and <strong><code>var</code></strong> is the pooled variance estimate: + * </p><p> + * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code> + * </p><p> + * with <strong><code>var1<code></strong> the variance of the first sample and + * <strong><code>var2</code></strong> the variance of the second sample. + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + */ + double homoscedasticT(double[] sample1, double[] sample2) + throws IllegalArgumentException; + /** + * Computes a 2-sample t statistic, without the hypothesis of equal + * subpopulation variances. To compute a t-statistic assuming equal + * variances, use {@link #homoscedasticT(double[], double[])}. + * <p> + * This statistic can be used to perform a two-sample t-test to compare + * sample means.</p> + * <p> + * The t-statisitc is</p> + * <p> + * <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code> + * </p><p> + * where <strong><code>n1</code></strong> is the size of the first sample + * <strong><code> n2</code></strong> is the size of the second sample; + * <strong><code> m1</code></strong> is the mean of the first sample; + * <strong><code> m2</code></strong> is the mean of the second sample; + * <strong><code> var1</code></strong> is the variance of the first sample; + * <strong><code> var2</code></strong> is the variance of the second sample; + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + */ + double t(double[] sample1, double[] sample2) + throws IllegalArgumentException; + /** + * Computes a 2-sample t statistic </a>, comparing the means of the datasets + * described by two {@link StatisticalSummary} instances, without the + * assumption of equal subpopulation variances. Use + * {@link #homoscedasticT(StatisticalSummary, StatisticalSummary)} to + * compute a t-statistic under the equal variances assumption. + * <p> + * This statistic can be used to perform a two-sample t-test to compare + * sample means.</p> + * <p> + * The returned t-statisitc is</p> + * <p> + * <code> t = (m1 - m2) / sqrt(var1/n1 + var2/n2)</code> + * </p><p> + * where <strong><code>n1</code></strong> is the size of the first sample; + * <strong><code> n2</code></strong> is the size of the second sample; + * <strong><code> m1</code></strong> is the mean of the first sample; + * <strong><code> m2</code></strong> is the mean of the second sample + * <strong><code> var1</code></strong> is the variance of the first sample; + * <strong><code> var2</code></strong> is the variance of the second sample + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The datasets described by the two Univariates must each contain + * at least 2 observations. + * </li></ul></p> + * + * @param sampleStats1 StatisticalSummary describing data from the first sample + * @param sampleStats2 StatisticalSummary describing data from the second sample + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + */ + double t( + StatisticalSummary sampleStats1, + StatisticalSummary sampleStats2) + throws IllegalArgumentException; + /** + * Computes a 2-sample t statistic, comparing the means of the datasets + * described by two {@link StatisticalSummary} instances, under the + * assumption of equal subpopulation variances. To compute a t-statistic + * without the equal variances assumption, use + * {@link #t(StatisticalSummary, StatisticalSummary)}. + * <p> + * This statistic can be used to perform a (homoscedastic) two-sample + * t-test to compare sample means.</p> + * <p> + * The t-statisitc returned is</p> + * <p> + * <code> t = (m1 - m2) / (sqrt(1/n1 +1/n2) sqrt(var))</code> + * </p><p> + * where <strong><code>n1</code></strong> is the size of first sample; + * <strong><code> n2</code></strong> is the size of second sample; + * <strong><code> m1</code></strong> is the mean of first sample; + * <strong><code> m2</code></strong> is the mean of second sample + * and <strong><code>var</code></strong> is the pooled variance estimate: + * </p><p> + * <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))</code> + * </p><p> + * with <strong><code>var1<code></strong> the variance of the first sample and + * <strong><code>var2</code></strong> the variance of the second sample. + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The datasets described by the two Univariates must each contain + * at least 2 observations. + * </li></ul></p> + * + * @param sampleStats1 StatisticalSummary describing data from the first sample + * @param sampleStats2 StatisticalSummary describing data from the second sample + * @return t statistic + * @throws IllegalArgumentException if the precondition is not met + */ + double homoscedasticT( + StatisticalSummary sampleStats1, + StatisticalSummary sampleStats2) + throws IllegalArgumentException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a one-sample, two-tailed t-test + * comparing the mean of the input array with the constant <code>mu</code>. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the mean equals + * <code>mu</code> in favor of the two-sided alternative that the mean + * is different from <code>mu</code>. For a one-sided test, divide the + * returned value by 2.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a> + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array length must be at least 2. + * </li></ul></p> + * + * @param mu constant value to compare sample mean against + * @param sample array of sample data values + * @return p-value + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double tTest(double mu, double[] sample) + throws IllegalArgumentException, MathException; + /** + * Performs a <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm"> + * two-sided t-test</a> evaluating the null hypothesis that the mean of the population from + * which <code>sample</code> is drawn equals <code>mu</code>. + * <p> + * Returns <code>true</code> iff the null hypothesis can be + * rejected with confidence <code>1 - alpha</code>. To + * perform a 1-sided test, use <code>alpha * 2</code></p> + * <p> + * <strong>Examples:</strong><br><ol> + * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at + * the 95% level, use <br><code>tTest(mu, sample, 0.05) </code> + * </li> + * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code> + * at the 99% level, first verify that the measured sample mean is less + * than <code>mu</code> and then use + * <br><code>tTest(mu, sample, 0.02) </code> + * </li></ol></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the one-sample + * parametric t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a> + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array length must be at least 2. + * </li></ul></p> + * + * @param mu constant value to compare sample mean against + * @param sample array of sample data values + * @param alpha significance level of the test + * @return p-value + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error computing the p-value + */ + boolean tTest(double mu, double[] sample, double alpha) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a one-sample, two-tailed t-test + * comparing the mean of the dataset described by <code>sampleStats</code> + * with the constant <code>mu</code>. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the mean equals + * <code>mu</code> in favor of the two-sided alternative that the mean + * is different from <code>mu</code>. For a one-sided test, divide the + * returned value by 2.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The sample must contain at least 2 observations. + * </li></ul></p> + * + * @param mu constant value to compare sample mean against + * @param sampleStats StatisticalSummary describing sample data + * @return p-value + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double tTest(double mu, StatisticalSummary sampleStats) + throws IllegalArgumentException, MathException; + /** + * Performs a <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm"> + * two-sided t-test</a> evaluating the null hypothesis that the mean of the + * population from which the dataset described by <code>stats</code> is + * drawn equals <code>mu</code>. + * <p> + * Returns <code>true</code> iff the null hypothesis can be rejected with + * confidence <code>1 - alpha</code>. To perform a 1-sided test, use + * <code>alpha * 2.</code></p> + * <p> + * <strong>Examples:</strong><br><ol> + * <li>To test the (2-sided) hypothesis <code>sample mean = mu </code> at + * the 95% level, use <br><code>tTest(mu, sampleStats, 0.05) </code> + * </li> + * <li>To test the (one-sided) hypothesis <code> sample mean < mu </code> + * at the 99% level, first verify that the measured sample mean is less + * than <code>mu</code> and then use + * <br><code>tTest(mu, sampleStats, 0.02) </code> + * </li></ol></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the one-sample + * parametric t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/sg_glos.html#one-sample">here</a> + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The sample must include at least 2 observations. + * </li></ul></p> + * + * @param mu constant value to compare sample mean against + * @param sampleStats StatisticalSummary describing sample data values + * @param alpha significance level of the test + * @return p-value + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + boolean tTest( + double mu, + StatisticalSummary sampleStats, + double alpha) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a two-sample, two-tailed t-test + * comparing the means of the input arrays. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the two means are + * equal in favor of the two-sided alternative that they are different. + * For a one-sided test, divide the returned value by 2.</p> + * <p> + * The test does not assume that the underlying popuation variances are + * equal and it uses approximated degrees of freedom computed from the + * sample data to compute the p-value. The t-statistic used is as defined in + * {@link #t(double[], double[])} and the Welch-Satterthwaite approximation + * to the degrees of freedom is used, + * as described + * <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm"> + * here.</a> To perform the test under the assumption of equal subpopulation + * variances, use {@link #homoscedasticTTest(double[], double[])}.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the p-value depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return p-value for t-test + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double tTest(double[] sample1, double[] sample2) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a two-sample, two-tailed t-test + * comparing the means of the input arrays, under the assumption that + * the two samples are drawn from subpopulations with equal variances. + * To perform the test without the equal variances assumption, use + * {@link #tTest(double[], double[])}.</p> + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the two means are + * equal in favor of the two-sided alternative that they are different. + * For a one-sided test, divide the returned value by 2.</p> + * <p> + * A pooled variance estimate is used to compute the t-statistic. See + * {@link #homoscedasticT(double[], double[])}. The sum of the sample sizes + * minus 2 is used as the degrees of freedom.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the p-value depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @return p-value for t-test + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double homoscedasticTTest( + double[] sample1, + double[] sample2) + throws IllegalArgumentException, MathException; + /** + * Performs a + * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm"> + * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code> + * and <code>sample2</code> are drawn from populations with the same mean, + * with significance level <code>alpha</code>. This test does not assume + * that the subpopulation variances are equal. To perform the test assuming + * equal variances, use + * {@link #homoscedasticTTest(double[], double[], double)}. + * <p> + * Returns <code>true</code> iff the null hypothesis that the means are + * equal can be rejected with confidence <code>1 - alpha</code>. To + * perform a 1-sided test, use <code>alpha * 2</code></p> + * <p> + * See {@link #t(double[], double[])} for the formula used to compute the + * t-statistic. Degrees of freedom are approximated using the + * <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm"> + * Welch-Satterthwaite approximation.</a></p> + * <p> + * <strong>Examples:</strong><br><ol> + * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at + * the 95% level, use + * <br><code>tTest(sample1, sample2, 0.05). </code> + * </li> + * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code>, + * at the 99% level, first verify that the measured mean of <code>sample 1</code> + * is less than the mean of <code>sample 2</code> and then use + * <br><code>tTest(sample1, sample2, 0.02) </code> + * </li></ol></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li> + * <li> <code> 0 < alpha < 0.5 </code> + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @param alpha significance level of the test + * @return true if the null hypothesis can be rejected with + * confidence 1 - alpha + * @throws IllegalArgumentException if the preconditions are not met + * @throws MathException if an error occurs performing the test + */ + boolean tTest( + double[] sample1, + double[] sample2, + double alpha) + throws IllegalArgumentException, MathException; + /** + * Performs a + * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm"> + * two-sided t-test</a> evaluating the null hypothesis that <code>sample1</code> + * and <code>sample2</code> are drawn from populations with the same mean, + * with significance level <code>alpha</code>, assuming that the + * subpopulation variances are equal. Use + * {@link #tTest(double[], double[], double)} to perform the test without + * the assumption of equal variances. + * <p> + * Returns <code>true</code> iff the null hypothesis that the means are + * equal can be rejected with confidence <code>1 - alpha</code>. To + * perform a 1-sided test, use <code>alpha * 2.</code> To perform the test + * without the assumption of equal subpopulation variances, use + * {@link #tTest(double[], double[], double)}.</p> + * <p> + * A pooled variance estimate is used to compute the t-statistic. See + * {@link #t(double[], double[])} for the formula. The sum of the sample + * sizes minus 2 is used as the degrees of freedom.</p> + * <p> + * <strong>Examples:</strong><br><ol> + * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at + * the 95% level, use <br><code>tTest(sample1, sample2, 0.05). </code> + * </li> + * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2, </code> + * at the 99% level, first verify that the measured mean of + * <code>sample 1</code> is less than the mean of <code>sample 2</code> + * and then use + * <br><code>tTest(sample1, sample2, 0.02) </code> + * </li></ol></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The observed array lengths must both be at least 2. + * </li> + * <li> <code> 0 < alpha < 0.5 </code> + * </li></ul></p> + * + * @param sample1 array of sample data values + * @param sample2 array of sample data values + * @param alpha significance level of the test + * @return true if the null hypothesis can be rejected with + * confidence 1 - alpha + * @throws IllegalArgumentException if the preconditions are not met + * @throws MathException if an error occurs performing the test + */ + boolean homoscedasticTTest( + double[] sample1, + double[] sample2, + double alpha) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a two-sample, two-tailed t-test + * comparing the means of the datasets described by two StatisticalSummary + * instances. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the two means are + * equal in favor of the two-sided alternative that they are different. + * For a one-sided test, divide the returned value by 2.</p> + * <p> + * The test does not assume that the underlying popuation variances are + * equal and it uses approximated degrees of freedom computed from the + * sample data to compute the p-value. To perform the test assuming + * equal variances, use + * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the p-value depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The datasets described by the two Univariates must each contain + * at least 2 observations. + * </li></ul></p> + * + * @param sampleStats1 StatisticalSummary describing data from the first sample + * @param sampleStats2 StatisticalSummary describing data from the second sample + * @return p-value for t-test + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double tTest( + StatisticalSummary sampleStats1, + StatisticalSummary sampleStats2) + throws IllegalArgumentException, MathException; + /** + * Returns the <i>observed significance level</i>, or + * <i>p-value</i>, associated with a two-sample, two-tailed t-test + * comparing the means of the datasets described by two StatisticalSummary + * instances, under the hypothesis of equal subpopulation variances. To + * perform a test without the equal variances assumption, use + * {@link #tTest(StatisticalSummary, StatisticalSummary)}. + * <p> + * The number returned is the smallest significance level + * at which one can reject the null hypothesis that the two means are + * equal in favor of the two-sided alternative that they are different. + * For a one-sided test, divide the returned value by 2.</p> + * <p> + * See {@link #homoscedasticT(double[], double[])} for the formula used to + * compute the t-statistic. The sum of the sample sizes minus 2 is used as + * the degrees of freedom.</p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the p-value depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html">here</a> + * </p><p> + * <strong>Preconditions</strong>: <ul> + * <li>The datasets described by the two Univariates must each contain + * at least 2 observations. + * </li></ul></p> + * + * @param sampleStats1 StatisticalSummary describing data from the first sample + * @param sampleStats2 StatisticalSummary describing data from the second sample + * @return p-value for t-test + * @throws IllegalArgumentException if the precondition is not met + * @throws MathException if an error occurs computing the p-value + */ + double homoscedasticTTest( + StatisticalSummary sampleStats1, + StatisticalSummary sampleStats2) + throws IllegalArgumentException, MathException; + /** + * Performs a + * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm"> + * two-sided t-test</a> evaluating the null hypothesis that + * <code>sampleStats1</code> and <code>sampleStats2</code> describe + * datasets drawn from populations with the same mean, with significance + * level <code>alpha</code>. This test does not assume that the + * subpopulation variances are equal. To perform the test under the equal + * variances assumption, use + * {@link #homoscedasticTTest(StatisticalSummary, StatisticalSummary)}. + * <p> + * Returns <code>true</code> iff the null hypothesis that the means are + * equal can be rejected with confidence <code>1 - alpha</code>. To + * perform a 1-sided test, use <code>alpha * 2</code></p> + * <p> + * See {@link #t(double[], double[])} for the formula used to compute the + * t-statistic. Degrees of freedom are approximated using the + * <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/prc31.htm"> + * Welch-Satterthwaite approximation.</a></p> + * <p> + * <strong>Examples:</strong><br><ol> + * <li>To test the (2-sided) hypothesis <code>mean 1 = mean 2 </code> at + * the 95%, use + * <br><code>tTest(sampleStats1, sampleStats2, 0.05) </code> + * </li> + * <li>To test the (one-sided) hypothesis <code> mean 1 < mean 2 </code> + * at the 99% level, first verify that the measured mean of + * <code>sample 1</code> is less than the mean of <code>sample 2</code> + * and then use + * <br><code>tTest(sampleStats1, sampleStats2, 0.02) </code> + * </li></ol></p> + * <p> + * <strong>Usage Note:</strong><br> + * The validity of the test depends on the assumptions of the parametric + * t-test procedure, as discussed + * <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html"> + * here</a></p> + * <p> + * <strong>Preconditions</strong>: <ul> + * <li>The datasets described by the two Univariates must each contain + * at least 2 observations. + * </li> + * <li> <code> 0 < alpha < 0.5 </code> + * </li></ul></p> + * + * @param sampleStats1 StatisticalSummary describing sample data values + * @param sampleStats2 StatisticalSummary describing sample data values + * @param alpha significance level of the test + * @return true if the null hypothesis can be rejected with + * confidence 1 - alpha + * @throws IllegalArgumentException if the preconditions are not met + * @throws MathException if an error occurs performing the test + */ + boolean tTest( + StatisticalSummary sampleStats1, + StatisticalSummary sampleStats2, + double alpha) + throws IllegalArgumentException, MathException; +} |