Modelling Tutorial 1
The goal of this page is to provide a modelling tutorial to get you up to speed with our computational modelling approaches as fast as possible. These are work in progress.
Last updated
Was this helpful?
The goal of this page is to provide a modelling tutorial to get you up to speed with our computational modelling approaches as fast as possible. These are work in progress.
Last updated
Was this helpful?
The first thing we will do is run a toy model. The model represents this basic system. This contains 3 biomolecular "species". These can be thought of as 3 proteins named A, B and C. There are 4 biochemical "reactions". Each arrow is one reaction.
Note that every species has an arrow going into it and an arrow coming out of it. This is almost always true of models because otherwise the protein will increase its concentration forever, or decrease to nothing.
Login with your username and password.
Login with your username and password
Click on toy model.ipynb to open the main interactive notebook where you will be doing your coding.
First we'll simply run the toy model, get a graph, and then we'll figure out what we've done!
Once the first cell has run you can hit shift+enter repeatedly to run all cells in entire sheet. This will be very slow the first time as it needs to install a bunch of packaged.
The next bit of code looks complicated! But remember we can ignore any lines with a # at the start!
You will actually never need to change most of this block of text but we'll briefly go through what it does. The first line puts all of our file names together into a list that is called "arguments". You will never need to change this. If you want to change the file names of the model that's created you would change that in the first block of code where it says "thisModelName=toyModel.jl"
The final two lines that start with include(... simply bring the new model that has been created into Julia so you can run it.
Next comes the key bit of code where the simulation actually happens
The first line defines the starting concentrations for each of the biomolecular components. So we start with 1nM of A, 0nM of B and 0nM of C. We call these initial conditions y0.
The second line tell Julia that the toyModel is an "ODEFunction". This means that Julia knows to treat it as a model that we can simulate and means we can now refer to it as simply "f", for function, rather than "toyModel". The third line creates an "ODEProblem". A "problem" in maths isn't a problem at all, it's a challenge. Here we are challenging the computer to solve our function "f", using the initial conditions "y0" from time 0 to time "maxTimeTC". Remember we defined "maxTimeTC" as 60 above (or 240 if we are simulating 4 hours). So you can read this line as "I am challenging you to simulate this system, starting with the concentrations [1,0,0] for 60 minutes. The final line is where the simulation actually happens. "Go and fetch me a solution to this problem". This line tells the computer to save the solution with the name "sol". The "solution" is a prediciton of what the time course will look like. We won't wory about abstol, reltol and saveat for now, you are not likely to change these.
This section is challenging. To edit models you need to understand how they're created. Take your time with this section and ask Simon when you get stuck.
A model is a "system of equations". "system" because there will be many equations: one for each biomolecule "equations" because there is an equals sign in the maths.
Here is an example equation that makes the model. We'll first show the maths and then talk about what that looks like as computer code.
Take a look at toyModel.jl on the server and you'll see the file contains this text.
So with the above information, we could just go from the picture of the model, and write computer code and solve it. Indeed, many people do that. But, you could make a typo, or create a model that isn't biologically realistic. For example what if you have A going down because it is turning into B, but forget to have B going up by the same amount? If you just wrote the code it would be easy to make mistakes like this. To avoid this, and to automatically have nice tables of paramters and reactions, we instead define our models in three CSV files, which we will introduce now.
csv2model will combine these files automatically to create a model you can run, but it's worth knowing what it's doing. Below explains what csv2model will do when it is run.
CSV files = Comma Separated Value files. These are basically Excel tables, and can be opened and edited in Excel.
Modifiers is empty because everything in our diagram is either a product or a substrate (at the start or the end of an arrow). If we had biomolecules in our diagram that changes the rate at which an arrow proceeded, without actually being changed by that reactions, we would call that a modifier.
This file also specifies which kinetic law/rate law to use for each reaction. You probably are not familiar with the concept of a rate law or a kinetic law, unless you have som modelling training (why are you here!?). You may have heard of Michaelis–Menten kinetics, or even mass action kinetics. These are the main rate laws/kinetic laws we will use.
A "rate law" or "kinetic law" is just a peice of maths that defines how fast something will happen. The most simple is "mass action kinetics". Mass Action kinetics are usually used for binding. The rate law most people know is Michaelis-Menten kinetics, which is usually used for enzyme-mediated reactions. We'll talk about rate laws in the next file. For now, all you need to know is that this refers to some maths and tells the code which maths to use for each arrow.
The final information in this file is "parameters". These are numbers, like 7 or 42, but here we give them names. In the above examples we said k1_Aexp = 1 so here we are telling the computer which number to use (by name), and in the parameters.csv file we'll give each parameter a numerical value.
and then look up each parameters in the above excel table, hopefully you can see how we get the below equation:
So now we have a file that define the arrows (reactions.csv), and a file that defines the numbers (paramters.csv). All we need now is a file that defines how to combine the numbers mathematically and that's where our third and final file comes in.
If you look at the reactions file you'll see that the first reaction has no substrate, Aas a product, and uses the "Constant Exp" kinetic law, with "k1_Aexp" as the paramter. When building the model, the computer will look up the "Constant Exp" rate law and put whatever code is provided in the Rate Law Definition into the equation for A. In this case the code is just: {k1}.
The curly brackets "{ }" mean that a parameter should be substituted in. The text inside the curly brackets tells the computer which parameter to substitute in. So {k1} tells the computer to substitute in the first paramter in the reactions file parameters column. In this case this is the first and only paramters in reactions file paramters colummn for this reaction: k1_Aexp. We also know from above that k1_Aexp = 1 in the parameters file (paramters.csv).
Where there are square brackets "[]" this means that a biomolecule should be sustituted in. S1 means the first substrate, M1 would mean the first modifier (but let's not worry about modifiers for now!).
You can see from the "Mass Action with Substrate" rate law that [S1] * {k1} means the first substrate is multiplied by the first parameter.
Remember the files are combined automatically by CSV2Model. Here we explain how that works but you will never need to do this manually. You will only ever edit the CSV files. You will then always run CSV2Model and tell it where the CSVfiles are and it will automatically create the model for you.
csv2model will repeat this process automatically for every part of your reactions file. So now we know how it all works let's try and make changes to the model
. Please download all the files by hitting the green Code button and then Download ZIP. Extract the zip somewhere on your PC.
Now, we will need to upload the toy model files to the server where we will actually run the model. Full information on connecting to our servers , but we will go over the basics you need again here.
Head to this URL in a web browser.
Create a new folder
Rename it Toy Model
Open the Toy Model folder, it will be emty. Drag and drop all the files from the Toy Model folder that you extracted onto your computer into this empty folder.
Hit upload on each of these files.
First you'll want to click on the first cell in the sheet so it is selected, it will look like this
Then you'll want to hit shift and enter on your keyboard, which is the same as choosing Cell > Run Cells from the menu.
When you do that the on the left of the cell will turn briefly from: to: and the dot in the top left will briefly turn from: to: Both of these are signs that the code in a cell is running, and when the cell has finished running it will turn back. This might be less than a second for a small cell or hours for complicated models!
If successful you should see the final cell returns a graph!
We'll go through each block of code and figure out what we did and what it all means. Starting at the top the first block of code looks like this:
The first three lines tell the programming language we're using (Julia), where the files are that define the model. A model consists of reactions, rateLaws and parameters. Each of these is a CSV file and the first three lines tell the computer where those files are and what they are called. These files are combined by a programme called csv2model to create the actual model.
The fourth line tell the code where csv2model is on the computer.
The fifth line tells csv2model what you want the model it creates to be called.
The final line tell Julia how long you want to run the model for. Here we simulate 60 virtual minutes. This isn't how long the code takes to run, it will finish in seconds, but it will simulate 60 virtual minutes.
The next block of code looks like this: This will download and install any packages we need into Julia. We need packages that help us run models, make plots, load files, and do statistics. You only need to run this once, not every time you run the model. So when it has finished running the first time you can remove this code. The easiest way to remove code is to turn it into what is called a "code comment". "Code comments" are bits of text that the comupter ignores and programmers use to write notes to themselves. In Julia any line that starts with a # sign is totally ignored by the computer. So select all the code in this block: and then press Ctrl + / (windows) or command + / (mac) to add a # sign before every line. Now if you select this block of code and you press shift + enter to run it, nothing happens. Try it!
The next block of code tells Julia we want to use all the packages we installed above: When you run this block the first time it will load some packages (quite slowly), but the next time you run it it will be very quick because they are already loaded.
The two lines that start cmd=... and run(cmd) are telling CSV2Model to create the model using the three CSV files we defined above. This will create "toyModel.jl" automatically. We'll talk about how that happens in .
Finally: no prizes for guessing what this does!
This graph looks a bit crap. This is caused by us only saving the simulation every 1 minute. If you remove the "saveat" part of the solve line you'll get a really smooth graph!
If k1_Aexp = 1, if k1_AtoB = 2, then If you substitute 1 where k1_Aexp is and 2 where k1_AtoB is, then as Julia code the above equation looks like this:
Note that dy[1] simply means the rate of change of the first molecular species, in this case that means the rate of change of A. dy[2] would be the rate of change of B etc.
Reactions.csv This file can be throught of as defining the diagram/picture of the model. Each arrow or interaction in the diagram will create a line in this file. All you need to create a reactions file is the diagram above. Here is the toy model reactions.csv file opened in Excel: This file has 4 lines, and if you scroll up to the top of this document you'll notice the Toy Model diagram has 4 arrows. Each line of this file encodes one arrow on the diagram. Every reaction has a substrate and a product. If A turns into B then the substrate is A and the product is B (see line 3 in the image above). You'll notice line 2 doesn't have a substrate, this is because A is being created out of nothing in the diagram. You'll also notice that C doesn't have a product, this is because C degrades into nothing.
Parameters.csv
This file is use to look up the numerical values that each parameter has. So this is where we define that k1_Aexp = 1 and k1_AtoB = 2. If we open the parameters file in Excel we see this:
This tells the computer the value of each parameter. They're not usually nice round numbers but for the sake of the toy model we'll keep them simple!
If you look at the equation we gave above:
RateLaws.csv You'll notice there were only 2 kinetic laws used in the reactions.csv file. These correspond to the two lines in the RateLaws.csv file. Every rate law mentioned in the reactions file, has to have a line in the rate laws file with exactly the same name. The spelling, including capital letters and even spaces must be identical (computers are dumb). There are only two columns in the rate laws file: the rate law name (which must match the name usef in the reactions file), and the rate law definition. The rate law definition is actually computer code and uses very specific notation. You'll notice there are lots of brackets flying around!
Reaction 1
So putting everything together. Reaction 1 in reactions.csv is A being created from nothing, with the rate law "Constant Exp" and the parameterk1_Aexp. CSV2Model will look up k1_Aexp = 1, from the parameters file. This will result in adding "+1" to the equation for A because this reactions makes A go up. This explains how the first arrow in this diagram:
This arrow is represented by this line of the reactions file: which looks up this rate law: and this parameter: to create the first part of this equation and turn it into this Julia code: Phew! Reaction 2 This reaction is very similar but includes a substrate and uses a different rate law.
Reaction 2 is A turning into B, with the kinetic law "Mass Action with substrate" and the parameter k1_AtoB.
This arrow is represented by this line in the reactions file:
which looks up this rate law:
It looks up the first substrate in the reaction, which is A. And looks up this parameter value:
to create the second part of the equation for A:
There is a minus sign at the front because the arrow makes A go down.
Thie turns into this code:
Both reaction 1 and reaction 2 affect A, one going up and one going down, so all together the code for the rate of change of A becomes:
Click on parameters.csv to edit the file. Change k1_Aexp from 1 to 0.1 (10 times lower). Save the changes with File Save. Then shift and enter through the entire sheet the plot should go from this: to this:
Then shift click through the file to change the graph from: to:
We need to add a new reaction for every new arrow (there is one new arrow) and we need to change the substrate for c->, which previously had no substrate but now has D as a substrate. So the reaction file goes from this: to this: Save this and reupload it (you can drag and drop or hit upload). Make sure to overwrite the existing reactions file. You'll also need to add this new parameter, I chose the value 2 but you can choose anything: Upload this changed file too. Now we'll need to add an initial condition for D: and shift + enter through the entire sheet to get this graph:
