ENISI-MSM: A Jupyter Notebook repository from NIMML

ENteric Immunity SImulator (ENISI) Multi scale model (MSM), RRID:SCR_016918 (SciCrunch.org database).

This repository contanins all the relevant code and data for the following paper:

High-Resolution Computational Modeling of Immune Responses in the Gut (Gigascience. 2019 Jun 1;8(6))

Meghna Verma, Josep Bassaganya-Riera, Andrew Leber, Nuria Tubau-Juni, Stefan Hoops, Vida Abedi, Xi Chen, Raquel Hontecillas. Paper: https://www.ncbi.nlm.nih.gov/pubmed/31185494

Please cite our paper if you use the codes or learnt from our work

The text includes detailed instructions regarding - i) installing ENISI-MSM and it's dependencies, ii) running the program on a local system and on a server and iii) scripts used for the processing of the outputs generated from the code. Additionally, README.mkd in the /ENISI-MSM/Howtorunasimulation and /ENISI-MSM/Sensitivity-Analysis folders also provides detailed instructions on running simulation and sensitivity analysis respectively.

Installation

  mkdir ENISI
  cd ENISI
  git clone https://github.com/NIMML/ENISI-Dependencies 
  git clone https://github.com/NIMML/ENISI-MSM

Building ENISI-Dependencies

  cd "path-to-ENISI"/ENISI-Dependencies
  mkdir build
  cd build
  cmake ../
  make

Building ENISI-MSM

  cd "path-to-ENISI"/ENISI-MSM
  mkdir build
  cd build
  cmake -DENISI_MSM_DEPENDENCY="path-to-ENISI"/ENISI-DEPENDENCIES/install" ..
  make

Run the program

Running on the local system

Change the paths below in the run.sh file (can be located in the "path-to-ENISI"/ENISI-MSM/Howtorunasimulation folder).
- Path for mpirun in run.sh to be changed to your "path-to-ENISI"/ENISI-Dependencies/install/bin/ directory.
- Path for ENISI-MSM executable to be changed to the location of your ~/ENISI/ENISI-MSM/bin/ directory
Create a folder where the output files are to be saved (for e.g. OutputFolder) with the following file contents :
- config.props, run.props, model.props, CD4.cps and MregDiff.cps (All included in the "path-to-ENISI"/ENISI-MSM/Howtorunasimulation folder).
- Configurable parameter file - model.props.
- run.props and config.props are the configurable files where you can change -
  - Number of TICKS (that is a measure of computational time, i.e stop.at = number of TICKS) (run.props)
  - Size of the grid cell (run.props)
  - Path to output folder (config.props)
Run the executable -
```
../run.sh "path-to-OutputFolder"
```

Running on server

Install and build ENISI-Dependencies and ENISI-MSM on the server.
Create a folder to run the simulation and store the output files (for e.g. OutputFolder). The contents include:
- config.props, run.props, model.props, CD4.cps and MregDiff.cps and job.sh files (All included in the "path-to-ENISI"/ENISI-MSM/Howtorunasimulation folder).
- Configurable parameter file - model.props.
- The run.props and config.props are the files where you can change -
  - Number of TICKS (that is a measure of computational time, i.e stop.at = number of TICKS)
  - Size of the grid cell.
- The path-to-OutputFolder is provided in the CONFIG variable specified in the job.sh file.
Run the executable.
```
sh job.sh
```

Scripts

All the scripts and parameter sets are listed in "path-to-ENISI"/ENISI-MSM/Processing folder.

Parameter sets

"path-to-ENISI"/ENISI-MSM/Processing/ParameterSets folder contains the parameter files (model.props) to be used when running the program (refer to 'Run the program' section above) to reproduce the files used to plot the results in the paper (currently under review).
The files are named as model_*.props where "*" represents the different condition.
When running each simulation for the different condition, rename the file to model.props.

Code for figures in the paper

All the jupyter notebooks that create the figure in the paper are provided in the "path-to-ENISI"/ENISI-MSM/Processing/Figures.
The files are named as Fig*_Code.ipynb where "*" represents the figure number.

Other scripts

The bash and python scripts are provided in the "path-to-ENISI"/ENISI-MSM/Processing/Others folder. Each script has a comment section that decribes the usage, purpose and required location of the script.

The folder structure for the below scrips are as follows:

   ~/alloutputs/allRuns/setting0/run0

The alloutputs folder contains the collections of all outputs.
The allRuns folder (inside the alloutputs folder) contains the settings folder.
The setting folder corresponds to a different set of parameters.
The run folder corresponds to the replicates (for e.g. 10) for individual parameter set. (The run folder is similar to the folder created in Step 2 of running the jobs locally and on the server. The run folders include all the files provided in the "path-to-ENISI"/ENISI-MSM/Howtorunasimulation folder)
1. lp_code.py (can be located in any folder; the "path-to-lp_code.py" is required by the tsvcsv.sh).
2. tsvcsv.sh (to be located in ~/alloutputs/).
3. average_and_SD.py (to be located in ~/alloutputs/allRuns/setting0/).

The scripts for Sensitivity-Analysis and the steps are detailed in "path-to-ENISI"/ENISI-MSM/Sensitivity-Analysis/.