This directory and its subdirectory contain source and
binary files for the statitics support packages that can
be run across multiple platforms.
The directory is organized as follows:
1) .\ ->
a) stat.c (single c source)
b) makefile.rst (common for windows, OS2 16, and OS2386)
c) makefile (for Windows NT)
d) sources (sources file for Windows NT)
e) The header file, teststat.h, required for building
the dlls is under ..\inc\.
2) .\win (FOR WINDOWS)
a) .\src (contains the remaining .asm file, and the
module def file)
b) .\bin (the binary statwin.dll file)
3) .\WIN32 (FOR WIN32 APPS)
a) .\src (contains the .def file and an i386 sub-dir.
and a mips subdir, each containing an asm file)
b) .\bin (the binary file)
4) .\os2286 (FOR 16 bit OS/2 Cruiser and Sloop apps)
a) .\src (the module def file)
b) .\bin (the binary stat286.dll file)
5) .\os2386 (FOR 32 bit OS/2 Cruiser apps)
a) .\src (the module def file)
b) .\bin (the binary stat386.dll file)
**********************************************************************
To build an application that uses a statistics DLL:
--------------------------------------------------
To use one of the above binaries, please read the USAGE NOTES at the
end of this document. Please copy the teststat.h file from this
directory to the directory where you are building your application.
Copy the relevant .dll to your libpath.
It is essential that you define the type of system you are building
your application for, since the header file uses some special types
that are dependent on the system. While compiling your application,
add the following flag: -DXXX where XXX stands for one of:
WIN - for Windows applications
OS2286 - for 16 bit OS/2 applications
OS2386 - for 32 bit OS/2 applications
WIN32 - for Win32 applications.
**********************************************************************
To build one of the dlls:
------------------------
If building a Windows, OS2 16 or OS/2 32 bit dll:
--------------------------------------------------------
a) Copy the stat.c file found under this directory
and teststat.h from ..\inc\. to a local directory.
Copy the .asm file from win\src if building for WIN.
b) Also copy the "makefile.rst" from here to the same directory.
c) From ???\src copy the remaining files to the local directory,
where ??? represents win, os2286 or os2386.
d) Edit "makefile.rst" to define the system that you are making the
dll for. Eg. if you are making the dll for windows, remove
the comment sign (#) from the line "WIN=TRUE" in the makefile
and ensure that the other system defines (OS2286 and OS2386)
are commented out.
f) Type "nmake -f makefile.rst" and the dll will be created for
you. (Ensure that your development environment is set up for
the right system).
If building the Win32 dll:
-------------------------
a) Copy stat.c, makefile and sources files found under this
directory and teststat.h from ..\inc\. to a local directory.
b) tc the win32\src directory to your local directory. This
will create an i386 (or mips) sub-directory containing an asm
file on your local machine.
c) From the directory where you have your sources file, type
"build -xxx statw32" from the command line, where xxx represents
your target system. It is 386 by default.
d) A binary file "statw32.dll" will be created along with the
.obj file under .\xxx\obj where xxx is your target system.
It is i386 by default.
In case you have any questions, or if you run into any problems,
contact vaidy (936-7812).
*****************************************************************
USAGE NOTES
-----------
This is the user's guide to using TestStat.dll, the
statistical package. In case of questions contact vaidy (936-
7812).
This document describes the use of each of the functions
available through this module and then demonstrates the use
of these routines through an example.
This module provides basic statistical routines which can be
used to compute average, min, max, standard deviation, and
statistical convergence. Statistical convergence of the
average is determined by the number of test iterations required
for the average to converge to a "stable" value. The number of
iterations required is computed on the fly as the data is
collected, so that the caller is informed when enough data is
collected (the average is stable). Stable averages obtained in
this way can be compared to other stable averages obtained under
different experimental conditions with known confidence levels.
Notes in this document describe the meanings of stability and
confidence more formally.
In addition to the functionlity described above, this module
also provides routines that generate normally distributed
random numbers. Three routines are provided that return
random numbers within a specified boundary, a set of uniformly
distributed random numbers within the range 0 to 1 and a normally
distributed set of numbers around a mean, which satisfy a given
mean and standard deviation.
1) TestStatOpen:
-------------
Description: Allocates an instance data array for the data set
and other global data structures required by the high level
functions.
USHORT FAR PASCAL
TestStatOpen (
USHORT usMinIterations,
USHORT usMaxIterations
);
usMinIterations - The minimum number of iterations
that the calling application has to run before
the convergence algorithm may be used.
usMaxIterations - The maximum number of iterations
that the test program may run. The maximum
acceptable value is 64K. An internal data array
of usMaxIterations of ULONGs is allocated. The
caller should bear this in mind when setting this
parameter.
Remarks: This routine should be called before the first
call to TestStatInit. If usMinIterations is zero, an error
code is returned. If usMinIterations is greater than
usMaxIterations an error code is returned. If usMinIterations
is equal to usMaxIterations, TestStatConverge will return TRUE
after that many iterations. This function frees the caller
from the responsibility of allocating any data storage or
book-keeping.
Return Value: 0 if the call succeeded.
An error code indicating a failure. The
error code may be one of:
STAT_ERROR_ILLEGAL_MIN_ITER
STAT_ERROR_ILLEGAL_MAX_ITER
STAT_ERROR_ALLOC_FAILED
See also: TestStatInit, TestStatConverge, TestStatValues,
TestStatClose.
2) TestStatInit:
-------------
Description: Initializes variables required by the convergence
and statistics routines.
VOID FAR PASCAL
TestStatInit (
VOID
);
Remarks: This routine should be called before the first
call to TestStatConverge and after each call to
TestStatValues, if you want to converge on a new set of
data.
Return Value: None.
See also: TestStatOpen, TestStatClose, TestStatConverge,
TestStatValues.
3) TestStatConverge:
-----------------
Description: Automatically computes number of iterations
required for 95% confidence in data obtained.
BOOL FAR PASCAL
TestStatConverge (
ULONG ulNewDataPoint,
);
ulNewDataPoint - The data point obtained for the
current iteration.
Remarks: This routine should be called for each
iteration of the test. The first call to this routine
should be preceded by a call to TestStatInit. The test
program should check for the return value and should stop
the test as soon as a TRUE is returned.
In making tests of significance, sometimes errors will be
encountered in the results concerning an hypothesis tested.
The hypothesis is that the difference between the actual
mean in one experiment and the actual mean in a second
experiment is less than a specified value. This
difference is expressed as a percentage of the first
experiment's mean. We call this difference, the "precision"
of the comparison.
If the assumption is true and the results of the tests leads one
to believe that it is false, the condition is described as a
TYPE I error. If the assumption is false and the test results
show that the two means are within the prescribed difference, the
condition is described as a TYPE II error.
The probability of TYPE I error is set by the significance level
of the test. Choosing a small probability of one type of error,
increases the probability of the other type.
The routines in this module operate on the following set of
assumed parameters:
95% confidence that if the means differ by less than 5% they
are really the same, and 85% confidence that if the means
differ by more than 5% that they are really different.
The algorithm in this module uses these assumptions to determine
the number of iterations needed to achieve these levels of
confidence.
The reason for emphasizing TYPE II error is that a TYPE I error
indicates that the means differ, when in fact, they are the same.
If they differ, we will usually explore why, and in doing so, will
discover that they are not really different after all. If, on the
other hand, we get a TYPE II error, then this means that the
results show no difference, whereas the means really are
different. This is to be avoided since if means don't differ
from one run to the next, we are unlikely to look further into
the problem.
When additional iterations are forced by a high usMinIterations,
then the resulting precision will usually be less than 5%.
Conversely, when usMaxIterations are reached without converging,
then the precision will be greater than 5%. The precision returned
by TestStatValues will indicate how meaningful the comparisons of
two means will be.
Return Value: FALSE if further iterations are required for
the test to converge or usMinIterations has
not been reached.
TRUE if already converged or maximum limit
on iterations has been reached.
See also: TestStatOpen, TestStatInit, TestStatValues,
TestStatClose.
4) TestStatValues:
----------------
Description: Automatically computes a number of useful
statistical values for a given set of data.
VOID FAR PASCAL
TestStatValues (
PSZ pszOutputString,
USHORT usOutlierFactor,
PULONG * pulDataArray,
PUSHORT pcusElementsInArray,
PUSHORT pcusDiscardedValues,
);
pszOutputString - A pointer to a string buffer to which
output data may be returned. The minimum size of
the buffer should be 81 bytes. The string will
be a NULL terminated ascii string.
usOutlierFactor - Factor that defines the range of
acceptable data values. A value of zero will ignore
this factor and all data will be considered
valid.
pulDataArray - A pointer to the data array. If the outlier
factor has been chosen, this array has as many elements
as there were good data points in the data set. Else,
all the data points are contained in the data array.
pcusElementsInArray - The number of elements in the array
pointed to by puDataArray.
pcusDiscardedValues - pointer to the number of data
points discarded based upon the outlier factor.
Remarks: This routine should be called only once for
each test, normally after TestStatConverge has returned
TRUE. Any call to this should be followed by a call to
TestStatInit before the next call to TestStatConverge,
if you want to converge on a new set of data. The Outlier
factor decides the range of acceptable values in the data set.
The format of the returned string will be (as in C):
"%4u %10lu %10lu %10lu %6u %5u %10lu %4u %2u ".
These represent the mode number, mean, minimum, maximum,
the number of iterations completed, the precision, the standard
deviation, number of points discarded, and, the outlier factor
from the data set. The mode number will always be zero.
The precision will be 5% in case test results converged before
the limit on the maximum iterations is reached. Otherwise,
it returns the precision of the results gathered.
The precision value in this case assumes that the Type I error
and Type II error probabilities are 85% and 95% respectively.
The outlier factor determines along with the standard deviation
any abnormal data points. Any data point that does not satisfy:
[Mean - (SDev * OF)] < Data Point < [Mean + (SDev * OF)],
where SDev is the standard deviation computed with good data
points and OF is the outlier factor, is left out in the
statistics computation. The standard deviation is
recomputed and this process is repeated until there are no
abnormal data entries in the data set. The number of
outliers that were discarded is also returned to the calling
program. To ignore the outlier factor and this process of
elimination, the outlier factor may be set to zero.
Otherwise, the outlier factor should be at least 2 in order
for the results to be meaningful.
Return Value: None
See also: TestStatOpen, TestStatClose, TestStatInit,
TestStatConverge
5) TestStatClose:
-------------
Description: Deallocates instance data structures and
all memory allocated by TestStatOpen and TestStatInit.
VOID FAR PASCAL
TestStatClose (
VOID
);
Remarks: This routine should be called after the last
call to TestStatValues. A call to this must be followed by a
call to TestStatOpen and TestStatInit, in that order, before
the application calls TestStatConverge and TestStatValues.
Return Value: None
See also: TestStatOpen, TestStatInit, TestStatConverge,
TestStatValues.
------------------------------------------------------------
Usage of Statistical routines for convergence and values: TestApp
------------------------------------------------------------------
#define MIN_ITERATION 3
#define MAX_ITERATION 200
#define OUTLIER_FACTOR 4
Body of test application
{
USHORT usMinIteration = MIN_ITERATION;
USHORT usMaxIteration = MAX_ITERATION;
ULONG ulDataForCurrentIter;
ULONG far *pulDataArray; // make sure you have the "far" for 16 bit.
char chOutputBufferForString [81];
USHORT usOutlierFactor = OUTLIER_FACTOR;
USHORT cusDiscardedValues;
USHORT cusElementsInArray;
:
:
if (!TestStatOpen (usMinIteration,
usMaxIteration)) {
// Data Array could not be allocated.
// Cannot do convergence/statistics routines;
// Check parameters to call;
}
do { // for each test or if need to run convergence again
TestStatInit ()
// Initialize test variables;
:
do { // convergence loop; do until a
// TRUE is returned
// Start the timer;
// Test operation;
// Stop the timer;
ulDataForCurrentIter = // get the elapsed time for
// operation;
} while (!TestStatConverge (ulDataForCurrentIter));
// the data set has converged. Call the Statistics
// routine for the values and output data
TestStatValues (OutputBufferForString,
usOutlierFactor,
&pulDataArray,
&cusDiscardedValues,
&cusElementsInArray,
);
// the OutputBufferForString array has all the data.
// iDiscardedValues has the number of discarded values
//
} while (//more tests or need to converge on new data set )
:
:
TestStatClose();
:
}
-------------------------------------------------------------------
Random Number Generation Routines:
6) TestStatUniRand:
---------------
Description: Returns a number within the range of 0 to 1 based on
a starting seed.
double FAR PASCAL
TestStatUniRand (
VOID
);
Remarks: This routine returns a set of uniformly distributed numbers
between 0 and 1, on being, called repeatedly. TestStatUniRand makes
use of the multiplicative congruential algorithm discussed in Knuth,
Vol. II, Chapter 3. A starting seed is chosen along with a
multiplier and a modulus values. The seed for the next iteration is
computed from these values as follows:
Temp Value = X * A, where,
X is the current seed value and A is the multiplier. The remainder
of the division of this value by the modulus identifier is
determined. This will be the seed for the next iteration. This
value is divided by the modulus value to obtain a normalized value
(that lies between 0 and 1). This normalized value is returned to
the caller.
Through experiments, Sullivans, W. L has determined that a good set of
values is returned by selecting one of the 9 following values as
starting seeds:
32347753, 52142147, 52142123, 53214215, 23521425, 42321479,
20302541, 32524125, 42152159.
TestStatUniRand uses 32347753 as the starting seed. A good set of
values, mentioned above, implies that for the given seed, it takes
a very large number of iterations, before the set of returned values
is repeated. The following values have been chosen for the
multiplier and the modulus by M.C. Pike and I.D. Hill (reference):
Multiplier - 3125
Modulus id - 67108864
Return Value: A double float between 0 and 1.
See also: TestStatShortRand, TestStatRand, TestStatNormDist.
7) TestStatShortRand:
-----------------
Description: Returns a number within the range of 0 to 65535 based on
a starting seed.
USHORT FAR PASCAL
TestStatShortRand (
VOID
);
Remarks: This routine returns a set of uniformly distributed numbers
between 0 and 65535, on being, called repeatedly. TestStatShortRand makes
use of the multiplicative congruential algorithm discussed in Knuth,
Vol. II, Chapter 3. A starting seed is chosen along with a
multiplier and a modulus values. The seed for the next iteration is
computed from these values as follows:
Temp Value = X * A, where,
X is the current seed value and A is the multiplier. The remainder
of the division of this value by the modulus identifier is
determined. This will be the seed for the next iteration. This
value is multiplied by 65535 and divided by the modulus value
to obtain a value between 0 and 65535. This value is returned to
the caller.
Through experiments, Sullivans, W. L has determined that a good set of
values is returned by selecting one of the 9 following values as
starting seeds:
32347753, 52142147, 52142123, 53214215, 23521425, 42321479,
20302541, 32524125, 42152159.
TestStatShortRand uses 32347753 as the starting seed. A good set of
values, mentioned above, implies that for the given seed, it takes
a very large number of iterations, before the set of returned values
is repeated. The following values have been chosen for the
multiplier and the modulus by M.C. Pike and I.D. Hill (reference):
Multiplier - 3125
Modulus id - 67108864
Return Value: A USHORT between 0 and 65535.
See also: TestStatUniRand, TestStatRand, TestStatNormDist.
8) TestStatRand:
------------
Description: Returns a uniformly distributed random number within
a specified range.
ULONG FAR PASCAL
TestStatRand (
ULONG ulLower,
ULONG ulUpper
);
ulLower - Specifies the lower boundary of the desired random
number. Should be atleast 1 in value.
ulUpper - Specifies the upper boundary of the desired random
number. May not exceed 67108863.
Remarks: TestStatRand calls TestStatNorm for obtaining a normalized
random number. The value obtained from TestStatNorm is then
multiplied by the range (i.e. the difference between ulUpper and
ulLower). The computed value is then added to the lower limit
and the resulting number is returned. It should be noted that both
ulLower and ulUpper are included in the range of returned random
numbers.
Return Value: A random number within the specified range.
See Also: TestStatShortRand, TestStatUniRand, TestStatNormDist.
9) TestStatNormDist:
----------------
Description: With every call, returns a number that forms a set
of points whose mean is approximately the input mean and whose
standard deviation is nearly equal to the input standard deviation.
A normally distributed set of points is generated.
LONG FAR PASCAL
TestStatNormDist (
ULONG ulMean,
USHORT usSDev
);
Remarks: This routine uses a formula discussed in 'Random Number
Generation and Testing', IBM Data Processing Techniques, C20-8011
and 'Tuning an Operating System for General Purpose Use', Russell
P. Blake, Online Conferences (info. to be filled in).
TestStatNormDist makes use of TestStatShortRand to get a set of
uniformly distributed numbers. It generates a point around the
input mean using the following formula:
14
_
lRetVal <- Mean + ( -7 + >_ TestStatShortRand ()) * Std. Dev
i=1
The set of points generated with several calls to this routine
will be uniformly distributed with a mean of about the input mean
and a standard deviation of approximately the input standard
deviation. The returned value may be negative, too, depending
upon the values returned by TestStatShortRand and the input standard
deviation!
Return Value: A long integer.
See also: TestStatShortRand, TestStatUniRand, TestStatRand.
