Difference between revisions of "Team:TU-Eindhoven/Software"

Line 34: Line 34:
 
<br/><br/><br/><br/><br/><br/><br/><br/>
 
<br/><br/><br/><br/><br/><br/><br/><br/>
 
</body>
 
</body>
−
<h6>As already mentioned, traditional stochastic or ODE-solver simulation methods require every possible reaction to be defined, with all possible molecular states being named. The valences of the constructs that we are interested in, have the chance to form a very complex and connected network. It would be impossible to define this network beforehand. Since more systems are too complex to simulate with the traditional stochastic or ODE-solver simulation methods, researchers have begun to develop another modeling language, for example the BioNetGen Language (BNGL). The main advantage of BNGL is that the specification of reaction rules is required, but not the specification of all reactions. To make this possible, the molecules need to be specified in another way, namely with the different components and states that it can be in. The components can form a bond with components of another molecule and the states can change, which may be required for binding with another molecule. In short, rule-based-modelling requires the definition of rules, and the computer will figure out the rest.<sup>[1]</sup></h6>
+
<h2>NFsim manual for dummies</h2>
 +
 
 +
<h6>NFsim is useful if you want to simulate a system with many interacting molecules in different states and/or molecules with many interacting sites where a bond can be formed. For an in depth explanation about how NFsim works, we refer to the first chapter of the NFsim manual provided by Yale University, which can be found here: http://emonet.biology.yale.edu/sites/default/files/files/NFsim_manual_v1_11.pdf
 +
</h6>
 
<br/>
 
<br/>
  
−
<h6>The BNGL can be applied using a Network-Free Stochastic Simulator (NFsim). NFsim is especially useful for the simulation of systems with large reaction networks and a high degree of combinatorial complexity.It keeps track of the state of the system that actually exists and does not consider every possible configuration.<sup>[1]</sup></h6><br/>
+
<h6>The second chapter “Getting Started” shows different steps which will guide you to install the required software. It is, however, more focused on Mac and Linux, we will therefore provide additional information for windows users.Furthermore, there are also some links in the manuals that are expired, so we will also be providing working links in this tool.
 +
</h6>
 +
<br/>
  
−
<h2>Defining the rules</h2>
+
<h6>The first step is to download the NFsim zip file, which can be found on this page (instead of the provided site in the manual):
−
<h6>After installing NFsim on Windows (with the addition of Active Perl), Mac, or Linux using the NFsim Manual, we made a BNGL file with rules matching to our designed system. We started with defining the <i>parameters</i>, which include the association and dissociation rates of the defined parts. The next section is where we defined the <i>molecule types</i>, which means that we define the different parts/constructs. We did it as follows (visualized in <a href="#Figure_1">Figure 1</a>):
+
http://michaelsneddon.net/nfsim/download/
−
<ul>
+
In most cases, the zip file will be saved on the folder “Downloads”, which is undesired. We recommend that you place the file to another location, which can easily be found and reached. For example, we created a new folder on our D-drive (mostly used for data), and named it NFsim. We placed the zip file into this folder and there we unpacked / unzipped the file. NFsim is now located in D:NFsim\NFsim_v1/11. It is recommended to use names without spaces, or choose an underscore _ instead.
−
  <li><span>The Scaffold Constructs with its three binding pocket, where each pocket can have two different states, one where the pocket is empty and one where the inducer is bound</span></li>
+
In addition to downloading NFsim, it is required to install a Perl interpreter for Windows user. We downloaded Active Perl (name: ActivePerl-5.24.1.2402-MSWin32-x64-401627.exe) from: https://www.activestate.com/activeperl/downloads
−
  <li><span>The Binding Partner, which has one site for binding to one scaffold pocket and one site for binding to the Center Point</span></li>
+
The last download we also recommend is that of an text editor, namely Notepad ++, which can be found here:
−
  <li><span>The Center Point with four binding sites, where each site can bind to a different Binding Partner</span></li>
+
https://notepad-plus-plus.org/download/v7.5.1.html
−
  <li><span>The inducer, without any binding sites or states</span></li>
+
This was additional information for step 1 of chapter 2
−
</ul>
+
<br/>
−
<div id="Figure_1"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_1_of_model_part" /></div><br/>
+
  
−
The next step is the definition of the <i>species</i>, which means that you can define the initial amount of the already defined molecule types. It is not sufficient to only mention the molecule type, as you also need to define the state of the pockets. We choose to start with only empty pockets of the Scaffold Construct.<br/>
+
TThe next step in the manual explains how you can open a terminal / command prompt. Windows uses the name CMD. This Command Prompt can be find by going to “start” and then by typing “cmd”. After opening cmd, you should check if perl is installed correctly by typing: “perl -v”. The results are shown in Figure 1.
−
In the section of the <i>observables</i>, you define a molecule with a name and then define the molecule that you want to know the amount of. This can be in a specific state of the molecule (for example where the pockets are filled with the inducer) or more general, being the total amount of the molecule (not dependent on the state of its pockets or bonds with other molecules). It is also possible to define a bond between two molecules and count the amount of the bonds. At the end of the simulation, the output will be a .gdat file including the amount of the observables over the time-steps.<br/>
+
<br/>
−
The last section is the section where the whole simulation is based on: <i>reaction rules</i>, where you define all the possible reactions and give them a value as defined with the parameters. Our reactions rules include:
+
−
<ul>
+
−
  <li><span>The binding of one of the Center Point pockets with a Binding Partner. (four different reaction rules)</span></li>
+
−
  <li><span>The binding of an inducer to the pocket of the Scaffold Construct. (three different reaction rules)</span></li>
+
−
  <li><span>The binding of a Binding Partner with a pocket of the Scaffold Construct, of which the pocket already needs to have an inducer bound to it. (Three different reaction rules)</span></li>
+
−
  <li><span>And for each of the above also the reverse reaction, as the system is dynamic. (4 + 3 + 3 different reaction rules)</span></li>
+
−
</ul><br/>
+
  
−
The BNGL-file ends with defining the simulation (with its end-time and number of steps) that has to be executed. Additionally, by adding one extra line, you can let the program generate a xml-file, which is useful for running the simulation in another way. This gives the option to generate even more output-files. The last two lines of the BNGL-file can look like:
+
<div id="Figure_1"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
−
<ul>
+
 
−
  <li><span>simulate_nf({suffix=>nf,t_end=>…,n_steps=>…,get_final_state=>1});</span></li>
+
The next step is to check whether NFsim is also installed correctly. This is done by first changing the directory of the command prompt to the directory were NFsim is installed / unzipped. We already mentioned that we installed it on our D-drive, so the first step is to change the drive. The easiest way to do this is by typing: “D:”, which lets you go the D-drive after you use the “enter” key on your keyboard. Next, change the directory to the NFsim directory. This can be done with: “cd D:\NFsim\NFsim_v1.11” where cd stands for Change Directory and after a space you type the folders where NFsim is installed. This path can be found easily by using the windows explorer, going to the correct folder and then clicking on it. The path then changes from the one in Figure 2 to a selectable name, like “D:\NFsim\NFsim_v1.11”, which can be copied and then placed in the command prompt. The shortcut “ctrl + v” doesn’t work in the command prompt, so you will need the right mouse button and paste the text.
−
  <li><span>writeXML();</span></li>
+
<br/>
−
</ul><br/>
+
  
−
The output generated of the final state is a .species-file and shows all the molecules in their final state. This can be, in the case of a very large network, a very long name for one molecule, as there are many bonds that connect the different molecules with each other, leading to one large molecule definition.<br/>
 
−
Other output files that are generated are an additional xml-file and one file containing the data (.gdat) of the observables.<br/>
 
−
The xml-file can be used to run the simulation in another way, with additional flags. The “dump” flag is very useful if complex formation is an important result. The result of the files generated with dump can be analyzed easily with the MATLAB functions provided by NFsim. We wrote our own script to use the provided functions and extract and visualize the desired data. An example of the results is shown in <a href="#Figure_2">Figure 2</a>.
 
 
<div id="Figure_2"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 
<div id="Figure_2"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
The next step is to verify that the installation of NFsim was successful, which can be done by typing: “perl BNG2.pl -v”. If the installation is correct, the command prompt will look like the command prompt in Figure 3, after pressing the “enter” key.
 +
<br/>
 +
 +
<div id="Figure_3"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
Together with the installation of NFsim, you installed also some example models, which can be found in the folder “models”. The simple_system.bngl file is very nice as a start to see how output can be generated. We recommend that you open the bngl files with Notepad ++, as this is a very easy way to not only look at the files, but also to edit them if desired.
 +
Next to the simple_system.bngl file, we wrote a general file of our own with nice descriptions of each step and called this file: “system_example.bngl”. The description about how a bngl file is build up, can be found on our wiki page in the rule-based-model section: https://2017.igem.org/Team:TU-Eindhoven/Model/Rule_based_model
 +
<br/>
 +
 +
Link to download the bngl file
 +
(You need to save this file in the “models” folder of “NFsim_v1.11”
 +
<br/>
 +
 +
After you wrote your own bngl file, it is time to execute the file and get some results. The easiest way is to have a bngl file which has a line that states: “writeXML();” so that an XML file will be created during the first time we run the model and we can use the xml-file to run the same model again, but with different time steps.
 +
<br/>
 +
 +
The xml-file is created by typing the following line in the command prompt, as shown in Figure 4:
 +
“perl BNG2.pl -xml models/system_example.bngl”
 +
br/>
 +
 +
<div id="Figure_4"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
After generating an xml-file, you can run the model in another way, namely via a windows executable. The advantage is that you then can give additional commands, like the command “dump”. NFsim calls this a flag and they made a whole table that describes the command line arguments and their function. The table can be found on pages 38-40 of the manual.
 +
For the dump flag, we first need to make an empty folder. This can be done easily with the command “mkdir” followed by the name of the folder you want to create, for example “dumpDir_example_dump”. Furthermore, with -Steps you can redefine the number of steps, with -sim you can define the end time of the simulation and with -o, you can specify the output file of your simulation. The command line can for example look like below and in Figure 5:
 +
.\bin\NFsim_MSWin32.exe -xml system_example.xml -dump "[0:0.1:1]->dumpDir_example_dump/" -oSteps 10 -sim 1 -o “system_example_nf.gdat”
 +
<br/>
 +
 +
<div id="Figure_5"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 
</h6>
 
</h6>
 +
 +
<h2>Codes for visualization</h2>
 +
<h6>It is easy to visualize the results generated with Matlab. NFsim also provides some tools that you can use in the folder NFtools, but we will explain how you need to prepare Matlab and how you can use them. We ourselves already had Matlab 2016b installed, so the visualization may differ a bit, depending on your matlab version. There are also some functions that have changed over the time that Matlab exists, so it is possible that you will get a warning if you use another version. In most cases it isn’t a problem.
 +
<br/>
 +
 +
After opening Matlab you will end up in the home tab, shown in Figure 6. In this tab you can find an icon with the description: “Set Path”, like in Figure 7.
 +
<br/>
 +
 +
<div id="Figure_6"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
<div id="Figure_7"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
The window “Set Path” then opens and by clicking on “Add with Subfolders…” you can select the NFtools folder. This is done by first going to the driver (D-drive), followed by the NFsim folder, then NFsim_v1.11 and there you will see the folder NFtools, as in Figure 8. Select the NFtools folder, press Save and then Matlab will add the folders and their subfolders.
 +
<br/>
 +
 +
<div id="Figure_8"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
Then you need to go to the right directory for the Matlab editor. In Figure 9 you need to search for the icon visualized in Figure 10, which stands for “Browse for folder”. Then select the right path, which in this case, again is to “NFsim_v1.11”. The matlab code you can download below, can be saved in the general NFsim folder, which you can see in the editor window as depicted in Figure 9.
 +
<br/>
 +
 +
<div id="Figure_9"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
<div id="Figure_10"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
By clicking on the green arrow which says “run”, Matlab will execute the program and give output in the command window, see Figure 11, but also four figures with graphs. The first figure contains three different graphs, which are also displayed separately in the other three figures. We also gave Matlab the command to save the last three figures, so that you can easily access them again and place them on your wiki page for example. The figures generated with Matlab for the system_example file (with an end time of 10 seconds with 100 steps) are depicted in Figures 12-14.
 +
<br/>
 +
 +
<div id="Figure_11"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
<div id="Figure_12"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
<div id="Figure_13"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
<div id="Figure_14"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
 +
If you look at the legends, you see that we used different methods to generate the graphs in the figures. Which method is most useful depends on the system that is implemented in the model. Therefore, it is useful to look at the data in the workspace (Figure 15) of Matlab to see which method works the best for generating your output. In our example, the results of method 1 and method 2 are the same for the total amount of complexes and for the total amount of molecules, so therefore we choose to only depict the results of method 1 and 3 in our graphs.
 +
<br/>
 +
<div id="Figure_15"><img src="https://static.igem.org/mediawiki/2017/6/67/T--TU-Eindhoven--iGEM_general.png" width="60" height="60" alt="Figure_2_of_model_part" /></div>
 +
  
 
<br/><br/><br/>
 
<br/><br/><br/>
−
<div class="sources">
 
−
<sup>[1] </sup>Sneddon M.W., Faeder J.R. and Emonet T. <i>Efficient modeling, simulation and coarse-graining of biological complexity with NFsim. </i><b>Nature Methods</b> (2011) 8(2):177-83.</div>
 
 
</html>
 
</html>
 
{{TU-Eindhoven_footer}}
 
{{TU-Eindhoven_footer}}

Revision as of 10:32, 28 October 2017

Menu

Menu







NFsim manual for dummies

NFsim is useful if you want to simulate a system with many interacting molecules in different states and/or molecules with many interacting sites where a bond can be formed. For an in depth explanation about how NFsim works, we refer to the first chapter of the NFsim manual provided by Yale University, which can be found here: http://emonet.biology.yale.edu/sites/default/files/files/NFsim_manual_v1_11.pdf

The second chapter “Getting Started” shows different steps which will guide you to install the required software. It is, however, more focused on Mac and Linux, we will therefore provide additional information for windows users.Furthermore, there are also some links in the manuals that are expired, so we will also be providing working links in this tool.

The first step is to download the NFsim zip file, which can be found on this page (instead of the provided site in the manual): http://michaelsneddon.net/nfsim/download/ In most cases, the zip file will be saved on the folder “Downloads”, which is undesired. We recommend that you place the file to another location, which can easily be found and reached. For example, we created a new folder on our D-drive (mostly used for data), and named it NFsim. We placed the zip file into this folder and there we unpacked / unzipped the file. NFsim is now located in D:NFsim\NFsim_v1/11. It is recommended to use names without spaces, or choose an underscore _ instead. In addition to downloading NFsim, it is required to install a Perl interpreter for Windows user. We downloaded Active Perl (name: ActivePerl-5.24.1.2402-MSWin32-x64-401627.exe) from: https://www.activestate.com/activeperl/downloads The last download we also recommend is that of an text editor, namely Notepad ++, which can be found here: https://notepad-plus-plus.org/download/v7.5.1.html This was additional information for step 1 of chapter 2
TThe next step in the manual explains how you can open a terminal / command prompt. Windows uses the name CMD. This Command Prompt can be find by going to “start” and then by typing “cmd”. After opening cmd, you should check if perl is installed correctly by typing: “perl -v”. The results are shown in Figure 1.
Figure_2_of_model_part
The next step is to check whether NFsim is also installed correctly. This is done by first changing the directory of the command prompt to the directory were NFsim is installed / unzipped. We already mentioned that we installed it on our D-drive, so the first step is to change the drive. The easiest way to do this is by typing: “D:”, which lets you go the D-drive after you use the “enter” key on your keyboard. Next, change the directory to the NFsim directory. This can be done with: “cd D:\NFsim\NFsim_v1.11” where cd stands for Change Directory and after a space you type the folders where NFsim is installed. This path can be found easily by using the windows explorer, going to the correct folder and then clicking on it. The path then changes from the one in Figure 2 to a selectable name, like “D:\NFsim\NFsim_v1.11”, which can be copied and then placed in the command prompt. The shortcut “ctrl + v” doesn’t work in the command prompt, so you will need the right mouse button and paste the text.
Figure_2_of_model_part
The next step is to verify that the installation of NFsim was successful, which can be done by typing: “perl BNG2.pl -v”. If the installation is correct, the command prompt will look like the command prompt in Figure 3, after pressing the “enter” key.
Figure_2_of_model_part
Together with the installation of NFsim, you installed also some example models, which can be found in the folder “models”. The simple_system.bngl file is very nice as a start to see how output can be generated. We recommend that you open the bngl files with Notepad ++, as this is a very easy way to not only look at the files, but also to edit them if desired. Next to the simple_system.bngl file, we wrote a general file of our own with nice descriptions of each step and called this file: “system_example.bngl”. The description about how a bngl file is build up, can be found on our wiki page in the rule-based-model section: https://2017.igem.org/Team:TU-Eindhoven/Model/Rule_based_model
Link to download the bngl file (You need to save this file in the “models” folder of “NFsim_v1.11”
After you wrote your own bngl file, it is time to execute the file and get some results. The easiest way is to have a bngl file which has a line that states: “writeXML();” so that an XML file will be created during the first time we run the model and we can use the xml-file to run the same model again, but with different time steps.
The xml-file is created by typing the following line in the command prompt, as shown in Figure 4: “perl BNG2.pl -xml models/system_example.bngl” br/>
Figure_2_of_model_part
After generating an xml-file, you can run the model in another way, namely via a windows executable. The advantage is that you then can give additional commands, like the command “dump”. NFsim calls this a flag and they made a whole table that describes the command line arguments and their function. The table can be found on pages 38-40 of the manual. For the dump flag, we first need to make an empty folder. This can be done easily with the command “mkdir” followed by the name of the folder you want to create, for example “dumpDir_example_dump”. Furthermore, with -Steps you can redefine the number of steps, with -sim you can define the end time of the simulation and with -o, you can specify the output file of your simulation. The command line can for example look like below and in Figure 5: .\bin\NFsim_MSWin32.exe -xml system_example.xml -dump "[0:0.1:1]->dumpDir_example_dump/" -oSteps 10 -sim 1 -o “system_example_nf.gdat”
Figure_2_of_model_part

Codes for visualization

It is easy to visualize the results generated with Matlab. NFsim also provides some tools that you can use in the folder NFtools, but we will explain how you need to prepare Matlab and how you can use them. We ourselves already had Matlab 2016b installed, so the visualization may differ a bit, depending on your matlab version. There are also some functions that have changed over the time that Matlab exists, so it is possible that you will get a warning if you use another version. In most cases it isn’t a problem.
After opening Matlab you will end up in the home tab, shown in Figure 6. In this tab you can find an icon with the description: “Set Path”, like in Figure 7.
Figure_2_of_model_part
Figure_2_of_model_part
The window “Set Path” then opens and by clicking on “Add with Subfolders…” you can select the NFtools folder. This is done by first going to the driver (D-drive), followed by the NFsim folder, then NFsim_v1.11 and there you will see the folder NFtools, as in Figure 8. Select the NFtools folder, press Save and then Matlab will add the folders and their subfolders.
Figure_2_of_model_part
Then you need to go to the right directory for the Matlab editor. In Figure 9 you need to search for the icon visualized in Figure 10, which stands for “Browse for folder”. Then select the right path, which in this case, again is to “NFsim_v1.11”. The matlab code you can download below, can be saved in the general NFsim folder, which you can see in the editor window as depicted in Figure 9.
Figure_2_of_model_part
Figure_2_of_model_part
By clicking on the green arrow which says “run”, Matlab will execute the program and give output in the command window, see Figure 11, but also four figures with graphs. The first figure contains three different graphs, which are also displayed separately in the other three figures. We also gave Matlab the command to save the last three figures, so that you can easily access them again and place them on your wiki page for example. The figures generated with Matlab for the system_example file (with an end time of 10 seconds with 100 steps) are depicted in Figures 12-14.
Figure_2_of_model_part
Figure_2_of_model_part
Figure_2_of_model_part
Figure_2_of_model_part
If you look at the legends, you see that we used different methods to generate the graphs in the figures. Which method is most useful depends on the system that is implemented in the model. Therefore, it is useful to look at the data in the workspace (Figure 15) of Matlab to see which method works the best for generating your output. In our example, the results of method 1 and method 2 are the same for the total amount of complexes and for the total amount of molecules, so therefore we choose to only depict the results of method 1 and 3 in our graphs.
Figure_2_of_model_part



Footer







  • Logo TUe
  • Logo IBA
  • Logo PAMM
  • Logo ICMS