Difference between revisions of "Team:Paris Bettencourt/Software"

(Good version !)
Line 2: Line 2:
 
{{Paris_Bettencourt/menu}}
 
{{Paris_Bettencourt/menu}}
 
{{Paris_Bettencourt/modelingBanner}}
 
{{Paris_Bettencourt/modelingBanner}}
 
  
 
<html>
 
<html>
  
 
<h3>Introduction</h3>
 
<h3>Introduction</h3>
As explained in the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling">modeling page</a>, this program modelize the cells population evolution with mother cell differentiation and cell division.
+
As explained in the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a>, this program modelize the cells population evolution with mother cell differentiation and cell division.
 
<br />
 
<br />
 
We focus here on the stochastic program.
 
We focus here on the stochastic program.
Line 27: Line 26:
 
<li>\(imageToMatrix\) : convert an image into a matrix.</li>
 
<li>\(imageToMatrix\) : convert an image into a matrix.</li>
 
<li>\(initCells\) : initialization of the cells.</li>
 
<li>\(initCells\) : initialization of the cells.</li>
<li>\(initialization\) : initialization of the programm.</li>
+
<li>\(initialization\) : initialization of the program.</li>
 
<li>\(initTimeEvent\) : calcul the different time.</li>
 
<li>\(initTimeEvent\) : calcul the different time.</li>
 
<li>\(initVariables\) : variables initialization.</li>
 
<li>\(initVariables\) : variables initialization.</li>
Line 41: Line 40:
 
<li>\(writeParameters\) : write a text file with the parameters.</li>
 
<li>\(writeParameters\) : write a text file with the parameters.</li>
 
<li>\(launchStochasticProgramm\) : launch the stochastic time evoluation simulation.</li>
 
<li>\(launchStochasticProgramm\) : launch the stochastic time evoluation simulation.</li>
<li>\(k1OptimizationStochastic\) : calcul the number of differenciated cells and vitamin with differents k1 in a stochastic way.</li>
+
<li>\(k1OptimizationStochastic\) : calcul the number of differentiated cells and vitamin with differents k1 in a stochastic way.</li>
 
<li>\(k1OptimizationStochasticAndDeterministic\) : superimpose the deterministic and stochastic models.</li>
 
<li>\(k1OptimizationStochasticAndDeterministic\) : superimpose the deterministic and stochastic models.</li>
 
</ul>
 
</ul>
Line 47: Line 46:
 
<ul>
 
<ul>
 
<li>\(timeEvolutionDeterministic\) : show the time evolution by numerical calculus and equations.</li>
 
<li>\(timeEvolutionDeterministic\) : show the time evolution by numerical calculus and equations.</li>
<li>\(k1OptimizationDeterministic\) : calcul the number of differenciated cells with differents k1 in a deterministic way.</li>
+
<li>\(k1OptimizationDeterministic\) : calcul the number of differentiated cells with differents k1 in a deterministic way.</li>
 
</ul>
 
</ul>
 
<h3>Input</h3>
 
<h3>Input</h3>
Line 61: Line 60:
 
You can choose if you prefer to generate a random or a predetermined position for the initial cells.
 
You can choose if you prefer to generate a random or a predetermined position for the initial cells.
 
<br />
 
<br />
You have two cells types : mother cells and differenciated cells.
+
You have two cells types : mother cells and differentiated cells.
 
<h5>Random initial position</h5>
 
<h5>Random initial position</h5>
 
The input array must contain four integer values in this order.
 
The input array must contain four integer values in this order.
Line 75: Line 74:
 
<br />
 
<br />
  
In the programm, the input variable has the following pattern.
+
In the program, the input variable has the following pattern.
 
<br />
 
<br />
 
\(input = [MC_0, DC_0, sizeMatCell, sizeMat]\)
 
\(input = [MC_0, DC_0, sizeMatCell, sizeMat]\)
Line 98: Line 97:
 
<li>the image must be square and in jpeg format.</li>
 
<li>the image must be square and in jpeg format.</li>
 
<li>255 means no cell.</li>
 
<li>255 means no cell.</li>
<li>128 means one differenciated cell.</li>
+
<li>128 means one differentiated cell.</li>
 
<li>0 means one mother cell.</li>
 
<li>0 means one mother cell.</li>
 
</ul>
 
</ul>
Line 106: Line 105:
 
<ul>
 
<ul>
 
<li>#FFFFFF (white) means no cell.</li>
 
<li>#FFFFFF (white) means no cell.</li>
<li>#800000 (red) means one differenciated cell.</li>
+
<li>#800000 (red) means one differentiated cell.</li>
 
<li>#000000 (black) means one mother cell.</li>
 
<li>#000000 (black) means one mother cell.</li>
 
</ul>
 
</ul>
Line 114: Line 113:
 
<img src="https://static.igem.org/mediawiki/2015/9/9a/IgemImg.png" style="width:20%;height:20%;" alt="Example of predetermined cells initial position with mother cells" title="Example of predetermined cells initial position with mother cells" >
 
<img src="https://static.igem.org/mediawiki/2015/9/9a/IgemImg.png" style="width:20%;height:20%;" alt="Example of predetermined cells initial position with mother cells" title="Example of predetermined cells initial position with mother cells" >
 
<br />
 
<br />
Here is an other example with mother cells (black) and differenciated cells (red).
+
Here is an other example with mother cells (black) and differentiated cells (red).
 
<br />
 
<br />
<img src="https://static.igem.org/mediawiki/2015/a/a4/IgemParisBettencourtImg.png" style="width:20%;height:20%;" alt="Example of predetermined cells initial position with mother cells (black) and differenciated cells (red)" title="Example of predetermined cells initial position with mother cells (black) and differenciated cells (red)" >
+
<img src="https://static.igem.org/mediawiki/2015/a/a4/IgemParisBettencourtImg.png" style="width:20%;height:20%;" alt="Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)" title="Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)" >
 
<br />
 
<br />
  
Line 131: Line 130:
 
</ul>
 
</ul>
 
<br />
 
<br />
In the programm, the rate constants variable has the following pattern.
+
In the program, the rate constants variable has the following pattern.
 
<br />
 
<br />
 
\(constantRate = [\mu_{1}, \sigma_{1}, \mu_{2}, \sigma_{2}, \mu_{3}, \sigma_{3}, k_{4}]\)
 
\(constantRate = [\mu_{1}, \sigma_{1}, \mu_{2}, \sigma_{2}, \mu_{3}, \sigma_{3}, k_{4}]\)
Line 161: Line 160:
  
 
<br />
 
<br />
In the programm, the action variable has the following pattern.
+
In the program, the action variable has the following pattern.
 
<br />
 
<br />
 
\(action = [createFolder, showAnimation, plotGraph\)]
 
\(action = [createFolder, showAnimation, plotGraph\)]
Line 208: Line 207:
 
<h4>Raw data</h4>
 
<h4>Raw data</h4>
 
<ul>
 
<ul>
<li>\(mainTic\) : start of the programm.</li>
+
<li>\(mainTic\) : start of the program.</li>
 
<li>\(MC_0\) : initial number of mother cells in the medium.</li>
 
<li>\(MC_0\) : initial number of mother cells in the medium.</li>
 
<li>\(DC_0\) : initial number of differentiated cells in the medium.</li>
 
<li>\(DC_0\) : initial number of differentiated cells in the medium.</li>
Line 254: Line 253:
 
<li>\(timeSpent\) : computation time (in seconds).</li>
 
<li>\(timeSpent\) : computation time (in seconds).</li>
  
 
 
</ul>
 
</ul>
 
<h4>Folder creation</h4>
 
<h4>Folder creation</h4>
 +
If the \(action\) variable \(createFolder\) is set, the program will save important results data in this folder.
 +
<br />
 +
<ul>
 +
<li>\(parameters.txt\) : text file containing differents simulation parameters and results</li>
 +
<li>\(data.mat\) : MATLAB file containing simulation the raw data structure. To load the file, use this formula : \(load('data.mat')\).</li>
 +
</ul>
 +
<br />
 +
<br />
 +
 
<h4>Graphs</h4>
 
<h4>Graphs</h4>
 +
If the \(action\) variable \(plotGraph\) is set, the program will show the graphs.
 +
<br />
 +
Moreover if the \(action\) variable \(createFolder\) is set, the program will save the graphs in the folder.
 +
 
<h4>Animation</h4>
 
<h4>Animation</h4>
 +
If the \(action\) variable \(showAnimation\) is set, the program will show the cell animation.
 +
<br />
 +
Moreover if the \(action\) variable \(createFolder\) is set, the program will save the images in the folder.
  
 
<h3>Examples</h3>
 
<h3>Examples</h3>
 +
We present here some results obtained with the program. For more details about the model see the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a>.
 +
 
<h4>Time evolution of mother cells, differentiated cells and vitamin</h4>
 
<h4>Time evolution of mother cells, differentiated cells and vitamin</h4>
 
<h5>Graphs</h5>
 
<h5>Graphs</h5>
 +
As explained in the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a> the program give these results.
 +
<br />
 +
<img width="100%" src="https://static.igem.org/mediawiki/2015/1/14/StochasticEvolution.png" title="Stochastic evolution of the system" alt="Stochastic evolution of the system" style="align:center;">
 +
<br />
 +
<img width="100%" src="https://static.igem.org/mediawiki/2015/0/0b/OptimizeK1Stochastic.png" title="Stochastic vitamin optimization" alt="Stochastic vitamin optimization" style="align:center;">
 +
<br />
 +
<img width="100%" src="https://static.igem.org/mediawiki/2015/9/97/StochasticEventTimeProbabilityDistribution.png" title="Distribution of event time probability" alt="Distribution of event time probability" style="align:center;">
 +
 
<h5>Animation</h5>
 
<h5>Animation</h5>
 +
Here is an example with mother cells (black) and differentiated cells (red).
 +
<br />
 +
This image is the cell input.
 +
<br />
 +
<img style="width:30%;height:30%;" src="https://static.igem.org/mediawiki/2015/a/a4/IgemParisBettencourtImg.png" alt="Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)" title="Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)" >
 +
<br />
 +
The result is the following animation after a conversion in a gif file.
 +
<br />
 +
The mother cells are in orange and the differentiated cells are in yellow.
 +
<br />
 +
<img style="width:30%;height:30%;" src="https://static.igem.org/mediawiki/2015/7/73/IgemParisBettencourtGif.gif" alt="Animation example with predetermined cells initial position with mother cells and differentiated cells" title="Animation example with predetermined cells initial position with mother cells and differentiated cells" >
 +
<br />
 +
 
<h4>Vitamin optimization</h4>
 
<h4>Vitamin optimization</h4>
 +
This program is designed to maximize the vitamin production. Here are some results.
 +
<br />
 +
<img width="100%" src="https://static.igem.org/mediawiki/2015/0/0b/OptimizeK1Stochastic.png" title="Stochastic vitamin optimization" alt="Stochastic vitamin optimization" style="align:center;">
 +
 
<h4>Deterministic and stochastic vitamin optimization comparison</h4>
 
<h4>Deterministic and stochastic vitamin optimization comparison</h4>
 
+
Here is a comparison between the two models.
<h3>Programm explanation</h3>
+
<br />
<h4>Step by step</h4>
+
<img width="100%" src="https://static.igem.org/mediawiki/2015/3/3c/CompareStochasticAndDeterministic.png" title="Comparison of deterministic and stochastic vitamin optimization" alt="Comparison of deterministic and stochastic vitamin optimization" style="align:center;">
<h4>Parallel computing</h4>
+
  
 
<h3>Conclusion</h3>
 
<h3>Conclusion</h3>
 
+
Feel free to use and modify this program. The source code is available in <a href="https://github.com/iGEMParisBettencourt2015" alt="Source code in GitHub"> GitHub : iGEM Paris Bettencourt 2015</a> under the <a href="http://www.gnu.org/licenses/gpl.txt" alt="GNU General Public License" >GNU General Public License version 3.0</a>.
 +
For more informations concerning the model see the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a>.
 
</html>
 
</html>
  
 
{{Paris_Bettencourt/footer}}
 
{{Paris_Bettencourt/footer}}

Revision as of 20:59, 12 September 2015

Introduction

As explained in the modeling page, this program modelize the cells population evolution with mother cell differentiation and cell division.
We focus here on the stochastic program.

Files

The MATLAB code is available in GitHub under the GNU General Public License version 3.0.
Here is a quick explanation of the differents files ie the differents functions.

Stochastic algorithm

  • \(timeEvolutionStochastic\) : the main function to calcul the time evolution.
  • \(checkInput\) : check the input and show an error message if the input is not good.
  • \(elmPixel\) : find the coordinates of a pixel around an other pixel.
  • \(errorProgramm\) : display an error and stop the programm.
  • \(freePosition\) : create a list of free pixels around one pixel.
  • \(getComputerName\) : get the computer name.
  • \(getSizeMat\) : find the matrice size.
  • \(imageToMatrix\) : convert an image into a matrix.
  • \(initCells\) : initialization of the cells.
  • \(initialization\) : initialization of the program.
  • \(initTimeEvent\) : calcul the different time.
  • \(initVariables\) : variables initialization.
  • \(isBinary\) : check if a number is 0 or 1.
  • \(isPositiveInteger\) : check if a number is a positive integer (1) or not (0).
  • \(makeCells\) : make the cells.
  • \(randEvent\) : generate the next random event.
  • \(randPosition\) : find a free position for a cell.
  • \(saveInitialParameters\) : save the initial parameters in a text file.
  • \(saveResult\) : save and plot the results.
  • \(showAndSaveEventTimeDistribution\) : show and save the event time probability distribution.
  • \(showPopulation\) : show the cells matrix.
  • \(writeParameters\) : write a text file with the parameters.
  • \(launchStochasticProgramm\) : launch the stochastic time evoluation simulation.
  • \(k1OptimizationStochastic\) : calcul the number of differentiated cells and vitamin with differents k1 in a stochastic way.
  • \(k1OptimizationStochasticAndDeterministic\) : superimpose the deterministic and stochastic models.

Deterministic algorithm

  • \(timeEvolutionDeterministic\) : show the time evolution by numerical calculus and equations.
  • \(k1OptimizationDeterministic\) : calcul the number of differentiated cells with differents k1 in a deterministic way.

Input

In order to launch a simulation, you must define five variables.
  • cells.
  • rate constants.
  • fermentation period.
  • action.
  • folder name.

Cells input

You can choose if you prefer to generate a random or a predetermined position for the initial cells.
You have two cells types : mother cells and differentiated cells.
Random initial position
The input array must contain four integer values in this order.
  • \(MC_0\) : initial number of mother cells in the medium.
  • \(DC_0\) : initial number of differentiated cells in the medium.
  • \(sizeMatCell\) : cells box size (in pixels).
  • \(sizeMat\) : real box size (in pixels).

Warning : \(sizeMatCell\) must be larger than \(sizeMat\).

In the program, the input variable has the following pattern.
\(input = [MC_0, DC_0, sizeMatCell, sizeMat]\)

Here is an example.
  • \(MC_0 = 5 \phantom{t} (cells)\)
  • \(DC_0 = 0 \phantom{t} (cells)\)
  • \(sizeMatCell = 100 \phantom{t} (pixels)\)
  • \(sizeMat = 250 \phantom{t} (pixels)\)
Predetermined initial position
In order to make an easy predetermined initial position input, we wrote a code which understand images.
The input must contain the image path.
It is very easy to design a custom image ie a custom spatial cell distribution. You must follow these four rules (we work only with the image red component)
  • the image must be square and in jpeg format.
  • 255 means no cell.
  • 128 means one differentiated cell.
  • 0 means one mother cell.
0, 128 and 255 are red components of any colours that you want because the MATLAB code take into account only the image red component.
If you want, you can use the following hexadecimal colours codes.
  • #FFFFFF (white) means no cell.
  • #800000 (red) means one differentiated cell.
  • #000000 (black) means one mother cell.

Here is an example only with mother cells.
Example of predetermined cells initial position with mother cells
Here is an other example with mother cells (black) and differentiated cells (red).
Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)

Rate constants

You have to define seven variables.
  • \(\mu_{1}\) : mother cell differentiation time mean.
  • \(\sigma_{1}\) : mother cell differentiation time standard deviation.
  • \(\mu_{2}\) : mother cell doubling time mean.
  • \(\sigma_{2}\) : mother cell doubling time standard deviation.
  • \(\mu_{3}\) : differentiated cell doubling time mean.
  • \(\sigma_{3}\) : differentiated cell doubling time standard deviation.
  • \(k_{4}\) : rate constant of the differentiated cell vitamin production.

In the program, the rate constants variable has the following pattern.
\(constantRate = [\mu_{1}, \sigma_{1}, \mu_{2}, \sigma_{2}, \mu_{3}, \sigma_{3}, k_{4}]\)

Here is an example.
  • \(\mu_{1} = 1 \phantom{t} (hours)\)
  • \(\sigma_{1} = 0.1 \phantom{t} (hours)\)
  • \(\mu_{2} = 1.0502 \phantom{t} (hours)\)
  • \(\sigma_{2} = 0.1 \phantom{t} (hours)\)
  • \(\mu_{3} = 2.1004 \phantom{t} (hours)\)
  • \(\sigma_{3} = 0.1 \phantom{t} (hours)\)
  • \(k_{4} = 1 \phantom{t} (hours^{-1})\)

Fermentation period

The fermentation period \(t\) is a simple scalar variable.
You can use \(t = 5 \phantom{t} (hours)\) for example.

Action

In order to choose what you want to do, you must define three booleans.
  • \(createFolder\) : create a folder in the disk to save informations.
  • \(showAnimation\) : show the poulation animation. Warning : require a lot of computing power.
  • \(plotGraph\) : plot the results in graphs.

In the program, the action variable has the following pattern.
\(action = [createFolder, showAnimation, plotGraph\)]

In the following example we want to create a folder and plot the graphs.
  • \(createFolder = 1\)
  • \(showAnimation = 0\)
  • \(plotGraph = 1\)

In the following example we want to show the cell animation.
  • \(createFolder = 0\)
  • \(showAnimation = 1\)
  • \(plotGraph = 0\)

In the following example we want to show the cell animation and save the images in a folder.
With the images you can create gif animations.
  • \(createFolder = 1\)
  • \(showAnimation = 1\)
  • \(plotGraph = 0\)

Folder name

The \(folderName\) variable is a string containing the folder where results folder are store in the disk.
You can use \(folderName =\) '\(Results\)' for example.

Output

Four types of output are generated.
  • raw data : all the useful informations.
  • folder creation : if chosen in the \(action\) variable, a folder is created.
  • graphs : if chosen in the \(action\) variable, graphs are generated.
  • animation : if chosen in the \(action\) variable, cell animation is generated.

Raw data

  • \(mainTic\) : start of the program.
  • \(MC_0\) : initial number of mother cells in the medium.
  • \(DC_0\) : initial number of differentiated cells in the medium.
  • \(pasDistributionTimeEvent\) : resolution for the graph time event distribution plot (see the \(initVariables\) function).
  • \(frameRate\) : animation framerate (see the \(initVariables\) function).
  • \(timeShowPopulation\) : simulation time between two animations (see the \(initVariables\) function).
  • \(simulationTime\) : fermentation period \(t\).
  • \(resultFolderName\) : folder where the results folder are created.
  • \(\mu_{1}\) : mother cell differentiation time mean.
  • \(\sigma_{1}\) : mother cell differentiation time standard deviation.
  • \(\mu_{2}\) : mother cell doubling time mean.
  • \(\sigma_{2}\) : mother cell doubling time standard deviation.
  • \(\mu_{3}\) : differentiated cell doubling time mean.
  • \(\sigma_{3}\) : differentiated cell doubling time standard deviation.
  • \(k_{4}\) : rate constant of the differentiated cell vitamin production.
  • \(cVitamin\) : vitamin counter.
  • \(time\) : main timer containing the simulation time.
  • \(createFolder\) : action boolean.
  • \(showPopulationBool\) : action boolean.
  • \(plotGraph\) : action boolean.
  • \(input\) : input array.
  • \(cTime1\) : time distribution counter 1 (see the \(randEvent\) function).
  • \(cTime2\) : time distribution counter 2 (see the \(randEvent\) function).
  • \(cTime3\) : time distribution counter 3 (see the \(randEvent\) function).
  • \(counterEvent\) : event counter.
  • \(timerShow\) : time animation counter.
  • \(sizeMat\) : real box size (in pixels).
  • \(nextEvent\) : .
  • \(time1Array\) : time distribution array 1 (see the \(initTimeEvent\) function).
  • \(time2Array\) : time distribution array 2 (see the \(initTimeEvent\) function).
  • \(time3Array\) : time distribution array 3 (see the \(initTimeEvent\) function).
  • \(cell\) : structure containing all the cells informations.
  • \(sizeMatCell\) : cells box size (in pixels).
  • \(timeNextEvent\) : time before the next event.
  • \(saveTime\) : array containing the simulation time evolution.
  • \(saveNbrMC\) : array containing the mother cells time evolution.
  • \(saveNbrDC\) : array containing the differentiated cells time evolution.
  • \(saveNbrVitamin\) : array containing the vitamin time evolution.
  • \(folderName\) : folder where the results are stored. The pattern is the following : \(resultFolderName/DD-MM-YY\_hh\_mm\_ss\_mss\).
  • \(imgType\) : image type (see the \(initilization\) function).
  • \(parametersFileName\) : parameters file name where the parameters are saved (see the \(initilization\) function).
  • \(parametersDoc\) : file object where the parameters are saved.
  • \(maxMC\) : maximum number of mother cells.
  • \(maxDC\) : maximum number of differentiated cells.
  • \(maxVitamin\) : maximum number of vitamins.
  • \(timeSpent\) : computation time (in seconds).

Folder creation

If the \(action\) variable \(createFolder\) is set, the program will save important results data in this folder.
  • \(parameters.txt\) : text file containing differents simulation parameters and results
  • \(data.mat\) : MATLAB file containing simulation the raw data structure. To load the file, use this formula : \(load('data.mat')\).


Graphs

If the \(action\) variable \(plotGraph\) is set, the program will show the graphs.
Moreover if the \(action\) variable \(createFolder\) is set, the program will save the graphs in the folder.

Animation

If the \(action\) variable \(showAnimation\) is set, the program will show the cell animation.
Moreover if the \(action\) variable \(createFolder\) is set, the program will save the images in the folder.

Examples

We present here some results obtained with the program. For more details about the model see the modeling page.

Time evolution of mother cells, differentiated cells and vitamin

Graphs
As explained in the modeling page the program give these results.
Stochastic evolution of the system
Stochastic vitamin optimization
Distribution of event time probability
Animation
Here is an example with mother cells (black) and differentiated cells (red).
This image is the cell input.
Example of predetermined cells initial position with mother cells (black) and differentiated cells (red)
The result is the following animation after a conversion in a gif file.
The mother cells are in orange and the differentiated cells are in yellow.
Animation example with predetermined cells initial position with mother cells and differentiated cells

Vitamin optimization

This program is designed to maximize the vitamin production. Here are some results.
Stochastic vitamin optimization

Deterministic and stochastic vitamin optimization comparison

Here is a comparison between the two models.
Comparison of deterministic and stochastic vitamin optimization

Conclusion

Feel free to use and modify this program. The source code is available in GitHub : iGEM Paris Bettencourt 2015 under the GNU General Public License version 3.0. For more informations concerning the model see the modeling page.