## The Commons Math *TTest.java* source code

/*
* 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>One-sided or two-sided
* <li>Paired or unpaired (for two-sample tests)
* <li>Homoscedastic (equal variance assumption) or heteroscedastic
* (for two sample tests)</li>
* <li>Fixed significance level (boolean-valued) or returning p-values.
* </li>
* <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-valued methods return p-values;
* <code>boolean-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).
* <p>
* Input to tests can be either <code>double[] arrays or
* {@link StatisticalSummary} instances.</p>
*
*
* @version $Revision: 811786 $ $Date: 2009-09-06 05:36:08 -0400 (Sun, 06 Sep 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 and the sample array consisting of the (signed)
* differences between corresponding entries in <code>sample1 and
* <code>sample2.
* <p>
* <strong>Preconditions:

* <li>The input arrays must have the same length and their common length
* must be at least 2.
* </li>

*
* @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, or
* <i> p-value, 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 and the sample
* array consisting of the signed differences between corresponding elements of
* <code>sample1 and

`sample2.`

* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The input array lengths must be the same and their common length must
* be at least 2.
* </li>

*
* @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 and
* <code>sample2 is 0 in favor of the two-sided alternative that the
* mean paired difference is not equal to 0, with significance level
* <code>alpha.
* <p>
* Returns <code>true iff the null hypothesis can be rejected with
* confidence <code>1 - alpha. To perform a 1-sided test, use
* <code>alpha * 2

* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The input array lengths must be the same and their common length
* must be at least 2.
* </li>
* <li> ` 0 < alpha < 0.5 `

* </li>

*
* @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>

* <strong>Preconditions:

* <li>The observed array length must be at least 2.
* </li>

*
* @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 to

`mu`

.
* <p>
* This statistic can be used to perform a one sample t-test for the mean.
* </p>

* <strong>Preconditions:

* <li>`observed.getN() > = 2`

.
* </li>

*
* @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))
* </p>

* where <strong>`n1`

is the size of first sample;
* <strong>` n2`

is the size of second sample;
* <strong>` m1`

is the mean of first sample;
* <strong>` m2`

is the mean of second sample
* </ul>
* and <strong>`var`

is the pooled variance estimate:
* </p>

* <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))
* </p>

* with <strong>`var1````
the variance of the first sample and
* <strong>
````var2`

the variance of the second sample.
* </p>

```
* <strong>Preconditions:
```

```
* <li>The observed array lengths must both be at least 2.
* </li>
```

```
*
* @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)
```

* </p>
* where <strong>`n1`

is the size of the first sample
* <strong>` n2`

is the size of the second sample;
* <strong>` m1`

is the mean of the first sample;
* <strong>` m2`

is the mean of the second sample;
* <strong>` var1`

is the variance of the first sample;
* <strong>` var2`

is the variance of the second sample;
* </p>

* <strong>Preconditions:

* <li>The observed array lengths must both be at least 2.
* </li>

*
* @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)

* </p>

* where <strong>`n1`

is the size of the first sample;
* <strong>` n2`

is the size of the second sample;
* <strong>` m1`

is the mean of the first sample;
* <strong>` m2`

is the mean of the second sample
* <strong>` var1`

is the variance of the first sample;
* <strong>` var2`

is the variance of the second sample
* </p>

* <strong>Preconditions:

* <li>The datasets described by the two Univariates must each contain
* at least 2 observations.
* </li>

*
* @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))
* </p>

* where <strong>`n1`

is the size of first sample;
* <strong>` n2`

is the size of second sample;
* <strong>` m1`

is the mean of first sample;
* <strong>` m2`

is the mean of second sample
* and <strong>`var`

is the pooled variance estimate:
* </p>

* <code>var = sqrt(((n1 - 1)var1 + (n2 - 1)var2) / ((n1-1) + (n2-1)))
* </p>

* with <strong>`var1````
the variance of the first sample and
* <strong>
````var2`

the variance of the second sample.
* </p>

```
* <strong>Preconditions:
```

```
* <li>The datasets described by the two Univariates must each contain
* at least 2 observations.
* </li>
```

```
*
* @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, or
* <i>p-value, associated with a one-sample, two-tailed t-test
* comparing the mean of the input array with the constant <code>mu
```

.
* <p>
* The number returned is the smallest significance level
* at which one can reject the null hypothesis that the mean equals
* <code>mu

in favor of the two-sided alternative that the mean
* is different from <code>mu. For a one-sided test, divide the
* returned value by 2.</p>
* <p>
* <strong>Usage Note:

* 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
* </p>

* <strong>Preconditions:

* <li>The observed array length must be at least 2.
* </li>

*
* @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 is drawn equals

`mu`

.
* <p>
* Returns <code>true iff the null hypothesis can be
* rejected with confidence <code>1 - alpha. To
* perform a 1-sided test, use <code>alpha * 2

* <p>
* <strong>Examples:

* <li>To test the (2-sided) hypothesis `sample mean = mu `

at
* the 95% level, use <br>`tTest(mu, sample, 0.05) `

* </li>
* <li>To test the (one-sided) hypothesis ` sample mean < mu `

* at the 99% level, first verify that the measured sample mean is less
* than <code>mu and then use
* <br>`tTest(mu, sample, 0.02) `

* </li>

* <p>
* <strong>Usage Note:

* 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
* </p>

* <strong>Preconditions:

* <li>The observed array length must be at least 2.
* </li>

*
* @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, or
* <i>p-value, associated with a one-sample, two-tailed t-test
* comparing the mean of the dataset described by <code>sampleStats
* with the constant <code>mu.
* <p>
* The number returned is the smallest significance level
* at which one can reject the null hypothesis that the mean equals
* <code>mu in favor of the two-sided alternative that the mean
* is different from <code>mu. For a one-sided test, divide the
* returned value by 2.</p>
* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The sample must contain at least 2 observations.
* </li>

*
* @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 is
* drawn equals <code>mu.
* <p>
* Returns <code>true iff the null hypothesis can be rejected with
* confidence <code>1 - alpha. To perform a 1-sided test, use
* <code>alpha * 2.

* <p>
* <strong>Examples:

* <li>To test the (2-sided) hypothesis `sample mean = mu `

at
* the 95% level, use <br>`tTest(mu, sampleStats, 0.05) `

* </li>
* <li>To test the (one-sided) hypothesis ` sample mean < mu `

* at the 99% level, first verify that the measured sample mean is less
* than <code>mu and then use
* <br>`tTest(mu, sampleStats, 0.02) `

* </li>

* <p>
* <strong>Usage Note:

* 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
* </p>

* <strong>Preconditions:

* <li>The sample must include at least 2 observations.
* </li>

*
* @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, or
* <i>p-value, 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:

* 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>
* <strong>Preconditions:

* <li>The observed array lengths must both be at least 2.
* </li>

*
* @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, or
* <i>p-value, 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:

* 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>
* <strong>Preconditions:

* <li>The observed array lengths must both be at least 2.
* </li>

*
* @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

`sample1`

* and <code>sample2 are drawn from populations with the same mean,
* with significance level <code>alpha. 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 iff the null hypothesis that the means are
* equal can be rejected with confidence <code>1 - alpha. To
* perform a 1-sided test, use <code>alpha * 2

* <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>
* <strong>Examples:

* <li>To test the (2-sided) hypothesis `mean 1 = mean 2 `

at
* the 95% level, use
* <br>`tTest(sample1, sample2, 0.05). `

* </li>
* <li>To test the (one-sided) hypothesis ` mean 1 < mean 2 `

,
* at the 99% level, first verify that the measured mean of <code>sample 1
* is less than the mean of <code>sample 2 and then use
* <br>`tTest(sample1, sample2, 0.02) `

* </li>

* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The observed array lengths must both be at least 2.
* </li>
* <li> ` 0 < alpha < 0.5 `

* </li>

*
* @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

`sample1`

* and <code>sample2 are drawn from populations with the same mean,
* with significance level <code>alpha, 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 iff the null hypothesis that the means are
* equal can be rejected with confidence <code>1 - alpha. To
* perform a 1-sided test, use <code>alpha * 2. 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:

* <li>To test the (2-sided) hypothesis `mean 1 = mean 2 `

at
* the 95% level, use <br>`tTest(sample1, sample2, 0.05). `

* </li>
* <li>To test the (one-sided) hypothesis ` mean 1 < mean 2, `

* at the 99% level, first verify that the measured mean of
* <code>sample 1 is less than the mean of `sample 2`

* and then use
* <br>`tTest(sample1, sample2, 0.02) `

* </li>

* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The observed array lengths must both be at least 2.
* </li>
* <li> ` 0 < alpha < 0.5 `

* </li>

*
* @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, or
* <i>p-value, 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:

* 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>
* <strong>Preconditions:

* <li>The datasets described by the two Univariates must each contain
* at least 2 observations.
* </li>

*
* @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, or
* <i>p-value, 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:

* 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
* </p>

* <strong>Preconditions:

* <li>The datasets described by the two Univariates must each contain
* at least 2 observations.
* </li>

*
* @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 and

`sampleStats2`

describe
* datasets drawn from populations with the same mean, with significance
* level <code>alpha. 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 iff the null hypothesis that the means are
* equal can be rejected with confidence <code>1 - alpha. To
* perform a 1-sided test, use <code>alpha * 2

* <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>
* <strong>Examples:

* <li>To test the (2-sided) hypothesis `mean 1 = mean 2 `

at
* the 95%, use
* <br>`tTest(sampleStats1, sampleStats2, 0.05) `

* </li>
* <li>To test the (one-sided) hypothesis ` mean 1 < mean 2 `

* at the 99% level, first verify that the measured mean of
* <code>sample 1 is less than the mean of `sample 2`

* and then use
* <br>`tTest(sampleStats1, sampleStats2, 0.02) `

* </li>

* <p>
* <strong>Usage Note:

* 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>
* <strong>Preconditions:

* <li>The datasets described by the two Univariates must each contain
* at least 2 observations.
* </li>
* <li> ` 0 < alpha < 0.5 `

* </li>

*
* @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;
}

## Other Commons Math examples (source code examples)

Here is a short list of links related to this Commons Math TTest.java source code file: