Modelling overview - quickstart
In this document we provide a high-level overview of the modelling and simulation interfaces.
Exploring existing models
The primary interface for exploring LimbNET's model database is the models listing, which can be opened by clicking models in the left-hand navigation menu.
All models that are available in LimbNET can be browsed here:
- all models belonging to the current user,
- any models from any other user that are shared (public).
Let's say that we would like to find an existing demo model to investigate. If we already know the name, we can immediately search for the model using the "filter by name" field.
However, if we are just browsing the model listing we can also use other functionality to narrow down our search. For example, if we wanted to find models corresponding to publications (which the creators have tagged as such) we could use the "filter tags" dropdown, selecting "publication" to show all available models that have been tagged with the "publication" tag:
Here we can see all models that have been tagged as related to a publication. To find out a bit more about the models, we can click the small arrow on the left of any model, to expand that row and show the user-provided description for that model:
In the same way, we can find models that have specifically been designated as demos of LimbNET's functionality. Let's find an interesting demo model to further explore the modelling interface: untick "publication" from the filter tags dropdown, and select "demo". A new list of models will appear that we can explore further.
Simulate an existing model
We will take a look at the so-called "Gray-Scott" reaction-diffusion model, since it exhibits a number of interesting behaviours - including spontaneous Turing-like patterning - under a relatively small number of parameters and variables.
In the models listing, find the model called "Demo: Gray-Scott (basic)", and on the right of the row click on the sim button to directly open the simulation view. If you can't find the model directly, type "gray scott" into the filter by name field to restrict the visible models to what we are interested in. Upon opening the simulation view, you will see the following:
Run a simulation
There are a number of new interface elements to take into account; for the time being, and in order to have some data that we can play with, let's click on the green "simulate" button (in the top right) directly. This will start a simulation of the open model on the server, and stream the results back to our open client view. Upon clicking the button, and starting the simulation, a green progress bar will appear, updated regularly with the status of the simulation:
Once the simulation is complete, the progress bar will disappear, and we can view the results of the simulation.
View simulation results
How can we view the simulation results? First we need to select the variable that we are interested in plotting. The visualisation consists of (up to) three different configurable colour channels, red, green and blue, and for any given channel we can select one variable from the model.
Select the variable "u" in the red channel; the visualisation will update to show the selected variable at the initial time point. Since we are looking at the first time point we will see the initial conditions (the starting pattern) for the variable "u"; in this case, some dark spots in a red background.
Now, let's see how the pattern develops over time. At the bottom of the simulation view are the time controls; you can use these to skip to any point in the simulation, play an animation of the simulation, or step through it, or scroll through the pattern in real time:
Adjust parameters in the simulation view
It is clear that starting from the initial spotty pattern, the system quickly and dynamically evolves to form a network of stripes.
What other patterns can be formed by this system?
Open the parameters dialog by clicking the "parameters" button in the simulation view, and change the value of the parameter k to 0.057:
After changing the value of k, close the Parameters dialog and run the simulation again by clicking on the green "Simulate" button in the top right. We will again have to wait a short moment for the results to be streamed back to the client interface.
Once the simulation is complete, explore the results over time again, using the time slider. Observe what happens to the "u" variable this time - instead of forming a network of stripes, it forms an array of spots that move around over time, and eventually self-organise within the 2D space.
Tip
The parameter dialog in the simulation view is a quick and easy way to play around with model parameters - and their perturbations - and observe how the model predictions change as a result. Remember, parameter changes made here will not be saved to the stored model specification.
Visualise multiple variables
So far we covered the behaviour of a single variable in our model, "u". We can also select any other variable that is present in the model specification and has been simulated. For example, click on the "red" channel dropdown and change the selection from "u" to "v"; you will see that the "v" variable is mostly out-of-phase with "u", with "holes" where "u" forms spots.
If we want to see both variables at the same time, it's as simple as selecting the desired variable in another colour channel. For example, with "v" selected in the red channel, select "u" in the green channel. You will now see both variables plotted over the mesh simultaneously, while still manipulating the time controls as before:
View an existing model in the editor
We have seen the output of simulating a model - dynamically evolving spatiotemporal patterns - however, if we want to delve into a model's implementation we will need to open the editor.
If you are already in the simulation view, you can open the editor by clicking on the "editor" button. If you are not in the simulation view, follow the steps in exploring existing models above, and when you have found the model named "Demo: Gray-Scott (basic)", click it's corresponding "editor" button in the models listing.
Upon opening the editor, you will see the following:
Note the statement at the top - since the model belongs to another user (even though it is public) - you cannot edit it directly as it stands.
However, it is possible to see all the details of the model, including the underlying equations. Scroll down, to the "Mesenchyme" section, and inside to the "Reactions (mesenchyme)", where you will see both of the variables we have looked at earlier - "u" and "v" - and their corresponding equations. For reference, the equations - typeset in mathematical notation - would normally look as follows:
The parameters "F" and "k" are defined in the "Parameters" section of the model editor, above, along with their numerical values.
Copy and modify an existing model
Let's see how we can take an existing model, and modify it.
In the model editor, you will see there is a button at the top labelled "save as". This will create a copy of the open model, owned by you. Click the button, and a dialog will pop up asking that you enter a name for your version of the model. Enter a name that is meaningful to you, and click "OK"; this will save a fresh copy of the model in its current state - owned by you - and will open it in the editor. Now you are free to edit any part of the model - the equations, variables and parameters.
To get a taste of how this might work, let's add some noise to the variable "u", in order to see how robust the pattern is in the presence of some temporal perturbation...
Scroll down once again to the model equations ("Reactions (mesenchyme)" section in the editor).
In the "noise" field for the variable "u", enter 0.01 * u.
What does this mean?
This function will add Gaussian noise (i.e., a perturbation that will follow a normal distribution) with a variance of 0.01 to the variable "u", scaled according to the magnitude of "u".
So, as the value of "u" increases, so the size of the noise will increase, and conversely as "u" decreases the noise magnitude will be smaller.
This is a common way of modelling general biological noise.
Click "simulation" in the top right, followed by "save and simulate", which will apply our new changes to the model specification and open the simulation view. Click the green "simulate" button in the top right, and wait for the model to be built and simulated, and for the results to be downloaded.
We can visualise "u" as before, by clicking on one of the colour channel dropdown menus and selecting the variable there. And, finally, we can scroll through the behaviour of "u" over time and see that indeed it changes now that some perturbation has been applied.
What happens as we change the size of the perturbation?
One way to find out would be to go back to the model editor and change the value 0.01 in the noise field to some other number.
However, as we have already seen, we can change parameters directly from the simulation view.
It is not yet possible to do this for our noise.
Why?
We have not yet defined a parameter!
Go back to the model editor, scroll up to the section "Parameters" where you will see the existing parameters "k" and "F".
Click on the green "new parameter" button, and an empty row will appear below the existing parameters.
Enter some name for the new parameter - for example noise_mag, standing for noise magnitude - and a value, for example 0.01 as before.
Now scroll down again to the reaction for the variable "u", and change the "noise" expression to noise_mag * u.
We have replaced a hard-coded value with a parameter that we can freely change.
Save the model, or as before click "simulate" and "save and simulate", and you will see that the noise magnitude can now be adjusted directly from the simulation view.
Create a new model from scratch
Now that we have gone through the core elements of LimbNET's modelling functionality, you're ready to make your own models. Why not take a look at the tutorials section for a walkthrough of the model creation process, or for more in-depth information on models, the model development user guide.