Menu "Data" Analysis of Results

This module permits users to analyse the data produced during a simulation. See the Introduction, or the window elements.

Elements of the Analysis of Results window

Introduction

1. From the Browser using the data produced by the latest simulation, which are stored in memory until a new simulation run is launched;
2. during a debugging session (button Analysis), when a simulation is interrupted; in this case the data are available up to the next to last simulation step, and after the analysis of (partial) result the simulation can continue;
3. loading the data from a file containing simulation data previously saved. This option is alwasy offered even when a data set is available in memory as in the previous two cases.
4. Loading data currently stored in the model. These series can be analysed only at the current time step, that is they are available with one value.
   

The window for the Analysis of Result shows the data available listed in the Series Available list box. The series to be elaborated must be selected and moved in the central list Series Selected: all the commands concerning plotting, producing statistics or save data concern only the series in this box. Users can select the options available and then issue one of the following commands:

• graphical representations of the series. The series are plotted in graphs in different arrangements according to the options chosen (e.g. time series or cross section). The graphs are shown in individual windows which are listed in the rightmost list box Graphs, and can be brought up in the foreground by double-clicking on their title in the list;
• descriptive statistics, either taken over time or cross-section. They are printed in the Log window;
• text files, containing in the columns the series produced. A variety of formats are available for export from Lsd, to be subsequently imported in an external package for further elaboration;
• postscript files containing the graphical representation produced on the windows in a format suitable for inclusion in a word processor.

1. Empty the central list box, if necessary.
2. Select the series of interest in the Series Available list box, possibly after sorting the available series in a suitable order or filtering them in a particular way, and move them in the central list box Series Selected (button ">").
3. Set the options of interest (e.g. automatic scaling, color or no color graphs, type of plotting, etc.)
4. Issue the command (e.g. plot, statistics etc.)
5. If necessary, compare with the model description (e.g. the equation for the Variable plotted) available from the menu Help

Series Available
List of the series available. The series are presented in the following format:
InstallBase 1_11 (30 - 200)
which contains the following information:

• the name of the Variable or Parameter (InstallBase);
• a code to distinguish between the same Variables or Parameters in different Objects of the model (1_11). This code contains as many digits as the hierarchical level of the Object containing the Variable, in the example the first highest level Object and the eleventh of the second level. The user can check in the model report, observable from the menu Help, where the Variable is placed.
• the first and last simulation time step for which the data are available (30 - 200). In the example the Object containing this Variable has been created in the 30th time step, and lasted up to 200th time step.

Selection Methods
From this list variables must be selected to be moved in the list of the Series Selected. using the  Button '>'. The labels can be selected using the mouse with the usual bindings:

•  click on one label to select it and de-select any other;
•  keep the control key pressed and click on a label to add it to the selection without de-selecting other ones.
•  click on a selected label to de-select it;
•  click and scroll the mouse pointer oevr the listbox to select all the labels encountered;
•  click on one label, keep the shift key pressed and click on another label to select all the labels between the two;

Variables' equations
Clicking with the right button of the mouse while keeping the shift key pressed the system pops up a window showing the code for the variable. Note that if the series concern a parameter's value, this operation has no effect.

Button ">"
Insert in the listbox Series Selected the variables selected in the Series Available.

• Sort: list the series according to their increasing label alphabetical order and to their code.
• Sort (end): sort the labels according to, firstly, their increasing alphabetical label order, and, secondly, then to their "end" date, the time step when the Object containing the Variable has been removed by the model. If no Object has been removed during the simulation, this option sorts the labels identically to the previous one, Sort. But if some Object have been removed, this sorting method shows sequentially the series with the same labels placing first the series in Objects still existing.
• Un-sort: reproduce the original order of the series, with the ones contained in the highest Objects first, and then grouped according the Object containing them.

• Data from the current configuration of the model. These data will conventionally be marked as data at time step 0, and can be used to make cross-section graphs or statistics only, since the system can retrieve only the values of the elements at the current time step. Note that the system offers a auto-completion facility, so that the window to inser the label of the desired element is automatically filled in.
  
• Data loaded from  file(s) of Lsd results saved from a previous simulation run(s). This option loads the data from a files selected with the usual file selection method. When a file is loaded, its series will be marked by adding a "F" letter in the end of the label, and the file is assigned an increasing number, indicated in the Log window. This file number is also indicated in the first location of the tag of the series. This convention permits to differentiate from series produced during the last simulation run, from those data loaded from the file and, in case, of the different data files loaded.  It is possible to also load several files, usually produced by  multiple runs.
• (available only if some series is present in the Series Selected listbox) Data from creation of new series obtained as elaboration of the selected series. The system can generate a new series using the average, minimum, maximum or variance of the selected series. The user is asked to specify the label of the new variable and the tag. See here for further details.
  

• Compute over series: the new variable will be composed by as many time steps as the selected ones. Each time step value is computed elaborating the same time step values of the selected series. For example, (choosing Average) being v_t^j the value of series j (with j={1, 2, ...n}) at time t the new series will be computed as: NewSeries_t=SUM_j[ v_t^j ] / n
• Compute over cases: The new series will be composed by as many time steps as the number of series selected. Each value is computed elaborating all the values for one of the series selected across all the time steps of the series. For example, (choosing Average) being v_t^j the value of series j at time t the new series will be computed, for the conventional time step j, as: NewSeries_j=SUM_t[v_t^j ] / m, where m is the total number of time steps of the series

Listbox "Graphs"
List of graphs already created by means of a plot command. Each graph is linked to one item in this listbox, where they appear with the title assigned when created, an increasing counter. Double clicking on one of the lines in the list brings the selected graph in the foreground. Graphs created directly by gnuplot are reported in the listbox but are re-created any time their title is double-clicked.
Graphs may be destroyed (and removed from the list) either clicking on the item to remove with the right button of the mouse, or selecting it and pressing the Delete key.
 

Notice that the secondary scale is indicated among parenthesis in the Y axis (see the example graph). Pressing the Shift key, the mouse cursor over the graph indicate the position in respect of the secondary scale.

"Watch"
Checkbox that, if on, refreshes all the Lsd windows during the creation of the graph, showing the process of graph creation. If checked off, the plot is made in background, increasing slightly the speed of producing the graph.
If checked off, users cannot access the Lsd windows during the plot of graphs. This is relevant because during the creation of a graph the user can abort the plotting (the button for Plot is changed in Stop), if the graph is too complex and taking too much time to be plotted.

Button "Plot"
This button creates a graph window plotting the data from series listed in Series Selected and using the options for: Cases to Plot; Y scale; Color; Lines / Point; Point size; Grids, Time Series / Cross Section option, Sequence / XY Plotting option.
The graphs produced depend on the options Time Series / Cross Section and Sequence / XY Plotting chosen, and the number of series selected, for a total of five different types of graphs:

Time Series & Sequence 
The standard time series plotting, where X contains the time step of the simulation and the series are plotted. The system automatically removes series non existing during the cases considered, or truncates as necessary. Lines connects points from the same series in different times. Note that if the number of time steps is larger than the available definition (640 points) the system computes one single point (the average) for each datum falling in the same X value.

Cross Section & Sequence 
The X axis corresponds to the series, the Y axis to their value and the lines with different colors correspond to a particular time step of the simulation. The cases to plot, and the order in which the Variables has to appear in the X axis, are set with a specific window. It is possible to rank the series listed in the X axis according to increasing or decreasing values (at a certain time step), or to use the same rank as appear in the Series Selected listbox. A label below the X axis reports the number of series used. The lines connect points from the different series at the same time step.

Time Series & XY Plotting and more than one series selected 
The X axis reports the values from the very first series in the window Series Selected. The graph will contain a line for each subsequent series, placing a point for each value from the first series. For example, suppose there are three series in the Series Selected list (X¹, X², and X³). The graph will contain two lines (or groups of points) at the coordinates (X¹_t,X²_t) and (X¹_t,X³_t), for each time step t included in the user's selection of cases. The graph is produced by gnuplot (see here for details on how to manage the windows produced by gnuplot).

Time Series & XY Plotting and one single series selected 
This graph reports the phase diagram of a series. The X axes contain values of the series selected, and on the Y axes are reported the values of future time. It is possible to insert a 45° line in the graph so to indicate the stable points (where X_t=X_t+1). The user is requested to insert a lag value, and a single series will be produced for each lag. For example, consider the user requesting three lags. The graph will contains two series at the coordinates (X_t,X_t+1) and (X_t,X_t+2) respectively.

Cross Section & XY Plotting
This graph considers data from a single time step. It uses the values from a group of series for the X values and produces lines from group(s) of other series.
The user is asked to specify one single time step and how many series will give the values for the X axis. It is necessary that the number of series chosen for the X axis is an exact divisor of the rest of the series. For example, if the Series Selected list contains 6000 series, the user can choose 1000, 2000 or 3000 as "block length". If 2000 is chosen (and k is the time step chosen) the system considers the values from the first 2000 series as values defining the X axis, and two other data sets (from the 2001 to 4000, and from 4001 to 6000) that will provide the Y values to plot. The graph will therefore contain two lines defined by the 2000 points each with coordinates {(X¹_k,X²⁰⁰¹_k), (X²_k,X²⁰⁰²_k), ..., (X²⁰⁰⁰_k,X⁴⁰⁰⁰_k)} for the first series and  {(X¹_k,X⁴⁰⁰¹_k), (X²_k,X⁴⁰⁰²_k), ..., (X²⁰⁰⁰_k,X⁶⁰⁰⁰_k)} for the second.
 

• Insert time step to use : insert the time step when the data must be used. By default the window reports the latest time step available for the data
• Insert number of columns : the system requires to know the length of the lines in the lattice. For example, if the number of columns is 40, then the 41st series is considered to be the first value of the second line.
• Lattice width : width of the lattice plot, expressed in screen pixels
• Lattice height : heigth of the lattice plot, expressed in screen pixels

Lsd uses gnuplot automatically to create the XY graphs (see plot for further details). It is a three steps procedure:

1. create a data file and a command file with the data to use and the gnuplot commands for the desired graph; these files are located in a subdirectory of the model's own directory named plotxy_n, where n is the graph number reported in the Graph listbox.
2. execute gnuplot's commands resulting in graph with a format suitable to be imported in Tcl/Tk, the graphical language used by Lsd.
3. create a standard Lsd windows for a graph importing the gnuplot generated graph.

Users may customize the gnuplot graphs by acting directly on the commands to gnuplot. To do this use the following steps:

1. Create a graph using the desired series with the XY Plot option on. This will store the data for the graph in the file 'data.gp' located in a directory called plotxy_N, where N is the plot number, descending from the model directory. See the Model Info in LMM to know the model directory. The file gnuplot.gp will contain the gnuplot commands.
2. Close the window containing the generated plot.
3. Open with an editor (e.g. LMM itself) the file gnuplot.gp.
4. Edit and save the file gnuplot.gp. For example, add a line stating set nokey and save.
5. Double-click on the item in Graphs corresponding on the deleted graph,

Note that the graphs exported from gnuplot to Tk tend to be pretty large. Before loading them Lsd scans these files (reaching even tens of Mb's) and removes the duplications, leaving manageable files of few tens of Kb's.

Grids
This option set on causes the graphs to be plotted with a grid dividing the space in sections of 25% each, both on the vertical and horizontal dimension.

Selection of Cases for "Cross Section" Analysis
When the option "Cross Section" is checked on (but in the case of XY plots), this function allows to decide the cases, i.e. the time steps, to consider as single series. It applies both for plots (where one line indicates a time step over all the Variables selected) or for statistics, taken over the Variables selected at a given time.
The window below asks users the list of cases to be considered, to be typed and added to a list, and then the sorting.

The leftmost section of the window contains the entry where to type the cases to use. Below the entry there is the list of cases already selected.

The central part contains four buttons:

• Add: include the typed case in the list of time steps selected. It is equivalent to pressing the key Enter.
• Delete: remove from the list of time steps the elements currently highlighted
• Continue: end the insertion of cases and continue the operation of plotting, or making statistics on, the cases selected (short cut: c).
• Abort: abort the operation, returning to the main Anlysis of Result window

• Sorting Ascending: the Variables will appear according to their increasing values at the time highlighted in the list of Time Steps selected when the button is pressed. That is, the Variable with the lowest value at the time indicated will appear on the left of the graph, while the Variable with the highest value at the same time step will appear on the right of the graph.
• Sorting Descending: the Variables will appear according to their decreasing values at the time highlighted in the list of Time Steps selected when the button is pressed. That is, the Variable with the highest value at the time indicated will appear on the left of the graph, while the Variable with the lowest value at the same time step will appear on the right of the graph.
• No sort: the order of the Variables will be the same used in the list of Vars. to Plot.

In case you want to insert a sequence of times, to generate many series, there are several shortcuts:

• Control-f (for from). The value indicated will be used as the first time step to insert.
• Control-t (for to). The value indicated will be used as the last time step to insert.
• Control-x . The value indicated will be used as step of the series. For example, starting from 2 and setting step 3 you will insert 2-5-8-11-14 etc, until the value indicated for final time.
• Control-z . Insert the series as defined. If no step value have been indicated it will use step 1.
  

• Lsd Result Files: file contains data that can be loaded in a new session of Analysis of Result in Lsd
• Text Files: file contains data in a generalized format

Labels to use
The option "Original" leaves the same series name as in the Lsd model, attaching a progressive number to distinguish between different instances of the same series. This options can cause problems when Variables have long names and the packages meant to be used for the data treatment accepts only few characters (e.g. SPSS and Statistica use only up to 8 characters for variables names). The option New Names allows users to assign a name that replaces the original name of the variable, and the system assigns a progressive number to distinguish between the different variables. For example, if the new name assigned is "Col", the series will be indicated by Col1, Col2 etc.
Users can add a '#' symbol before the first line indicating the Variable's labels. This is the standard for files accepted by gnuplot which ignores the columns' headers.

Columns delimiter 
Three options are available. The default is the standard Tab delimited file, where the column are separated by the tab character (accepted by most packages). The second option allows users to specify their own delimiter for columns (e.g. semicolon, spaces etc.). The last option allows users to create fixed length columns. This means that each column will contain exactly the spaces indicated. For variables labels (first line) the possible extra spaces are filled with spaces, while for the values are filled trailing decimal zeros.
 
 

General Options 
Lastly, users can decide whether to have variables labels in the first row of the file (some packages don't accept data mixed with labels). In case there are missing data, users can specify the code for missing values.
  

• average;
• variance;
• minimum
• maximum
• standard deviation

The header indicates the number of cases considered in all. But, if the Variable lasted only few time steps, the statistics are computed only over the actual time steps it lasted. These are indicated in between parenthesis after the name and code of the Variable. In the example the first line concern a Variable lasting for all the 400 cases. Instead, the second and third Variable have lasted for 349 and 26 cases respectively.

For cross section statistics, each line refers to a time step and reports the statistics over the Variables considered. Again, the computation consider only the periods of existence for the Variables:

Cross Section Descriptive Stats.
3 Variables          Average Var. Min  Max Sigma
Case 50 (1)               8   0      8   8     0
Case 100 (2)             60 169     47  73    18.3848
Case 370 (3)          7.667 10422.2  1 251   125.033

In the example above the statistics requested concern three Variables and three time steps, 50, 100 and 370. In between parenthesis is reported how many Variables existed in each case (1, 2 and 3).

For plotting graphs the results depend also on the option Sequence / XY Plot (see here). See help on plot for further details.

• In case of Time Series the X axis will be occupied by the values of the very first entry in the list of the Series Selected. and the graph will consider as separate data sets any other series. For example, suppose there are three series in the Series Selected list, X¹, X², and X³ The graph will contain two lines (or groups of points) at the coordinates (X¹_t,X²_t) and (X¹_t,X³_t), for each time step t included in the user's selection of cases.

• In case of Cross Section, the user will be asked to specify one single time step and how many series will give the values for the X axis. It is necessary that the number of series chosen for the X axis is an exact divisor of the rest of the series. For example, if the Series Selected list contains 6000 series, the user can choose 1000, 2000 or 3000 as "block length". If 2000 is chosen (and k is the time step chosen) the system considers the values from the first 2000 series as values defining the X axis, and two other data sets (from the 2001 to 4000, and from 4001 to 6000) that will provide the Y values to plot. The graph will therefore contain two lines defined by the 2000 points with coordinates {(X¹_k,X²⁰⁰¹_k), (X²_k,X²⁰⁰²_k), ..., (X²⁰⁰⁰_k,X⁴⁰⁰⁰_k)} for the first series and  {(X¹_k,X⁴⁰⁰¹_k), (X²_k,X⁴⁰⁰²_k), ..., (X²⁰⁰⁰_k,X⁶⁰⁰⁰_k)} for the second.

• Include graph labels: include in the file the labels for the series.
• Color or Gray: produces a color or gray shades postcript file
• Landscape or Portrai: produces a horizontal- or vertical-riented postscript file
• Dimension: allows users to define the width (in millimeters) of the picture in the postcript file
• filename: choose the file name for the picture
• Choose file: allows users to modify the name of the file and its directory

The example above is a (time series) plot where the series have been selected as the only Objects surviving at a given time (using the option Sort (end) ), with colors and no grids.
These windows are sensitive to the mouse passing over them: the bottom part of the window prints the series over which the mouse is positioned (InstallBase 1_5 in the example), the X value (Case num: 208) and the Y value (Y value: 310.3831). This sensitivity permits to read a graph containing very many series, even when using the no color option.

Graphs can be improved adding new labels and modifying existing ones:

• Click and drag one of the existing label moves them around the graphs;
• Click the right button of the mouse over one label to edit its text, dimension,  font and color.
• Press the Shift key and Click to create a new label;

Frequently a user produces quite many graphs, and the screen becomes easily crowded of graphs. To move easibly among the graph windows the user can exploit two features:

• double-clicking on the label of one graph the listbox Graphs in main Analysis of Result control window brings that graph in the foreground.
• double-clicking on a graphs window brings the main Analysis of Result control windows in the foreground.

• Analysis of Results - Help. Show this help page
• Model Report show the model report, containing model structure. See the help on the model report.
• Model Help show the model help, containing the modeller's comment on the model. See the help on the model help.

• Select all the series: select all the series with the chosen label.
• Select for series' tags: series are associated with tags containing as many numbers as the hierachy of objects containing them. In the example, the variable HerfEval is located in an object in the third hierarchical level, and therefore you need two digits to indicate the exact copy of the object containing it: one for the second layer and one for the third layer (the first layer is Root which is present with only one copy). Choosing this criterion, the user can place one value in one of the cells (only one) and the system will select all the series respecting the condition in respect of the indicated number in the tag's position indicated by the cell.
• Select for values of another series: it is possible to select the series in respect of the values that another series in the same object takes at a given time step. The user needs to indicate the label of the other series, the time step to be used, and the value to be used for comparison. The condition indicates the criterion by which to compare the value of the selecting series.
  

1. Generate the graph with the default options.
2. Close the newly generated window with the graph.
3. Opening the file gnuplot.gp with any text editor (for example, with LMM), considering that the directory containing it is called plotxy_N where N is the number of graph.
4. Edit the gnuplot.gp file
5. Double-click on the name of the graph in the Graph listbox in the main Analysis of Result window of Lsd.

• set xlabel : determines the label for the X axis. The same command works for the ylabel and zlabel.
• set dgrid3d 30,30,4 : this command determines the definition of the graph. The first two values (30,30 by default) indicate the number of segments used on the X and Y axis. The higher this number the more precise is the graph (and the heavier is the memory requirements). The third value (4 by default) indicates the approximation for the Z values. The higher the closer.
• set pm3d : draws a surface connecting the points of the series. This is set by default. Removing this line you generate a graph made only of lines or dots (as indicated in the option Lines/Points in the main Analysis of Results window. For example, using the Lines option you would obtain:

• set palette gray or  set palette color : generate the surface in gray shades or colors (only if the option set pm3d is present).
  
• set grid :  uses a grid for the plane X-Y

• splot: is the command for a 3D graph
• 'data.gp': is the data file
• using 1:2:3 : is the command sayng that the surface must use the data in columns 1 and 2 for the independent variables, and 3 for the dependent variable.
• with lines : indicates to use lines to connect the points. Alternatievely, one can be points, or pm3d for the surface only (but, in the case, you need the option set pm3d).
  
• t "my tytle" : indicates the title for the series. To omit the title set t ""