Histogram2D charts display collections of 2D histograms. Each histogram is rendered as rectangular color cells, with colors representing the PDF value or density at each (x, y) position. The X and Y axes automatically scale to fit all histogram data. The charts display data from Histogram2D Data objects, with customizable visual appearance settings for each. Scale labels and grid lines are optional.

Histogram2D

In AnyLogic, 2D histograms have two modes: Show envelopes and Show bins.

An envelope is a color-filled region that encloses a certain percentage of the data distribution: a 95% envelope is a contour that encloses the central 95% of the probability mass, a 50% envelope encloses the central 50% of the data (the ‘core’ of the distribution), and so on. The lower bound refers to the inner boundary of these regions, essentially the density threshold value that defines where each envelope begins.

In bin mode, the color scale is applied independently to each X-axis interval. A cell’s color indicates its probability density relative to other cells in the same vertical column, not relative to the entire 2D distribution. For example, the darkest cell in each column represents the highest density within that X interval, even if its absolute PDF value is lower than that of cells in other columns.

To create a 2D histogram

1. Drag the  Histogram2D element from the  Analysis palette into the graphical editor.
2. In the Properties view, navigate to the Data section and specify histogram data item(s) you want to display.
3. Select the data object in the Histogram combo box.
4. In the Title box, enter the data item name to be displayed in the chart legend.
5. Specify the color for this data object. Click the control to use the color picker.
6. In the topmost section of the Properties view, select the preferred display mode:
   • Show envelopes — Displays the histogram as colored regions enclosing a certain percentage of data distribution
   • Show bins — Displays the histogram as colored cells reflecting the PDF value

To add a data item

By default, a new 2D histogram already has one data item. To add another, follow these steps:

1. Select the 2D histogram in the graphical editor or in the Projects view.
2. Go to the Data section of the properties.
3. Click the  Add button. A new property section with settings for one more data item will appear below.

To remove a data item

1. Select the 2D histogram in the graphical editor or in the Projects view.
2. Go to the Data section of the properties.
3. Locate the section defining the data item you want to remove from the 2D histogram.
4. In this section, click the  button.

General

Name — The name of the chart. The name is used to identify and access the chart from code.

Show name — If selected, the name of the chart is displayed in the presentation diagram.

Lock — If selected, the element is locked; it will not respond to any mouse actions during the model development time. To select the element, click its icon in the Elements view.

Ignore — If selected, the chart is excluded from the model.

Show envelopes — If selected, histogram2D data will be displayed as envelopes.

Show bins — If selected, histogram2D data will be displayed as bins.

Data

Data — The name of the Histogram2D Data object which will be displayed on this histogram.

Title — The data item name to be shown in the chart legend.

Color — The color of the data item. Click the control to use the color picker.

The  and  arrows — Allow you to rearrange the data items.

The  button — Allows you to remove data items from the chart.

The  Add button — Creates a section for a new data item.

Data update

Update data automatically — If selected, new data samples will be added automatically.

Use model time —  [Visible if Update data automatically is selected] If selected, the event will occur at the specified model time.

Use calendar date — [Visible if Update data automatically is selected] If selected, the event will occur at the specified calendar date.

First update time — [Visible if Update data automatically and Use model time are selected] The time of the first update defined as a number of model time units that must pass from the model start.

Update date — [Visible if Update data automatically and Use calendar dates are selected] The calendar date and time of the event.

Recurrence time — [Visible if Update data automatically is selected] The time that must pass between recurring updates.

Appearance

Horizontal axis labels — Specifies the position of the horizontal axis labels relative to the chart:

None — No labels will be displayed
Below
Above

Vertical axis labels — Specifies the position of the vertical axis labels relative to the chart:

None — No labels will be displayed
Left
Right

Style — Click to access extra appearance settings and then click each control to adjust them using the color picker.

Background color — The background color for the entire area allocated for the element. The background color for the chart area can be adjusted later in the Chart area section.
Border color — The color of the element border.
Labels color — The color of the chart labels.
Grid color — The color of the chart grid. Select no color if you do not want the grid to be displayed.

Position and size

Level — The level this chart belongs to.

X — The X-coordinate of the element’s upper left corner.

Y — The Y-coordinate of the element’s upper left corner.

Width — The width of the element (in pixels).

Height — The height of the element (in pixels).

Legend

Show legend — If selected, the chart legend is displayed.

Position — [Enabled if Show legend is selected] Controls the legend position relative to the chart.

Area size — [Enabled if Show legend is selected] Controls the size of the legend area (between the element border and the divider): width for North/South legend position or height for West/East position.

Text color — [Enabled if Show legend is selected] The color that will be used to display the legend. Click the control to adjust the settings using the color picker.

Chart area

This section defines the visual properties of the chart area.

X Offset — The horizontal offset of the chart area from the left edge of the element.

Y Offset — The vertical offset of the chart area from the left edge of the element.

Width — The width of the chart area (in pixels).

Height — The height of the chart area (in pixels).

Style — Click to access extra appearance settings and then click each control to adjust them using the color picker.

Background color — The chart area background color.
Border color — The color of the chart area border.

Actions

On selection change — The code executed when the user selects particular data items. This code is executed either when the user changes the selection by clicking on items in the chart legend, or when the selection is changed programmatically by selectItem().

You can use the following variables:

• int[] selectedIndices — returns the indices of currently selected data items
• boolean programmatically — defines whether items were selected programmatically (true) or not (false)

Visibility

Visible — Toggles the visibility of the element. The chart is visible when the box is checked or when the specified expression evaluates to true, and not visible otherwise.

Agent presentation — If selected, the chart is included in the agent presentation. This means that if the agent hosting this control is embedded in another agent, the control will remain visible.

Expert

Replication — The replication factor of the chart. Here you can specify how many copies of the chart will be created. If you leave this box empty, only one chart will be created.

Data items

Function	Description
void addHistogram2D(Histogram2DData hist, String title, Color color)	Adds a histogram2D data object to the chart with the specified visual appearance. hist — the histogram2D object to add. title — the histogram2D data title. color — the color corresponding to the highest PDF.
int getCount()	Returns the number of data items currently displayed by this chart.
ChartItem get(int i)	Returns the chart’s Histogram2DData item with the given index.
String getTitle(int i)	Returns the title of chart’s Histogram2DData item with the given index.
Color getColor(int i)	Returns the color of the chart item (Histogram2DData) with the given index. i — index of the item.
void setColor(int i, Color c)	Sets the new color of the chart item (Histogram2DData) with the given index. i — index of the item. c — the new color of the item.
void remove(int i)	Removes the Histogram2DData item with the given index from the chart.
int remove(ChartItem ci)	Removes the given Histogram2DData item from the chart.
void removeAll()	Removes all items from the chart.

Selecting data items

Function	Description
void selectItem(int itemIndex, boolean selected)	Selects or clears (depending on selected value) the chart item with given index.
void setSelectedItemIndices(int[] selectedIndices)	Selects only chart items with the given indices. selectedIndices — an array with indices of chart items to be selected (other chart items will be deselected), may be null — this clears selection.
int[] getSelectedItemIndices()	Returns the number of chart items (data items or data sets) currently displayed by this chart.

Updating chart data manually

Function	Description
void updateData()	Updates all data items displayed by this chart.

Location

Function	Description
double getX()	Returns the X-coordinate of the element (upper left corner).
double getY()	Returns the Y-coordinate of the element (upper left corner).
void setX(double x)	Sets the X-coordinate of the element. x — the new value of X-coordinate.
void setY(double y)	Sets the Y-coordinate of the element. y — the new value of Y-coordinate.
void setPos(double x, double y)	Sets new coordinates for the element. x — the new value of x coordinate. y — the new value of y coordinate.

Size

Function	Description
double getWidth()	Returns the width of the element.
double getHeight()	Returns the height of the element.
void setWidth(double w)	Sets new width for the element. w — new value of the chart width.
void setHeight(double h)	Sets new height for the element. h — new value of the chart height.

Visibility

Function	Description
boolean isVisible()	Checks the visibility of the element. Returns true if the element is visible, and false otherwise.
void setVisible(boolean v)	Sets the visibility of the element. v — visibility: if true — the element is set to be visible, if false — not visible.

Copying chart data to the clipboard

Function	Description
String copyToClipboard()	Copies all chart data to the system clipboard in text form. Returns the text representation of all chart data.

How can we improve this article?

Send