...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 27c16dbb69.

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

_____________________________________________________________ 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.