Squashed 'third_party/boostorg/math/' content from commit 0e9549f
Change-Id: I7c2a13cb6a5beea4a471341510d8364cedd71613
git-subtree-dir: third_party/boostorg/math
git-subtree-split: 0e9549ff2f854e6edafaf4627d65026f2f533a18
diff --git a/doc/distributions/students_t_examples.qbk b/doc/distributions/students_t_examples.qbk
new file mode 100644
index 0000000..483631e
--- /dev/null
+++ b/doc/distributions/students_t_examples.qbk
@@ -0,0 +1,781 @@
+
+[section:st_eg Student's t Distribution Examples]
+
+[section:tut_mean_intervals Calculating confidence intervals on the mean with the Students-t distribution]
+
+Let's say you have a sample mean, you may wish to know what confidence intervals
+you can place on that mean. Colloquially: "I want an interval that I can be
+P% sure contains the true mean". (On a technical point, note that
+the interval either contains the true mean or it does not: the
+meaning of the confidence level is subtly
+different from this colloquialism. More background information can be found on the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm NIST site]).
+
+The formula for the interval can be expressed as:
+
+[equation dist_tutorial4]
+
+Where, ['Y[sub s]] is the sample mean, /s/ is the sample standard deviation,
+/N/ is the sample size, /[alpha]/ is the desired significance level and
+['t[sub ([alpha]/2,N-1)]] is the upper critical value of the Students-t
+distribution with /N-1/ degrees of freedom.
+
+[note
+The quantity [alpha][space] is the maximum acceptable risk of falsely rejecting
+the null-hypothesis. The smaller the value of [alpha] the greater the
+strength of the test.
+
+The confidence level of the test is defined as 1 - [alpha], and often expressed
+as a percentage. So for example a significance level of 0.05, is equivalent
+to a 95% confidence level. Refer to
+[@http://www.itl.nist.gov/div898/handbook/prc/section1/prc14.htm
+"What are confidence intervals?"] in __handbook for more information.
+] [/ Note]
+
+[note
+The usual assumptions of
+[@http://en.wikipedia.org/wiki/Independent_and_identically-distributed_random_variables independent and identically distributed (i.i.d.)]
+variables and [@http://en.wikipedia.org/wiki/Normal_distribution normal distribution]
+of course apply here, as they do in other examples.
+]
+
+From the formula, it should be clear that:
+
+* The width of the confidence interval decreases as the sample size increases.
+* The width increases as the standard deviation increases.
+* The width increases as the ['confidence level increases] (0.5 towards 0.99999 - stronger).
+* The width increases as the ['significance level decreases] (0.5 towards 0.00000...01 - stronger).
+
+The following example code is taken from the example program
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp].
+
+We'll begin by defining a procedure to calculate intervals for
+various confidence levels; the procedure will print these out
+as a table:
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void confidence_limits_on_mean(
+ double Sm, // Sm = Sample Mean.
+ double Sd, // Sd = Sample Standard Deviation.
+ unsigned Sn) // Sn = Sample Size.
+ {
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "__________________________________\n"
+ "2-Sided Confidence Limits For Mean\n"
+ "__________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << Sn << "\n";
+ cout << setw(40) << left << "Mean" << "= " << Sm << "\n";
+ cout << setw(40) << left << "Standard Deviation" << "= " << Sd << "\n";
+
+We'll define a table of significance/risk levels for which we'll compute intervals:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Note that these are the complements of the confidence/probability levels: 0.5, 0.75, 0.9 .. 0.99999).
+
+Next we'll declare the distribution object we'll need, note that
+the /degrees of freedom/ parameter is the sample size less one:
+
+ students_t dist(Sn - 1);
+
+Most of what follows in the program is pretty printing, so let's focus
+on the calculation of the interval. First we need the t-statistic,
+computed using the /quantile/ function and our significance level. Note
+that since the significance levels are the complement of the probability,
+we have to wrap the arguments in a call to /complement(...)/:
+
+ double T = quantile(complement(dist, alpha[i] / 2));
+
+Note that alpha was divided by two, since we'll be calculating
+both the upper and lower bounds: had we been interested in a single
+sided interval then we would have omitted this step.
+
+Now to complete the picture, we'll get the (one-sided) width of the
+interval from the t-statistic
+by multiplying by the standard deviation, and dividing by the square
+root of the sample size:
+
+ double w = T * Sd / sqrt(double(Sn));
+
+The two-sided interval is then the sample mean plus and minus this width.
+
+And apart from some more pretty-printing that completes the procedure.
+
+Let's take a look at some sample output, first using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm
+Heat flow data] from the NIST site. The data set was collected
+by Bob Zarr of NIST in January, 1990 from a heat flow meter
+calibration and stability analysis.
+The corresponding dataplot
+output for this test can be found in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+section 3.5.2] of the __handbook.
+
+[pre'''
+ __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 195
+ Mean = 9.26146
+ Standard Deviation = 0.02278881
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.676 1.103e-003 9.26036 9.26256
+ 75.000 1.154 1.883e-003 9.25958 9.26334
+ 90.000 1.653 2.697e-003 9.25876 9.26416
+ 95.000 1.972 3.219e-003 9.25824 9.26468
+ 99.000 2.601 4.245e-003 9.25721 9.26571
+ 99.900 3.341 5.453e-003 9.25601 9.26691
+ 99.990 3.973 6.484e-003 9.25498 9.26794
+ 99.999 4.537 7.404e-003 9.25406 9.26886
+''']
+
+As you can see the large sample size (195) and small standard deviation (0.023)
+have combined to give very small intervals, indeed we can be
+very confident that the true mean is 9.2.
+
+For comparison the next example data output is taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+[pre'''
+ __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 3
+ Mean = 37.8000000
+ Standard Deviation = 0.9643650
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.816 0.455 37.34539 38.25461
+ 75.000 1.604 0.893 36.90717 38.69283
+ 90.000 2.920 1.626 36.17422 39.42578
+ 95.000 4.303 2.396 35.40438 40.19562
+ 99.000 9.925 5.526 32.27408 43.32592
+ 99.900 31.599 17.594 20.20639 55.39361
+ 99.990 99.992 55.673 -17.87346 93.47346
+ 99.999 316.225 176.067 -138.26683 213.86683
+''']
+
+This time the fact that there are only three measurements leads to
+much wider intervals, indeed such large intervals that it's hard
+to be very confident in the location of the mean.
+
+[endsect]
+
+[section:tut_mean_test Testing a sample mean for difference from a "true" mean]
+
+When calibrating or comparing a scientific instrument or measurement method of some kind,
+we want to be answer the question "Does an observed sample mean differ from the
+"true" mean in any significant way?". If it does, then we have evidence of
+a systematic difference. This question can be answered with a Students-t test:
+more information can be found
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+on the NIST site].
+
+Of course, the assignment of "true" to one mean may be quite arbitrary,
+often this is simply a "traditional" method of measurement.
+
+The following example code is taken from the example program
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp].
+
+We'll begin by defining a procedure to determine which of the
+possible hypothesis are rejected or not-rejected
+at a given significance level:
+
+[note
+Non-statisticians might say 'not-rejected' means 'accepted',
+(often of the null-hypothesis) implying, wrongly, that there really *IS* no difference,
+but statisticans eschew this to avoid implying that there is positive evidence of 'no difference'.
+'Not-rejected' here means there is *no evidence* of difference, but there still might well be a difference.
+For example, see [@http://en.wikipedia.org/wiki/Argument_from_ignorance argument from ignorance] and
+[@http://www.bmj.com/cgi/content/full/311/7003/485 Absence of evidence does not constitute evidence of absence.]
+] [/ note]
+
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void single_sample_t_test(double M, double Sm, double Sd, unsigned Sn, double alpha)
+ {
+ //
+ // M = true mean.
+ // Sm = Sample Mean.
+ // Sd = Sample Standard Deviation.
+ // Sn = Sample Size.
+ // alpha = Significance Level.
+
+Most of the procedure is pretty-printing, so let's just focus on the
+calculation, we begin by calculating the t-statistic:
+
+ // Difference in means:
+ double diff = Sm - M;
+ // Degrees of freedom:
+ unsigned v = Sn - 1;
+ // t-statistic:
+ double t_stat = diff * sqrt(double(Sn)) / Sd;
+
+Finally calculate the probability from the t-statistic. If we're interested
+in simply whether there is a difference (either less or greater) or not,
+we don't care about the sign of the t-statistic,
+and we take the complement of the probability for comparison
+to the significance level:
+
+ students_t dist(v);
+ double q = cdf(complement(dist, fabs(t_stat)));
+
+The procedure then prints out the results of the various tests
+that can be done, these
+can be summarised in the following table:
+
+[table
+[[Hypothesis][Test]]
+[[The Null-hypothesis: there is
+*no difference* in means]
+[Reject if complement of CDF for |t| < significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: there
+*is difference* in means]
+[Reject if complement of CDF for |t| > significance level / 2:
+
+`cdf(complement(dist, fabs(t))) > alpha / 2`]]
+
+[[The Alternative-hypothesis: the sample mean *is less* than
+the true mean.]
+[Reject if CDF of t > 1 - significance level:
+
+`cdf(complement(dist, t)) < alpha`]]
+
+[[The Alternative-hypothesis: the sample mean *is greater* than
+the true mean.]
+[Reject if complement of CDF of t < significance level:
+
+`cdf(dist, t) < alpha`]]
+]
+
+[note
+Notice that the comparisons are against `alpha / 2` for a two-sided test
+and against `alpha` for a one-sided test]
+
+Now that we have all the parts in place, let's take a look at some
+sample output, first using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm
+Heat flow data] from the NIST site. The data set was collected
+by Bob Zarr of NIST in January, 1990 from a heat flow meter
+calibration and stability analysis. The corresponding dataplot
+output for this test can be found in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm
+section 3.5.2] of the __handbook.
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 195
+Sample Mean = 9.26146
+Sample Standard Deviation = 0.02279
+Expected True Mean = 5.00000
+
+Sample Mean - Expected Test Mean = 4.26146
+Degrees of Freedom = 194
+T Statistic = 2611.28380
+Probability that difference is due to chance = 0.000e+000
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Mean != 5.000 NOT REJECTED
+Mean < 5.000 REJECTED
+Mean > 5.000 NOT REJECTED
+]
+
+You will note the line that says the probability that the difference is
+due to chance is zero. From a philosophical point of view, of course,
+the probability can never reach zero. However, in this case the calculated
+probability is smaller than the smallest representable double precision number,
+hence the appearance of a zero here. Whatever its "true" value is, we know it
+must be extraordinarily small, so the alternative hypothesis - that there is
+a difference in means - is not rejected.
+
+For comparison the next example data output is taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 3
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+Expected True Mean = 38.90000
+
+Sample Mean - Expected Test Mean = -1.10000
+Degrees of Freedom = 2
+T Statistic = -1.97566
+Probability that difference is due to chance = 1.869e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Mean != 38.900 REJECTED
+Mean < 38.900 NOT REJECTED
+Mean > 38.900 NOT REJECTED
+]
+
+As you can see the small number of measurements (3) has led to a large uncertainty
+in the location of the true mean. So even though there appears to be a difference
+between the sample mean and the expected true mean, we conclude that there
+is no significant difference, and are unable to reject the null hypothesis.
+However, if we were to lower the bar for acceptance down to alpha = 0.1
+(a 90% confidence level) we see a different output:
+
+[pre
+__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 3
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+Expected True Mean = 38.90000
+
+Sample Mean - Expected Test Mean = -1.10000
+Degrees of Freedom = 2
+T Statistic = -1.97566
+Probability that difference is due to chance = 1.869e-001
+
+Results for Alternative Hypothesis and alpha = 0.1000
+
+Alternative Hypothesis Conclusion
+Mean != 38.900 REJECTED
+Mean < 38.900 NOT REJECTED
+Mean > 38.900 REJECTED
+]
+
+In this case, we really have a borderline result,
+and more data (and/or more accurate data),
+is needed for a more convincing conclusion.
+
+[endsect]
+
+[section:tut_mean_size Estimating how large a sample size would have to become
+in order to give a significant Students-t test result with a single sample test]
+
+Imagine you have conducted a Students-t test on a single sample in order
+to check for systematic errors in your measurements. Imagine that the
+result is borderline. At this point one might go off and collect more data,
+but it might be prudent to first ask the question "How much more?".
+The parameter estimators of the students_t_distribution class
+can provide this information.
+
+This section is based on the example code in
+[@../../example/students_t_single_sample.cpp students_t_single_sample.cpp]
+and we begin by defining a procedure that will print out a table of
+estimated sample sizes for various confidence levels:
+
+ // Needed includes:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Bring everything into global namespace for ease of use:
+ using namespace boost::math;
+ using namespace std;
+
+ void single_sample_find_df(
+ double M, // M = true mean.
+ double Sm, // Sm = Sample Mean.
+ double Sd) // Sd = Sample Standard Deviation.
+ {
+
+Next we define a table of significance levels:
+
+ double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+
+Printing out the table of sample sizes required for various confidence levels
+begins with the table header:
+
+ cout << "\n\n"
+ "_______________________________________________________________\n"
+ "Confidence Estimated Estimated\n"
+ " Value (%) Sample Size Sample Size\n"
+ " (one sided test) (two sided test)\n"
+ "_______________________________________________________________\n";
+
+
+And now the important part: the sample sizes required. Class
+`students_t_distribution` has a static member function
+`find_degrees_of_freedom` that will calculate how large
+a sample size needs to be in order to give a definitive result.
+
+The first argument is the difference between the means that you
+wish to be able to detect, here it's the absolute value of the
+difference between the sample mean, and the true mean.
+
+Then come two probability values: alpha and beta. Alpha is the
+maximum acceptable risk of rejecting the null-hypothesis when it is
+in fact true. Beta is the maximum acceptable risk of failing to reject
+the null-hypothesis when in fact it is false.
+Also note that for a two-sided test, alpha must be divided by 2.
+
+The final parameter of the function is the standard deviation of the sample.
+
+In this example, we assume that alpha and beta are the same, and call
+`find_degrees_of_freedom` twice: once with alpha for a one-sided test,
+and once with alpha/2 for a two-sided test.
+
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate df for single sided test:
+ double df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i], alpha[i], Sd);
+ // convert to sample size:
+ double size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size;
+ // calculate df for two sided test:
+ df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i]/2, alpha[i], Sd);
+ // convert to sample size:
+ size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size << endl;
+ }
+ cout << endl;
+ }
+
+Let's now look at some sample output using data taken from
+['P.K.Hou, O. W. Lau & M.C. Wong, Analyst (1983) vol. 108, p 64.
+and from Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55
+J. C. Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.]
+The values result from the determination of mercury by cold-vapour
+atomic absorption.
+
+Only three measurements were made, and the Students-t test above
+gave a borderline result, so this example
+will show us how many samples would need to be collected:
+
+[pre'''
+_____________________________________________________________
+Estimated sample sizes required for various confidence levels
+_____________________________________________________________
+
+True Mean = 38.90000
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+
+
+_______________________________________________________________
+Confidence Estimated Estimated
+ Value (%) Sample Size Sample Size
+ (one sided test) (two sided test)
+_______________________________________________________________
+ 75.000 3 4
+ 90.000 7 9
+ 95.000 11 13
+ 99.000 20 22
+ 99.900 35 37
+ 99.990 50 53
+ 99.999 66 68
+''']
+
+So in this case, many more measurements would have had to be made,
+for example at the 95% level, 14 measurements in total for a two-sided test.
+
+[endsect]
+[section:two_sample_students_t Comparing the means of two samples with the Students-t test]
+
+Imagine that we have two samples, and we wish to determine whether
+their means are different or not. This situation often arises when
+determining whether a new process or treatment is better than an old one.
+
+In this example, we'll be using the
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3531.htm
+Car Mileage sample data] from the
+[@http://www.itl.nist.gov NIST website]. The data compares
+miles per gallon of US cars with miles per gallon of Japanese cars.
+
+The sample code is in
+[@../../example/students_t_two_samples.cpp students_t_two_samples.cpp].
+
+There are two ways in which this test can be conducted: we can assume
+that the true standard deviations of the two samples are equal or not.
+If the standard deviations are assumed to be equal, then the calculation
+of the t-statistic is greatly simplified, so we'll examine that case first.
+In real life we should verify whether this assumption is valid with a
+Chi-Squared test for equal variances.
+
+We begin by defining a procedure that will conduct our test assuming equal
+variances:
+
+ // Needed headers:
+ #include <boost/math/distributions/students_t.hpp>
+ #include <iostream>
+ #include <iomanip>
+ // Simplify usage:
+ using namespace boost::math;
+ using namespace std;
+
+ void two_samples_t_test_equal_sd(
+ double Sm1, // Sm1 = Sample 1 Mean.
+ double Sd1, // Sd1 = Sample 1 Standard Deviation.
+ unsigned Sn1, // Sn1 = Sample 1 Size.
+ double Sm2, // Sm2 = Sample 2 Mean.
+ double Sd2, // Sd2 = Sample 2 Standard Deviation.
+ unsigned Sn2, // Sn2 = Sample 2 Size.
+ double alpha) // alpha = Significance Level.
+ {
+
+
+Our procedure will begin by calculating the t-statistic, assuming
+equal variances the needed formulae are:
+
+[equation dist_tutorial1]
+
+where Sp is the "pooled" standard deviation of the two samples,
+and /v/ is the number of degrees of freedom of the two combined
+samples. We can now write the code to calculate the t-statistic:
+
+ // Degrees of freedom:
+ double v = Sn1 + Sn2 - 2;
+ cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+ // Pooled variance:
+ double sp = sqrt(((Sn1-1) * Sd1 * Sd1 + (Sn2-1) * Sd2 * Sd2) / v);
+ cout << setw(55) << left << "Pooled Standard Deviation" << "= " << sp << "\n";
+ // t-statistic:
+ double t_stat = (Sm1 - Sm2) / (sp * sqrt(1.0 / Sn1 + 1.0 / Sn2));
+ cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+
+The next step is to define our distribution object, and calculate the
+complement of the probability:
+
+ students_t dist(v);
+ double q = cdf(complement(dist, fabs(t_stat)));
+ cout << setw(55) << left << "Probability that difference is due to chance" << "= "
+ << setprecision(3) << scientific << 2 * q << "\n\n";
+
+Here we've used the absolute value of the t-statistic, because we initially
+want to know simply whether there is a difference or not (a two-sided test).
+However, we can also test whether the mean of the second sample is greater
+or is less (one-sided test) than that of the first:
+all the possible tests are summed up in the following table:
+
+[table
+[[Hypothesis][Test]]
+[[The Null-hypothesis: there is
+*no difference* in means]
+[Reject if complement of CDF for |t| < significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: there is a
+*difference* in means]
+[Reject if complement of CDF for |t| > significance level / 2:
+
+`cdf(complement(dist, fabs(t))) < alpha / 2`]]
+
+[[The Alternative-hypothesis: Sample 1 Mean is *less* than
+Sample 2 Mean.]
+[Reject if CDF of t > significance level:
+
+`cdf(dist, t) > alpha`]]
+
+[[The Alternative-hypothesis: Sample 1 Mean is *greater* than
+Sample 2 Mean.]
+
+[Reject if complement of CDF of t > significance level:
+
+`cdf(complement(dist, t)) > alpha`]]
+]
+
+[note
+For a two-sided test we must compare against alpha / 2 and not alpha.]
+
+Most of the rest of the sample program is pretty-printing, so we'll
+skip over that, and take a look at the sample output for alpha=0.05
+(a 95% probability level). For comparison the dataplot output
+for the same data is in
+[@http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm
+section 1.3.5.3] of the __handbook.
+
+[pre'''
+ ________________________________________________
+ Student t test for two samples (equal variances)
+ ________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.145
+ Sample 1 Standard Deviation = 6.4147
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.481
+ Sample 2 Standard Deviation = 6.1077
+ Degrees of Freedom = 326
+ Pooled Standard Deviation = 6.3426
+ T Statistic = -12.621
+ Probability that difference is due to chance = 5.273e-030
+
+ Results for Alternative Hypothesis and alpha = 0.0500'''
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+]
+
+So with a probability that the difference is due to chance of just
+5.273e-030, we can safely conclude that there is indeed a difference.
+
+The tests on the alternative hypothesis show that we must
+also reject the hypothesis that Sample 1 Mean is
+greater than that for Sample 2: in this case Sample 1 represents the
+miles per gallon for Japanese cars, and Sample 2 the miles per gallon for
+US cars, so we conclude that Japanese cars are on average more
+fuel efficient.
+
+Now that we have the simple case out of the way, let's look for a moment
+at the more complex one: that the standard deviations of the two samples
+are not equal. In this case the formula for the t-statistic becomes:
+
+[equation dist_tutorial2]
+
+And for the combined degrees of freedom we use the
+[@http://en.wikipedia.org/wiki/Welch-Satterthwaite_equation Welch-Satterthwaite]
+approximation:
+
+[equation dist_tutorial3]
+
+Note that this is one of the rare situations where the degrees-of-freedom
+parameter to the Student's t distribution is a real number, and not an
+integer value.
+
+[note
+Some statistical packages truncate the effective degrees of freedom to
+an integer value: this may be necessary if you are relying on lookup tables,
+but since our code fully supports non-integer degrees of freedom there is no
+need to truncate in this case. Also note that when the degrees of freedom
+is small then the Welch-Satterthwaite approximation may be a significant
+source of error.]
+
+Putting these formulae into code we get:
+
+ // Degrees of freedom:
+ double v = Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2;
+ v *= v;
+ double t1 = Sd1 * Sd1 / Sn1;
+ t1 *= t1;
+ t1 /= (Sn1 - 1);
+ double t2 = Sd2 * Sd2 / Sn2;
+ t2 *= t2;
+ t2 /= (Sn2 - 1);
+ v /= (t1 + t2);
+ cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+ // t-statistic:
+ double t_stat = (Sm1 - Sm2) / sqrt(Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2);
+ cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+
+Thereafter the code and the tests are performed the same as before. Using
+are car mileage data again, here's what the output looks like:
+
+[pre'''
+ __________________________________________________
+ Student t test for two samples (unequal variances)
+ __________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.145
+ Sample 1 Standard Deviation = 6.4147
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.481
+ Sample 2 Standard Deviation = 6.1077
+ Degrees of Freedom = 136.87
+ T Statistic = -12.946
+ Probability that difference is due to chance = 1.571e-025
+
+ Results for Alternative Hypothesis and alpha = 0.0500'''
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+]
+
+This time allowing the variances in the two samples to differ has yielded
+a higher likelihood that the observed difference is down to chance alone
+(1.571e-025 compared to 5.273e-030 when equal variances were assumed).
+However, the conclusion remains the same: US cars are less fuel efficient
+than Japanese models.
+
+[endsect]
+[section:paired_st Comparing two paired samples with the Student's t distribution]
+
+Imagine that we have a before and after reading for each item in the sample:
+for example we might have measured blood pressure before and after administration
+of a new drug. We can't pool the results and compare the means before and after
+the change, because each patient will have a different baseline reading.
+Instead we calculate the difference between before and after measurements
+in each patient, and calculate the mean and standard deviation of the differences.
+To test whether a significant change has taken place, we can then test
+the null-hypothesis that the true mean is zero using the same procedure
+we used in the single sample cases previously discussed.
+
+That means we can:
+
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_intervals Calculate confidence intervals of the mean].
+If the endpoints of the interval differ in sign then we are unable to reject
+the null-hypothesis that there is no change.
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_test Test whether the true mean is zero]. If the
+result is consistent with a true mean of zero, then we are unable to reject the
+null-hypothesis that there is no change.
+* [link math_toolkit.stat_tut.weg.st_eg.tut_mean_size Calculate how many pairs of readings we would need
+in order to obtain a significant result].
+
+[endsect]
+
+[endsect][/section:st_eg Student's t]
+
+[/
+ Copyright 2006, 2012 John Maddock and Paul A. Bristow.
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt).
+]
+