***************************
* USER MANUAL FOR MiStImm *
***************************

- This program package (MiStImm - Microscopic Stochastic Immun System Simulator) is developed by Csaba Kerepesi, Tamás Szabados, Gábor Szabados, Tamás Kiss, Kristóf Hörömpöly, Endre Szecsei.
- For any support and contact please write here: kerepesi@sztaki.hu (Csaba Kerepesi)

***Licence***

- MiStImm is a free software: you may redistribute it and/or modify its under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.
- MiStImm are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details (http://www.gnu.org/licenses/).
- For any other inquiries send an email to Csaba Kerepesi: kerepesi@sztaki.hu

***How to cite***

- Please cite the following publication:

Kerepesi C, Bakács T, Szabados T. 
"MiStImm: an agent-based simulation tool to study the self-nonself discrimination of the adaptive immune response." 
Theoretical Biology and Medical Modelling, 16:9 (2019), https://doi.org/10.1186/s12976-019-0105-5

***Downloading***

- Download link https://github.com/kerepesi/MiStImm/archive/master.zip
- Unzip the files

***Short introduction: the main parts***

1. MiStImm_marc25_2019.c: A C program and an exe file for simulating the microscopic stochastic model of the humoral immune development.
2. indat1: A text file containing the input parameters of the above MiStImm_marc25_2019 program and their short explanations.
3. outdat-<number> and out2-<number>: The output generated by the MiStImm_marc25_2019 program.
4. indrawc_jul23_2016.pas: A Pascal program and an exe file for generating figures (visualization) from the above outdat file:
	- time diagram of the numbers of the different cells and proteins, 
	- developing antigen lattice,
	- developing peptide lattice.
5. Out2Vizu.pl: A Perl program for generating figures (visualization) from the above out2 file:
	- time evolution of weak, intermediate and strong reproductions.

*** Quick start for Windows step by step ***

0. Download MiStImm (https://github.com/kerepesi/MiStImm/archive/master.zip), unzip, and enter the main folder 
1. Run MiStImm_marc25_2019.exe (when it finished it will generate a file with the prefix "outdat")
2. Run indrawc_jul23_2016.exe
3. Choose the number of the newly generated outdat file (outdat-<number>-1956), for example: "7".
4. Choose background color (w/b). For example "b" (black). 
5. For the time diagram in a bird's eye view choose the option 1 ("Time diagram") by typing "1" then make the following settings: 
	- First time instant = 0
	- Last time instant = 4000
	- Time step = 8
	- Vertical unit = 4000
	- Delay = 1. 
6. Press "Enter" and then choose the option "1" ("actual file again")
7. For the time diagram in a closer view choose "1" ("Time diagram") then make the following settings: 
	- First time instant = 2900
	- Last time instant = 4000
	- Time step = 2
	- Vertical unit = 200
	- Delay = 1
8. Press "Enter" and then choose the option "1" ("actual file again")
9. For the developing antigen lattice or the developing peptide lattice choose option "2" or "5", respectively. 
	- First time instant = 0
	- Last time instant = 4000
	- Plotting with (p)oints: press "p"
	- Time step = 2
	- Delay = 10
	- You may freeze the screen and then start again by pressing the space bar. 
10. Press "Enter" and then choose the option 3 ("exit")

*** Workflow for multiple simulation (running in Windows cmd) ***

- Requirements: Install Perl for Windows if it needed (e.g. download from http://strawberryperl.com/)
- delete all earlier output files from the start directory
- perl Multirun.pl
- create an out directory (e.q.: md ERS-nr350-div50)
- move outdat-* ERS-nr350-div50
- move out2-* ERS-nr350-div50
- cd ERS-nr350-div50
- dir /b outdat-* > ERS-nr350-div50-outdatlist.txt
- perl ..\AnalyzerOutdat.pl ERS-nr350-div50-outdatlist.txt 50
- perl ..\CountStat.pl ERS-nr350-div50-outdatlist.txt-AnalyzerOutdat-50.txt

*** Indat1 changes to convert ERS model to CRS model ***

- 1-1(comptype)=0->1
- 2-3(mediumreprod)=1->0
- 2-4(weakr)=1->0
- 8-6(tauthm0)=5->30 

*** Computing the Fisher's exact p-values ***

- download R for Windows (https://cran.r-project.org/bin/windows/base/)
#Package info: https://stat.ethz.ch/R-manual/R-devel/library/stats/html/fisher.test.html
Ratio <-
matrix(c(307, 225, 193, 275),
       nrow = 2,
       dimnames =
       list(c("Win", "Loss"),
            c("ERS", "CRS")))
fisher.test(Ratio,  alternative = "greater")
#Simplier version:
fisher.test(rbind(c(307,225),c(193,275)), alternative="great")$p.value

*** Some help to indrawc_jul23_2016.exe ***

- In "1. Time diagram" menu option: 
	- one time step is 550 time unit
	- the program draws 4.5 vertical units
	- choose time step 1
	
*** Converting "outdat" outpu files into three separate csv files by Outdat2CSV.py ***

- python Outdat2CSV.py outdat-1518016285-1956-respERS

*** Converting "out2" output files into a csv files by Out2toCSV.pl ***

- perl Out2toCSV.pl out2-1550497283-1956-respERS 0 4000 20 > out2-1550497283-1956.csv

*** Compilation of the C program MiStImm_marc25_2019.c:

- in Windows: Dev-C++ 5.11
- in Linux (gcc 5.4.0): gcc MiStImm_marc25_2019.c -lm -o MiStImm_marc25_2019