Virtual Thymus Model

The virtual thymus model is a multiscale model of migration, proliferation, and differentiation of T cell precursors, as well as the thymic epithelial cells that make up the thymus in medaka fish (Oryzias latipes). For representing the cells, it uses a cell-based model with the overlapping spheres formalism. 

The first version of the model was developed to investigate the development of different proportions of αβ and γδ T cell subtypes [1]. The model has been further developed to investigate clonal dynamics of T cells and the introduction of lesioned clones [2].

Editing and running the model

The model has been implemented and simulated in the Multi-Scale Modeling and Simulation Platform EPISIM [3].

EPISIM consists of two software components: EPISIM Modeller and EPISIM Simulator. Source codes for these two software components are available at:

• EPISIM Modeller [4]: https://gitlab.com/EPISIM/EPISIM-Modeller (requires log in to GitLab to access)
• EPISIM Simulator [5]: https://gitlab.com/EPISIM/EPISIM-Simulator 

Binaries for EPISIM can be downloaded at: http://tigacenter.bioquant.uni-heidelberg.de/episim.html

At the time of writing this text (2024-06-14), the download links for the binaries on EPISIM's official website no longer work. Therefore, a copy of the binaries and source codes that were used to develop and simulate the Virtual Thymus Model have been uploaded to this repository.

Biomechanical Model

In EPISIM, the Biomechanical Model includes codes to define the model geometry, initial cell positions, and biomechanical interactions between cells. All of these are hardcoded in EPISIM Simulator [5]. The parts of the Biomechanical Model that were specifically developed for the Virtual Thymus Model can be found in the source code of EPISIM Simulator by navigating to:

EPISIM-Simulator/src/episimmcc/centerbased3d/tcellmedaka/

The codes for the initial cell distribution depend on parameters whose values can be changed dynamically before simulation start, e.g. to generate different distributions of thymic epithelial cells, or generate a starting population of thymocytes. These parameters can be changed either in the graphical user interface of EPISIM Simulator in the tab "Biomechanical-Model", or by providing a text file with the parameter names and corresponding values when launching the program via the command line.

To make these parameters also accessible to EPISIM Modeller, special build instructions can be given to the compiler of EPISIM Simulator to generate the "Model Connector Component" that can be imported into EPISIM Modeller. For further details on how this works and the software design of EPISIM, please refer to reference 6 (in German).

Cell Behavioral Model

In EPISIM, the Cell Behavioral Model represents the internal logic of each individual cell. To use a metaphor, it’s the “genetic code”, which during the simulation will result in context-dependent “expression” of selected submodels. The Cell Behavioral Model can be edited in the graphical user interface of EPISIM Modeller, which uses graphical programming to represent state transitions using a flowchart-type design.

The Cell Behavioral Model of the latest version of the Virtual Thymus Model is stored in the file Virtual_Thymus_Model_v2.zip. It comes pre-loaded with the necessary Model Connector Component (Virtual_Thymus_Model_MCC.jar).

Step-by-step instructions:

Installing EPISIM Modeller

(Windows)

• Unpack the contents of "EpisimModeller_Windows_Setup_64-bit.zip", then double-click on the unpacked executable file.
• Follow the instructions in the installation wizard.
• Double-click on the executable file EpisimModeller.exe to run the program.

(Linux)

• Unpack the contents of "EpisimModeller_Linux_64-bit.tar.gz"
• Execute the file "EpisimModeller" to run the program.

Importing the Cell Behavioral Model of the Virtual Thymus Model

• Open EPISIM Modeller.
  If this is the first time opening the program, close the welcome screen by clicking the "X" on the tab to access the regular graphical user interface.
• Click on “File > Import”
• Select “EPISIM Modeller Project“, then click “Next”
• Select the option “Select archive file”, then click “Browse…”
• Navigate to the location of the file “Virtual_Thymus_Model_v2.zip” and select it.
• Click “Finish”.
• The Cell Behavioral Model will now be loaded into the workspace and can be explored and edited via the graphical user interface.

The top-level submodel is called "start.mbe". Parameters pertaining to the Cell Behavioral Model, internal model variables, and some parameters of the Biomechanical Model can be inspected in "ModelParameters.data".

Compiling the Cell Behavioral Model into a binary that can be loaded into EPISIM Simulator

• Click on the 8th icon on the top left bar (alt text: "Transform the active modeling project into executable code") .
• Click on "Select"
• Scroll down and click on "start.mbe", then OK.
• Click on "Generate".
• Navigate to your desired directory and click on "Save".

If the above process fails, you may need to reload the Model Connector Component by clicking on Biomechanics > Link Biomechanical Model and selecting the Virtual_Thymus_Model_MCC.jar file provided in this repository.

Simulation

EPISIM Simulator integrates the multiscale Cell Behavioral Model with the Biomechanical Model and any implemented Partial Differential Equation (PDE) model, and executes the simulation while providing visualization.

Installing EPISIM Simulator

(Windows)

• Unpack the contents of "EpisimSimulator_Windows_Setup_64-bit.zip", then double-click on the unpacked executable file.
• Follow the instructions in the installation wizard.
• Double-click on the executable file EpisimSimulator.exe to run the program.

(Linux)

• Unpack the contents of EPISIM_Simulator_linux64bit.zip
• Execute "EpisimSimulatorStart.sh" in the command line.

Loading and running the simulation

• Open EPISIM Simulator
• Click on “File > Open EPISIM-Cell-Model”
• Navigate to the location of the file “Virtual_Thymus_Model_executable.jar” and select it (or use your own generated jar file created with EPISIM Modeller).
• To change Cell Behavioral Model parameters, use the tab “Cell-Behavioral-Model”.
• To change Biomechanical Model parameters, use the tab “Biomechanical-Model”.
• To change the PDE model of extracellualr IL-7 diffusion, use the tab "Diffusion-Model".
• Click on the play icon (bottom left triangle) to start the simulation.

References

1. Aghaallaei, Narges, et al. "αβ/γδ T cell lineage outcome is regulated by intrathymic cell localization and environmental signals." Science Advances 7.29 (2021): eabg3613. https://www.science.org/doi/full/10.1126/sciadv.abg3613
2. Tsingos, E., Dick, A. M., & Bajoghli, B. (2024). bioRxiv preprint https://doi.org/10.1101/2024.06.25.600590 
3. Sütterlin, Thomas, et al. "Bridging the scales: semantic integration of quantitative SBML in graphical multi-cellular models and simulations with EPISIM and COPASI." Bioinformatics 29.2 (2013): 223-229. https://academic.oup.com/bioinformatics/article-abstract/29/2/223/201876
4. EPISIM Modeller, commit 6429fcaa0037372eb57f7c1c454ad4cec9a3c115. https://gitlab.com/EPISIM/EPISIM-Modeller
5. EPISIM Simulator, commit eb8678756122fa14df33065af927839aa21b57b3. https://gitlab.com/EPISIM/EPISIM-Simulator 
6. Sütterlin, Thomas. "Entwurf und Realisierung eines computergestützten Systems zur in silico Modellierung und Simulation von Epithelgeweben." (2016). Doctoral dissertation. Heidelberg University https://katalog.ub.uni-heidelberg.de/titel/67985535