Time Color Chart

Time color chart displays the trend of a number of data sets during the latest time as bars consisting of horizontal stripes of different colors (color depends on the data value). The time axis shows the data in the specified time window. It is always horizontal and directed to the right. Every chart update (either automatic or manual) causes the evaluation of boolean expressions defined over data items. If some condition evaluates to true, the color of the bar stripe is set to the color defined for this condition, otherwise the next condition is checked.

This chart can be used to visualize the change of a (discrete) state of an object over time, e.g. busy / idle, traveling / loading / unloading / parked / maintenance, etc.

Time color chart

 To create a time color chart

  1. Drag the  Time Color Chart  element from the  Analysis palette into the graphical editor.
  2. Open the Data section of the chart's Properties and add data items you want to display on the chart.
  3. Open the Color mapping section of the chart's Properties and create color mappings.
  4. Open the Appearance section of the chart's Properties. In the Time axis format field you can choose the format of time axis labels: whether you want Model time units (0, 10, 20, ..) or Model date (Jan 21. 2015 23:00, Jan 22. 2015 01:00, ... ) to be displayed. All possible formats of date and time labels are described here.

Properties

General

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

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

Visible on upper level – If selected, the chart is also visible on the upper level where this agent lives.

Time window - The time horizon displayed by the chart. In the Advanced properties section, you can find the related option, Time window moves. There you can select whether the chart's time window moves according to the current model time (Continuously), or it moves only when a new data point is added on the chart (As data becomes available).

Data

 Add data item – This button opens a new property section, which allows to configure a data item you want to visualize on this chart: 

Title – The title for this data item, which will be shown in the chart legend. 

Value – [Visible if the Value option is selected above] The expression that will be evaluated to obtain a new value to be added onto the chart.

Data set – [Visible if the Data set option is selected above] The name of the data set that collects values you want to display on this chart.

To remove a data item from the chart, click the  button to the right of the data item's property section. Use the arrows and to arrange the order of the data item sections.

Color mapping

 Add color mapping – The button opens a new property section, which allows to configure a color mapping defined as a condition-color pair.

Value – Using the controls to the right, define the condition. You specify a condition by selecting a comparison operator (>, , <, = or ) and providing the code expression in the field to the right. That is how you compose the condition, e.g.: Value >= 100. 

Color – The color the chart's data stripe will be painted with when the specified condition evaluates to true.

To duplicate a color mapping, select it and click the button below the color mapping's property section. To remove a color mapping from the chart, select it and click the button. Use the arrows and to arrange the order of the color mappings. 

Conditions are checked by comparing the current value of the data item specified in the Data properties section with the result of evaluating the expression. If the condition evaluates to true, the current chart's data stripe will be painted with the Color corresponding to this condition. 

If multiple conditions are specified, they are checked in the top-to-bottom sequential order. The first successful verification (i.e., when the specified condition evaluates to true) will determine the color the chart's data stripe will be painted with. 

Note that expressions are evaluated only once at the start of the model and during the model run each expression returns the same fixed value.

Default color – the color the chart's data stripe will be painted with when none of the specified conditions are met.

Data update

Do not update data automatically - If selected, chart is not updated automatically with new data samples.

Update data automatically – If selected, new data samples are added automatically with the specified Recurrence time. Also, you can define here whether you want to Use model time or Use calendar dates. Depending on this choice, you can specify when updating begins with either First update time or Update date properties.

Display up to ... latest samples (applies to "Value" data items only) - Maximum number of the latest values that will be displayed for each data item with the Value option selected. 

Appearance

Bars relative width – The slider allows adjusting the thickness of the stripes (100% - maximum, 50% - half, etc.)

Horizontal axis labels – The control specifies the position of horizontal axis labels relative to the chart (Below or Above). Choose None, if you do not want labels to be displayed.

Time axis format – Here you can choose the format of time axis: whether you want Model time units (0, 10, 20, ...) or Model date (e.g. Jan 21. 2009 23:00, Jan 22. 2009 01:00, ... ) to be displayed. All possible formats of time axis are described here.

Labels color – The control specifies the color of the chart labels.

Background color – Background color for the chart. 

Border color – Color used to draw chart border. 

Grid color – The control specifies the color of the chart grid. Choose No Fill, if you do not want grid to be displayed.

Position and size

X – The x-coordinate of the chart's upper left corner.

Y – The y-coordinate of the chart's upper left corner.

Width – The width of the chart shape (in pixels).

Height – The height of the chart shape (in pixels).

Legend

Show legend – If selected, the chart legend is displayed. You can control the legend position relative to the chart using the Position group of buttons. The size of the area allocated for the legend can be defined using either Width or Height control (depends on the legend's Position). Text color can also be adjusted.

Chart area

This section defines visual properties of the chart area:

X Offset – The x-offset of the chart area relative to the whole area allocated for the chart and all its accompanying elements.

Y Offset – The y-offset of the chart area relative to the whole area allocated for the chart and all its accompanying elements.

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

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

Background color – Background color for the chart area. 

Border color – Color used to draw the border of the chart area. 

Advanced

Visible – The chart visibility. The chart is visible when the specified expression evaluates to true, and not visible otherwise.

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

On item removal –  The code executed when the user removes some particular data item(s) from the chart. This code is executed either when the user removes items from the context menu of the chart legend, and when data items are removed programmatically via functions remove() and removeAll().
You can use two variables here:
int removedIndex
- index of the just removed data item.
boolean programmatically - defines, whether the item was removed programmatically (true), or not (false).

On selection change –  The code executed when the user selects some particular data item(s). This code is executed either when the user changes the selection by clicking on items in the chart legend, and when the selection is changed programmatically via the function selectItem()
You can use two variables here:
int[] selectedIndices - the indices of currently selected data items.
boolean programmatically - defines, whether items were selected programmatically (true), or not (false).

Time window moves – Here you can choose whether the chart's time window moves according to the current model time (Continuously), or it moves only when new data point is added on the chart (As data becomes available).

Log to database – If selected, the data collected by the chart during the simulation will be saved in the datasets_log model execution log (if logging is turned on in the model's Database properties).

Show name – If selected, the chart name is displayed on a presentation diagram.

Adding/removing chart's data items

 To add a data item on a chart
  1. Select the chart in the graphical editor.
  2. Navigate to the Data section of the Properties view.
  3. Click the Add data item button. New property section defining settings for a new data item appears above.
  4. First, choose the source of data for this data item - Value or Data set.

  5. Specify the title for this data item in the Title box. This text will be shown in the chart legend.
 To remove a data item from a chart
  1. In the Data section of the chart's properties, select the section defining the data item you want to remove.
  2. Click the  button below all sections.

Defining color mappings

You should also define the correspondence of data item values and colors.

 To define a color mapping
  1. Navigate to the Color mapping section of the chart's properties.
  2. Click the  Add color mapping button. A new property section defining settings for a new color mapping appears above.
  3. Configure the color mapping:
    1. Select the comparison operator (>, , <, = or ) for comparing the Value of the data item with the result of evaluating the expression.
    2. In the code field to the right, provide an expression.
    3. Set the color for the mapping using the Color control. This color will be used to paint the current chart's data stripe when the condition defined in this color mapping evaluates to true

If multiple color mappings are specified for the chart, the conditions specified for them are checked in the top-to-bottom sequential order. The first successful verification (i.e., when the specified condition evaluates to true) will determine the color the chart's data stripe will be painted with. Therefore, by changing the order of the color mapping, you affect the appearance of the chart. 

 To reorder color mappings
  1. Navigate to the Color mapping section of the chart's properties.
  2. Select select the section defining the color mapping you want to move and use the arrows and below to move it up or down in the list.
 To remove a color mapping
  1. In the Color mapping section of the chart's properties, select the section defining the color mapping you want to remove.
  2. Click the  button below all sections.

Functions

Location

Function

Description

double getX()

Returns the X coordinate of the chart (namely, the X coordinate of its upper left corner).

double getY()

Returns the Y coordinate of the chart (namely, the Y coordinate of its upper left corner).

void setX(double x)

Sets the X coordinate of the chart.

Parameter:
x - the new value of X coordinate

void setY(double y)

Sets the Y coordinate of the chart.

Parameter:
y - the new value of Y coordinate

void setPos
(double x,
double y)

Sets new coordinates for the chart shape.

Parameters:
x - the new value of x coordinate
y - the new value of y coordinate

Size

Function

Description

double getWidth()

Returns the width of the chart shape.

double getHeight()

Returns the height of the chart shape.

void setWidth(double w)

Sets new width for the chart shape.

Parameter:
w - new value of the chart width

void setHeight(double h)

Sets new height for the chart shape.

Parameter:
h - new value of the chart height

Visibility

Function

Description

boolean isVisible()

Checks the visibility of the chart. Returns true if the chart is visible, and false otherwise. 

void setVisible(boolean v)

Sets the visibility of the chart.

Parameter:
v - visibility: if true - the chart is set to be visible, if false - not visible.

Adding and removing chart's data items

Function

Description

void addDataSet
(DataSet ds)

Adds a data set to the chart with default title "Data set".

Parameter:
ds - the data set to add

void addDataSet
(DataSet ds,
String title)

Adds a DataSet with the specified title.

Parameters:
ds - the data set to add
title - the data set's title

int getCount()

Returns the number of chart items (data items or data sets) currently displayed by this chart.

ChartItem get(int i)

Returns the chart item (DataItem, DataSet, etc.) with the given index.

String getTitle(int i)

Returns the title of chart item (DataItem, DataSet, etc.) with the given index.

void remove(int i)

Removes the item (DataItem, DataSet, etc.) with the given index from the chart.

int remove
(ChartItem ci)

Removes the given item (DataItem, DataSet) from the chart.

void removeAll()

Removes all items from the chart.

Selecting data items

Function

Description

void selectItem(int itemIndex, boolean selected)

Selects/deselects (depending on selected value) chart item with given index.

void setSelectedItemIndices
(int[] selectedIndices)

Selects only chart items with the given indices.

Parameter:
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 currently selected chart items (data items or data sets).

Updating chart data manually

Function

Description

void updateData()

Updates all data items displayed by this chart. 

Copying chart data to the Clipboard

Function

Description

String copyToClipboard()

Copies all chart data to the system clipboard  in the form of a tab-separated table with linear interpolation of values where needed. The table is limited to 1000 values. Returns the text representation of all chart data.


Related topics

Scaling Charts

Chart Area

Chart Legend

Chart Grid and Labels

Updating Charts

Changing Chart Appearance at Runtime

 API Reference: TimeColorChart Class