Running models : Working with visualisation tools

Working with helpers

A helper is a tool that can be used to interact with a simulation. Simile provides helpers to display the results of a simulation, for example, to plot graphs, or tabulate data, or to enter data into a simulation as it proceeds. Some helpers do both: for example, the grid display helper also enables the user to set a value for any grid square. It is simple to add new helpers to Simile. If you are interested in learning how to develop new helpers for your own models, please contact us at Simulistics.

Most of the helpers are used as follows:

  • If using the Single-window Model Run Environment, select or create an empty pane
  • Add a helper tool, either by clicking that helper's button in the MRE toolbar or by selecting it from the pull-down menu ("Add..." or "I/O Tools" -> "Add...")
  • Specify which model variables will drive the display, by clicking on them either in the model diagram or in the Model Explorer tool
  • If the tool can display multiple data items, hit the + button to add further items to the display.

Extra features common to several helpers:

  • Clear the display with the clear button
  • Remove a data item from the display with the - button (values already displayed for it may persist)
  • Add notes to the display area of canvas-based helpers (e.g., plotter, grid display) with the T text button
  • Configure the helper with the configure button

Simile comes provided with a number of standard helpers. Some are generic, such as the "Plotter" and "Data table" helpers. Others are quite domain-specific - the "Lollipop diagram" helper, for example, was developed for displaying tree growth - but are included because (with a little imagination) they can be applied to a range of situations.

The configuration of helpers best suited to viewing a particular model can be saved to a file.

In: Contents >> Running models

 

Running models : Working with visualisation tools : Plotter

Plotter helper

 

The plotter helper is for plotting graphs of one or more variables against time. If a variable has many values, e.g., one in a multiple instance submodel, all the values will be plotted. Different colours are used for different variables, and for data from successive model runs. Hovering over a trace on the diagram will result in a popup window giving the indices of the particular value it represents, the time in the run at which that point was plotted, and its value at that time and at the current time.

Clearing the display

To remove all the plotted data, click on the button.

Selecting elements to plot

One or more elements can be added to the graph.

  • to add an element, click on the button. An instruction is then posted to click on the model element to be plotted. This can be on the model diagram or in the model explorer.
  • to remove an element, click on the button. An instruction is then posted to click on the element to be removed, in the legend of the graph. Data already plotted for that element will not be removed untiil the clear button is clicked.

Highlighting a trace

Clicking on one of the traces will highlight it by drawing it in double thickness. You can highlight many traces at once. Clicking on it again will reset its display state to normal.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Table

Data table helper

The data table helper is a tool for tabulating the results of a simulation run. You can use it if you want to inspect the simulation results in more detail than you can on a graph, or if you want to export the results, as a data file in comma-separated value (CSV) format, to data presentation or analysis software, e.g. Microsoft Excel.

You can specify as many model variables as you want. Any of the variables can be nested in multiple-instance submodels to any depth, in which case each instance of the submodel will be allocated one column. The leftmost column displays the times at which the values were recorded. Columns can be removed, if desired, after the simulation has completed. The precision (number of decimal places) to which the numbers are displayed can be increased or decreased before each run of the simulation.

Note that for very large arrays of values this tool can run quite slowly, because it is oriented towards interactive display. It can be improved by turning off updating at every display time (this option is available in the properties dialogue). If you want to save very large data sets, or time series from long runs, it may be quicker to use the snapshot tool.

Clearing the display

To remove all the tabulated data, click on the button. This preserves the column headings, but removes all the rows of data except those corresponding to the current time.

Choosing elements to tabulate

The elements to be tabulated are selected as column headings. The procedure for choosing elements is as follows:

  • to add an element, click on the button. An instruction is posted, to click on the element to be tabulated. The element can be chosen from the model diagram or from the model explorer.

  • to remove an element, click on the button. An instruction is posted, to click on the column headings to be removed. The first click indicates the start of the range of columns to be removed, the second click indicates the end of the range. If the same column is selected twice, only that column is removed.

Saving table data

To save the data displayed in the helper, click on the Save button. The table will be saved in .csv format with the headers and values arranged as they currently appear in the display. Where headers are spread over more than one column, empty fields will be added to the saved table so that subsequent headers in the same row still line up with the correct data columns.

Arranging the layout

The layout of the table is controlled using the Table properties dialogue box. Clicking on the Properties button will bring up a dialogue box with two tabs. These tabs provide options to change the table layout, and to alther the way in which values are displayed.

Adjusting table layout:

This allows the user to designate which dimensions of the data to use as row and column headings. For example, time can be used as either a row or column heading, and element names and element indices can be used similarly. This tab also includes the option to show current values only as an alternative to showing values for all time points with the relevant time as a row or column heading.

Adjusting value display format

This tab, titled "Variable formats",  provides several options for adjusting the way in which values are displayed in the table. The pulldown menu at the top allows you to specify which values the changes made here should apply to; the default is "All" but you can choose to re-format the values of only one particular variable in the table by selecting its caption here.

The leftmost listbox allows you to select the type of value which is being displayed. As opposed to pure numeric values, you may choose to display them as angles (d °m ' s ") with conversion from radians if appropriate, or dates/times with conversion from Julian days. Boolean is provided in case your data uses numerical values to represent true/false states, but if the value is actually boolean in the model, this will be selected by default.

The next listbox allows you to select from a variety of formats for each value type, most importantly between General and Scientific (exponential) for numeric values. The right frame allows the number of decimal places displayed to be adjusted via a spinbox, and provides an option to highlight negative values by displaying them in red as in accounting ledgers.

Logging data over time

Normally, the table helper shows data from the model at any time point corresponding to start of a display interval. By selecting "current values only" from the layout tab, the helper can be made to display only the values for the start of the current display interval. No time heading or time values will appear. In this mode you can unselect "update at display intervals" on the same tab, which results in the data not being updated at all except when the update button is clicked. When a time axis is displayed, the data is still logged even when it is not updated in the table, so clicking the update button will result in all the values since it was last clicked being displayed.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualization tools : Layers

Layer display

The layer display tool differs from Simile's other display tools in that it allows a number of different types of display to be superimposed to create a composite image of processes in a 2-D modelled world. When the layer display is selected, a blank window appears in the run environment, and the 'Add' menu is replaced by a 'Layers' menu which allows the modeller to add instances of layer tools to the display, and to manipulate existing layers.

There are currently four different layer tools:

As of Simile v6.9 there are also a set of '2-D shapes' tools, for adding layers consisting of circles, lines or ellipses. These are analogous to the corresponding object types in the 3-D Shapes tool.

The spatial grid and polygon maps are similar to the corresponding stand-alone spatial grid and polygon tools, with the exception that they cannot be used to change values of model components. The background photo tool simply allows an image to be displayed behind anything that is added by the other tools, and the moving individuals tool displays icons (specified as series of Tk canvas drawing commands) for members of a submodel which includes values representing their co-ordinates in a 2-D space.

Layers menu

When the layer tool is first added, the layers menu will consist of a single entry labelled "Add new layer here". This cascades to a set of menus listing the available layer tools according to their source, like the menu for selecting the regular helper tools. Once a layer tool is added, the modeller will be prompted to select files and/or click on model components whose values will control the layer display, after which the layer will be added to the display. The layers menu now has a new entry for this layer, with 'Add new layer here' entries above and below it.

Once layers have been added, the menu lists all the existing layers, with 'Add new layer here' entries above, below and between them to allow new layers to be added at any position in the stack. Selecting the entry for an existing layer cascades to options to move the layer to the top or bottom of the stack, up or down one level, delete it or open its properties dialogue. A layer's properties dialogue will have a set of input widgets, some of which are unique to the layer type, and some common between various layer tools. The common ones are:

  • Select colours: This allows the colours representing the different model values (as shown in the legend) to be changed.
  • Range: The range of values covered by the colour spectrum can be widened or narrowed.
  • Offset and scale: Normally, data with the same numerical X and Y coordinates will display at the same point in the window in any layer tool, but these values adjust the display position of each layer. They can be used to compensate for different coordinate units being used in different parts of your model, or to show different maps side by side in the same window.
  • Legend side: For tools that can display a legend, this selects at which side of the window it appears, if at all. If multiple legends are added to the same side, the ones for the higher layers will be drawn on the inside.

In: Contents >> Running models >> Working with helpers

Working with visualization tools : Layers : Spatial grid map

Spatial grid map

 

This layer tool is very similar to the spatial grid display, with a couple of exceptions:

  • It cannot be used to set the values of model components
  • If used with a component in a hexagonal grid, the cells will be shown in a 'brickwork' pattern corresponding to the centres of the hexagons.

This tool may also be slower than the spatial grid display, since a more complex image scaling operation is required to get the grid to the exact scale to match other components.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualization tools : Layers : Polygon map

Polygon map

This layer tool is generally similar to the polygon helper, and is set up in a similar way. The differences are as follows:

  • It can be set to redraw the polygon outlines at each display interval, to cope with models in which polygons appear and disappear, or change shape
  • It cannot be used to set values of model components
  • The value for the colour is selected first. If this is from a hexagonal grid submodel, there is no need to provide vertex coordinates -- the helper generates the hexagon outlines itself.
  • The properties dialogue allows a stipple pattern to be chosen for filling the polygons. This allows lower layers to be partially seen through them.

This tool is faster than the old polygon helper with large numbers of polygons.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualization tools : Layers : Background photo

Background photo

This is not really a visualization tool at all -- it just allows an image to be displayed as a background to the layers. Generally the image will be some form of map that corresponds to the data in the model. Because the pixel pitch of the image may not correspond to the position data in the model, the properties dialogue allows an offset and scale to be set for the image display. Thus the tool also allows the who;e layer display to be annotated with small images.

When the tool is selected, a file selection dialogue appears for choosing the image file, which immediately displays. Its offset and scale are then adjusted via its properties dialogue. To change the image, delete the layer and add a new one.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualization tools : Layers : Show moving individuals

Show moving individuals

If a model includes a group of submodel instances representing mobile individuals, it may be desirable to display them on a map background using icons. That is what this layer tool is for. It can draw a lot of copies of an icon representing an individual at positions specified by model data. It can also vary the size and orientation of the icons according to data from the model.

The image data file

In order to do this, the icon must be expressed as a series of canvas drawing commands in the Tk language. Tk is the standard graphics extension for scripting languages including Tcl, Perl, Python and Ruby. An example file to draw the ants in the image on the Layer tool page is included in Simile's examples directory, and the images for Simile's population channels are also encoded in this way. These files typically have the extension .cnv. It is hoped to offer a Paintbox-style drawing tool for creating images in this format in the near future.

The file consists of a series of commands to draw the icon on a canvas referred to as $c. This will cause it to be drawn in the layer display when sourced by this tool's code. If the ability to rotate the icon is to be used, then only canvas objects that can be drawn at any angle should be included, i.e., avoid arcs and ovals (unless circular) and rectangles. As well as drawing commands, the file should include an instruction to set the hotspot -- this is the point in the image that will be positioned on the map point given by the model data, as a pair of integers, e.g.,

set hotspot {100 150}

Similarly the scale should be set, i,e., the number of canvas units of the drawing commands corresponding to one unit of map space. A large value will mean the image is drawn small, and is useful for precision because positions and line thicknesses in the image file must be integers.

set scale 10

It should also set the axis direction, in which the image as drawn by the canvas commands appears to be facing. This can either be a compass point (ne, sw, etc), an hour on the clock face (6h, 9h, etc) or a number which will be treated as the number of radians the axis lies anticlockwise from the x axis. e.g., these three forms are valid and equivalent:

set axis n

set axis 12h

set axis 1.57

Setting up the tool

When the layer is selected, a file selection dialogue appears for choosing the image file. Once the file is selected, its contents are loaded into the helper setup, so the file is not consulted again -- if the image is altered, the layer must be deleted and re-created to display the new version of the image. Now you will be prompted to click on model components for the x and y coordinates of the individuals' positions on the map. These have to be supplied. You will be prompted to click on two more model components to specify the size and orientation of the individuals. If you do not wish the icons to be changed in size, just click on one of the components you have already clicked on at this point, and the size will not be altered. The value of the orientation component can be a number, which is interpreted as the number of radians anticlockwise from the x axis which the image will be shown facing. Alternatively it can be a member one of the enumerated types used to index the neighbour directions in the special-purpose submodels, in which case the image will be drawn facing in that direction. In either case, if the value of the direction component is the same as the axis direction in the model file, the icon is drawn unrotated. If no rotation is to be done, select a component that has already been selected for x or y position as the rotation.

In: Contents >> Running models >> Working with helpers >> Layer tool

Running models : Working with visualization tools : 3-D Shape Viewer

3-D Shape Viewer

This is another helper that can superimpose shapes representing information from a number of different model components which may represent different types of object and have different array dimensions. In this case, a set of model components can be used to provide data for a shape or group of shapes in a 3-D scene. For instance in this representation of a plant, a sphere is used to show the root volume, cylinders are used to show the leaf stems (petioles) and ellipses are used to show the leaves themselves.

When the helper is first invoked, the grid is displayed showing X axis indices in red, Y in blue and Z in black. There are currently three types of shape which can be added. The dimensions of all model values used to create each set of shapes must be the same. To add a set of shapes, select the type using the menu button at the bottom. You will then be prompted to identify the model components to be used, and choose the colour(s) using a standard colour selection dialogue. All shapes in each set will have the same colour(s). When the selections are complete, the shapes will be added to the display.

Sphere

This is the simplest type. It requires model components representing the X, Y and Z coordinates of the sphere centres, and one for the radii of the spheres. The colour must also be specified.

Line

This requires seven model components, representing the X, Y and Z co-ordinates of the start and end of the line, plus one representing the line thickness. The colour must also be specified.

Ellipse

This requires eight model components. The first three are the X, Y and Z co-ordinates of the ellipse centre. Then there is one for the radius of the ellipse along the X (major) axis, and one for the eccentricity, which is the factor by which the Y axis radius is smaller. The ellipse will be drawn parallel to the XY plane if the next two are zero. The first of these is the rotation about the X axis, which rolls the ellipse around the major axis. Then comes rotation about the Y axis, which tilts it around the minor axis. The last one is rotation around the Z axis, which revolves the ellipse in its plane. Note that each rotation also rotates the axes for subsequent rotations. In addition to the model components, two colours must be specified for ellipses, the first for the front (initially upper) surface, the second for the back.

Navigating the scene

The view in the shape viewer can be adjusted using the mouse. The camera can be swivelled around the centre of the view by left-dragging in the view window, and zoomed in and out using the scroll wheel. Right-dragging will cause the camera to move perpendicularly to the direction in which it is looking.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualization tools : Sliders

Sliders for Variable Parameters

This window contains sliders (or switches, or combo boxes, depending on the data type) for variables marked as being  "Fixed parameters" or "Variable parameters" in the equation dialogue box for those variables.

Choosing which vaues to display

You can use the add button to add a slider for a model component if it is a fixed or variable parameter. The - button allows you to remove the slider for a particular model component. The "add all variables" button will add sliders for all model components marked as variable parameters, as it is for these that sliders are most usually required. The Clear button will remove all sliders. Sliders are grouped by submodel, if their variables are in different submodels.

Input widgets for different data types

On this page I am sometimes using the word "slider" to refer to an input widget for a model component, but it will only actually be a graphical slider if the component has a numerical value. In this case the slider will be drawn horizontally with a numerical legend with values between the component's minimum and maximum values as specified in the equation dialogue. If the component has an integer value, the slider will snap between integer points when it is dragged along the scale, otherwise it can be dragged smoothly along the scale. There is an entry box to the left of each slider, allowing a number to be typed in if you want to set the slider's position to an exact value.

Note that each slider is scaled individually according to the maximum and minimum values provided in the equation dialogue box. This information comes from the values for Min and Max entered in the Equation dialogue window. The initial value for the slider comes from the value entered into the Equation field of that window; if no value was given, then the slider is positioned at the mid-way point.

If the component has a boolean value, its entry widget will be a checkbutton. Checking the button sets the value to "true".

If the component's value is a member of an enumerated type, the entry widget is a combobox with a pulldown list of the type's members, allowing you to choose one.

Sliders for multiple values

Adding a slider for a variable with multiple values (e.g., from a multiple-instance submodel) will cause a group of input widgets to be added. The variable's caption appears above, rather than to the left of, the sliders, and each one has an index to the left indicating which model value it affects. If the values form a one-dimensional array, there will be a single input widget for each value. However, if the array is more than one-dimensional, there will only be a separate slider for each inermost index. Moving a slider will set all the values with that innermost index.

You cannot add a slider for a model component inside a variable-membership (e.g., population) submodel.

Interaction with the model (changed in v6.8)

Moving a slider directly affects the corresponding value in the model. If the model is not actually running when the slider is moved, an extra rate evaluation is immediately performed in order that other model values that depend on the slider are also immediately affected. This does not affect state variables such as compartment values. After this rate evaluation is done, the visualization tools are updated so the values being displayed are those resulting from the slider move. For example this update may produce a vertical line on the plotter between the old and new values.

Resetting the model now causes variable parameters to go to their default values. Sliders will move to the default values by themselves on reset. So, to use a slider to run a model with different values from reset, the slider should be adjusted to the initial value after reset but before starting the model run, which now causes the value to take effect at the initial time. Simile v6.9 also includes a preference choice to allow sliders to keep their values over model reset. To choose this option, uncheck 'reset sliders on model reset' in the Run tab of the preferences window.

For fixed parameters, setting the value with a slider has the same effect as setting it in the file parameters dialogue box. That is, no change will occur until the next model reset. If you adjust an input widget, the model will prompt you to reset it before continuing to run in order that the change takes effect. The sliders cannot be adjusted while the model is running.

The slider for a value will move by itself in response to a change in the component's value caused by something else when the model is running. Thus, if you have a slider associated with a variable parameter which also receives values from a time series, the slider will move to the value for each time point as that time arrives. A slider associated with a fixed parameter compartment will move to follow the compartment's value as the model runs, but cannot be adjusted until the model in paused, after which the adjustment only takes effect when the model is reset.

In: Contents >> Running models

 

Running models : Working with visualisation tools : Others

Using other helpers

Because of the ease with which new helpers can be developed (see below for details) a great many other helpers exist, alongside the plotter and the data table. These helpers are of a variety of ages and provenances, and do not conform to any consistent interface. Some were developed for specific applications, and although they are of general interest, reflect their origins in their design.

In order to use a helper, your model firstly needs to be built: that is, you need to have selected the "Build" item from the "Model" menu, as described in Running Models. Almost all these helpers work best in the multiple-windows run time environment. The procedure for adding helpers differs, depending on whether the single or multiple-window run time environment is selected.

The other helpers included in the standard installation of Simile are:

With the exception of the "Plot value against time" helper, all these helpers are primarily designed to display data from multiple-instance submodels. The spatial grid display and the three-dimensional viewer are designed to display data from multiple patches of land. The time lollipop display and the time profiles helper are designed to display the attributes of each instance of a population submodel. All these helpers use the following procedure for binding variables.

There are a few other tools, which don't actually perform the input/output functions of helpers but which are implemented as helpers because they operate on the executing model. One  is used to initialise the pseudo-random number generator:

 Initialise pseudo-random number generator

Another is used to alter the behaviour of functions defined by sketch graphs:

 Edit function sketch graph

New to Simile v6: a tool which saves selected model values to file each time step:

 Data logger 

Binding variables to helpers

When you select, for example, the "Plot value against time" helper, you need to specify which variable in your model will be plotted. Therefore, the helper issues an instruction, asking you to select a variable by clicking on it in the model explorer or in the model diagram window. Other helpers require more than one variable: in these cases, the instructions indicate the sequence in which the variables should be selected. For example, the "Lollipop diagram" helper (which displays trees in three dimensions) requires you to click first on a variable representing the x-coordinate of each tree; then on one representing the y-coordinates; then on one representing the heights. Note that no checks are made to ensure that the variable you select for x-coordinates really does contain x-coordinates: it is up to you to choose the right one.

Each helper uses one of two methods for instructing you to select the necessary variable(s):

  • Separate instruction window: a small window instructing you to click on a model element. The window will tell you the role of the variable that you are selecting in relation to the helper's task, and you need to click on a variable that is appropriate to that role.
  • Instructions in the helper window: an instruction about what you should be doing in the helper window itself. One example is the slider input helper. Typically, this allows you to repeatedly select variables from the model, with each one being added to the helper.

Developing new helpers

Simile is probably unique in the world of visual modelling software in that no input/output tools are built into the software. Rather, every such tool is implemented as a separate program in an industry-standard interpreted language called Tcl/Tk. When you load Simile, it creates a list of available helpers by looking in the "IOTools" directory for appropriate files. This is the list of helpers that is then bound into the menus.

One advantage of this approach is that with simple programming anyone can implement a helper customised to their own requirements: there is no need to submit a request to Simulistics (though you are, of course, welcome to do so). This means that if you are modelling (for example) whales, you can implement a display helper that shows whales swimming around. These helpers can be distributed easily, as simply copying the file to the "IOTools" directory is sufficient to install the helper in each copy of Simile.

In: Contents >> Running models >> Working with helpers

 

Running models : Working with visualisation tools : Grid

Spatial grid display helper

The spatial grid display colours a two dimensional rectangular grid according to the value of a specified variable within each grid square. It is typically implemented using a multiple-instance fixed membership submodel. 

Positioning the grid squares

When you add a helper of this type, you are first requested to supply a variable to use as the colimn ids. This variable must have the same number of values as the one that is actually to be displayed, but it is only used to calculate the dimensions of the grid. The grid will have one column for each discrete value in this variable (e.g., if the values are 1,1,1,5,5,9,9,9,9 thenthere are 3 discrete values, 1, 5 and 9). The number of rows will be the total number of values divided by the number of columns. The actual values are unimportant.

You are then requested to supply a variable from which to get the values for the square colours. This variable should have the same number of values as that used to define the columns. If there are more values, the later ones will be ignored. The values are placed in the grid starting at the bottom left corner and going across to the right, then filling the next row from the bottom and so on. If there are fewer values than the number of cells in the grid, they will be used again to fill the rest of the grid.

Zooming and scrolling

The + and - buttons in this helper enlarge and reduce the displayed grid, in steps of one pixel per grid square. When the grid extends beyond the boundaries of the display port, you can use the scrollbars at the borders to bring various parts of it into view. Note that the colour legend will always obscure part of the grid if you can scroll perpendicularly to it. To see all of the grid, you can move the legend between the bottom and the right of the display using the "Orientation" radio buttons in the helper's properties dialogue. The 'Save' button will save an image showing the legend and visible part of the grid, in the format indicated by the supplied file extension.

Choosing colours for values

The legend shows which colours correspond to which values from the variable. It has different colours over a certain range of values. The range can be increased or decreased with the < and > arrow buttons in the toolbar, or it can be set exactly using the "Scale range" entry fields in the properties dialogue. If the data variable is boolean or enumerated type, there will be one colour for each of its possible values. If it is an integer, there will be a different colour for each value in the range, up to 100 colours. Otherwise, there will be 33 colours corresponding to smaller ranges of values within the whole range. Values outside the range are shown in the colour for the nearest end of the range.

For numerical values, there are three colours for low, middle and high, (black, yellow and white in the image above) with other colours fading between these for other values. The properties dialogue allows these three colours to be changed. In any case, the colour for a particular value or range of values can be changed by double clicking on it in the colour legend.

Viewing and changing information

The grid display normally updates as the model runs, but can be frozen by clicking the "Freeze" button at the right of the toolbar (this feature is left over from the days when the graphics took a long time to update; these days they are very fast).

Clicking on the display gives a popup with the column and row number of the grid square in which you clicked, plus its value (which will be approximate if the display is using colours to represent ranges of values). Dragging produces more poups for each grid square entered. Hovering over a colour in the legend shows what value it represents.

The grid helper can also be used to set the values of model parameters. This does not work for variables other than parameters. Click on the "enter edit mode" button (with the pencil icon) then click on the colour legend to select a colour to "paint" onto the grid. Click on the legend again to paint a new colour. Changes made to parameter values in this way will not take effect immediately; the same rules apply as for changes made with the slider helper.

Saving information as GeoTIFF

The second tab in the properties dialogue allows the grid to be saved as a GeoTIFF (for more information see section on loading GeoTIFF data). To use this tool you must have the GDAL library installed on your computer. Load a template file from which to copy the georeferencing data, then save a new file using the data from the grid. This is useful if you have parameterized your model with data from GeoTIFF files. You can also choose to have a file saved at each display interval after the grid data is updated; the time value will be appended to the chosen filename.

A three-dimensional view of a rectangular grid is also possible using the 3d viewer.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Plot value



Plot value against time
helper

This is the classic time-plot helper. It was not designed for
presentation in a printed document, but for giving the model developer a
robust, flexible display of how the value(s) for a single variable change
over time. It automatically re-scales, on both the X (time) and Y axes, it
can handle a variable no matter how deeply nested in multiple-instance
submodels, and it displays the results from previous runs for comparison.
It also gives the current values for all the variables in text form.

Each time you select a "Plot value against time" helper, you need to
choose the variable to be plotted before the helper is displayed. You are
alerted to this requirement by the message:

The following screen dumps show the standard ways this helper can be
used.

This shows the value for a single-valued variable "size" from three
successive runs of the model, using different parameter settings on each
run. Note the automatic use of a different colour for each run, and the
current value displayed at the bottom-left.

This shows the set of time plots for a single variable embedded inside a
fixed-membership multiple-instance submodel. Since the number of instances
is fixed for the duration of the run, we have the same number of lines
throughout. Note that the line for each instance is different, reflecting
the fact that each instance has different parameter values even though they
all behave according to the same equations.

Here again we have the plot for a single run, for a single variable
embedded inside a multiple-instance submodel. This time however the
submodel is a population submodel, with individual instances coming into
existence and disappearing during the course of the simulation run. Note
then how lines start during the simulation (unlike the previous example,
when all lines started at time zero), and also terminate during the course
of the simulation, as individual instances are killed off. Each line has a
different slope, reflecting the fact that the model was set up with a
randomly-determined parameter value for each instance.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Profiles



Time profiles helper

The time profiles helper is designed to show multiple attributes of each
instance of a population submodel. Each instance must be assigned a unique
identifier, which is plotted sequentially on the y-axis. A stacked bar
chart display is used to plot an arbitrary number of properties of that
instance against time.

For example, each individual in a population may hold wealth in the form
of property, stocks and shares, and cash. The time profiles helper will
display the changing wealth of each individual over time (the total height
of each bar) as well as the make-up of that wealth (the height of each
coloured segment).

For best results, the variables plotted should be scaled to be less than
50. Panning and zooming operations are implemented as for the plotter helper. The y-axis can be panned up or down and
the x-axis panned left or right to display different parts of the axis at
the same magnification, whilst both axes can also be zoomed in or out to
increase or decrease the magnification.

  • The cursor takes on the shape of a
    four-headed arrow when placed over a scale point. Dragging a scale point
    alters the range displayed by zooming in or out. To zoom in, drag the
    scale points away from the origin, i.e. to the right (on the x-axis) or
    upwards (on the y-axis). To zoom out, drag the scale points towards the
    origin, i.e. to the left (on the x-axis) or downwards (on the y-axis).
  • The cursor takes on the shape of a
    two-headed arrow when placed over the axis itself. Dragging the axis
    alters the range displayed by panning up or down, left or right.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Model Explorer

Model Explorer

The model explorer provides a nested tree view of all the variables, compartments and flows used in the model. The elements are arranged by submodel, hierarchically from the top level desktop. In variable-membership submodels, additional elements used only in those submodels are also displayed. When a "helper" window requires a variable to be selected, this action can be performed by clicking on the required variable in the model explorer.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Lollipop

Lollipop diagram helper

The "Lollipop diagram" is a means of displaying tree-like objects distributed in two dimensions. Each object has a size, which is used to calculate both the length of the trunk and branches. After invoking the helper, three variables are required for each component whose values are to be displayed, corresponding to the x-coordinates, the y-coordinates and the sizes. These can be variables or compartments, and are typically in a multiple-instance submodel. One tree then corresponds to each instance of the submodel.

Each set of values is displayed as trees of a diferent colour. A horizontal grid is also drawn, with x positions numbered in red, and y positions in blue. Numbers corresponding to heights of trees (z variable in the legend) are positioned above the grid corners in black.

There are sliders to adjust the longitude (view angle) and latitude (view elev.) of the point on an imaginary sphere surrounding the grid from which it is viewed. The image can be printed.

Note that all three variables can change through time, so although real-world trees may not move, their graphical representations can. This means the lollipop diagram helper can also be used for simulating animal movements, and so forth.

For best results, the x- and y-coordinates should be scaled between 0 and 100, and the size should be less than 25.

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : Initialise

Standard helpers: Initial pseudo-random number generator

The functions rand_var() and rand_const() generate random numbers. For greater understanding of model behaviour it is sometimes convenient to generate the same (or the same sequence) of random numbers for several model runs. To do this, it is necessary to seed the random number generator with the same integer value each run. For this reason, they are known as pseudo-random numbers. A simple tool is provided to enter the seed.

To enter the seed:

  1. enter an integer value in the edit box;
  2. click on the "Set seed" button; and
  3. reset the model.

Note: It is important that the reset button on the "Run Control" is used AFTER initialising the pseudo-random number generator using the "Set seed" command. This is because some random numbers are generated when the model is reset.

Example

Using the seed "123" will produce the following sequence of random numbers for the function rand_var(0,100) every time the simulation is performed:

62.3463, 2.2889, 13.6723, 11.7893, 92.8648, 56.7217, 93.8688, 96.4232, 96.3378, 75.1671, 49.0097, …

(At least if you are using the bundled MinGW C compiler under Windows. Other compilers may produce different sequences, owing to using different library implementations of the pseudorandom sequence generators, but this tool can still be used to achieve repeatability.)

In: Contents >> Running models >> Working with helpers

Running models : Working with visualisation tools : 3d

3d viewer helper

The 3d viewer helper is similar in operation to the spatial grid display helper, though four variables, rather than two, are required, to display the grid in three dimensions. These are, as before, the x-coordinates and the colours, but also, the y-coordinates and a sizes. Again, these are most commonly implemented using a fixed membership multiple-instance submodel.

 

3d viewer helper

The 3d viewer helper is similar in operation to the spatial grid display helper, though four variables, rather than two, are required, to display the grid in three dimensions. These are, as before, the x-coordinates and the colours, but also, the y-coordinates and a sizes. Again, these are most commonly implemented using a fixed membership multiple-instance submodel. 

Amongst the many menu options, is the ability to switch to a surface view of the grid, as shown in the following screen shot. There are also options to rotate the graph through three dimensions, and to select the colours used.

In: Contents >> Running models >> Working with helpers

 

Other visualization tools : Event sounds helper

Other visualization tools : Event sounds helper

The motivation behind Simile's visualization tools is to provide the modeller with a continuous, immediate understanding of what the model is doing. Sometimes the best way to do this is with sounds rather than graphics. With the addition of discrete events to the modelling language, we realized that their instantaneous nature does not lend itself to the kind of graphical displays that work for continuous values. 

So we created an event logger that also produces a sound each time a selected event occurs. Add an instance of this tool in the standard way, selecting 'Event sounds' from the list of helper titles. Now after clicking '+' in the helper window's toolbar, you can select a discrete event component in your model, and a sound file to play each time the event occurs. The window will show a 'ticker bar' which will move across the screen right to left, with a vertical line added each time the event occurs. Hovering over the lines will pop up the exact time and magnitude of the occurrence they represent.

Also, the sound will be played each time the event occurs. If your event has a numeric magnitude, then the volume of the sound will be determined by where each event's magnitude falls between the min and max values given for the event. Sound files in WAV format will play on all platforms -- files in other formats (e.g., mp3) may play on your particular platform but are not guaranteed to play on all.

If the chosen event occurs very frequently, or if it is in a simple model that runs very fast, the sounds may overrun each other producing unpleasant noise. In this case you can use the 'limit updates/sec' feature to slow the model execution down to the point where the sounds can be heard separately.

 

Running models : Working with visualisation tools : Polygon diagram

Polygon diagram

This tool enables a dataset to be displayed as the colours of polygonal areas on a map. It can be used either where vector data for an actual map is available (either in the model, or in a separate file), or where an area is represented as some regular set of shapes whose vertices can be calculated by the model, e.g. hexagonal tiling.

A lot of the functionality of the polygon helper, including scrolling and zooming, working with the colour legend, and using it to edit model parameter values, is exactly the same as for the grid helper. However, the graphics of the polygon helper are not quite as fast, so you are more likely to need the 'freeze display' and 'manual update' features.

Loading co-ordinates from file

If you choose this option you will get a file selector to locate the data for the coordinates. If you choose a file with the extension .dxf, Simile will attempt to load it as a DXF file, and will then colour the polygons in the order in which they are defined in the file. Otherwise, Simile currently expects the file to contain all the X coordinates in nested list form, followed by all the Y coordinates. This is not particularly convenient, so we should add the option to set the coordinates from file using the table data dialogue too.

Loading co-ordinates from model

Of course you can put fixed parameters in the model and load them using the table data dialogue, then use them to set the boundaries of the polygons. If you choose this option, you will be asked to select model elements representing the X and Y coordinates of the polygon vertices. These elements should have two-dimensional data arrays, with the outer index being the number of the polygon whose border they define, and the inner index being the number of the vertex around that polygon. There should be the same number and arrangement of X and Y coordinates.

The usual way to get the coordinates is to have a submodel for the vertices inside the submodel representing the polygons. This should be a per-record submodel if different polygons have different numbers of vertices. Put fixed parameters for Xs and Ys inside the vertices submodel. 

In: Contents >> Running models >> Working with helpers

Running models : Working with visualization tools : Edit sketch graph function

Standard helpers : edit sketch graph function

If your model contains equations that use the graph function, their function can be altered while the model is running. The tool for doing this appears as a helper, although it does not display values from the model or directly set them.

The helper is located in the "Standard tools" subdirectory menu and is called "Edit sketch graph function". Create an instance of the helper and click on the model component whose function you wish to alter. You will then see the same sketch graph editing window as when you originally created the sketch graph. You are able to drag the sketch line as well as edit the axis values and change the settings that control how the sketch is interpreted.

Any changes you make to the sketch graph function will take effect as soon as you hit the 'OK' button, but the helper will stay up until you delete it, allowing further changes to be made at any point. Note that the edited function will not be saved with the model. If you save the model after editing the sketch using the helper, it will keep the original version of the function. To change this you must go back to the equation dialogue and hit the "Graph" button.

 

Running models : Working with visualization tools : Data logger

The Data Logger tool does not display model data, but records it in files for later analysis with statistical tools. There are other ways of doing this:

  • The Table Helper can save its contents as a .csv file, but has poor performance with large data sets
  • The Snapshot tool can record values as the model runs, but only handles one variable, and needs setting up every time the model is run

By contrast, the Data Logger can handle any size of data set that is usable within Simile, and can log multiple variables, either in separate files or as columns in a single file. Since it is a standard helper, many instances can be added for different groups of values, and the setup can be saved as part of a general helper layout.

Using the tool

The tool's canvas will be blank when it is first added. To log a variable, hit the + button and click the variable on the model diagram. It will be listed within its hierarchy of submodels, with a '-' button ffor its removal. Hit + again to add more variables. The rightmost button in the helper's toolbar switches between saving separate files for each variable (named by the variable's caption) and a single file (log.csv) with each variable in its own column.

Saved file format

The helper will not save any data until you select a folder in which to save it. Click the toolbar button with the folder icon and navigate to the desired location. Now a line is written to the log file(s) at each display point as the model executes. The files are in .csv format with the time points stored in the left hand column. If the values being saved are arrays, they will be written as series of alternating indices and values, with each series enclosed in curly brackets, i.e., the same format as data popups or directly-entered file parameters.

The file is closed when the model is paused, and opened for appending more data when it is restarted. When the model is first run after a reset or rebuild, the file will be opened for writing, so the previous contents will be overwritten unless they have been moved.

As of Simile v6.9, it is also possible to log model data to a database -- either a file in some Excel-compatible format (.xls, .xlsx etc) or a MySQL database. To log to a database file, simply select it from the file dialogue. To log to a MySQL database, cancel the file dialogue and this will cause the database specification dialogue to appear. Here you enter the hostname, username, password and name of the MySQL database.

When logging to a database, each component being logged will have values put in its own column in the database. If logging an array component, there will be a separate column for each element in the array, named value/n where value is the name of the component and n is the index of the element. (value/n1/n2/... for multi-dimensional arrays). The values will be written to a table called 'Run 0' until the model is reset, after which new tables called 'Run 1', 'Run 2' etc will be created for data values from subsequent runs.