==========================================================================
= PIBSIGS.LBR =
==========================================================================

Introduction:
------------

PIBSIGS.LBR contains Turbo Pascal procedures which
compute a variety of statistical distribution functions. The
distributions include the Beta, Log Gamma, Incomplete Gamma, F, t,
Chi-square, and Normal distributions. Both the forward
and inverse functions are provided. Although specific routines for
the binomial and negative binomial distribution are not given here,
probabilities and percentage points for those two distributions
can be computed from the Beta distribution.

Machine-dependent constants assume that Turbo-87 is to be used.
All machine-dependent constants are located in module SIGCONST.PAS,
if you wish to change them. You will need to change them if you don't
use Turbo-87.

I assume that you know something about these distributions, and when
they should be used. If you don't, these routines may not be very
useful to you. If you'd like to learn more about the subject of
statistical distributions, I suggest you read the series of books
by Johnson and Kotz, covering both discrete and continuous
statistical distributions. The publisher is Houghton Mifflin.


Files:
-----

Library PIBSIGS.LBR contains the following files:

README.DOC --- what you are reading now.

--- Basic distribution and support routines

ALGAMA.PAS --- logarithm of gamma function
CDBETA.PAS --- cumulative Beta distribution
CDNORM.PAS --- cumulative normal distribution
ERF.PAS --- Gaussian error function
GAMMAIN.PAS --- incomplete gamma integral
LOGTEN.PAS --- base 10 logarithm
POWER.PAS --- raise number to a real power
POWERI.PAS --- raise number to an integer power
POWTEN.PAS --- computes powers of ten
SIGCONST.PAS --- machine dependent constants

--- Point probability routines

SIGCHI.PAS --- significance of chi-square
SIGF.PAS --- significance of F
SIGNORM.PAS --- significance of normal value
SIGT.PAS --- significance of t

--- Inverse distributions (percentage points)

BETINV.PAS --- Inverse Beta
CINV.PAS --- Inverse chi-square
FINV.PAS --- inverse F
NINV.PAS --- inverse normal (low accuracy)
NINV2.PAS --- inverse normal (high accuracy)
TINV.PAS --- inverse t

--- Demonstration routines

TESTINVC.PAS --- demonstrate inverse chi-square
TESTINVF.PAS --- demonstrate inverse F
TESTINVN.PAS --- demonstrate inverse normal
TESTINVT.PAS --- demonstrate inverse t
TESTSIGC.PAS --- demonstrate chi-square significance
TESTSIGF.PAS --- demonstrate F significance
TESTSIGN.PAS --- demonstrate normal probability
TESTSIGT.PAS --- demonstrate t significance

--- File containing "(*$I" include directives for all the distribution
routines:

SIGALL.PAS

All of the Pascal source modules (ending in .PAS) are squeezed, so that
they actually appear as *.PQS in the PIBSIGS.LBR library file.
For instance, SIGF.PAS appears under the name SIGF.PQS. The Pascal
routines were squeezed WITHOUT the time and date stamp, so your favorite
unsqueezer should have no difficulty. I especially recommend
Alan Losoff's ALUSQ.COM.


Credits:
-------

These routines are translations of Fortran and Assembler routines which I
have used in various programs for many years. Many of the algorithms
are modified from ones which appeared in Applied Statistics or the
Communications of the ACM algorithms sections. If the algorithm comes from
one of those sources, that is mentioned in the header comments for the
corresponding routine.

I chose the algorithms included here based upon extensive experience and
empirical, simulation, and theoretical studies that demonstrate these
to be among the best available in terms of speed, accuracy, and robustness.
However, the area of computing for statistical distributions is
a constantly changing one, and any of the methods included here may soon
be retired in favor of new and better ones.


What PIBSIGS does:
------------------

PIBSIGS provides a fairly complete library of statistical distribution
routines covering the three most commonly used families of distributions:
the Incomplete Beta (F, t, binomial); the Incomplete Gamma (Chi-square);
and the Normal. These three distributions can also be used to approximate
many other families.

These routines may be used to compute the observed probabilities of
hypothesis tests and to compute percentage points required for the
construction of confidence intervals.

The basic routines for the beta and gamma distributions allow you to
specify the degree of accuracy you want and the maximum number of
iterations allowed. These routines also return an accuracy indicator
showing how many digits of precision were actually calculated. Note that
this doesn't mean that the answers are correct to that many places,
just that two successive ietratively derived values match to as many
decimal places as indicated.

The programs beginning with TEST... are brief demonstrations of how to
use the lower-level routines. The test programs typically ask for
a test value or probability value, and degrees of freedom. The output is
either the corresponding probability or percentage point.


Using PIBSIGS:
--------------

Extract all the .PQS files from the library. For most library utilities
this request appears as follows:

LU A PIBSIGS.LBR
or
LU86 -A PIBSIGS.LBR

After extracting all the files, unsqueeze all of the .PQS files.
Using an unsqueezer like Losoff's ALUSQ, this can be done as
follows:

ALUSQ *.PQS

If your unsqueezer doesn't allow wildcards, you will have to unsqueeze
each file one at a time.

To use the routines in your program, include the following routines
in this order before any others from PIBSIGS:

SIGCONST.PAS
LOGTEN.PAS
POWER.PAS
POWERI.PAS
POWTEN.PAS
ALGAMA.PAS
ERF.PAS

Then write includes for the specific routines you want. The sample programs
TEST*.PAS show which modules need to be included to use a given distribution.

To get ALL of the PIBSIGS modules included, copy the file SIGALL.PAS into your
program. SIGALL.PAS contains include directives for all the PIBSIGS modules
(except the test program, of course). Note that you can't include SIGALL.PAS
using a "(*$I" directive, since Turbo Pascal doesn't allow nested includes.


Glitches:
--------

These routines are designed to work with TURBO-87, the 8087 version
of Turbo Pascal. You must alter the constants in SIGCONST.PAS for the
non-8087 version. I have NOT tested the routines without the 8087.
I'd appreciate some feedback on how well they perform.

I hope that there are no coding errors in the routines; if you find
any, please let me know ASAP as indicated below.

I'd also appreciate any feedback on the performance of these routines,
or suggestions for alternate algorithms that you have found to be
valuable -- especially algorithms for troublesome cases where the
algorithms presented here have difficulties. In particular, it would
be nice to have algorithms that perform accurately and efficiently
to approximate the Incomplete Beta distribution with large degrees
of freedom -- greater than 100000. Such degrees of freedom DO occur
quite often in approximating multivariate distributions (e.g.,
Box's M test for assessing homogeneity of covariance matrices).


Usage Restrictions
------------------

I've placed these routines in the public domain. You are free to
add to them, correct them, extend them, or do whatever else you wish,
but PLEASE do NOT sell them as your own work. That's not nice.
If you wish to use these in a commercial product, PLEASE let me know
that you intend to do so (see below) so that I can inform you of
any needed bug fixes. You may use these routines in commercial
programs AS LONG AS you mention that I wrote them and you DO NOT
INCREASE THE PROGRAM'S PRICE JUST BECAUSE THESE ROUTINES ARE INCLUDED.


Comments:
--------

Send comments, suggestions, etc. to PHILIP BURNS on either of the
following two Chicago BBSs:

Gene Plantz's BBS: (312) 882 4227
Ron Fox's BBS: (312) 940 6496

or on the SMUG BBS:

SMUG BBS (P. Olympia): (301) 963 5249

As time permits, I will be adding other statistical distribution
functions to these such as approximations for multivariate
distributions, non-central distributions, and so on. Your comments
and suggestions are most welcome.


Thanks,
Phil Burns
May, 1985