# Creating Histograms

Histogram

The term histogram typically refers to a picture of a number of observations. The observations are divided over equal-length intervals, and the number of observed values in each interval is counted. Each count is referred to as a frequency, and the corresponding interval is called a frequency interval. The picture of a number of observations is then constructed by drawing, for each frequency interval, the corresponding frequency as a bar. A histogram can thus be viewed as a bar chart of frequencies.

Histogram support

The procedures and functions discussed in this section allow you to create histograms based on a large number of trials in an experiment conducted from within your model. You can set up such an experiment by making use of random data for each trial drawn from one or more of the distributions discussed in the AIMMS Language Reference. The histogram frequencies, created through the functions and procedures discussed in this section, can be displayed graphically using the standard AIMMS bar chart object.

Histogram functions and procedures

AIMMS provides the following procedure and functions for creating and computing histograms.

`HistogramCreate`

(*histogram-id*[,*integer-histogram*][,*sample-buffer-size*])`HistogramDelete`

(*histogram-id*)`HistogramSetDomain`

(*histogram-id*,*intervals*[,*left*,*width*][,*left-tail*][,*right-tail*])`HistogramAddObservation`

(*histogram-id*,*value*)`HistogramAddObservations`

(*histogram-id*,*values-parameter*)`HistogramGetFrequencies`

(*histogram-id*,*frequency-parameter*)`HistogramGetBounds`

(*histogram-id*,*left-bound*,*right-bound*)`HistogramGetObservationCount`

(*histogram-id*)`HistogramGetAverage`

(*histogram-id*)`HistogramGetDeviation`

(*histogram-id*)`HistogramGetSkewness`

(*histogram-id*)`HistogramGetKurtosis`

(*histogram-id*)

The *histogram-id* argument assumes an integer value. The arguments
*frequency-parameter*, *left-bound* and *right-bound* must be one-
dimensional parameters (defined over a set of intervals declared in your
model). The optional arguments *integer-histogram* (default 0),
*left-tail* (default 1) and *right-tail* (default 1) must be either 0 or
1. The optional argument *sample-buffer-size* must be a positive
integer, and defaults to 512.

Creating and deleting histograms

Through the procedures `HistogramCreate`

and `HistogramDelete`

you
can create and delete the internal data structures associated with each
individual histogram in your experiment. Upon success, the procedure
`HistogramCreate`

passes back a unique integer number, the
*histogram-id*. This reference is required in the remaining procedures
and functions to identify the histogram at hand. The observations
corresponding to a histogram can be either continuous or integer-valued.
AIMMS assumes continuous observations by default. Through the optional
*integer-histogram* argument you can indicate that the observations
corresponding to a histogram are integer-valued.

Sample buffer size

For every histogram, AIMMS will allocate a certain amount of memory for
storing observations. By default, AIMMS allocates space to store samples
of 512 observations at most. Using the optional *sample-buffer-size*
argument, you can override the default maximum sample size. As long as
the number of observations is still smaller than the sample buffer size,
all observations will be stored individually. As soon as the actual
number of observations exceeds the sample buffer size, AIMMS will no
longer store the individual observations. Instead, all observations are
then used to determine the frequencies of frequency intervals. These
intervals are determined on the basis of the sample collected so far,
unless you have specified interval ranges through the procedure
`HistogramSetDomain`

.

Setting the interval domain

You can use the function `HistogramSetDomain`

to define frequency
intervals manually. You do so by specifying

the number of fixed-width

*intervals*,the lower bound of the

*left*-most interval (not including a left-tail interval) together with the (fixed)*width*of intervals to be created (optional),whether a

*left-tail*interval must be created (optional), andwhether a

*right-tail*interval must be created (optional).

The default for the *left* argument is `-INF`

. *Note that the left
argument is ignored unless the width argument is strictly greater than
0*. Note that the selection of one or both of the tail intervals causes
a corresponding increase in the number of frequency intervals to be
created.

Use of tail intervals

Whenever an observed value is smaller than the lower bound of the
left-most fixed-width interval, AIMMS will update the frequency count of
the left-tail interval. If the left-tail interval is not present, then
the observed value is lost and the procedure `HistogramAddObservation`

and `HistogramAddObservations`

(to be discussed below) will have a
return value of 0. Similarly, AIMMS will update the frequency count of
the right-tail interval, when an observation lies beyond the right-most
fixed-width interval.

Adjusting the interval domain

Whenever, during the course of an experiment, the number of added
observations is still below the sample buffer size, you are allowed to
modify the interval ranges. As soon as the number of observations
exceeds the sample buffer size, AIMMS will have fixed the settings for
the interval ranges, and the function `HistogramSetDomain`

will fail.
This function will also fail when previous observations cannot be placed
in accordance with the specified interval ranges.

Adding observations

You can use the procedure `HistogramAddObservation`

to add a new
observed value (or `HistogramAddObservations`

to add a set of values)
to a histogram. Non-integer observations for integer-valued histograms
will be rounded to the nearest integer value. The procedure will fail,
if the observed value cannot be placed in accordance with the specified
interval ranges.

Obtaining frequencies

With the procedure `HistogramGetFrequencies`

, you can request AIMMS to
fill a one-dimensional parameter (slice) in your model with the observed
frequencies. The cardinality of the index domain of the frequency
parameter must be at least as large as the total number of frequency
intervals (including the tail interval(s) if created). The first element
of the domain set is associated with the left-tail interval, if created,
or else the left-most fixed-width interval.

Interval determination

If you have provided the number of intervals through the procedure
`HistogramSetDomain`

, AIMMS will create this number of frequency
intervals plus at most two tail intervals. Without a custom-specified
number of intervals, AIMMS will create 16 fixed-width intervals plus two
tail intervals. If you have not provided interval ranges, AIMMS will
determine these on the basis of the collected observations. As long as
the sample buffer size of the histogram has not yet been reached, you
are still allowed to modify the number of intervals prior to any
subsequent call to the procedure `HistogramGetFrequencies`

.

Obtaining interval bounds

Through the procedure `HistogramGetBounds`

you can obtain the left and
right bound of each frequency interval. The bound parameters must be
one-dimensional, and the cardinality of the corresponding domain set
must be at least the number of intervals (including possible left- and
right-tail intervals). The lower bound of a left-tail interval will be
`-INF`

, the upper bound of a right-tail interval will be `INF`

.

Obtaining statistical information

The following functions provided statistical information:

`HistogramGetObservationCount`

The total number of observations,`HistogramGetAverage`

the arithmetic mean,`HistogramGetDeviation`

standard deviation,`HistogramGetSkewness`

skewness, and`HistogramGetKurtosis`

kurtosis coefficient.

Example

In the following example, a number of observable outputs `o`

of a
mathematical program are obtained as the result of changes in a single
uniformly distributed input parameter `InputRate`

. The interval range
of every histogram is set to the interval [0,100] in 10 steps, and it is
assumed that the set associated with index `i`

has at least 12
elements.

```
for (o) do
HistogramCreate( HistogramID(o) );
HistogramSetDomain( HistogramID(o), intervals: 10, left: 0.0, width: 10.0 );
endfor;
while ( LoopCount <= TrialSize ) do
InputRate := Uniform(0,1);
solve MathematicalProgram;
for (o) do
HistogramAddObservation( HistogramID(o), ObservableOutput(o) );
endfor;
endwhile;
```

```
for (o) do
HistogramGetFrequencies( HistogramID(o), Frequencies(o,i) );
HistogramGetBounds( HistogramID(o), LeftBound(o,i), RightBound(o,i) );
HistogramDelete( HistogramID(o) );
endfor;
```