CellSium Readme

CellSium - Cell Simulator for microfluidic microcolonies

CellSium example simulation result

Front Matter

CellSium is a cell simulator developed for the primary application of generating realistically looking images of bacterial microcolonies, which may serve as ground truth for machine learning training processes.

Publication

If you use CellSium within scientific research, we ask you to cite our publication:

Sachs CC, Ruzaeva K, Seiffarth J, Wiechert W, Berkels B, Nöh K (2022) CellSium: versatile cell simulator for microcolony ground truth generation Bioinformatics Advances, Volume 2, Issue 1, 2022, vbac053, doi: 10.1093/bioadv/vbac053

It is available on the Bioinformatics Advances homepage at DOI: 10.1093/bioadv/vbac053 <https://doi.org/10.1093/bioadv/vbac053>.

Documentation

The documentation to CellSium can be built using Sphinx, or be found readily built at Read the Docs.

License

CellSium is available under the BSD license (see LICENSE.rst / license section).

Installation

Installation using pip

CellSium can be installed via pip, ideally create and activate an environment beforehand to install CellSium in.

> python -m pip install cellsium

Installation using conda

CellSium is available in the modsim Anaconda channel as well, using packages from the conda-forge channel. It can be installed with the following commands:

> conda install -c modsim -c conda-forge -y cellsium

Usage

Once installed, run CellSium via python -m cellsium, specifying the desired entrypoint and options, such as outputs. CellSium is built modular, various output modules can be activated simultaneously. To get an overview of the available options, use the --help switch. Furthermore, the main mode of setting tunable parameters are so called tunables, which can be set from the command line using the -t switches. A list of tunables can be shown using the --tunables-show argument.

> python -m cellsium --help
usage: __main__.py [-v] [-q] [-c CELL] [-p] [-w] [-o OUTPUT] [-h] [-m MODULE]
               [--Output {COCOOutput,CsvOutput,FluorescenceRenderer,GenericMaskOutput,JsonPickleSerializer,MeshOutput,NoisyUnevenIlluminationPhaseContrast,PhaseContrastRenderer,PlainRenderer,PlotRenderer,QuickAndDirtyTableDumper,SvgRenderer,TiffOutput,TrackMateXML,UnevenIlluminationPhaseContrast,YOLOOutput}]
               [--PlacementSimulation {Box2D,Chipmunk,NoPlacement}] [-t TUNABLE] [--tunables-show] [--tunables-load TUNABLES_LOAD] [--tunables-save TUNABLES_SAVE]

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output-file OUTPUT
  -w, --overwrite
  -p, --prefix
  -c CELL, --cell CELL
  -q, --quiet
  -v, --verbose
  -m MODULE, --module MODULE
  --Output {COCOOutput,CsvOutput,FluorescenceRenderer,GenericMaskOutput,JsonPickleSerializer,MeshOutput,NoisyUnevenIlluminationPhaseContrast,PhaseContrastRenderer,PlainRenderer,PlotRenderer,QuickAndDirtyTableDumper,SvgRenderer,TiffOutput,TrackMateXML,UnevenIlluminationPhaseContrast,YOLOOutput}
  --PlacementSimulation {Box2D,Chipmunk,NoPlacement}
  -t TUNABLE, --tunable TUNABLE
  --tunables-show
  --tunables-load TUNABLES_LOAD
  --tunables-save TUNABLES_SAVE

You can for example run a default simulation by just starting CellSium, the results will be shown interactively using matplotlib:

> python -m cellsium

For more in-depth usage examples, please see the examples section of the documentation.

Docker

An alternative to installing CellSium locally is running it via Docker. To run CellSium without interactive (GUI) elements, the following Docker command can be used, with parameters to CellSium being appended.

> docker run --tty --interactive --rm --volume `pwd`:/data --user `id -u` ghcr.io/modsim/cellsium

To use interactive (GUI) elements such as the PlotRenderer, an X server must be reachable; under Linux the following command can be used:

> docker run --tty --interactive --rm --volume `pwd`:/data --user `id -u` --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix ghcr.io/modsim/cellsium