A table is used to gather statistics
on a sequence of discrete values such
as interarrival times, service times,
or response times. Data values are "recorded"
in a table to include them in the statistics.
A table does not actually store the
recorded values; it simply updates the
statistics each time a value is included.
(See section
11.6, "Moving Windows",
for the only exception to this rule.)
The statistics maintained by a table
include the minimum, maximum, range,
mean, variance, standard deviation,
and coefficient of variation. Optional
features for a table allow the creation
of a histogram, the calculation of confidence
intervals, and the computation of statistics
for values in a moving window.
First-time users of tables should focus
on the following three sections, which
explain how to set up tables, record
values, and produce reports. Subsequent
sections describe the more advanced
features of tables.
A table is declared in a CSIM program
using the built-in type TABLE.
Example:
TABLE t;
Before a table can be used, it must
be initialized by calling the table
function.
Prototype:
TABLE table (char*
name);
Example:
t = table ("response times");
The table name is used only to identify
the table in the output reports. Up
to 80 characters in the name will be
stored by CSIM. A newly created table
contains no values and all the statistics
are zero.
A table can be initialized as a permanent
table using the permanent_table
function.
Prototype:
TABLE permanent_table
(char* name)
Example:
t = permanent_table
("response times");
The information in a permanent table
is not cleared when the reset
function is called, and a permanent
table is not deleted when rerun
is called. In all other ways, a permanent
table is exactly like any other table.
Permanent tables are often used to gather
data across multiple runs of a model.
As a general rule, do not make a table
permanent unless you have a specific
reason for doing so.
A value is included in a table using
the tabulate
function.
Prototype:
void tabulate(TABLE
t, double value)
Example:
tabulate(t, 1.0);
Tables are designed to maintain statistics
on data of type double. Data of other
types, such as integer, must be cast
to type double in the call to record.
Earlier versions of CSIM used an alternative
statement to accomplish this function:
Prototype:
void record(double
value, TABLE t)
Example:
record(1.0, t);
Caution:
It is a common mistake to reverse the
order of the parameters in calls to
record.
Think of "recording the value x
in table t".
Reports for tables are most often produced
by calling the report
function, which prints reports for all
statistics gathering objects. A report
can be generated for a specified table
at any time by calling the report_table
function.
Prototype:
void report_table(TABLE
t)
Example:
report_table(t);
Reports can be produced for all existing
tables by calling the report_tables
function.
Prototype:
void report_tables(void)
Example:
report_tables();
The report for a table will include
the table name and all statistics, as
illustrated below. If the table is empty,
a message to that effect is printed
instead of the statistics.
A summary report for all tables can
be generated by calling the table_summary
function.
Prototype:
void table_summary(void)
Example:
table_summary();
The report that is produced contains
one line for each table and includes
only a subset of the statistics. If
a table is empty, no statistics will
appear in the last three columns.
A histogram can be specified for a table
in order to obtain more detailed information
about the recorded values. The mode
and other percentiles can often be estimated
from a histogram. A histogram is specified
for a table by calling the table_histogram
function.
Prototype:
void table_histogram(TABLE
t, long nbucket,
double min, double max)
Example:
table_histogram(t,
10, 0.0, 10.0);
The number of buckets in the histogram
will be nbucket.
The smallest value in the first bucket
will be min;
the largest value in the last bucket
will be max.
All buckets will have the same width
of (max-min)/nbucket.
An underflow bucket and an overflow
bucket will automatically be created
if needed to hold values less than min
or greater than max.
Usually, a histogram is specified for
a table immediately after the table
is initialized. Additional calls can
be made to table_histogram
to change the characteristics of the
histogram, but only if the table is
empty.
A report for a table having a histogram
will include an additional section as
illustrated below. For each bucket in
the histogram, the following information
will be displayed: the smallest value
the bucket can hold, the number of values
in the bucket, the proportion of all
values that are in the bucket, the proportion
of all values in the bucket and all
preceding buckets, and a bar whose length
corresponds to the proportion of values
in the bucket.
If leading or trailing buckets contain
no values, the lines in the report for
these buckets will not be printed. This
allows the histogram to be output as
compactly as possible without losing
any information.
CSIM must save information for each
bucket in a histogram. Consequently,
the storage requirements for a table
that has a histogram are proportional
to the number of buckets.
CSIM can automatically compute confidence
intervals for the mean of the data in
any table. The confidence interval calculations
are enabled by calling the table_confidence
function.
Prototype:
void table_confidence(TABLE
t)
Example:
table_confidence(t);
If confidence intervals have been requested,
the report for a table will have an
additional section, as illustrated below.
Chapter 16,
"Confidence Intervals and Run Length
Control" describes confidence intervals
in detail and explains how to interpret
the information in this report.
By default, all values recorded in a
table are included in the statistics.
If a moving window is specified for
a table, only the last n
values are used in computing the statistics,
where n
is called the window size. A moving
window is specified for a table using
the table_moving_window
function.
Prototype:
void table_moving_window(TABLE
t, long n)
Example:
table_moving_window(t,
1000);
Usually, a table's moving window is
specified immediately after the table
is initialized. Additional calls can
be made to table_moving_window
to change the table's window size. It
is an error to specify a moving window
for a table that is not empty.
If a table has a window size of n,
the last n
values recorded in the table must be
saved by CSIM. Consequently, the storage
requirements for a table having a moving
window are proportional to its window
size.
All statistics maintained by a table
can be retrieved during the execution
of a model or upon its completion. The
attributes of a table (i.e.,
its name and moving window size) can
also be retrieved.
| Prototype: |
Functional
value: |
| char* table_name(TABLE
t) |
pointer to name
of table |
| long table_window_size(TABLE
t) |
size of moving
window |
| long table_cnt(TABLE
t) |
number of values
recorded |
| double table_min(TABLE
t) |
minimum value |
| double table_max(TABLE
t) |
maximum value |
| double table_sum(TABLE
t) |
sum of values
|
| double table_sum_square(TABLE
t) |
sum of squares
of values |
| double table_mean(TABLE
t) |
mean of values |
| double table_range(TABLE
t) |
range of values |
| double table_var(TABLE
t) |
variance of values |
| double table_stddev(TABLE
t) |
standard deviation
of values |
| double table_cv(TABLE
t) |
coefficient of
variation of
values |
The following inspector functions retrieve
information about the confidence interval
associated with a table:
| Prototype: |
Functional
Value: |
| double table_conf_halfwidth(double
level, TABLE t) |
halfwidth |
| double table_conf_lower(double
level, TABLE t) |
lower end |
| double table_conf_upper(double
level, TABLE t) |
upper end |
The following inspector functions retrieve
information about the run length control
associated with a table:
| long table_batch_size(TABLE
t) |
current size
of batch |
| long table_batch_count(TABLE
t) |
number of batches
used |
| long table_converged(TABLE
t) |
TRUE or FALSE |
| double table_conf_mean(TABLE
t) |
mid point of
conf. int. |
| double table_conf_accuracy(double
level, TABLE t) |
accuracy achieved |
Although most statistics are mathematically
undefined if there is no data, the corresponding
inspector functions return a value of
zero if the table is empty.
The following inspector functions retrieve
information about the histogram associated
with a table.
| Prototype: |
Functional
value: |
| long table_histogram_num(TABLE
t) |
number of buckets |
| double table_histogram_low(TABLE
t) |
smallest value
that is not underflow |
| double table_histogram_high(TABLE
t) |
largest value
that is not overflow |
| double table_histogram_width(TABLE
t) |
width of each
bucket |
| long table_histogram_bucket(TABLE
t,long i) |
number of values
in
bucket |
| long table_histogram_total(TABLE
t) |
number of values
in all buckets |
The number of buckets in a histogram
does not include the underflow or overflow
buckets. Bucket
number 0 is the underflow bucket;
bucket number 1+table_histogram_num(
) is the overflow bucket. If
a histogram has not been specified for
a table, the above inspector functions
all return zero values.
The inspector functions that retrieve
information about the results of run-length
control are described in section
16.
The name of a table can be changed at
any time using the set_name_table
function.
Prototype:
void set_name_table(TABLE
t, char* new_name)
Example:
set_name_table(t,
"elapsed time");
Only the first 80 characters of the
table's name are stored.
Resetting a table causes all information
maintained by the table to be reinitialized.
All optional features selected for the
table (e.g.,
histogram, confidence intervals, moving
window) remain in effect and are also
reinitialized.
The reset
function is usually used to reset all
statistics gathering tools at once.
A specific table can be reset using
the reset_table
function.
Prototype:
void reset_table(TABLE
t)
Example:
reset_table(t);
Although permanent tables are not reset
by the reset function, they can be reset
explicitly by calling reset_table.
When a table is no longer needed, its
storage can be reclaimed using the delete_table
function.
Prototype:
void delete_table(TABLE
t)
Example:
delete_table(t);
Once a table has been deleted, it must
not be further referenced. If enhancements
(either histogram, confidence intervals,
or moving window) have been defined
for a table, the each of these enhancements
is also deleted when the corresponding
table is deleted.
