Skip to content

Home

Jump to bottom
Gaelle Letort edited this page Nov 26, 2018 · 22 revisions

Presentation

PhysiBoSS (from the merging of PhysiCell and MaBoSS) is an adapted version of PhysiCell (see physicell.mathcancer.org ) to integrate in it Boolean network computation inside each cell. PhysiCell is developped in Paul Macklin's lab (mathcancer.org). MaBoSS and PhysiBoSS are developped in the Computational Systems Biology of Cancer group (sysbio.curie.fr)
Code is written in C++ and open-source. In PhysiCell, there are two main part: BioFVM part which handle the diffusion/production of molecules (e.g. oxygen) and the PhysiCell part that handle the cells' physics. A cell can have a "classic" implementation of the cell cycle (adapted from PhysiCell1.0 initial implementation), or a cell cycle progression mode determined by a Boolean network assigned to each individual cell by MaBoSS. Interestingly, this framework could be easily adapted to other networks or implementations.


PhysiCell-MaBoSS example


3 executables are proposed in the PhysiBoSS release: PhysiBoSS which handles the actual simulation, PhysiBoSS_CreateInitTxtFile which offers the possibility to automatically generate an initial state of the simulation file and PhysiBoSS_Plot which allows the user to create an svg file showing a snapshot of the simulation at a specific time point.

Overview:

How to use:

Examples

Future development

Availability/License

References/Links

How to use

Compiling PhysiBoSS

PhysiBoSS should be compatible with most Linux and MacOS systems that have a C++ compiler with OpenMP support. For Windows operating system or others non compatible systems, a Docker version is available here.

First, clone the PhysiBoSS repository, and compile it by going into the PhysiBoSS directory and type make install. The executables will be created in the bin directory if all goes well. It requires a recent version of c++, at least c++11. PhysiBoSS can be compiled in Debug, Release or Proliling modes, to set in the Makefile file, default is Release mode which is the fastest one.

Summary of the steps to download and install PhysiBoSS on Linux system: 

git clone https://github.com/gletort/PhysiBoSS.git
cd PhysiBoSS
make install
If the compilation fails, refer to this documentation page for more explanations.

To generate/update code-specific documentation, type 'make doc' in the main directory. The documentation is generated with doxygen, which can be configured in the Doxyfile file present in this directory. It will generate the documentation files in the 'doc/html' folder (initially empty in the repository). You can visualize it in any browser by opening the 'doc/html/index.html' file.

Running one simulation

An 'output' and 'microutput' directories should be present in the main directory of the simulation from which the executable will be called. Ideal structure would be to have a simulation directory containing the parameter file (e.g. parameter.xml), the initial configuration file (optional, e.g. init.txt) and the outputs folder. Informations files will be created in this directory (report.txt). Information on how the simulation is running (initialisation completed or not, current time, wall time) are printed to the terminal, we redirected them to the file msg.txt when running them using an automated script. Report.txt gives a quick summary of the simulation, with the number of cells that divided or died in between output times. In the folder 'output', txt files named 'cells_' followed by the time value are generated during the simulation, containing the current cells states (position/size/cycle state).

Simulation organization

Input parameter file

XML format is used for input parameter file, as proposed in the MultiCellDS standardization initiative (see here ). To parse the xml files, we integrated in our code the Tinyxml2 files, developed by Lee Thomason (website ) and freely available. In the current version, we have 4 main parts: a set of parameters defining the simulation features (time steps, spatial limits..), a set of parameters defining the cell properties (one for each cell strain to be simulated), the definition of the network parameters and a set of parameters to define the initial configuration (either a geometry specification or input files names).

Example of a parameter file (with only few parameters shown): 

<?xml version="1.0" encoding="UTF-8" ?>

<simulation>
<time_step> 0.2 </time_step>
<mechanics_time_step> 0.1 </mechanics_time_step>
....
</simulation>


<cell_properties>
<mode_motility> 1 </mode_motility>
<polarity_coefficient> 0.5 </polarity_coefficient>
...
</cell_properties>


<network>
<network_update_step> 10 </network_update_step>
...
</network>


<initial_configuration>
<load_cells_from_file> init.txt </load_cells_from_file>
...
</initial_configuration>

Complete examples of parameter files are given with the release of PhysiBoSS.

Create initial file

Simulation can be loaded from a given initial file containing the position of all initial cells, their state, size... With PhysiBoSS code, an executable PhysiBoSS_CreateInitTxtFile is given, which allows the user to create a .txt file containing those informations for given parameters and chosen modes (e.g. a sphere of radius 300 µm). See the page PhysiBoSS_CreateInitTxtFile for more informations on what it can do and how to use it.

It's also possible to create a custom initial file from a binary image like it was done to generate the initial state of the example image above.
For this, we can use use an output of a previous simulation as the input initial file or build our own using semi-colon separated (';') columns such as: Time;ID;x;y;z;radius;volumetotal;volumenuclearsolid, etc. Additionally, we have made an R script that generates such a file from the list of positive pixels in a binary image (that can be generated with ImageJ) available here.

Plot a given time point

The executable PhysiBoSS_Plot given with the release allows the user to plot a specific time point of the simulation after it has run, directly from the command line. The time point must have been saved in the 'output' directory, and the plot will be a .svg file. Several options can be specified to PhysiBoSS_Plot, as can be seen here

Visualization

To visualize time evolution of 3D simulation results, we used the software Paraview which allows high flexibility and interactive viewing options. We provide within PhysiBoSS release several paraview state files to directly set-up the visualization of PhysiBoSS output files on Paraview. See the image below for an example of how a typical PhysiBoSS result looks in Paraview with our state files:

Visualization with Paraview

If you have issues using our state files or if you want to modify the initial set-up, the steps to visualize the output files as spheres in Paraview are explained here

Examples

  • Step by step simulation of a sphere of 100 µm radius of active cells, under TNF injection: see here.
  • Step by step simulation of a cell population with initial 'Hello World' shape, under TNF injection: see here.
  • Step by step simulation of cell sorting by differential adhesion, see here.
  • Step by step simulation of a cell population composed of 2 different strains see here.
  • Step by step simulation of a cell population composed of 3 different strains see here.
  • Step by step simulation of a cell population surrounded by degradable ECM, constraining the growth of the population see here.

Future development

  • Extension of the possible inputs/outputs between PhysiCell and MaBoSS network.
  • Improvement of PhysiBoSS outputs: format, visualization, analysis
  • Development of a detailed fiber-shaped extra-cellular matrix representation.
  • Implementation of graphical interface.

Availability/License

PhysiBoSS is totally open-source, in the hope that it will be used by other teams and improved and developped by other users. If you are interested in working with/on it, please don't hesitate to contact us.

All source code is freely available and can be modified by third-parts. Please, cite the original publications of PhysiBoSS and PhysiCell if you use it. Refer to the licenses in 'Licenses' folder of this repository for more informations.

References/Links

For PhysiCell:

  • Paul Macklin's lab website
  • PhysiCell publication: A. Ghaffarizadeh, S.H. Friedman, S.M. Mumenthaler, and P. Macklin, PhysiCell: an Open Source Physics-Based Cell Simulator for 3-D Multicellular Systems, bioRxiv 088773, 2016. DOI: 10.1101/088773.
  • BioFVM website
  • BioFVM publication: A. Ghaffarizadeh, S.H. Friedman, and P. Macklin. BioFVM: an efficient, parallelized diffusive transport solver for 3-D biological simulations. Bioinformatics, 2015.
    For MaBoSS:
  • MaBoSS website
  • MaBoSS publication: Stoll G, Viara E, Barillot E, Calzone L. Continuous time Boolean modeling for biological signaling: application of Gillespie algorithm. BMC Syst Biol. 2012 Aug 29;6:116. doi: 10.1186/1752-0509-6-116.
  • Our team
  • PhysiBoSS publication: Letort G, Montagud A, Stoll G, Heiland R, Barillot E, Macklin P, Zinovyev A, Calzone L . PhysiBoSS: a multi-scale agent-based modelling framework integrating physical dimension and cell signalling. Bioinformatics, bty766, doi:10.1093/bioinformatics/bty766


    • Author
    Contact for comments/questions:
    Gaelle Letort, Institut Curie, U900.
    [email protected]

contact: [email protected]

Clone this wiki locally