Time plot

Properties
Functions

Time plot displays the history of several data items during the latest time horizon as lines. The time axis is always horizontal and directed to the right. Depending on the interpolation type, the line in between two data samples is either interpolated linearly or keeps the previous value until the next one.

Time plot

To create a time plot

Drag the Time Plot element from the Analysis palette into the graphical editor.
In the Data section of the chart’s Properties add and configure the data item.
First, choose the source of data for this data item - Value or Data set.
- If you want to display how a variable or a parameter changes over time, choose the Value option and type the name of this variable or parameter in the Value field. Moreover, you can type here any expression you want. This expression will be evaluated with the defined recurrence time and the result of the calculation will be added onto the chart.
- Otherwise, if you want to display values collected in some data set, choose the Data set option and type the dataset's name in the Data set field below.
In the Title edit box, type the text that will be shown in the chart legend as the title of this data item.
Choose the marker style from the Point style drop-down list. Optionally, define the Line width using the controls to the right.
Specify the color to paint points and/or line for this data item. Click the arrow in the Color control and choose the color you wish.
If you want to connect points with a line, select the Draw line check box in the Appearance section and specify the presentation option in the controls below. Set the interpolation type (Step or Linear) using the Interpolation drop-down list.
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 (like 0, 10, 20, ..) or Model date formatted somehow (like Jan 21, 2009, 11:00:48 PM, Jan 22, 2009, 01:00:28 AM, etc. ) to be displayed.

All possible formats of date and time labels are described in Chart grids and labels.

To add a data item

By default a new plot already has one data item. If you want to add another, follow these steps:

Select the plot in the graphical editor or in the Projects view.
Go to the Data section of the Properties view.
Click the button. New property section defining settings for one more data item appears above.

To remove a data item

Select the plot in the graphical editor or in the Projects view.
Go to the Data section of the Properties view.
Select the section defining the data item you want to remove from the plot.
Click the button below all sections.

Properties

General

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

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

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

Data

— This button opens new property section, which allows to configure one more data item you want to visualize on this plot.

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

Value — [Visible if the Value option is selected above] Expression that will be evaluated to obtain new value to be added onto the chart.

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

Point style — Marker style, which will be used to display data set points on the plot.

Line width — [Visible if Draw line is selected] Width of the line connecting data item's points on the plot.

Color — Color, which will be used to draw this data item value on the plot. Click inside the control and choose a color from the set of most used ones, or choose some custom color using the Colors dialog box.

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

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.

Scale

Time window — The time horizon displayed by the chart. In 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 new data point is added on the chart (As data becomes available).

Vertical scale — Here you can choose scale type for the vertical axis of the plot. Choose auto-scaling mode (Auto), or Fixed scale with minimum and maximum specified in From and To edit boxes correspondingly.

Appearance

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.

Vertical axis labels — The control specifies the position of vertical axis labels relative to the chart (Left or Right). 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 (Jan 21, 2009, 11:00:48 PM, Jan 22, 2009, 01:00:28 AM, ... ) to be displayed. All possible formats of time axis are described in Chart grids and labels.

Background color — Background color for the chart.

Border color — Color used to draw chart border.

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

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

Draw line — If selected, data item's points on the plot are connected with lines.

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

Interpolation — [Visible if the Draw line option is selected] Defines the interpolation of the plot, i.e. what values plot takes between two adjacent data set points. There are two options:

Linear — two adjacent data set points are connected with a straight-line segment
Step — the y-value between two adjacent data set points is the same as in the point with less x-value

Position and size

Level — Level to which this plot belongs.

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 plot (in pixels).

Height — The height of the plot (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 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).

Show name — If selected, the name of the plot is displayed on the presentation diagram.

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

Functions

Data items

Function	Description
void addDataSet(DataSet ds)	Adds a DataSet to the chart with default title "Data set" and default visual appearance: royalBlue color, line of 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 to the chart a given title and default visual appearance: royalBlue color, line of 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, 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.
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.
Color getColor(int i)	Returns the color of the chart item (DataItem, DataSet) with the given index. i — 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 — index of the item; c — the new color of the item
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. 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.

Setting chart's axis scale

Function	Description
void setFixedVerticalScale(double minimum, double maximum)	Sets fixed scale for vertical axis of plot. minimum — minimum of chart axis scale maximum — 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 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. x — the new value of X coordinate
void setY(double y)	Sets the Y coordinate of the chart. y — the new value of Y coordinate
void setPos(double x, double y)	Sets new coordinates for the chart shape. 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. w — new value of the chart width
void setHeight(double h)	Sets new height for the chart shape. 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. v — visibility: if true — the chart is set to be visible, if false — not visible.

Copying chart data to 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?