Team:Paris Bettencourt/Software

Introduction

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

Files

The MATLAB code is available on GitHub under the GNU General Public License version 3.0.
Here is a quick explanation of the different files i.e. the different functions.

Stochastic algorithm

  • \(timeEvolutionStochastic\) : calculate 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 another pixel.
  • \(errorProgramm\) : display an error and stop the program.
  • \(freePosition\) : create a list of free pixels around one pixel.
  • \(getComputerName\) : get the computer name.
  • \(getSizeMat\) : find the matrix size.
  • \(imageToMatrix\) : convert an image into a matrix.
  • \(initCells\) : initialize the cells.
  • \(initialization\) : initialize the program.
  • \(initTimeEvent\) : calculate the different time.
  • \(initVariables\) : initialize the variables.
  • \(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 evolution simulation.
  • \(k1OptimizationStochastic\) : calculate the number of differentiated cells and vitamin with different \(k_{1}\) in a stochastic way.
  • \(k1OptimizationStochasticAndDeterministic\) : superimpose the deterministic and stochastic models.

Deterministic algorithm

  • \(timeEvolutionDeterministic\) : show the time evolution by numerical calculus and equations.
  • \(k1OptimizationDeterministic\) : calculate the number of differentiated cells with different \(k_{1}\) in a deterministic way.

Input

In order to launch a simulation, you must define five variables.
  • Initial cells.
  • Rate constants.
  • Fermentation period.
  • Action.
  • Folder name.

Cells input

You can choose to generate a random or a predetermined position for the initial cells.
You have two cell 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 that understands images.
The input must contain the image path.
It is very easy to design a custom image i.e. 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 colors 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 another 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 Boolean variables.
  • \(createFolder\) : create a folder in the disk to save information.
  • \(showAnimation\) : show the cell population animation. Warning : requires 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 name where results folder are stored in the disk.
You can use \(folderName =\) '\(Results\)' for example.

Output

Four types of output are generated.
  • raw data : all the useful information.
  • 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 frame rate (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\) : next event type.
  • \(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' information.
  • \(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 \(initialization\) function).
  • \(parametersFileName\) : parameters file name where the parameters are saved (see the \(initialization\) 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 in this folder.
  • \(parameters.txt\) : text file containing different simulation parameters and results.
  • \(data.mat\) : MATLAB file containing 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 sees 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 on GitHub : iGEM Paris Bettencourt 2015 under the GNU General Public License version 3.0. For more information concerning the model see the modeling page.