*! version 1.0 2021-10-25 Mark Chatfield

Title

tolerance -- Tolerance intervals (normal distribution)

Syntax

Generate tolerance intervals from input data:

tolerance varname [if] [in],
percentofpop(#)
[confidence(#)
onesided
method(method_type)]

Immediate command:

tolerancei #obs #mean #sd,
percentofpop(#)
[confidence(#)
onesided
method(method_type)]

options

percentofpop(#) required; specifies the percentage of the population for an interval to contain/cover

confidence(#) specifies a percentofpop% tolerance interval with #% confidence is to be calculated.
If this option is omitted, a percentofpop%-expectation tolerance interval is calculated
(which is equivalent to a percentofpop% prediction interval)

onesided specifies one-sided tolerance intervals are to be calculated

method(method_type) The default for a two-sided percentofpop% tolerance interval with conf% confidence is an approximate method recommended by Howe (1969).
Specify method(howesimpler) to use a simpler method also described by Howe (1969). See Remarks for more.

Description

tolerance, and the immediate command tolerancei, calculate one-sided or two-sided tolerance intervals,
assuming a sample has been drawn randomly from a normal distribution.
The factor, k, used in the calculation (mean ± k × sd, mean - k × sd, or mean + k × sd) is also reported.
k is a function of: #obs, percentofpop, confidence and onesided.

Tolerance intervals are statistical intervals that contain
(or cover) at least a percentage of a population,
either on average, or else with a stated confidence. Prediction intervals, and confidence intervals on quantiles can be regarded
as special cases of tolerance intervals (Vangel, 2005).

A 95% tolerance interval with #% confidence is an interval that contains at least 95% of a population, with #% confidence.

A 95%-expectation tolerance interval is an interval that contains at least 95% of a population, on average.
It is equivalent to a 95% prediction interval.
A prediction interval is an interval where a future measurement is expected to lie, with a given confidence level. See Chapter 4.7 (p55) of Meeker et al. (2017) for the formula.

A one-sided p% tolerance interval with #% confidence
is equivalent to a one-sided #% confidence interval for the pth percentile (Meeker et al. 2017).

[Extra] A two-sided 95% confidence interval for the pth percentile can be formed by
using the bounds of one-sided p% tolerance intervals with 97.5% confidence.
It is an oversight of [R] centile that this exact method is not available.

Remarks

The old tolerance command (Lachenbruch 2004) was described incorrectly.
p(#) was described as the confidence level, and gamma(#) as the coverage proportion, whereas
the opposite was true: gamma(#) was the confidence level, and p(#) the coverage proportion.
I have deliberately avoided referring to gamma or beta in the new tolerance command because, confusingly,
the parameters have been used inconsistently in the literature to refer to (i) confidence level & (ii) coverage/content, and vice versa.

Re: method for a calculating a two-sided percentofpop% tolerance interval with conf% confidence.
Approximate intervals are calculated because I have decided to calculate approximate (rather than exact - maybe I'll add this one day) values of k.
By default, Howe (1969)'s recommended method for our situation is used (k=λ_3). Young (2010) used this method.
method(howesimpler) will allow use of a simpler method (k=λ_1) described by Howe (1969),
and used by tolerance.
Note, the simpler method was described by Howe (1969) purely to make the point that
"nothing is gained by using the Wald-Wolfowitz approximation rather than the simpler [method]".

Examples

. sysuse auto, clear

Computing a 95%-expectation tolerance interval (equivalently a 95% prediction interval)

Either of these commands could be used:

. tolerance mpg, percentofpop(95)

. tolerancei 74 21.2973 5.785503, percentofpop(95)

Computing a 95% tolerance interval with a 99% confidence level

Either of these commands could be used:

. tolerance mpg, percentofpop(95) confidence(99)

. tolerancei 74 21.2973 5.785503, percentofpop(95) confidence(99)

Getting the same factors as those reported in Howe (1969)

Factors k=3.101 [and k=3.082] were reported in Table 1 for N=13 for the principal [and simpler] method, with percentofpop(95) confidence(95). Note the choice of mean and sd below does not affect the factor.

. tolerancei 13 0.1234 0.6789, percentofpop(95) confidence(95)

. tolerancei 13 0.1234 0.6789, percentofpop(95) confidence(95) m(howesimpler)

Computing a one-sided 90% tolerance interval with 95% confidence

(equivalently a one-sided 95% CI for the 90th percentile)

This reproduces the answer given in Example 4.4 (Section 4.4) in Meeker et al. (2017).

. tolerancei 5 50.10 1.31, percentofpop(90) confidence(95) onesided

[Extra] Computing a two-sided 95% confidence interval for the 2.5th percentile

tolerance can be used to produce an exact two-sided 95% confidence interval for the pth percentile, which [R] centile cannot yet do.

. tolerance mpg, percentofpop(2.5) confidence(97.5) onesided

. centile mpg, centile(2.5) level(95) meansd

Stored results

tolerance and tolerancei store the following in r():

Scalars

r(low) lower bound of interval

r(upp) upper bound of interval

r(k) factor used for two-sided interval

r(k_lb) factor used for one-sided interval

r(k_ub) factor used for the other one-sided interval

References

Howe, W. G. (1969) Two-sided tolerance limits for normal populations - some improvements. Journal of the American Statistical Association, 64, 610–620.

Lachenbruch, P. (2004) "TOLERANCE: Stata module to generate tolerance intervals from input data," Statistical Software Components S447401, Boston College Department of Economics, revised 19 Jan 2006.

Meeker, W. Q., G. J. Hahn and L. A. Escobar. (2017) Statistical Intervals: A guide for practitioners and researchers. Second edition. John Wiley & Sons, Inc.

Vangel, M. G. (2005) Tolerance Interval. In The Encyclopedia of Biostatistics, 2nd Edition, edited by P. Armitage and T. Colton. John Wiley & Sons, Ltd.

Young, D. S. (2010) "tolerance: An R Package for Estimating Tolerance Intervals".
Journal of Statistical Software. 36 (5): 1–39. ISSN 1548-7660. Retrieved 19 February 2013.
Documentation for Version 2.0.0 (2020-02-04) here:
"https://cran.r-project.org/web/packages/tolerance/tolerance.pdf"

Author

Mark Chatfield, The University of Queensland, Australia.

m.chatfield@uq.edu.au