Class TTest
- java.lang.Object
-
- org.apache.commons.statistics.inference.TTest
-
public final class TTest extends java.lang.Object
Implements Student's t-test statistics.Tests can be:
- One-sample or two-sample
- One-sided or two-sided
- Paired or unpaired (for two-sample tests)
- Homoscedastic (equal variance assumption) or heteroscedastic (for two sample tests)
Input to tests can be either
double[]
arrays or the mean, variance, and size of the sample.- Since:
- 1.1
- See Also:
- Student's t-test (Wikipedia)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TTest.Result
Result for the t-test.
-
Field Summary
Fields Modifier and Type Field Description private AlternativeHypothesis
alternative
Alternative hypothesis.private static TTest
DEFAULT
Default instance.private boolean
equalVariances
Assume the two samples have the same population variance.private double
mu
The true value of the mean (or difference in means for a two sample test).
-
Constructor Summary
Constructors Modifier Constructor Description private
TTest(AlternativeHypothesis alternative, boolean equalVariances, double mu)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static long
checkSampleSize(long n)
Check sample data size.private static double
computeDf(double v1, long n1, double v2, long n2)
Computes approximate degrees of freedom for two-sample t-test without the assumption of equal samples sizes or sub-population variances.private static double
computeHomoscedasticT(double mu, double m1, double v1, long n1, double m2, double v2, long n2)
Computes t statistic for two-sample t-test under the hypothesis of equal sub-population variances.private double
computeP(double t, double degreesOfFreedom)
Computes p-value for the specified t statistic.private static double
computeT(double mu, double m1, double v1, long n1, double m2, double v2, long n2)
Computes t statistic for two-sample t-test without the assumption of equal samples sizes or sub-population variances.private static double
computeT(double m, double v, long n)
Computes t statistic for one-sample t-test.double
pairedStatistic(double[] x, double[] y)
Computes a paired two-sample t-statistic on related samples comparing the mean difference between the samples tomu
.TTest.Result
pairedTest(double[] x, double[] y)
Performs a paired two-sample t-test on related samples comparing the mean difference between the samples tomu
.double
statistic(double[] x)
Computes a one-sample t statistic comparing the mean of the sample tomu
.double
statistic(double[] x, double[] y)
Computes a two-sample t statistic on independent samples comparing the difference in means of the samples tomu
.double
statistic(double m, double v, long n)
Computes a one-sample t statistic comparing the mean of the dataset tomu
.double
statistic(double m1, double v1, long n1, double m2, double v2, long n2)
Computes a two-sample t statistic on independent samples comparing the difference in means of the datasets tomu
.TTest.Result
test(double[] sample)
Performs a one-sample t-test comparing the mean of the sample tomu
.TTest.Result
test(double[] x, double[] y)
Performs a two-sample t-test on independent samples comparing the difference in means of the samples tomu
.TTest.Result
test(double m, double v, long n)
Perform a one-sample t-test comparing the mean of the dataset tomu
.TTest.Result
test(double m1, double v1, long n1, double m2, double v2, long n2)
Performs a two-sample t-test on independent samples comparing the difference in means of the datasets tomu
.TTest
with(AlternativeHypothesis v)
Return an instance with the configured alternative hypothesis.TTest
with(DataDispersion v)
Return an instance with the configured assumption on the data dispersion.static TTest
withDefaults()
Return an instance using the default options.TTest
withMu(double v)
Return an instance with the configuredmu
.
-
-
-
Field Detail
-
DEFAULT
private static final TTest DEFAULT
Default instance.
-
alternative
private final AlternativeHypothesis alternative
Alternative hypothesis.
-
equalVariances
private final boolean equalVariances
Assume the two samples have the same population variance.
-
mu
private final double mu
The true value of the mean (or difference in means for a two sample test).
-
-
Constructor Detail
-
TTest
private TTest(AlternativeHypothesis alternative, boolean equalVariances, double mu)
- Parameters:
alternative
- Alternative hypothesis.equalVariances
- Assume the two samples have the same population variance.mu
- true value of the mean (or difference in means for a two sample test).
-
-
Method Detail
-
withDefaults
public static TTest withDefaults()
Return an instance using the default options.- Returns:
- default instance
-
with
public TTest with(AlternativeHypothesis v)
Return an instance with the configured alternative hypothesis.- Parameters:
v
- Value.- Returns:
- an instance
-
with
public TTest with(DataDispersion v)
Return an instance with the configured assumption on the data dispersion.Applies to the two-sample independent t-test. The statistic can compare the means without the assumption of equal sub-population variances (heteroscedastic); otherwise the means are compared under the assumption of equal sub-population variances (homoscedastic).
- Parameters:
v
- Value.- Returns:
- an instance
- See Also:
test(double[], double[])
,test(double, double, long, double, double, long)
-
withMu
public TTest withMu(double v)
Return an instance with the configuredmu
.For the one-sample test this is the expected mean.
For the two-sample test this is the expected difference between the means.
- Parameters:
v
- Value.- Returns:
- an instance
- Throws:
java.lang.IllegalArgumentException
- if the value is not finite
-
statistic
public double statistic(double m, double v, long n)
Computes a one-sample t statistic comparing the mean of the dataset tomu
.The returned t-statistic is:
\[ t = \frac{m - \mu}{ \sqrt{ \frac{v}{n} } } \]
- Parameters:
m
- Sample mean.v
- Sample variance.n
- Sample size.- Returns:
- t statistic
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
; or the variance is negative- See Also:
withMu(double)
-
statistic
public double statistic(double[] x)
Computes a one-sample t statistic comparing the mean of the sample tomu
.- Parameters:
x
- Sample values.- Returns:
- t statistic
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
- See Also:
statistic(double, double, long)
,withMu(double)
-
pairedStatistic
public double pairedStatistic(double[] x, double[] y)
Computes a paired two-sample t-statistic on related samples comparing the mean difference between the samples tomu
.The t-statistic returned is functionally equivalent to what would be returned by computing the one-sample t-statistic
statistic(double[])
, with the sample array consisting of the (signed) differences between corresponding entries inx
andy
.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- t statistic
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
; or the the size of the samples is not equal- See Also:
withMu(double)
-
statistic
public double statistic(double m1, double v1, long n1, double m2, double v2, long n2)
Computes a two-sample t statistic on independent samples comparing the difference in means of the datasets tomu
.Use the
DataDispersion
to control the computation of the variance.The heteroscedastic t-statistic is:
\[ t = \frac{m1 - m2 - \mu}{ \sqrt{ \frac{v_1}{n_1} + \frac{v_2}{n_2} } } \]
The homoscedastic t-statistic is:
\[ t = \frac{m1 - m2 - \mu}{ \sqrt{ v (\frac{1}{n_1} + \frac{1}{n_2}) } } \]
where \( v \) is the pooled variance estimate:
\[ v = \frac{(n_1-1)v_1 + (n_2-1)v_2}{n_1 + n_2 - 2} \]
- Parameters:
m1
- First sample mean.v1
- First sample variance.n1
- First sample size.m2
- Second sample mean.v2
- Second sample variance.n2
- Second sample size.- Returns:
- t statistic
- Throws:
java.lang.IllegalArgumentException
- if the number of samples in either dataset is< 2
; or the variances are negative.- See Also:
withMu(double)
,with(DataDispersion)
-
statistic
public double statistic(double[] x, double[] y)
Computes a two-sample t statistic on independent samples comparing the difference in means of the samples tomu
.Use the
DataDispersion
to control the computation of the variance.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- t statistic
- Throws:
java.lang.IllegalArgumentException
- if the number of samples in either dataset is< 2
- See Also:
withMu(double)
,with(DataDispersion)
-
test
public TTest.Result test(double m, double v, long n)
Perform a one-sample t-test comparing the mean of the dataset tomu
.Degrees of freedom are \( v = n - 1 \).
- Parameters:
m
- Sample mean.v
- Sample variance.n
- Sample size.- Returns:
- test result
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
; or the variance is negative- See Also:
statistic(double, double, long)
-
test
public TTest.Result test(double[] sample)
Performs a one-sample t-test comparing the mean of the sample tomu
.Degrees of freedom are \( v = n - 1 \).
- Parameters:
sample
- Sample values.- Returns:
- the test result
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
; or the the size of the samples is not equal- See Also:
statistic(double[])
-
pairedTest
public TTest.Result pairedTest(double[] x, double[] y)
Performs a paired two-sample t-test on related samples comparing the mean difference between the samples tomu
.The test is functionally equivalent to what would be returned by computing the one-sample t-test
test(double[])
, with the sample array consisting of the (signed) differences between corresponding entries inx
andy
.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- the test result
- Throws:
java.lang.IllegalArgumentException
- if the number of samples is< 2
; or the the size of the samples is not equal- See Also:
pairedStatistic(double[], double[])
-
test
public TTest.Result test(double m1, double v1, long n1, double m2, double v2, long n2)
Performs a two-sample t-test on independent samples comparing the difference in means of the datasets tomu
.Use the
DataDispersion
to control the computation of the variance.The heteroscedastic degrees of freedom are estimated using the Welch-Satterthwaite approximation:
\[ v = \frac{ (\frac{v_1}{n_1} + \frac{v_2}{n_2})^2 } { \frac{(v_1/n_1)^2}{n_1-1} + \frac{(v_2/n_2)^2}{n_2-1} } \]
The homoscedastic degrees of freedom are \( v = n_1 + n_2 - 2 \).
- Parameters:
m1
- First sample mean.v1
- First sample variance.n1
- First sample size.m2
- Second sample mean.v2
- Second sample variance.n2
- Second sample size.- Returns:
- test result
- Throws:
java.lang.IllegalArgumentException
- if the number of samples in either dataset is< 2
; or the variances are negative.- See Also:
statistic(double, double, long, double, double, long)
-
test
public TTest.Result test(double[] x, double[] y)
Performs a two-sample t-test on independent samples comparing the difference in means of the samples tomu
.Use the
DataDispersion
to control the computation of the variance.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- the test result
- Throws:
java.lang.IllegalArgumentException
- if the number of samples in either dataset is< 2
- See Also:
statistic(double[], double[])
,test(double, double, long, double, double, long)
-
computeT
private static double computeT(double m, double v, long n)
Computes t statistic for one-sample t-test.- Parameters:
m
- Sample mean.v
- Sample variance.n
- Sample size.- Returns:
- t test statistic
-
computeT
private static double computeT(double mu, double m1, double v1, long n1, double m2, double v2, long n2)
Computes t statistic for two-sample t-test without the assumption of equal samples sizes or sub-population variances.- Parameters:
mu
- Expected difference between means.m1
- First sample mean.v1
- First sample variance.n1
- First sample size.m2
- Second sample mean.v2
- Second sample variance.n2
- Second sample size.- Returns:
- t test statistic
-
computeDf
private static double computeDf(double v1, long n1, double v2, long n2)
Computes approximate degrees of freedom for two-sample t-test without the assumption of equal samples sizes or sub-population variances.- Parameters:
v1
- First sample variance.n1
- First sample size.v2
- Second sample variance.n2
- Second sample size.- Returns:
- approximate degrees of freedom
-
computeHomoscedasticT
private static double computeHomoscedasticT(double mu, double m1, double v1, long n1, double m2, double v2, long n2)
Computes t statistic for two-sample t-test under the hypothesis of equal sub-population variances.- Parameters:
mu
- Expected difference between means.m1
- First sample mean.v1
- First sample variance.n1
- First sample size.m2
- Second sample mean.v2
- Second sample variance.n2
- Second sample size.- Returns:
- t test statistic
-
computeP
private double computeP(double t, double degreesOfFreedom)
Computes p-value for the specified t statistic.- Parameters:
t
- T statistic.degreesOfFreedom
- Degrees of freedom.- Returns:
- p-value for t-test
-
checkSampleSize
private static long checkSampleSize(long n)
Check sample data size.- Parameters:
n
- Data size.- Returns:
- the sample size
- Throws:
java.lang.IllegalArgumentException
- if the number of samples< 2
-
-