Menu

Line Chart

Watch the video tutorial on this subject!

Line Chart Description

Having a system that can do detailed simulations is great, but without the ability to analyze what is happening then its really no more than a sophisticated game. To do serious research into biomechanics or robotics the user needs to be able to view any data in the system over time to see how it changes. The line chart gives users this ability. They can select data items from any part in the system and repeatedly collect and display the value of that item throughout a simulation. Each chart can have up to six axis's and each axis can have an unlimited number of data columns. A data column keeps track of a variable from some component in the simulation.

The line chart is composed of a main charting window, and it has a hierarchy bar that lists all of the parts for this chart in a treeview format. There is also a properties section that lists the properties for any selected item. Below is a list of each these parts along with a description. You can also click on any part of the image in figure 1 to directly jump to a description.

Users also have a great deal of flexibility to change the look-and-feel of the charts. You have complete control over the colors, fonts, and labels. A number of predefined bitmaps are provided for use in the charts, and there are numerous predefined viewing styles that you can select. These are different themes that change a variety of properties to provide a consistent look-and-feel.

Figure 1. Line Chart Window. Click on any part of the window to jump to a description of that part.
Figure 2. Hierarchy Toolbar.
The hierarchy tool window shows the structural layout of your chart. There is a root node for the chart itself, and sub-nodes for each axis that has been added to the system. Then there are nodes below each axis for data columns on that axis. You can click on any node and its properties will be displayed in the property window below. Right-click on any selected item for a pop-up menu that will allow you to add items or delete the select item.

Figure 3. Properties Toolbar.
This toolbar displays the properties of any selected item. This allows you to view and modify the properties of the selected object. The properties are split into functional groups like 'Graphical Properties', 'Data properties' and so on. However, you can view an alphabetical list of the objects properties by clicking the AZ button that is just above the properties window.

This is the main part of the chart where the data is actually displayed. The user has a tremendous amount of control to change the look-and-feel of this area to suit their needs. You can set the titles, and configure the properties for each line on the chart.

Line Chart Properties

Data Properties

Auto collect Interval
If this is true then the chart will automatically calculate the smallest collect data interval based on the data columns added to the chart. This is particularly useful when charting integrate-and-fire neurons. A major problem with them is that if the collect data interval is larger than the time step of their simulation then you will only be seeing part of the data, and this means you will most likely not see all, or any, of the spikes. This can be quite confusing if you were expecting spikes. When this property is enabled it will ensure that you always sample the data at or below the time step value of the neuron simulation, and this will ensure that you will always see all the spikes for that neuron by default. However, this is not a cure-all. One problem with this is that the lower your sampling rate the more data you have to collect. So you have to have larger buffers and it takes more computer time to update the graph. This means slower simulations. So if you set this to false you can manually configure the various properties to trade-off buffer size and simulation speed. Please see the section on How data is collected.
Default value: True
Acceptable values: True/False

Collect Data Interval
Defines how often, in simulation time, data is collected for each data column. Please see the section on How data is collected.
Default value: 5 ms
Acceptable range: Any value greater than 0.

Collect Time Window
Defines the size of the simulation data collection buffer. The value is defined in seconds worth of data. The actual size of the buffer is determined using the collection data interval, this time window, and the number of data columns. Please see the section on How data is collected.
Default value: 3 s
Acceptable range:

End time
Allows the user to specify the end time when data will be collected. This property is only visible when the Set Start/End Time property is true, and will only be used then.
Default value: 0
Acceptable range: Any time less than End Time

Points To Keep
Defines the size of the graphs data buffer. This is the number of points it keeps in its array. when it tries to add more points than this the old data is scrolled off the end. Please see the section on How data is collected.
Default value: 15,000
Acceptable range: Any size greater than 0

Save Data When Closed
The chart can collect a lot of data points, and it is possible to have many charts open at the same time. This can lead to long load/save times to write/read the data in the charts. If this value is false then when the chart is closed the configuration for the chart is save, but none of the existing data is saved. If you set it to true then both the configuration and data are saved so that when the chart is opened again the last data simulated for that chart is still available.
Default value: False
Acceptable values: True/False

Set Start/End Time
The chart defaults to using a continuous data collection. It will attempt to collect data from the beginning of the simulation until the end. When it runs of buffer room the data will scroll off the edge so that only the data in the buffer will be shown. However, if you set this value to true then you explicitly specify the start and end times for when the chart should collect data. This allows you to pinpoint the specific time window where you data will be charted. This can lead to faster simulations since it has to collect less data.
Default value: False
Acceptable values: True/False

Start Time
Allows the user to specify the start time when data will be collected. This property is only visible when the Set Start/End Time property is true, and will only be used then.
Default value: 0
Acceptable range: Any time less than End Time

Update Data Interval
This is how often, in real time, the graphs data is updated. This can have a huge impact on the simulation speed. If you set it to update the graph too often it will slow the simulation down greatly, but if you set it to high then the simulations buffer will overfill and be erased and you will have gaps in the simulation. Please see the section on How data is collected.
Default value: 500 ms
Acceptable range: Any time greater than 0.

Graphical Properties

AutoScale
This property controls whether the graph will automatically scale data that is very small or very large. What we mean by scale is reduce or enlarge all data by 10, 100, 1000, 10000 and so on.
Default value: True
Acceptable range: True/False

Axis Font Scale
This property is used to adjust the font size for axis labels. Possible values range from .25 to 2.0 where the default value 1.0 means that the font size is normally the same size as grid numbers. Setting to 2.0 results in an axis label font size twice the size of the grid numbers.
Default value: 1
Acceptable range: 0.5 - 2.0

Bitmap Gradients
This property enables background bitmaps and gradients.
Default value: False
Acceptable range: True/False

Border Type
This property sets the grids border style.
Default value: DropShadow
Acceptable values:
DropShadow Drop shadow effect
SingleLine Simple line border around grid region
NoBorder No line or border around grid
Inset 3D inset style

Desk Bitmap Type
This property identifies a resource ID of a pre-existing bitmap for a background bitmap to be placed onto the desk area of the control. This property is only effective if BitmapGradientMode is TRUE.
Default value: None
Acceptable range: None, Custom, A-K

Desk Color
This property defines the color used as the background color on which the control is placed.
Default value: Lignt-Tan
Acceptable range: Any Color

Desk Gradient End
This property defines the end RGB color for a background gradient placed onto the controls desk area. The gradients style is defined with DeskGradientStyle and start color with DeskGradientStart. This property is only effective if BitmapGradientMode is TRUE, and DeskGradientStyle is non-zero.
Default value: Black
Acceptable range: Any Color

Desk Gradient Start
This property defines the start RGB color for a background gradient placed onto the controls desk area. The gradients style is defined with DeskGradientStyle and start color with DeskGradientStart. This property is only effective if BitmapGradientMode is TRUE, and DeskGradientStyle is non-zero.
Default value: Black
Acceptable range: Any Color

Desk Gradient Style
Controls how a background gradient is applied to the controls desk area. Start and end RGB colors are defined with DeskGradientStart and DeskGradientEnd. This property is only effective if BitmapGradientMode is TRUE.
Default value: DropShadow
Acceptable values:
NoGradient No Gradient
Vertical Gradient Top to Bottom
Horizontal Gradient Left to Right

Font Size
This property controls the font size used in the image creation process.
Default value: Medium
Acceptable range: Small, Medium, Large

Graph Back Color
This property identifies the color used as the background color for the objects graphing area.
Default value: White
Acceptable range: Any Color

Graph Bitmap Type
This property identifies a resource ID of a pre-existing bitmap for a background bitmap to be placed onto the graph area of the control. This property is only effective if BitmapGradientMode is TRUE.
Default value: None
Acceptable range: None, Custom, A-K

Graph Font Scale
This property is used to adjust the font size for graph labels. Possible values range from .25 to 2.0 where the default value 1.0 means that the font size is normally the same size as grid numbers. Setting to 2.0 results in an graph font size twice the size of the grid numbers.
Default value: 1
Acceptable range: 0.5 - 2.0

Grid In Front
This property controls whether the graphs grid is placed behind or in front of the plotting method graphics.
Default value: False
Acceptable values: True/False

Grid Line Control
This property controls the horizontal and vertical lines which make the graphs grid.
Default value: Both
Both Both horizontal and vertical grid lines
YAxis Horizontal grid lines
XAxis Vertical grid lines
None No grid lines

Grid Line Style
This property controls the style of line used to form the graphs grid.
Default value: Thin
Thin Thin solid line
Thick Thick solid line
Dot Dotted Line
Dash Dashed Line

Label Font
This property identifies the face-name of the font to be used for object labels. The other properties like size are not used. Only assign True-Type fonts to this property. Default value: Tahoma

Legend Font Scale
This property is used to adjust the font size for legend labels. Possible values range from .25 to 2.0 where the default value 1.0 means that the font size is normally the same size as grid numbers. Setting to 2.0 results in an legend font size twice the size of the grid numbers.
Default value: 1
Acceptable range: 0.5 - 2.0

Multi-Axis Separator Size
This property controls the height of the section/gap when MultiAxisStyle is set to SeperateAxis. Units are logical and are 1/100th of the size of the x axis label height. For example, a value of 100 produces an axis gap equal to the x axis label height, 200 produces an axis gap twice the height of the x axis label.
Default value: 100
Acceptable range: 25-300

Multi-Axis Style
This property determines if multiple axes will be stacked or separated. The size of the separation may be adjusted with MultiAxisSeparatorSize.
Default value: SeparateAxes
Acceptable range: GroupAllAxes, SeparateAxes

SubTitle
This property allows the user to specify the text for a subtitle.
Default value: Blank

Subtitle Font
This property identifies the face-name of the font to be used for the subtitle. The other properties like size are not used. Only assign True-Type fonts to this property.
Default value: Tahoma

Title
This property allows the user to specify the text for a title.
Default value: Blank

TitleFont
This property identifies the face-name of the font to be used for the title. The other properties like size are not used. Only assign True-Type fonts to this property.
Default value: Tahoma

Title Font Scale
This property is used to adjust the font size for the title and subtitle. Possible values range from .25 to 2.0 where the default value 1.0 means that the font size is normally the same size as grid numbers. Setting to 2.0 results in an title font size twice the size of the grid numbers.
Default value: 1
Acceptable range: 0.5 - 2.0

Viewing Style
There are a number of pre-defined look-and-feel settings for the graph. This allows you to select one of these styles for you chart. It automatically sets a number of parameters of the chart to produce the look. Once set you can then alter other parameters to modify the look further.
Default value: NoStyle
NoStyle No Style
LightInset Light Colors with Inset Border
LightShadow Light Colors with Shadow Border
LightLine Light Colors with Line Border
LightNoBorder Light Colors with No Border
MediumInset Medium Colors with Inset Border
MediumShadow Medium Colors with Shadow Border
MediumLine Medium Colors with Line Border
MediumNoBorder Medium Colors with No Border
DarkInset Dark Colors with Inset Border
DarkShadow Dark Colors with Shadow Border
DarkLine Dark Colors with Line Border
DarkNoBorder Dark Colors with No Border

X AutoScale
This property is used in conjunction with ManualMinX and ManualMaxX. This property allows manual control of the range of the graphs x axis scale.
Default value: None
None Automatic Scale Control
Min Manual Minimum Scale Control
Max Manual Maximum Scale Control
MinMax Both Minimum and Maximum Scale Control

X Axis color
This property controls the color used for the axis label and grid numbers/point labels along x axis.
Default value: Black
Acceptable range: Any Color

X Max Value
This property is used in conjunction with X AutoScale. If X AutoScale is equal to Max or MinMax, then the value defined by here will be the maximum extent for the bottom x axis.
Default value: 0
Acceptable range: Any number

X Min Value
This property is used in conjunction with X AutoScale. If X AutoScale is equal to Min or MinMax, then the value defined by here will be the minimum extent for the bottom x axis.
Default value: 0
Acceptable range: Any number

How Data Is Collected

Figure 4. Data Collection Procedure.

It is important to understand how the line chart collects data in order to be able to use it most effectively. Having it configured incorrectly can cause your simulations to slow down severely or lead to blocks of data not being collected. The user specifies the data they want to collect in the simulation. The Collect Data Interval parameter tells how often, in simulation time, the chart collects its data. You should remember that there are two time scales happening. Their is the simulation time. This depends on how fast or slow you simulation runs. It may take five minutes of real time to process 30 seconds of simulation, or you may be able process 5 minutes of simulation time in 20 seconds of real time. It all depends on your simulation. However, the Collect Data Interval property is always specified in simulation time. So if you tell it to collect data every 20 ms then it will take a snapshot of all the data in the chart every 20 ms the simulation run.

It stores that data in an internal buffer in the simulation. The size of this buffer is determined by the Collect Time Window property, Collect Time Interval, and the number of data columns in the chart. The user specifies how big of a time window they want for the buffer. If you have a really small collection interval and a really large time window then the actual size of the data buffer could be quite large. However, it is not really necessary for this buffer to be too big. The reason is that it is really just a temporary buffer. It holds the data until it can be transferred to the charts graph buffer. The user specifies an Update Time Interval. The chart periodically checks to see if there is any data available in the temporary buffer. If there is, then it empties the buffer and puts it into its own internal buffer for displaying. The interval between checks is determined by the Update Time Interval property.

Here is the sequence of events that happen simultaneously when data is collected. Each of these algorithms occur in separate threads so they run at the same time. Assume the Collect data Interval was 1 ms, and the Update data interval was 200 ms.

Figure 5. Data Collection Flow Chart.


If these values are configured incorrectly it can lead to several problems. If you are collecting too much data, or are trying to update the chart too fast, this can slow the simulation down or completely lock up the program. Also, If you update the chart too slowly it can also lead to problems. The reason is that the buffer in the simulator is only meant to be a temporary repositoyr for the data. The chart is supposed to check to see if it contains data, retrieve it, and clear the buffer out frequently. If this buffer fills up then the data is erased before it can overflow. When this happens you end up with a big gap in the data like what is shown in figure 6. To fix this change the Update Interval to be smaller so it checks the data buffer more often.

Figure 6. An example showing how the chart messes up if you set the update time interval too large. The data buffer fills up and must be cleared so when the chart checks for data it ends up with large gaps where data is not found. Compare the results of the two charts to notice the large difference between the two.


Line Chart Menu & Toolbar

The following items can be found in the main toolbar, main menu, and also in pop-up menus. You can view pop-up menus by selecting items in the Hierarchy tree and then right clicking on them to display the pop-up menu.

Add Chart Axis
Adds a new axis to the chart. The user can add up to six axis's.

Add Chart Item
Opens the Select Data Item dialog box so the user can choose data to add to the currently selected axis.

Delete
Deletes the currently selected item.

Export Data
This saves a tab separated text file in the project directory. The name of the file is the same as the name of the chart. You can open this file in Microsoft Excel or other spreadsheets to further manipulate the data.

View Data
Opens a dialog box that shows all of the data collected for this chart.

Set Zoom Axis
The user can zoom into the graph by clicking on the graph and holding the button down to select the area to zoom into. However, sometimes you may want to explicitly set the area to zoom into. Use this feature to start the zoom start/end values.