C-IMMSIM: the parameters
The model has many parameters. They can be sorted in three categories:
unknown values which we arbitrarily set to plausible values after performing a series of tests.
parameters that correspond to the initial conditions (i.e. the boundary conditions) and that determine the problem under investigation;
parameters whose value is known from standard immunology literature (e.g. [1]);
Moreover, since this model has been used in previous studies, most of the parameters have already been set [2,3,4,5,6,7,8,9,10,11]. A complete list of the parameter given in input to the simulator is reported below (with explanation) and in the same form of those contained in ASCII format in the package.
Arbitrary parameters
NBITSTR The bit-string length NBITSTR determines the repertoire size. It indicates the number of bits used to represent the molecules and the cells binding sites like cell receptors and antigen peptides and epitopes. It is usually equal to 12 corresponding to a potential repertoire of 2^{12}=4096 cell receptors;
minmatch Together with NBITSTR, the parameter minmatch that specifies the minimal number of matching bits that are required to have a non-zero probability to bind (see figure 1), determines the dimension of the subset of the whole repertoire that can be stimulated to grow when the system is challenged by an antigen. In fact, given the combination of bits that need to be matching over the NBITSTR possible, one can have up to {NBITSTR}\choose{minmatch} reacting clones of lymphocytes;
Affinity function. The probability to bind is a function of the Hamming distance
between the two binding sites of the interacting entities.
AffLevel this is the value of affinity (i.e. the probability to interact) between two binding sites whose match is minmatch;
PresentStr is the exponent in the formula used to determine the binding probability in the peptide-MHC match (in the antigen digestion and presentation procedure);
maxLocalFact: a cell that is duplicating creates a new cell with a probability that is decreased with the concentration of other cells in the same lattice point and is regulated by the parameter maxLocalFact;
Bystander The probability for a B or a TH to enter the mitotic cycle without direct cell-to-cell stimulation is computed as p = 1 - (1-Bystander)^{T_x} where T_x is the number of THs in site x that are in the DUPLICATION state (the extra requirement for a B cell to be stimulated to duplicate by the bystander effect is that it has to be in the PRESENTING_II state, that is presenting the antigen peptide with the MHC class II molecule.
Hole this parameter determines the artificial hole in the repertoire needed to see the effect of the hypermutation: by not allowing B cells with BCR (B cell receptor) with a match more than Hole bits to the single (it has to be just one!) antigen's epitope, one can observe a humoral response only by those B cells that have a BCR with a larger match that have been created by mutation. Usually, if one is not interested in the mutation process, Hole can be set to NBITSTR, i.e. no hole in the repertoiire, that is, complete repertoire. In that case the effect of the hypermutation is (as in reality) to increase the speed in searching for the matching clone for a mutating pathogen like, for example, the HIV-1;
AgMultFact this is the replication factor for the antigens that replicate as, for example, a bacteria. This value enters the replication algorithm according to the following formula Ag_x(t+1) = Ag_x(t) (1+AgMultFact) (i.e. AgMultFact in [0,1]).
IL2eff is a factor expressing the efficiency of Interleukin-2 in stimulating growth of the lynphocytes;
FullThymusSel is a flag (values yes or no) that specifies if the ThymusSelection procedure has to stop after Ninitial[_TH_] TH cells tried in the selection or has to continue until all Ninitial[_TH_] that satisfy the requisites imposed by the Thymic selection are found);
ThymEff represents the efficiency of the thymus in selecting non self-reactive thymocytes. In general the fraction of circulating auto-reactive TH and TC cells below 0.1%;
p_TH_Virus this is the probability for a virus (in particular the HIV-1) to infect a CD4 lymphocyte T helper. It is used to simulate HIV-1 infection and should be set to zero to disable this feature of the code (HIV-1 infection is not discussed in this user guide);
Parameters determining the initial conditions
microL this parameter is the system size in micro-liters of peripheral blood or, at convenience, a cubic micrometer of secondary tissue like a lymphnode. This parameter together with NBITSTR and minmatch fully determine the upper bound of RAM required by a simulation. The lattice dimension is automatically computed in a way that guarantees that by injecting a generic antigen, the system shows a normal primary humoral immune response which peaks in about 2-3 days and falls in less than a week. (This, although might sound as a rude assumption, is the best method that we can choose to set the lattice dimension given the arbitrary representation of the topology. In fact, the lattice is just a way to represent the concept of physical proximity of the cells during the interaction step of the simulation and should be considered as a working hypothesis.);
num_step is the number of time steps of the simulation. Each time step represents 8 hours;
Fc is a bit-string that specifies the shape of the constant region of the antibodies. It is used to simulate the Idiotypic Network. If Fc=-1 then the interactions Int_B_Ab and Int_B_IC are not executed and there is no formation of idiotypic interaction network;
NumMHCI is the number of MHC class I molecules one wants to represent inside a single cell;
MHCI1 ... MHCI_NumMHCI are the bit strings for the NumMHCI MHC class I molecules;
NumMHCII is the number of MHC class II molecules one wants to represent inside a single cell;
MHCII1 ... MHCII_NumMHCII are the bit strings for the NumMHCI MHC class I molecules;
NumSelfPep this is the number of self peptides used during the Thymus selection to define the self;
SelfPep1 ... SelfPep_NumSelfPep are the bit string for the NumSelfPep self peptides
NumAbPep this is used in the simulation of the Idiotypic Network;
AbPep1 ... AbPep_NumAbPep are the bit string for the NumAbPep peptides of the antibodies in the simulation of the Idiotypic Network;
Num_injs is the number of injections one wants to schedule during the simulation;
Inside is the number of bit strings (each corresponding to a peptide) to compose an antigen
Outside is the number of bit strings (each corresponding to an epitope) to compose an antigen;
RandomCarrier is a three-value flag used to make repeated injections of the same type but with a different epitope or peptide (used to simulate vaccination protocols in cancer treatments, not described here, see reference [12]);
TimeToInj for each of the Num_injs injections of antigens, one needs to specify the time step for the injection;
peptide1 ... peptide_Inside for each of the Num_injs injections of antigens, one needs to specify the peptides composing the antigen to be injected;
epitope1 ... epitope_Outside for each of the Num_injs injections of antigens, one needs to specify the epitopes composing the antigen to be injected;
Cont_Inj_Flag this is a flag. If it is on (i.e. equal to 1) then the same injection is performed every time step to simulate a massime chronic infection;
pRest_MA this is the probability that a macrophage enters the RESTING state;
Adjuvant this is the amount of adjuvant one wants to inject at the same time of the injection of the antigen. Note that in immunotherapies, the antigen injected is an immuno-stimulator and therefore the adjuvant helps the immune system to develop an therapeutic immune response. The adjuvant corresponds for example to the danger signal or IL-12 or IFN-gamma
p_MA_Virus this is the probability for a virus (in particular the HIV-1) to infect a macrophage. It is used to simulate HIV-1 infection and should be set to zero to disable this feature of the code (HIV-1 infection is not discussed in this user guide
p_DC_Virus this is the probability for a virus (in particular the HIV-1) to infect a dendritic cell. It is used to simulate HIV-1 infection and should be set to zero to disable this feature of the code (HIV-1 infection is not discussed in this user guide);
NmaxVirus this is the number of virus released by an infected cell when this bursts due to the viral load;
Parameters whose value is known from literature
pMutate it is the per-bit mutation probability for the antibodies. The hyper-mutation rate of antibodies is taken as the suggested value in [4], that is approximatively 10^{-4} x NBITSTR;
AbQty this is the number of antibodies molecules (or the equivalent concentration of them in suitable units) that are produced by a plasma B cell in a unit of time (in our case in a time step, that is, eight hours). Usually, the secretion rate of antibodies by plasma cells in terms of the resulting concentration is set equal to 10 ng/ml each eight hours;
p_MA_Ag is the probability for a macrophage to phagocyte an antigen;
p_MA_IC is the probability for a macrophage to phagocyte an immuno-complex. The rate p_MA_IC should be 4000-fold higher than p_MA_Ag [1] but this value, given other current settings, is not attainable;
p_DC_Ag is the probability for a dendritic cell to capture an antigen. DC affinity to antigen is usually taken six times greater than that of MA;
DupStep_B this is the number of time steps a B cells creates a copy of itself when duplicating;
DupStep_TH this is the number of time steps a TH cells creates a copy of itself when duplicating;
DupStep_TC this is the number of time steps a TC cells creates a copy of itself when duplicating;
The half-life of cells is known from literature. The half-life of memory cells is not given as a parameters but is dynamically computed during the simulation and for each cell separately (see the manual for more info). Those of immunoglobulins is about 23 days because we consider only type IgG.
Other information
On top of what said above on the way we set the parameters we have to add the following considerations.
First of all, those values are somehow constrained to the other parameters by the fact that we always require the humoral and cellular response (in terms of certain observable) to fall within a reasonable range of values. This is qualitatively granted by monitoring all entities during an immune response.
Secondly, the values are taken as the ones for which we can validate the model by running the special cases described in the section Model validation. By observing a correct behavior we can extrapolate by saying that the simulation conducted to pursue our study will also be constrained to follow a correct behavior. So, some argumentation go like the following: by taking a small value for MA or DCs affinity to the antigen, we do not observe an immune response because we block antigen presentation; by lowering the fraction of auto-reactive lymphocytes we get neither humoral nor cellular immune response; by increasing the half life of cells we get an unrealistic persistence of expanding clones of lymphocytes; by increasing the duplication rounds of stimulated cells we get an unrealistic clone expansion up to the saturation limit; increasing the simulation space, i.e. the number of ml of simulated blood, we recover the same behavior (in this sense the model is said to scale well) but then each simulation is proportionally more time consuming; changing the affinity law which determine the binding between entities results in a different affinity maturation dynamics, a problem which we do not want to address at the same time with the one we are studying (nevertheless we believe that the overall picture would not change dramatically). Lastly, the choice of bit-strings representing the MHC molecules, as the ones for the carriers is taken at random so to have a statistical sample of the space of all possibilities. By making a sufficiently large number of simulations, we can then compute averages values of the observable as described in the Result section.
As a final note it should be mentioned that since we are addressing the question of discriminating between protocols which differ, among other things, in the time between successive vaccine injections, the core parameters are those related to the average life of the cells and of the immunoglobulins. Luckily, these values are all known from the literature. The only exception is given by the half-life of memory cells. The question of how long a cell lives is very controversial and the idea that some cells become the memory of a previous infection remains to be proven. However, we adopt this as a working hypothesis and we overcome the difficulty of defining what is a memory cell by implementing a mechanism which automatically (and dynamically) changes the half-life of cells by applying a positive feedback to the half-life of each single cell on the basis of a successful binding; in other words, when a lymphocyte is useful because is actively involved in the immune response, then the stimulation is interpreted as a reinforcement of its usefulness to the immune system defense and its half-life is increased as a consequence. This is quite reasonable if we neglect phenomena like anergy. The result of this process is that the memory is formed by those cells that participated actively in the defense of the organism during the immune response.
The set of the input parameters, is reported below. This is considered the standard set of parameters, that is, these are the values used in all the simulations if not specified otherwise.
----------- Random Seed ------------------------------------
<1111> RS/* random seed */
<1> Generating logfile{0,1}
----------- Dimension determining params -------------------
<12> NBITSTR[even number]
<9> minmatch[NBITSTR/2, NBITSTR-1]
<1> #mL/* integer */
----------- Number of time steps----------------------------
<540> num_step/* a year is 1095 */
----------- B-IC Interaction -------------------------------
<-1> Fc string[-1, 2^NBITSTR-1]
----------- Various ----------------------------------------
<10> MaxLocalFact[0, 100]
<0.05> AffLevel[0.0, 1.0]
<0.5> PresentStr[0.0, 1.0]
<0.0> Bystander[0.0, 1.0]
<0.0012> pMutate [0.0, 1.0]
<10> Hole[minmatch+1, NBITSTR]
<0.1> pRemoveAg[0.0, 1.0]
<10> AbQty[0, 1000]
<0.01> p_MA_Ag[0.0, 1.0]
<0.05> p_MA_IC[0.0, 1.0]
<0.02> p_DC_Ag[0.0, 1.0]
<0.0> p_EP_Virus[0.0, 1.0]
<10.0> IL2eff [0.0, 1000.0] /* inv prop to division */
----------- MHC molecules ----------------------------------
<1> NumMHCI[1, MAX_NUM_MHCI]
<-1> MHCI1[0, 2^NBITSTR-1], -1=random
<1> NumMHCII[1, MAX_NUM_MHCII]
<-1> MHCII1[0, 2^NBITSTR-1], -1=random
----------- Thymus parameters ------------------------------
<0> FullThymusSel{0, 1}
<1000> ThymEff[0, THYMEFF]
----------- SelfPeptides & AbPeptides ----------------------
<1> NumSelfPep[0, NUMSELFPEP]
<398> SelfPep1[0, 2^NBITSTR-1]
<1> NumAbPep[0, NUMABPEP]
<0> AbPep1[0, 2^NBITSTR-1]
----------- Antigen related --------------------------------
<2> #inj Ag[1, MAX_NUM_INJS]
<1> Inside (peptide)[1, INSIDE]
<1> Outside (epitope)[1, OUTSIDE]
----------- Antigen injections -----------------------------
<0> RandomCarrier/* 0=no,1=norotation,2=carrierrotation */
<0> Time to inj ag[0, num_step]
<0>unharmful bacteria
<0.0>
<10000> Num Ag to inj ag[0, MAX_NUM_TYPE_INIT[_Ag]]
<2415> peptide [2600]
<0> epitope [4095]
<365> Time to inj ag[0, num_step]
<0>unharmful bacteria
<0.0>
<10000> Num Ag to inj ag[0, MAX_NUM_TYPE_INIT[_Ag]]
<2415> peptide [2600]
<0> epitope [4095]
----------- Cell Duplication -------------------------------
<4> DupStep_B[1, DUPSTEP_B]
<4> DupStep_TH[1, DUPSTEP_TH]
<4> DupStep_TC[1, DUPSTEP_TK]
----------- Various Flags ----------------------------------
<0> Cont_Inj_Flag{0, 1}
----------- HIV related ------------------------------------
<0.0> pRest_MA
<100> Adjuvant
<0.0> p_MA_Virus
<0.0> p_DC_Virus
<0> NmaxVirus/* 100 known by literature */
<0.0> p_TH_Virus/* this turns on HIV infection */
References (these are not updated)
1 Osborne BA Goldsby RA, Kindt TJ. Kuby Immunology, IV ed. W.H. Freeman and Company, New York, 2000.
2 P.E. Seiden and F. Celada. A model for simulating cognate recognition and response in the immune system. J. Theor. Biol., 158:329-357, 1992.
3 F. Celada and P.E. Seiden. A computer model of cellular interaction in the immune system. Immunology Today, 13:56-62, 1992.
4 F. Celada and P.E. Seiden. Affinity maturation and hypermutation in a simulation of the humoral immune response. Eur. J. Immunol., 26:1350, 1996.
5 D. Morpurgo, R. Serenth , P.E. Seiden, and F. Celada. Modelling thymic functions in a cellular automaton. International Immunology, 7:505-516, 1995.
6 F. Castiglione, M. Bernaschi, and S. Succi. Simulating the immune response on a distributed parallel computer. Int. J. Mod. Phys. C, 8:527-545, 1997.
7 F. Castiglione, M. Bernaschi, and S. Succi. A high performance simulatior of the immune response. Future Generation Computer Systems, 15:333-342, 1999.
8 S. Succi, F. Castiglione, and M. Bernaschi. Collective dynamics in the immune system response. Phys. Rev. Lett., 79:4493-4496, 1997.
9 M. Bernaschi, F. Castiglione, and S. Succi. Large-scale cellular automata simulations of the immune system response. Phys. Rev. E, 61:1851-1854, 2000.
10 M. Bernaschi and F. Castiglione. Design and implementation of an immune system simulator. Computers in Biology and Medicine, 31:303-331, 2001.
11 Castiglione F, Toschi F, Bernaschi M, Succi S, Benedetti R, Falini B and Liso A. Computational modeling of the immune response to tumor antigens: implications for vaccination. J Theo Biol, 237/4 pp 390-400 (2005)
