Team:ETHZ Basel/Achievements/Matlab Toolbox

From 2010.igem.org

(Difference between revisions)
(Background)
(Features)
 
(30 intermediate revisions not shown)
Line 4: Line 4:
= Matlab / Simulink Toolbox =
= Matlab / Simulink Toolbox =
== Background ==
== Background ==
-
[[Image:lemmingToolbox.jpg|thumb|250px|Screenshot of the Simulink blocks available in the Matlab <em>Lemming Toolbox</em>. Please note that these blocks can be visually assembled with the Simulink blocks of other Toolboxes (e.g. blocks for nearly any mathematical function), and that the algorithms we developed can be accessed directly through Matlab code, too.]]During the iGem competition we developed several fast algorithms (e.g. for cell detection and tracking), complex models, as well as novel visualization, user input and microscope control approaches. Already during their development we took serious efforts to construct all parts in a modular and interchangeable way to deal with the combinatorial diversity of the questions our models as well as the information processing had to answer. Besides the various modules which can easily be reused by people experienced in programming, we also developed a graphical block representation of the various modules based on Simulink. This graphical user interface (GUI) can also be used by people with no or only little programming knowledge to solve complex tasks. These tasks do not have to be necessarily related to our iGem project, but can e.g. include the simulation of wild type chemotaxis, the detection of various cell types or the transfer of image data between a microscope and Matlab. We bundled all for other people useful Matlab and Simulink files into an easy to use Matlab Toolbox, which we named the Lemming Toolbox. This Lemming Toolbox was also used extensively during our project and speeded up the in-silico part significantly due to its modular design, which allowed for fast reassembly of program parts to solve urgent last-minute questions.
+
[[Image:lemmingToolbox.jpg|thumb|350px|Screenshot of the Simulink blocks available in the toolbox. Please note that these blocks can be visually assembled with the Simulink blocks of other Toolboxes (e.g. blocks for nearly any mathematical function), and that the algorithms we developed can be accessed directly through Matlab code, too.]]
 +
 
 +
During the iGEM competition, we developed several fast algorithms (e.g. for cell detection and tracking), complex models, as well as novel visualization, user input and microscope control approaches. Already during their development, we took serious efforts to construct all parts in a modular and interchangeable way to deal with the combinatorial diversity of the questions our models as well as the information processing had to answer. Besides the various modules which can easily be reused by people experienced in programming, we also developed a graphical block representation of the various modules based on Simulink. This graphical user interface (GUI) can also be used by people with no or only little programming knowledge to solve complex tasks. These tasks do not have to be necessarily related to our iGEM project, but can e.g. include the simulation of wild type chemotaxis, the detection of various cell types or the transfer of image data between a microscope and Matlab. For the use of anyone interested, we bundled all these Matlab & Simulink files together in the form of an easy to use Matlab Toolbox, which we named the Lemming Toolbox. This Lemming Toolbox was also used extensively during our project and speeded up the ''in silico'' part significantly due to its modular design, which allowed for fast reassembly of program parts to solve urgent last-minute questions.
Since science is based on the open availability of information and approaches, we decided to give something back to the Systems and Synthetic Biology community by cleaning and documenting the Lemming Toolkit and making it available as Open Source under the GNU General Public License (see [http://www.gnu.org/licenses/gpl.html]). In the following we give a short overview about the abilities and requirements of the software, as well as providing free download possibilities.
Since science is based on the open availability of information and approaches, we decided to give something back to the Systems and Synthetic Biology community by cleaning and documenting the Lemming Toolkit and making it available as Open Source under the GNU General Public License (see [http://www.gnu.org/licenses/gpl.html]). In the following we give a short overview about the abilities and requirements of the software, as well as providing free download possibilities.
-
Finally we shortly present the various systems (Simulink models) build with the help of the Lemming Toolkit, for which we also provide download possibilities. We hope that the Lemming Toolkit can help other researches as well as future iGem participants to faster solve their tasks.
+
Finally we shortly present the various systems (Simulink models) built with the help of the Lemming Toolkit, for which we also provide download possibilities. We hope that the Lemming Toolkit can help other researches as well as future iGEM participants to faster solve their tasks.
== Features ==
== Features ==
-
The Lemming toolbox has, amongst others, the following features:
+
The Lemming toolbox has, among others, the following features:
-
* Two molecular ODE models of the [[Team:ETHZ_Basel/Modeling/Chemotaxis|chemotaxis pathway]], based on the published models of Spiro et al. (1997) and Mello & Tu (2003).
+
* Two molecular ODE models of the [[Team:ETHZ_Basel/Modeling/Light_Switch| light switch]], PhyB/PIF3 and ALR.
-
* A stochastic model of the [[Team:ETHZ_Basel/Modeling/Movement|movement of E. coli]] generating paths for an E. coli cell for time varying bias signals.
+
* Four molecular ODE models of the [[Team:ETHZ_Basel/Modeling/Chemotaxis|chemotaxis pathway]], based on the published models of Spiro et al. (1997), Mello & Tu (2003), Rao et al (2004) and Barkai & Leibler (1997).
 +
* A stochastic model of the [[Team:ETHZ_Basel/Modeling/Movement|movement of E. coli]] generating paths for an ''E. coli'' cell for time varying bias signals.
* Various image sources, e.g. modules loading saved microscope images, generating microscope look-alike images from simulations, or pulling images in real-time from a microscope<sup>(1)</sup>.
* Various image sources, e.g. modules loading saved microscope images, generating microscope look-alike images from simulations, or pulling images in real-time from a microscope<sup>(1)</sup>.
* Fast cell detection and tracking algorithms compatible with all image sources.
* Fast cell detection and tracking algorithms compatible with all image sources.
Line 18: Line 21:
* Various user input possibilities, like real-time control of modules with either a joystick or the keyboard.
* Various user input possibilities, like real-time control of modules with either a joystick or the keyboard.
* Modules enabling the control of a automated microscope with Matlab scripts<sup>(1)</sup>.
* Modules enabling the control of a automated microscope with Matlab scripts<sup>(1)</sup>.
-
* Either accessible to Matlab scripts, realized as a broad set of standardized Matlab functions, or by an...
 
* Intuitive graphical user interface based on Simulink, which can fully be combined with other Simulink toolboxes.
* Intuitive graphical user interface based on Simulink, which can fully be combined with other Simulink toolboxes.
* Modular and expandable design.
* Modular and expandable design.
Line 31: Line 33:
* Installed [http://www.mathworks.com/products/image/Image Image Processing Toolbox].
* Installed [http://www.mathworks.com/products/image/Image Image Processing Toolbox].
* Installed [http://www.mathworks.com/products/3d-animation/ Simulink 3D Animation] (former named Virtual Reality Toolbox).
* Installed [http://www.mathworks.com/products/3d-animation/ Simulink 3D Animation] (former named Virtual Reality Toolbox).
-
* Actual Windows, Mac OS or Linux operating system.
 
* Approximately 24 MB of free disk space.
* Approximately 24 MB of free disk space.
* When using the joystick input: Joystick with at least three axes and six buttons. Force feedback optional.
* When using the joystick input: Joystick with at least three axes and six buttons. Force feedback optional.
Line 37: Line 38:
== Download ==
== Download ==
-
To freely download the Lemming Toolbox, please visit SOMEWHERE. All program files are included as Matlab m-files and Simulink mdl-files, thus no additional source code files have to be provided. For (downloadable) examples, please see below.
+
The current release of the Matlab / Simulink Toolbox as well as all examples can be downloaded as single files or as all-in-one package from the project page on SourceForge.net. In addition, a [https://sourceforge.net/scm/?type=svn&group_id=337301 '''SVN repository'''] is available with the current development revision.
 +
 
 +
* [http://sourceforge.net/projects/ethzigem10/files/LemmingToolbox_Setup.zip/download '''Download the Matlab Toolbox including all models''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/LemmingToolbox.zip/download '''Download only the Matlab Toolbox''']
-
== Examples ==
+
==Implemented models and examples ==
=== Tracking the E. lemming from Saved Images ===
=== Tracking the E. lemming from Saved Images ===
-
[[Image:imageStreamJoystick.jpg|thumb|250px|Screenshot of the <em>Tracking from Image Stream Model</em> in the joystick input version.]]This example shows how to continuously load saved microscope files from the disk, and to detect and track the cells on them. Furthermore the user can select one cell for which the movement direction is visualized and for which the path is plotted. This model is available as a joystick input and a keyboard input version.
+
[[Image:imageStreamJoystick.jpg|thumb|250px|Screenshot of the <em>Tracking from Image Stream Model</em> in the joystick input version.]]This example shows how to continuously load saved microscopy files from the disk, and to detect and track the cells on them. Furthermore the user can select one cell for which the movement direction is visualized and for which the path is plotted. This model is available as a joystick input and a keyboard input version.
 +
* [http://sourceforge.net/projects/ethzigem10/files/imageStreamKeyboard.zip/download '''Download the keyboard version.''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/imageStreamJoystick.zip/download '''Download the joystick version.''']
<br clear="all" />
<br clear="all" />
=== Simulating the E. lemming ===
=== Simulating the E. lemming ===
[[Image:modelJoystick.jpg|thumb|250px|Screenshot of the <em>Simulation Model</em> in the joystick input version.]]This model exemplifies how to use the "molecular model" and the "movement model" block to stochastically generate possible paths of the E. lemming based on the light inputs. The user can manually input the light signals either with the joystick or the mouse or activate a controller which forces the E. lemming to a user defined direction. For every time-step a microscope look-alike image is generated and visualized. This model is available as a joystick input and a keyboard input version.
[[Image:modelJoystick.jpg|thumb|250px|Screenshot of the <em>Simulation Model</em> in the joystick input version.]]This model exemplifies how to use the "molecular model" and the "movement model" block to stochastically generate possible paths of the E. lemming based on the light inputs. The user can manually input the light signals either with the joystick or the mouse or activate a controller which forces the E. lemming to a user defined direction. For every time-step a microscope look-alike image is generated and visualized. This model is available as a joystick input and a keyboard input version.
 +
* [http://sourceforge.net/projects/ethzigem10/files/modelKeyboard.zip/download '''Download the keyboard version.''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/modelJoystick.zip/download '''Download the joystick version.''']
<br clear="all" />
<br clear="all" />
=== Simulating and Detecting the E. lemming ===
=== Simulating and Detecting the E. lemming ===
[[Image:fullModelKeyboard.jpg|thumb|250px|Screenshot of the <em>Simulation and Detection Model</em> in the keyboard input version.]]Same as the previous example, only that this time not the outputs of the "movement model" block are directly used to determine the position. Instead, the generated image for the visualization is also used as the input for the "cell detection" and the "cell tracking" block. The detected position of the E. lemming is then used for visualization and as an input for the controller. This version requires more sophisticated user inputs. This model is also available as a joystick input and a keyboard input version.
[[Image:fullModelKeyboard.jpg|thumb|250px|Screenshot of the <em>Simulation and Detection Model</em> in the keyboard input version.]]Same as the previous example, only that this time not the outputs of the "movement model" block are directly used to determine the position. Instead, the generated image for the visualization is also used as the input for the "cell detection" and the "cell tracking" block. The detected position of the E. lemming is then used for visualization and as an input for the controller. This version requires more sophisticated user inputs. This model is also available as a joystick input and a keyboard input version.
 +
* [http://sourceforge.net/projects/ethzigem10/files/fullModelKeyboard.zip/download '''Download the keyboard version.''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/fullModelJoystick.zip/download '''Download the joystick version.''']
<br clear="all" />
<br clear="all" />
-
=== Real-time Tracking and Control of the E. lemming (in-vivo)===
+
=== Real-time Tracking and Control of the E. lemming (''in vivo'')===
-
[[Image:realTimeModel.jpg|thumb|250px|Screenshot of the <em>Real-Time Cell Tracking Model</em> used to connect to the microscope and control the in-vivo E. lemming in real-time.]]The model shows the setup of how the connection to the microscope was established, how the E. lemming was controlled in real-time and forced in the direction the user defined either with the keyboard or with a joystick. This model exists also in a keyboard and in a joystick version, but is not provided for download here for several reasons: First, for the model a supported automatized microscope is needed. Second, additional software has to be installed. Although we could provide this software for download, mistakes in using it can easily damage the microscope and lead to serious financial harm. Nevertheless, if you have an automatized microscope, and you are skilled and authorized, you can contact us by mail ([mailto:moritz.lang@bsse.ethz.ch moritz.lang@bsse.ethz.ch]) and we will provide the models together with the needed software as well as with some security and usage information.
+
[[Image:realTimeModel.jpg|thumb|250px|Screenshot of the <em>Real-Time Cell Tracking Model</em> used to connect to the microscope and control the ''in vivo'' E. lemming in real-time.]]The model shows the setup of how the connection to the microscope was established, how the E. lemming was controlled in real-time and forced in the direction the user defined either with the keyboard or with a joystick. This model exists also in a keyboard and in a joystick version, but is not provided for download here for several reasons: First, for the model a supported automatized microscope is needed. Second, additional software has to be installed. Although we could provide this software for download, mistakes in using it can easily damage the microscope and lead to serious financial harm. Nevertheless, if you have an automatized microscope, and you are skilled and authorized, you can contact us by mail ([mailto:moritz.lang@bsse.ethz.ch moritz.lang@bsse.ethz.ch]) and we will provide the models together with the needed software as well as with some security and usage information.
<br clear="all" />
<br clear="all" />
=== Controller Design Model ===
=== Controller Design Model ===
[[Image:competitionModel.jpg|thumb|250px|Screenshot of the <em> Controller Design Model</em> used in the group internal controller design competition.]]This model represents the model which was used to design and evaluate the different controllers used to force the E. lemming on the user defined direction. For speed reasons, only a simple graphical output is required. Furthermore no user input is needed during the simulation.
[[Image:competitionModel.jpg|thumb|250px|Screenshot of the <em> Controller Design Model</em> used in the group internal controller design competition.]]This model represents the model which was used to design and evaluate the different controllers used to force the E. lemming on the user defined direction. For speed reasons, only a simple graphical output is required. Furthermore no user input is needed during the simulation.
 +
* [http://sourceforge.net/projects/ethzigem10/files/Competition.zip/download '''Download the original competition model.''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/modelSquare.zip/download '''Download the model showing how the controller is forcing the E. lemming around a rectangle.''']
<br clear="all" />
<br clear="all" />
-
=== E. lemming 2D (game) ===
+
=== E. lemming 2D Game ===
-
[[Image:gamingJoystick.jpg|thumb|250px|Screenshot of the <em>E. lemming 2D Gaming Model</em> in the joystick input version.]]Here, the user has to directly control the red and far-red light inputs to the "molecular model" block. In a slightly modified graphical visualization he thus has to "hunt" other E. coli cells. When close enough, the user can release photons to eliminate other cells. For more details, see [[Team:ETHZ_Basel/InformationProcessing/Game | here]]. This model is available as a joystick input and a keyboard input version.
+
[[Image:gamingJoystick.jpg|thumb|250px|Screenshot of the <em>E. lemming 2D Gaming Model</em> in the joystick input version.]]Here, the user has to directly control the red and far-red light inputs to the "molecular model" block. In a slightly modified graphical visualization, he/she thus has to "hunt" other ''E. coli'' cells. When close enough, the user can release photons to eliminate other cells. For more details, see [[Team:ETHZ_Basel/InformationProcessing/Game | here]]. This model is available as a joystick input and a keyboard input version.
 +
* [http://sourceforge.net/projects/ethzigem10/files/gamingKeyboard.zip/download '''Download keyboard version.''']
 +
* [http://sourceforge.net/projects/ethzigem10/files/gamingJoystick.zip/download '''Download joystick version.''']
<br clear="all" />
<br clear="all" />
== References ==
== References ==
-
[1] [http://www.pnas.org/content/94/14/7263.full Spiro et al: A model of excitation and adaptation in bacterial chemotaxis. PNAS 1997 94;14;7263-7268.]
+
[1] [http://www.gnu.org/licenses/gpl.txt GNU General Public License, Version 3]
-
[2] [http://www.cell.com/biophysj/retrieve/pii/S0006349503700216 Mello & Tu: Perfect and Near-Perfect Adaptation in a Model of Bacterial Chemotaxis. Biophysical Journal 2003 84;5;2943-2956.]
+
[2] [http://www.micro-manager.org/ μManager Website]

Latest revision as of 00:51, 28 October 2010

Matlab / Simulink Toolbox

Background

Screenshot of the Simulink blocks available in the toolbox. Please note that these blocks can be visually assembled with the Simulink blocks of other Toolboxes (e.g. blocks for nearly any mathematical function), and that the algorithms we developed can be accessed directly through Matlab code, too.

During the iGEM competition, we developed several fast algorithms (e.g. for cell detection and tracking), complex models, as well as novel visualization, user input and microscope control approaches. Already during their development, we took serious efforts to construct all parts in a modular and interchangeable way to deal with the combinatorial diversity of the questions our models as well as the information processing had to answer. Besides the various modules which can easily be reused by people experienced in programming, we also developed a graphical block representation of the various modules based on Simulink. This graphical user interface (GUI) can also be used by people with no or only little programming knowledge to solve complex tasks. These tasks do not have to be necessarily related to our iGEM project, but can e.g. include the simulation of wild type chemotaxis, the detection of various cell types or the transfer of image data between a microscope and Matlab. For the use of anyone interested, we bundled all these Matlab & Simulink files together in the form of an easy to use Matlab Toolbox, which we named the Lemming Toolbox. This Lemming Toolbox was also used extensively during our project and speeded up the in silico part significantly due to its modular design, which allowed for fast reassembly of program parts to solve urgent last-minute questions.

Since science is based on the open availability of information and approaches, we decided to give something back to the Systems and Synthetic Biology community by cleaning and documenting the Lemming Toolkit and making it available as Open Source under the GNU General Public License (see [1]). In the following we give a short overview about the abilities and requirements of the software, as well as providing free download possibilities. Finally we shortly present the various systems (Simulink models) built with the help of the Lemming Toolkit, for which we also provide download possibilities. We hope that the Lemming Toolkit can help other researches as well as future iGEM participants to faster solve their tasks.

Features

The Lemming toolbox has, among others, the following features:

  • Two molecular ODE models of the light switch, PhyB/PIF3 and ALR.
  • Four molecular ODE models of the chemotaxis pathway, based on the published models of Spiro et al. (1997), Mello & Tu (2003), Rao et al (2004) and Barkai & Leibler (1997).
  • A stochastic model of the movement of E. coli generating paths for an E. coli cell for time varying bias signals.
  • Various image sources, e.g. modules loading saved microscope images, generating microscope look-alike images from simulations, or pulling images in real-time from a microscope(1).
  • Fast cell detection and tracking algorithms compatible with all image sources.
  • Visualization methods for real-time post-processing and displaying microscope images, together with an intuitive representation of the results of upstream modules like cell detection.
  • Various user input possibilities, like real-time control of modules with either a joystick or the keyboard.
  • Modules enabling the control of a automated microscope with Matlab scripts(1).
  • Intuitive graphical user interface based on Simulink, which can fully be combined with other Simulink toolboxes.
  • Modular and expandable design.
  • Open Source under the GNU General Public License.
  • Platform independent.

(1)This functionality is only usable with one of the various supported microscopes and an installation of μManager and μPlateImager. A finished version of μPlateImager will be published soon, but a beta version can be obtained for free by writing a request to moritz.lang@bsse.ethz.ch. μManager is a third party open source program available under [2].

Requirements

The following requirements are only necessary to be able to use all features of the Lemming Toolbox. Most modules can still be used even if one or several of the requirements are not fulfilled. In such cases, we recommand to simply download the Toolbox and test the corresponding modules. We tried to make this list comprehensive, however we cannot guarantee that we did not miss one or several requirements. The following requirements we are aware of:

  • Matlab R2007b or higher (not tested with lower versions).
  • Installed Image Processing Toolbox.
  • Installed Simulink 3D Animation (former named Virtual Reality Toolbox).
  • Approximately 24 MB of free disk space.
  • When using the joystick input: Joystick with at least three axes and six buttons. Force feedback optional.
  • For smooth real-time image analysis we recommend at least a 1GHz processor with 1024 MB RAM.

Download

The current release of the Matlab / Simulink Toolbox as well as all examples can be downloaded as single files or as all-in-one package from the project page on SourceForge.net. In addition, a SVN repository is available with the current development revision.

Implemented models and examples

Tracking the E. lemming from Saved Images

Screenshot of the Tracking from Image Stream Model in the joystick input version.
This example shows how to continuously load saved microscopy files from the disk, and to detect and track the cells on them. Furthermore the user can select one cell for which the movement direction is visualized and for which the path is plotted. This model is available as a joystick input and a keyboard input version.


Simulating the E. lemming

Screenshot of the Simulation Model in the joystick input version.
This model exemplifies how to use the "molecular model" and the "movement model" block to stochastically generate possible paths of the E. lemming based on the light inputs. The user can manually input the light signals either with the joystick or the mouse or activate a controller which forces the E. lemming to a user defined direction. For every time-step a microscope look-alike image is generated and visualized. This model is available as a joystick input and a keyboard input version.


Simulating and Detecting the E. lemming

Screenshot of the Simulation and Detection Model in the keyboard input version.
Same as the previous example, only that this time not the outputs of the "movement model" block are directly used to determine the position. Instead, the generated image for the visualization is also used as the input for the "cell detection" and the "cell tracking" block. The detected position of the E. lemming is then used for visualization and as an input for the controller. This version requires more sophisticated user inputs. This model is also available as a joystick input and a keyboard input version.


Real-time Tracking and Control of the E. lemming (in vivo)

Screenshot of the Real-Time Cell Tracking Model used to connect to the microscope and control the in vivo E. lemming in real-time.
The model shows the setup of how the connection to the microscope was established, how the E. lemming was controlled in real-time and forced in the direction the user defined either with the keyboard or with a joystick. This model exists also in a keyboard and in a joystick version, but is not provided for download here for several reasons: First, for the model a supported automatized microscope is needed. Second, additional software has to be installed. Although we could provide this software for download, mistakes in using it can easily damage the microscope and lead to serious financial harm. Nevertheless, if you have an automatized microscope, and you are skilled and authorized, you can contact us by mail (moritz.lang@bsse.ethz.ch) and we will provide the models together with the needed software as well as with some security and usage information.


Controller Design Model

Screenshot of the Controller Design Model used in the group internal controller design competition.
This model represents the model which was used to design and evaluate the different controllers used to force the E. lemming on the user defined direction. For speed reasons, only a simple graphical output is required. Furthermore no user input is needed during the simulation.


E. lemming 2D Game

Screenshot of the E. lemming 2D Gaming Model in the joystick input version.
Here, the user has to directly control the red and far-red light inputs to the "molecular model" block. In a slightly modified graphical visualization, he/she thus has to "hunt" other E. coli cells. When close enough, the user can release photons to eliminate other cells. For more details, see here. This model is available as a joystick input and a keyboard input version.


References

[1] GNU General Public License, Version 3

[2] μManager Website