Package org.apache.commons.statistics.inference

Class TTest

  • public final class TTest
extends 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.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      double pairedStatistic​(double[] x, double[] y)
      Computes a paired two-sample t-statistic on related samples comparing the mean difference between the samples to mu.
      TTest.Result pairedTest​(double[] x, double[] y)
      Performs a paired two-sample t-test on related samples comparing the mean difference between the samples to mu.
      double statistic​(double[] x)
      Computes a one-sample t statistic comparing the mean of the sample to mu.
      double statistic​(double[] x, double[] y)
      Computes a two-sample t statistic on independent samples comparing the difference in means of the samples to mu.
      double statistic​(double m, double v, long n)
      Computes a one-sample t statistic comparing the mean of the dataset to mu.
      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 to mu.
      TTest.Result test​(double[] sample)
      Performs a one-sample t-test comparing the mean of the sample to mu.
      TTest.Result test​(double[] x, double[] y)
      Performs a two-sample t-test on independent samples comparing the difference in means of the samples to mu.
      TTest.Result test​(double m, double v, long n)
      Perform a one-sample t-test comparing the mean of the dataset to mu.
      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 to mu.
      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 configured mu.

    • Method Detail

      • 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 configured mu.

        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:
        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 to mu.

        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:
        IllegalArgumentException - if the number of samples is < 2; or the variance is negative
        See Also:
        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 to mu.

        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 in x and y.

        Parameters:
        x - First sample values.
        y - Second sample values.
        Returns:
        t statistic
        Throws:
        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 to mu.

        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:
        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 to mu.

        Use the DataDispersion to control the computation of the variance.

        Parameters:
        x - First sample values.
        y - Second sample values.
        Returns:
        t statistic
        Throws:
        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 to mu.

        Degrees of freedom are \( v = n - 1 \).

        Parameters:
        m - Sample mean.
        v - Sample variance.
        n - Sample size.
        Returns:
        test result
        Throws:
        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 to mu.

        Degrees of freedom are \( v = n - 1 \).

        Parameters:
        sample - Sample values.
        Returns:
        the test result
        Throws:
        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 to mu.

        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 in x and y.

        Parameters:
        x - First sample values.
        y - Second sample values.
        Returns:
        the test result
        Throws:
        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 to mu.

        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:
        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)