Parasim GUI Tutorial
This page describes how to create a parasim project and perform some basic analysis. It does not include creating properties -- signal temporal logic formulae (see Experiment File Format for their definition) or creating model in SBML.
For the purposes of this tutorial we will re-analyse SIR model (included in experiments). We will need:
Execute parasim (for example using parasim-gui.sh script). Two windows should appear:
- reduced project manager window (left) -- only toolbar and menu
- logger window (right) -- this one is unimportant right now
Open "new project" dialog either clicking on "new" button (with document icon), using menu ("Project -> New") or pressing "CTRL+N".
In the upper file chooser dialog enter the parasim experiments folder. Then enter "SIR" folder, change file filter to "XML files" and choose the file sir.model.xml. Create a new empty folder and select it in the lower file chooser. Click "OK". After a moment, an empty project should open in the project manager window.
To perform an analysis, it is necessary to import properties and create configurations
First, let us import some properties. Click on the "Import" button in the "Properties" panel (upper right corner of project manager window). The following dialog should appear:
Enter parasim experiments folder, the "SIR" folder and choose outbreak5.formula.xml. Rename it to "outbreak5" in the text area at the bottom of dialog (you may rename it anytime in the "Properties" panel) and click "OK".
Repeat this process with outbreakM50.formula.xml (rename it to "outbreakM50").
The "Properties" panel should now contain two properties.
When you hover over them, you may find out, what they mean (note, 5 is itial value of infected).
| Property | Formula | Explanation |
|---|---|---|
| outbreak5 | F[1,5](I>5) |
sometime between 1 s and 5 s there are more than 5 infected |
| outbreakM50 | F[1,5](I>50) |
sometime between 1 s and 5 s there are more than 50 infected |
Select the first property and click "Use". It should appear in the "Experiment" panel (upper left corner of project manager window). If it does not, we will correct it later.
Next, let us have a look at the "Simulation" panel (lower left corner of the project manager window).
The default values seem to be pretty decent. Simulation Start should generally be 0 and 100 s (1E2) for Simulation End should be ok too (note: the actual simulation length depends on used property). We do not know much about the model, so leave Time Step and **Maximal relative error" at 0.1 (1E-1). Should you need to simulate the model more precisely, you may change them later. The same goes for Abs error (maximum absolute error).
Now, as for Minimum and Maximum bounds for each model variable (S, I, R), we note that there are 100 individuals in the model as a whole, none die and none are born. Therefore, the minima should be 0 and maxima 100.
Click on "Save" button in the "Simulation" panel and choose a name for this configuration. Then click on "Use" button. This configuration should appear in the "Experiment" panel.
"Perturbation" panel is in the lower right corner of project manager window. It contains information on all model variables and parameters and is used to set perturbation interval for each of them.
Now, the most interesting analysis is what happens when we change "infectivity" and "recovery" parameters. Therefore, click on the checkboxes adjacent to these parameters. At the top of the panel, four input boxes should appear. Select some appropriate values for perturbation intervals (around default values), for example [0.001,0.05] for infectivity and [0.01,0.5] for recovery.
Save this configuration under the name the same way as simulation configuration and click "Use" for it to appear in the "Experiment" panel.
The only thing left necessary to launch an analysis is an experiment configuration. See the "Experiment" panel (upper left corner of project manager window).
The fields Property, Simulation configuration and Perturbation configuration should already contain values. If not, use drop-downs to choose these. Now, we have to add two settings:
- Timeout -- when analysis exceeds this time, it aborts. Two minutes should be more than enough for this model.
- Iteration limit -- This field relates to analysis precision. Five is generally a good value.
Now, save the experiment using "Save" button in the "Experiment" panel. It is ready to be launched.
Launch Experiment button in the toolbar should be available. Click it. A dialog should ask you whether you want to save the project (which we haven't saved since). It is generally a good idea to save your projects before launching an analysis. During analysis, parasim may communicate with external programs which may cause it to fall.
Messages now should appear in the logger window.
When an analysis is running, the logger window writes what happens and keeps track of how long it has been running. You may assume that as long as the timer keeps incrementing, the analysis is running. You may not understand most of the messages appearing in the window, but they may help you track the analysis progress.
When the analysis finishes, a plotter window should appear.
There is an area which displays points in the perturbation space. The analysed property is valid in green points and invalid in red points. It also displays global robustness value (top of the plotter window).
When the plotter window shows after the analysis terminates, it generally shows only one point. For better view of the results, use two drop-downs at the bottom of the window. You want them to select some of the variables or parameters you have perturbed. In this case, these are "infectivity" and "recovery".
When you click a point in the graph, a simulation from this point should appear in a new window.
This might have been the place to finish the tutorial. However, let us suppose we want to analyse the property "outbreakM50" as well. You might change the property the just-analysed experiment and analyse it anew. However, sometimes it might be better to keep older experiments.
To create a new experiment, click the "New" button in the "Experiment" panel. Drop-down list above it should now display no name. However, values of various fields of "Experiment" panel have not changed. Now, change the value of "Property" field to "outbreakM50" and save this experiment.
You may return to older experiments whenever you like using the drop-down in "Experiment" panel. It is also possible to have multiple perturbation and simulation configuration. You can manage these in the same way as experiments.
Project are opened using the open dialog. You may access it by the "Open" button in the toolbar (the one with folder icon), via menu ("Project -> Open") or by pressing "CTRL+O".
To open a project, you have to select its folder in the file chooser.