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

(software page merged with the modeling page)
 
Line 1: Line 1:
{{Paris_Bettencourt/header}}
 
{{Paris_Bettencourt/menu}}
 
{{Paris_Bettencourt/softwareBanner}}
 
  
<html>
 
 
<h3>Introduction</h3>
 
As explained on the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a>, this program models the cell population evolution with mother cell differentiation and cell division.
 
<br />
 
We focus here on the stochastic program.
 
 
<h3>Files</h3>
 
The MATLAB code is available on <a href="https://github.com/iGEMParisBettencourt2015/modeling" title="Source code in GitHub" >GitHub</a> under the GNU General Public License version 3.0.
 
<br />
 
Here is a quick explanation of the different files <i>i.e.</i> the different functions.
 
<h4>Stochastic algorithm</h4>
 
<ul>
 
<li>\(timeEvolutionStochastic\) : calculate the time evolution.</li>
 
<li>\(checkInput\) : check the input and show an error message if the input is not good.</li>
 
<li>\(elmPixel\) : find the coordinates of a pixel around another pixel.</li>
 
<li>\(errorProgramm\) : display an error and stop the program.</li>
 
<li>\(freePosition\) : create a list of free pixels around one pixel.</li>
 
<li>\(getComputerName\) : get the computer name.</li>
 
<li>\(getSizeMat\) : find the matrix size.</li>
 
<li>\(imageToMatrix\) : convert an image into a matrix.</li>
 
<li>\(initCells\) : initialize the cells.</li>
 
<li>\(initialization\) : initialize the program.</li>
 
<li>\(initTimeEvent\) : calculate the different time.</li>
 
<li>\(initVariables\) : initialize the variables.</li>
 
<li>\(isBinary\) : check if a number is 0 or 1.</li>
 
<li>\(isPositiveInteger\) : check if a number is a positive integer (1) or not (0).</li>
 
<li>\(makeCells\) : make the cells.</li>
 
<li>\(randEvent\) : generate the next random event.</li>
 
<li>\(randPosition\) : find a free position for a cell.</li>
 
<li>\(saveInitialParameters\) : save the initial parameters in a text file.</li>
 
<li>\(saveResult\) : save and plot the results.</li>
 
<li>\(showAndSaveEventTimeDistribution\) : show and save the event time probability distribution.</li>
 
<li>\(showPopulation\) : show the cells matrix.</li>
 
<li>\(writeParameters\) : write a text file with the parameters.</li>
 
<li>\(launchStochasticProgramm\) : launch the stochastic time evolution simulation.</li>
 
<li>\(k1OptimizationStochastic\) : calculate the number of differentiated cells and vitamin with different \(k_{1}\) in a stochastic way.</li>
 
<li>\(k1OptimizationStochasticAndDeterministic\) : superimpose the deterministic and stochastic models.</li>
 
</ul>
 
<h4>Deterministic algorithm</h4>
 
<ul>
 
<li>\(timeEvolutionDeterministic\) : show the time evolution by numerical calculus and equations.</li>
 
<li>\(k1OptimizationDeterministic\) : calculate the number of differentiated cells with different \(k_{1}\) in a deterministic way.</li>
 
</ul>
 
<h3>Input</h3>
 
In order to launch a simulation, you must define five variables.
 
<ul>
 
<li>Initial cells.</li>
 
<li>Rate constants.</li>
 
<li>Fermentation period.</li>
 
<li>Action.</li>
 
<li>Folder name.</li>
 
</ul>
 
<h4>Cells input</h4>
 
You can choose to generate a random or a predetermined position for the initial cells.
 
<br />
 
You have two cell types : mother cells and differentiated cells.
 
<h5>Random initial position</h5>
 
The input array must contain four integer values in this order.
 
<ul>
 
<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>\(sizeMatCell\) : cells box size (in pixels).</li>
 
<li>\(sizeMat\) : real box size (in pixels).</li>
 
</ul>
 
<br />
 
Warning : \(sizeMatCell\) must be larger than \(sizeMat\).
 
<br />
 
<br />
 
 
In the program, the input variable has the following pattern.
 
<br />
 
\(input = [MC_0, DC_0, sizeMatCell, sizeMat]\)
 
<br />
 
<br />
 
Here is an example.
 
<br />
 
<ul>
 
<li>\(MC_0 = 5 \phantom{t} (cells)\)</li>
 
<li>\(DC_0 = 0 \phantom{t} (cells)\)</li>
 
<li>\(sizeMatCell = 100 \phantom{t} (pixels)\)</li>
 
<li>\(sizeMat = 250 \phantom{t} (pixels)\)</li>
 
</ul>
 
 
<h5>Predetermined initial position</h5>
 
In order to make an easy predetermined initial position input, we wrote a code that understands images.
 
<br />
 
The input must contain the image path.
 
<br />
 
It is very easy to design a custom image <i>i.e.</i> a custom spatial cell distribution. You must follow these four rules (we work only with the image red component)
 
<ul>
 
<li>the image must be square and in jpeg format.</li>
 
<li>255 means no cell.</li>
 
<li>128 means one differentiated cell.</li>
 
<li>0 means one mother cell.</li>
 
</ul>
 
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.
 
<br />
 
If you want, you can use the following hexadecimal colors codes.
 
<ul>
 
<li>#FFFFFF (white) means no cell.</li>
 
<li>#800000 (red) means one differentiated cell.</li>
 
<li>#000000 (black) means one mother cell.</li>
 
</ul>
 
<br />
 
Here is an example only with mother cells.
 
<br />
 
<br />
 
<img src="https://static.igem.org/mediawiki/2015/9/9a/IgemImg.png" style="width:40%;height:40%;" alt="Example of predetermined cells initial position with mother cells" title="Example of predetermined cells initial position with mother cells" >
 
<p><b>Figure 1 :</b> Example of predetermined cells initial position with mother cells.</p>
 
<br />
 
Here is another 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:40%;height:40%;" 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)" >
 
<p><b>Figure 2 :</b> Example of predetermined cells initial position with mother cells (black) and differentiated cells (red).</p>
 
<br />
 
 
<h4>Rate constants</h4>
 
You have to define seven variables.
 
<ul>
 
<li>\(\mu_{1}\) : mother cell differentiation time mean.</li>
 
<li>\(\sigma_{1}\) : mother cell differentiation time standard deviation.</li>
 
<li>\(\mu_{2}\) : mother cell doubling time mean.</li>
 
<li>\(\sigma_{2}\) : mother cell doubling time standard deviation.</li>
 
<li>\(\mu_{3}\) : differentiated cell doubling time mean.</li>
 
<li>\(\sigma_{3}\) : differentiated cell doubling time standard deviation.</li>
 
<li>\(k_{4}\) : rate constant of the differentiated cell vitamin production.</li>
 
</ul>
 
<br />
 
In the program, the rate constants variable has the following pattern.
 
<br />
 
\(constantRate = [\mu_{1}, \sigma_{1}, \mu_{2}, \sigma_{2}, \mu_{3}, \sigma_{3}, k_{4}]\)
 
<br />
 
<br />
 
Here is an example.
 
<br />
 
<ul>
 
<li>\(\mu_{1} = 1 \phantom{t} (hours)\)</li>
 
<li>\(\sigma_{1} = 0.1 \phantom{t} (hours)\)</li>
 
<li>\(\mu_{2} = 1.0502 \phantom{t} (hours)\)</li>
 
<li>\(\sigma_{2} = 0.1 \phantom{t} (hours)\)</li>
 
<li>\(\mu_{3} = 2.1004 \phantom{t} (hours)\)</li>
 
<li>\(\sigma_{3} = 0.1 \phantom{t} (hours)\)</li>
 
<li>\(k_{4} = 1 \phantom{t} (hours^{-1})\)</li>
 
</ul>
 
 
<h4>Fermentation period</h4>
 
The fermentation period \(t\) is a simple scalar variable.
 
<br />
 
You can use \(t = 5 \phantom{t} (hours)\) for example.
 
<h4>Action</h4>
 
In order to choose what you want to do, you must define three Boolean variables.
 
<ul>
 
<li>\(createFolder\) : create a folder in the disk to save information.</li>
 
<li>\(showAnimation\) : show the cell population animation. Warning : requires a lot of computing power.</li>
 
<li>\(plotGraph\) : plot the results in graphs.</li>
 
</ul>
 
 
<br />
 
In the program, the action variable has the following pattern.
 
<br />
 
\(action = [createFolder, showAnimation, plotGraph\)]
 
<br />
 
<br />
 
In the following example we want to create a folder and plot the graphs.
 
<br />
 
<ul>
 
<li>\(createFolder = 1\)</li>
 
<li>\(showAnimation = 0\)</li>
 
<li>\(plotGraph = 1\)</li>
 
</ul>
 
<br />
 
In the following example we want to show the cell animation.
 
<br />
 
<ul>
 
<li>\(createFolder = 0\)</li>
 
<li>\(showAnimation = 1\)</li>
 
<li>\(plotGraph = 0\)</li>
 
</ul>
 
<br />
 
In the following example we want to show the cell animation and save the images in a folder.
 
<br />
 
With the images you can create gif animations.
 
<br />
 
<ul>
 
<li>\(createFolder = 1\)</li>
 
<li>\(showAnimation = 1\)</li>
 
<li>\(plotGraph = 0\)</li>
 
</ul>
 
 
<h4>Folder name</h4>
 
The \(folderName\) variable is a string containing the folder name where results folder are stored in the disk.
 
<br />
 
You can use \(folderName =\) '\(Results\)' for example.
 
 
<h3>Output</h3>
 
Four types of output are generated.
 
<ul>
 
<li>raw data : all the useful information.</li>
 
<li>folder creation : if chosen in the \(action\) variable a folder is created.</li>
 
<li>graphs : if chosen in the \(action\) variable graphs are generated.</li>
 
<li>animation : if chosen in the \(action\) variable cell animation is generated.</li>
 
</ul>
 
 
<h4>Raw data</h4>
 
<ul>
 
<li>\(mainTic\) : start of the program.</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>\(pasDistributionTimeEvent\) : resolution for the graph time event distribution plot (see the \(initVariables\) function).</li>
 
<li>\(frameRate\) : animation frame rate (see the \(initVariables\) function).</li>
 
<li>\(timeShowPopulation\) : simulation time between two animations (see the \(initVariables\) function).</li>
 
<li>\(simulationTime\) : fermentation period \(t\).</li>
 
<li>\(resultFolderName\) : folder where the results folder are created.</li>
 
<li>\(\mu_{1}\) : mother cell differentiation time mean.</li>
 
<li>\(\sigma_{1}\) : mother cell differentiation time standard deviation.</li>
 
<li>\(\mu_{2}\) : mother cell doubling time mean.</li>
 
<li>\(\sigma_{2}\) : mother cell doubling time standard deviation.</li>
 
<li>\(\mu_{3}\) : differentiated cell doubling time mean.</li>
 
<li>\(\sigma_{3}\) : differentiated cell doubling time standard deviation.</li>
 
<li>\(k_{4}\) : rate constant of the differentiated cell vitamin production.</li>
 
<li>\(cVitamin\) : vitamin counter.</li>
 
<li>\(time\) : main timer containing the simulation time.</li>
 
<li>\(createFolder\) : action boolean.</li>
 
<li>\(showPopulationBool\) : action boolean.</li>
 
<li>\(plotGraph\) : action boolean.</li>
 
<li>\(input\) : input array.</li>
 
<li>\(cTime1\) : time distribution counter 1 (see the \(randEvent\) function).</li>
 
<li>\(cTime2\) : time distribution counter 2 (see the \(randEvent\) function).</li>
 
<li>\(cTime3\) : time distribution counter 3 (see the \(randEvent\) function).</li>
 
<li>\(counterEvent\) : event counter.</li>
 
<li>\(timerShow\) : time animation counter.</li>
 
<li>\(sizeMat\) : real box size (in pixels).</li>
 
<li>\(nextEvent\) : next event type.</li>
 
<li>\(time1Array\) : time distribution array 1 (see the \(initTimeEvent\) function).</li>
 
<li>\(time2Array\) : time distribution array 2 (see the \(initTimeEvent\) function).</li>
 
<li>\(time3Array\) : time distribution array 3 (see the \(initTimeEvent\) function).</li>
 
<li>\(cell\) : structure containing all the cells' information.</li>
 
<li>\(sizeMatCell\) : cells box size (in pixels).</li>
 
<li>\(timeNextEvent\) : time before the next event.</li>
 
<li>\(saveTime\) : array containing the simulation time evolution.</li>
 
<li>\(saveNbrMC\) : array containing the mother cells time evolution.</li>
 
<li>\(saveNbrDC\) : array containing the differentiated cells time evolution.</li>
 
<li>\(saveNbrVitamin\) : array containing the vitamin time evolution.</li>
 
<li>\(folderName\) : folder where the results are stored. The pattern is the following : \(resultFolderName/DD-MM-YY\_hh\_mm\_ss\_mss\).</li>
 
<li>\(imgType\) : image type (see the \(initialization\) function).</li>
 
<li>\(parametersFileName\) : parameters file name where the parameters are saved (see the \(initialization\) function).</li>
 
<li>\(parametersDoc\) : file object where the parameters are saved.</li>
 
<li>\(maxMC\) : maximum number of mother cells.</li>
 
<li>\(maxDC\) : maximum number of differentiated cells.</li>
 
<li>\(maxVitamin\) : maximum number of vitamins.</li>
 
<li>\(timeSpent\) : computation time (in seconds).</li>
 
 
</ul>
 
<h4>Folder creation</h4>
 
If the \(action\) variable \(createFolder\) is set, the program will save important results in this folder.
 
<br />
 
<ul>
 
<li>\(parameters.txt\) : text file containing different simulation parameters and results.</li>
 
<li>\(data.mat\) : MATLAB file containing the raw data structure. To load the file, use this formula : \(load('data.mat')\).</li>
 
</ul>
 
 
<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>
 
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>
 
We present here some results obtained with the program. For more details about the model sees 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>
 
<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 />
 
<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;">
 
<p style="text-align:center"><b>Figure 3 :</b> Stochastic evolution of the system.</p>
 
<br />
 
<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;">
 
<p style="text-align:center"><b>Figure 4 :</b> Stochastic vitamin optimization.</p>
 
<br />
 
<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;">
 
<p style="text-align:center"><b>Figure 5 :</b> Distribution of event time probability.</p>
 
 
<h5>Animation</h5>
 
Here is an example with mother cells (black) and differentiated cells (red).
 
<br />
 
This image is the cell input.
 
<br />
 
<br />
 
<img style="width:40%;height:40%;" 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)" >
 
<p><b>Figure 6 :</b> Example of predetermined cells initial position with mother cells (black) and differentiated cells (red).</p>
 
<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 />
 
<br />
 
<img style="width:40%;height:40%;" 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" >
 
<p><b>Figure 7 :</b> Animation example with predetermined cells initial position with mother cells and differentiated cells.</p>
 
<br />
 
 
<h4>Vitamin optimization</h4>
 
This program is designed to maximize the vitamin production. Here are some results.
 
<br />
 
<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;">
 
<p style="text-align:center"><b>Figure 8 :</b> Stochastic vitamin optimization.</p>
 
 
<h4>Deterministic and stochastic vitamin optimization comparison</h4>
 
Here is a comparison between the two models.
 
<br />
 
<br />
 
<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;">
 
<p style="text-align:center"><b>Figure 9 :</b> Comparison of deterministic and stochastic vitamin optimization.</p>
 
 
<h3>Conclusion</h3>
 
Feel free to use and modify this program. The source code is available on <a href="https://github.com/iGEMParisBettencourt2015/modeling" title="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 information concerning the model see the <a href="https://2015.igem.org/Team:Paris_Bettencourt/Modeling" title="Modeling wiki page" >modeling page</a>.
 
</html>
 
 
{{Paris_Bettencourt/footer}}
 

Latest revision as of 19:52, 18 September 2015