Time plots show multiple data items over time as lines. The horizontal time axis runs left to right. Lines between data points use either linear interpolation or step interpolation (holding the previous value).

Time plot

To create a time plot

1. Drag the  Time plot element from the  Analysis palette into the graphical editor.
2. In the Data section of the chart’s properties, configure the first data item.
3. Select the data source for this item: Value or Data set.
   • If you want to display how a variable or a parameter changes over time, select the Value option and type the name of this variable or parameter in the Value edit box. Otherwise, type any expression you want: this expression will be evaluated with the defined recurrence time and the result of the calculation will be added to the chart.
   • To use values from a data set, select the Data set option and enter the data set’s name in the edit box.
4. Specify the name for the data item in the Title box. This text will be shown in the chart legend.
5. Specify the color for this data item’s plot. Click the control to use the color picker.
6. Open the Appearance section of the chart’s Properties. In the Time axis format box, you can choose the format of time axis labels: whether you want Model time units (like 0, 10, 20, …) or Model date formatted somehow (like Jan 21, 2009, 11:00:48 PM, Jan 22, 2009, 01:00:28 AM, and so on) to be displayed.

When finished, specify additional data items you want to be displayed in your chart.

To add a data item

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

1. Select the plot 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 plot 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 plot.
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.

Data

Value — [Visible if the Value option is selected above] The expression which dynamically evaluates the data item value.

Data set — [Visible if the Data set option is selected above] The name of the data set containing the values for the plot to display.

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

Style — Click to access extra appearance options:

Color — The color of the plot. Click the control to adjust it using the color picker.
Line width — The thickness of the plot line. Click one of the buttons or use the edit box next to them to set the width (in pixels). If the line width is set to 0, only the points will be displayed in the plot.
Point style — The shape of plot points. You can choose between none, square, round, or triangle.

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.

Maximum number of samples (applies to ‘Value’ data) — The “tail size” of the data set. Defines the number of the latest data items this plot will keep.

Scale

Time window — The time horizon displayed by the chart.

Time window moves — Specifies whether the time window moves according to the current model time (Continuously) or it moves only when a new data point is added to the chart (As data becomes available).

Vertical scale — Specifies the scale type for the vertical axis of the plot:

Auto — reserves an optimal space for the chart within the chart area
Fixed — defines the minimum and maximum axis points using the From and To edit boxes correspondingly

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.

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

Time axis format — The the time axis format to display: Model time units (0, 10, 20, …) or Model date (various date formats).

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.
Draw line — If selected, data item points on the plot are connected with a line.
Interpolation — [Visible if Draw line is selected above] Defines the behavior of the plot between adjacent points. There are two options:

Linear — points are connected with a straight line
Step — the Y-value between two adjacent points matches that of the point with the lower X-value

Fill area under line — [Visible if the Draw line option is selected] If selected, the area under the line will be tinted with the line color.

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).

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.
Axis color — The chart area axis color.

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 addDataSet(DataSet ds)	Adds a DataSet data set to the chart. It has the default title (Data set) and visual appearance: royalBlue color, the line with width 1 is drawn, points are not drawn, linear interpolation. ds — the data set to add
void addDataSet(DataSet ds, String title)	Adds a DataSet data set to the chart, with a given title and the default visual appearance: royalBlue color, the line with width 1 is drawn, points are not drawn, linear interpolation. ds — the data set to add title — the data set’s title
void addDataSet(DataSet ds, String title, Appearance appearance)	Adds a DataSet data set to the chart a given title and the appearance set by the configuration specified in the Appearance object passed as a parameter. ds — the data set to add title — the data set’s title appearance — the object describing the data set’s appearance
void addDataSet(DataSet ds, String title, Color color, boolean drawLine, int interpolationType, float lineWidth, int pointStyle)	Adds a DataSet to the chart with the specified visual appearance. ds — the data set to add title — the data set title color — the color of the data set plot drawLine — if true, the plot line is drawn interpolationType — interpolation type between two data points: TimePlot.INTERPOLATION_LINEAR — linear or TimePlot.INTERPOLATION_STEP — step interpolation lineWidth — the width of the line (0 for thinnest possible) pointStyle — what to draw at data points: TimePlot.POINT_SQUARE — squares, TimePlot.POINT_CIRCLE — circles, TimePlot.POINT_TRIANGLE — triangles, or TimePlot.POINT_NONE — none.
void addDataSet(DataSet ds, String title, Color color, boolean drawLine, boolean fillAreaUnderLine, int interpolationType,double lineWidth, int pointStyle)	Adds a DataSet to the chart with the specified visual appearance. ds — the data set to add title — the data set title color — the color of the data set plot drawLine — if true, the plot line is drawn fillAreaUnderLine — if true, the area under line is filled interpolationType — interpolation type between two data points: TimePlot.INTERPOLATION_LINEAR — linear or TimePlot.INTERPOLATION_STEP — step interpolation lineWidth — the width of the line (0 for thinnest possible) pointStyle — what to draw at data points: TimePlot.POINT_SQUARE — squares, TimePlot.POINT_CIRCLE — circles, TimePlot.POINT_TRIANGLE — triangles, or TimePlot.POINT_NONE — none.
int getCount()	Returns the number of chart items (data items or data sets) currently displayed by this chart.
DataSet get(int i)	Returns the chart item (DataItem, DataSet, and so on) with the given index. i — the index of the item
String getTitle(int i)	Returns the title of the chart item (DataItem, DataSet, and so on) with the given index. i — the index of the item
Color getColor(int i)	Returns the color of the chart item (DataItem, DataSet) with the given index. i — the index of the item
void setColor(int i, Color c)	Sets the new color of the chart item (DataItem, DataSet) with the given index. i — the index of the item;= c — the new color of the item
void remove(int i)	Removes the item (DataItem, DataSet, and so on) with the given index from the chart. i — The index of the data element.
int remove(ChartItem ci)	Removes the given item (DataItem, DataSet) from the chart. i — The item to remove.
void removeAll()	Removes all items from the chart.

Selecting data items

Function	Description
void selectItem(int itemIndex, boolean selected)	Selects or deselects (depending on the selected value) the chart item with the given index. itemIndex — The index of the data element. select — sets whether to select or deselect the element.
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 the chart items (data items or data sets) currently displayed by this chart.

Setting the axis scale of the chart

Function	Description
void setFixedVerticalScale(double minimum, double maximum)	Sets the fixed scale for the vertical axis of the plot. minimum — the minimum of chart axis scale maximum — the maximum of chart axis scale

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 the X-coordinate
void setY(double y)	Sets the Y-coordinate of the element. y — the new value of the Y-coordinate
void setPos(double x, double y)	Sets new coordinates for the element. x — the new value of the X-coordinate y — the new value of the Y-coordinate

Size

Function	Description
double getWidth()	Returns the width of the element.
double getHeight()	Returns the height of the element.
void setWidth(double width)	Sets new width for the element. width — the new value of the chart width
void setHeight(double height)	Sets new height for the element. height — the 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 chart is set to be visible, if false — not visible.

How can we improve this article?

Send