Team:Paris Bettencourt/Software


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 programm.
  • \(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 differenciated 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 differenciated 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 differenciated 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 programm, 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 differenciated 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 differenciated 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 differenciated cells (red).
Example of predetermined cells initial position with mother cells (black) and differenciated 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 programm, 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 programm, 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 programm.
  • \(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

Graphs

Animation

Examples

Time evolution of mother cells, differentiated cells and vitamin

Graphs
Animation

Vitamin optimization

Deterministic and stochastic vitamin optimization comparison

Programm explanation

Step by step

Parallel computing

Conclusion