AnyLogic 9
Expand
Font size

Histogram data

The Histogram Data object does the following:

  • Performs standard statistical analysis on the data values being added (calculates mean, minimum, maximum, deviation, variance, and mean confidence interval).
  • Builds the PDF (probability distribution, or density function).
  • May calculate (depending on the user choice) CDF (cumulative distribution function) on the fixed set of intervals defined by the user and the lower and higher confidence measures (or values at risk with a given percent) with tolerance equal to the interval width.

The collected statistics can be visualized with the Histogram object.

To add a histogram data element

  1. Drag the  Histogram Data element from the  Analysis palette into the graphical editor.
  2. Go to the Properties view.
  3. Enter the expression you want to collect statistics over in the Value edit box.
  4. If you want CDF to be calculated, select the Calculate CDF check box.
  5. If you want percentiles to be calculated, select the Calculate percentiles check box and specify low and high confidence measures in the Low and High edit boxes correspondingly.
  6. Define histogram intervals. Auto-ranging does not require the user to pre-define the range of data. Instead, the object will automatically adjust the intervals to the actual data being added. You need to specify the Number of intervals and the Initial interval size.
  7. Finally, choose, how you want this data element to be updated.

Properties

General

Name — The name of the histogram data. The name is used to identify and access this analysis data object.

Value — The expression which dynamically evaluates the data object value.

Number of intervals — The number of intervals of the histogram.

Calculate CDF — If selected, CDF (cumulative distribution function) is calculated.

Calculate percentiles — If selected, percentiles are calculated. In this case, specify Low and High confidence measures.

Ignore — If selected, this analysis data object is excluded from the model.

Values range

Initial interval size — Specifies the initial interval size for this data element. It will automatically adjust the intervals to the actual data being added.

Data update

Update data automatically — If selected, new data samples will be added automatically with the specified Recurrence time. You can also specify whether you want to Use model time or Use calendar dates. Depending on this choice, you can specify when to start updating using either the First update time or Update date properties.

API for working with collected data

You can work with collected data using the following functions. Histogram data element is represented in AnyLogic with instance of the following classes — HistogramSimpleData and HistogramSmartData.

HistogramSimpleData
Data of a histogram with fixed minimum, maximum, and number of intervals. The outlaying samples are registered in special “too low” and “too high” intervals. This class provides the following functions:
Function Description
double getPDFOutsideHigh() Returns the percentage of samples (0..1) higher than the specified maximum.
double getPDFOutsideLow() Returns the percentage of samples (0..1) lower than the specified minimum.
void setMinMax(double min, double max) Clears the histogram data and sets the new range covered by the intervals.
HistogramSmartData
Data of a histogram with a fixed number of intervals, but with an automatically adjustable data range. The data range covered by the intervals always includes the full range of the data samples added. This class provides the following functions:
Function Description
double getIntervalWidth() Returns the current interval width, that is, the data range corresponding to one interval.
double getLowerBound() Returns the lower bound of the range covered by intervals.

Both classes inherit from the base class HistogramData that provides the most frequently used functions common to both types of histograms.

Common functions
Function Description
void add(double val) Adds a sample data item to the histogram data.

val — the sample value.
int count() Returns the number of samples added to the histogram data.
void reset() Fully resets the histogram data: discards all PDF/CDF data and statistics.
double max() Returns the maximum sample value, or -infinity if no samples have been added.
double mean() Returns the mean of the histogram.
double meanConfidence() Returns the half-width mean confidence interval of the histogram data. The mean confidence interval is calculated assuming that the confidence level is equal to 95%.
double min() Returns the minimum sample value, or infinity if no samples have been added.
double deviation() Returns the standard deviation of the histogram data.
int getNumberOfIntervals() Returns the number of intervals in the histogram data.
StatisticsDiscrete getStatistics() Returns the statistics object embedded into the histogram data.
double getXMax() Returns the upper bound of the range covered by the intervals.
double getXMin() Returns the lower bound of the range covered by the intervals.
PDF
Function Description
double getPDF(int index) Returns the PDF (probability distribution function) at the given interval.

index — The interval to retrieve the PDF from.
double getMaxPDF() Returns the maximum PDF value across all intervals, that is, the maximum number of hits per interval divided by the total number of samples.
CDF
Function Description
double getCDF(int index) Returns the CDF (cumulative distribution function) at the given interval.

index — The interval to retrieve the CDF from.
void setCDFEnabled(boolean yes) Enables or disables the CDF (cumulative distribution function) calculation.

yes — sets whether to enable the CDF calculation
boolean isCDFEnabled() Checks if the CDF (cumulative distribution function) calculation is enabled. Returns true if the CDF calculation is enabled, false otherwise.
Percentiles
Function Description
boolean arePercentilesEnabled() Checks if percentile calculation is enabled. Returns true if percentile calculation is enabled, false otherwise.
void setPercentilesEnabled(boolean yes) Enables or disables calculation of percentiles (the data values corresponding to a certain low and high percent bounds).

yes — sets whether to enable the calculation of percentiles
void setPercents(double low, double high) Sets the percent bounds for percentile calculation.

low — the lower bound
high — the upper bound
double getPercentHigh() Returns the high percent value used for percentile calculation (1 is 100%).
double getPercentLow() Returns the low percent value used for percentile calculation (1 is 100%).

Troubleshooting

If you run your model and cannot see the CDF line on your histogram (while the Show CDF checkbox is selected) — please open the properties of the Histogram Data object displayed by your histogram and select the Calculate CDF checkbox there.

How can we improve this article?