NetLogo banner

 Contact Us

 Modeling Commons

 User Manuals:


NetLogo User Community Models

(back to the NetLogo User Community Models)


by Pere-Joan Cardona and Clara Prats (Submitted: 03/30/2016)

[screen shot]

Download TBPatch
If clicking does not initiate a download, try right clicking or control clicking and choosing "Save" or "Download".(The run link is disabled because this model uses external files.)


The objective of this Individual-Based Model is to analyse and understand the influence of four factors, namely the tolerability of the infected alveolar macrophage (BLTOL), the anti-Th17 response, bacillary drainage and the encapsulation process, on the progression towards active tuberculosis (TB).


The fundamental entities in this model are alveoli and bacilli. The IBM has been built using the NetLogo structure (Tissue and Wilensky 2004) based on patches (spatial cells) and turtles (individuals). Thus, patches represent individual alveoli and turtles represent individual bacilli. The time step is 1 hour, and the simulated period is 42 days from initial infection.

### Patches or spatial cells

A grid of 46x46 alveoli is defined, each alveolus being represented by a spatial cell or patch (in humans, 0.3 mm). The whole grid is equivalent to a secondary lobule.
Each patch initially contains a single alveolar macrophage (AM) whose state is determined by the evolution of the infection. Patch variables are mostly related with the characteristics of the AM and other cells that they contain, each state being represented by a specific colour as follows:

- White patch: alveolus with the single initial AM;
- Black patch: alveolus whose AM has been destroyed by the bacilli;
- Blue patch: alveolus whose initial AM has been replaced by another one from the interstitium after its destruction, i.e. without the need for extravasation caused by an inflammatory response to enter the cell;
- Violet patch: alveolus with an activated AM (aAM);
- Pink patch: alveolus that has been occupied by polymorphonuclear neutrophils (PMNs) (neutrophilic infiltration); and
- Dark pink patch: necrotized alveolus (alveolus with caseum).

In addition, a brown patch defines the presence of fibroblasts, i.e. the capsule.

### Turtles or individuals

Bacilli are the mobile agents (individuals) and their properties are related to their state within the alveolar growth cycle, which is also identified with colours:

- Initial bacillary load (Ibac, in blue)
- Bacilli growing intracellularly (Ibac, in red)
- Non-growing extracellular bacilli (Ebac, in green)
- Growing extracellular bacilli (Ebac, in brown)
- Dormant bacilli (Dbac, in orange)
- Killed bacilli (Kbac, in yellow).

When growing, the time within the growth cycle (reproduction time) is also controlled.

### Global variables

The global variables are mostly related to the bacillary load of the system, as well as the PMN and aAM concentration and spatial distribution. A further important global variable is related to activation of the immune response, whicht can acquire values of 0 (no immune response yet) or 1 (immune response already activated).

### Process overview and scheduling

The simulation starts with definition of the initial configuration, in which a certain number of intracellular bacilli are randomly distributed in the space. The initial bacillary load can be chosen by the user. All alveoli are set to the initial single AM state (white). If encapsulation is considered, the limits of the space are changed to the encapsulated state (brown). The model assumes discrete time steps of 1 hour, as mentioned. Each hour, all individuals execute a series of actions, and their variables are updated immediately. The characteristics of the patches are also immediately updated as a consequence of evolution of the infection. Patches (i.e., alveoli) are submitted to actions that may affect the bacilli they contain.

The actions for individuals are, when possible: reproduce (either intracellularly or extracellularly), become extracellular when the macrophage is destroyed, be drained, be killed by the immune response, and re-infect. The actions for patches can be distinguished between those that affect the space and those that affect the AM contained in patches. The former include get encapsulated and get necrotized, whereas the latter (actions concerning the AM) are, when appropriate, be destroyed by intracellular bacilli growth, be replaced after destruction, and be activated by inflammatory response. Finally, when the global bacillary load exceeds a certain threshold, the immune response is activated everywhere. Global variables are updated at the end of each time step.

A detailed description of all submodels can be found in Cardona & Prats (2016).


The following sliders can be used to select the characteristics and initial conditions of the system to be simulated.

- Initial-bac: used to define the initial bacillary load of the challenge. Each initial bacillus will be located randomly.

- Doubling-time: refers to the doubling-time of the bacilli.

- Max-Ibac: this is the maximum bacillary load tolerated by the AM. Once reached, the cell is destroyed. This parameter defines the bacillary load tolerability (BLTOL).

- Ebacs-PMN: this is the bacillary load required to attract infiltration of the alveoli by PMNs.

- Bacs-immunity: the total bacillary load in the grid required to trigger the immune response.

- Immunity-Kbac: chance of killing intracellular bacilli once an AM is activated.

- Inflamm-attract: global number of bacilli that should be around an infected AM to be activated once the immune response has been triggered.

- Max-harbour: maximum bacillary load that can be supported by an alveolus. Once this number is reached, the induced inflammatory response has attracted sufficient cells (mainly PMNs) that it is finally destroyed, thereby inducing necrosis, and all the immerged bacilli become dormant (Dbac).

- Drain-alveoli: maximum distance that can be reached by Ebac or Dbac every time-point, representing the breathing amplitude (BAM).

- Drain-tissue: the drainage capacity of Ebac or Dbac once they are located in PMN-filled alveoli, thus representing the BAM. We have considered this to be equal to Drain-alveoli/2 in all cases.

- Reinfect: this is the probability of distant drainage of Dbac, thus representing the process observed once immune response is reached by those old aAMs that become foamy macrophages (FMs). These FMs drain out of the lesions (plenty with Dbac) and some of them destroyed on the way to reaching the upper bronchi.

- Drain-Dbac: this is the distance to which Dbac are drained as a result of the reinfection phenomenon.

- Anti-Th17 factor: to reduce the effect of the Th17 response, which favours the entry of PMNs into the different lesions once the immune response is reached.

- Encapsulation-ratio: this defines the ability to encapsulate, although we have defined only two conditions: when no encapsulation is considered, the capsule frame is eliminated from the program. It is only informed.

The simulation may be observed at the interface, but a text file is also generated with the evolution of most relevant variables.


The world shows the tuberculosis infection dynamics in a secondary lobule, each patch representing a single alveolus. Depending on the input parameters, the user can observe how the infecion is controlled by the hoset or how it evolves towards an active disease. In fact, four types of lesions may be observed:

- A: Proliferative in progression, with low numbers of Dbac and a high proportion of Kbac.
- B: Proliferative controlled, when there is a very low number of Dbac and a very high proportion of Kbac.
- C: Exudative, based on a large necrotic centre surrounded by an active ring of alveoli filled with PMNs and massive presence of Dbac.
- D: Exudative controlled, with smaller lesions than in type C surrounded by a ring of aAMs.


The user may explore the effect of these sliders:

- Max-Ibac or BLTOL: 16, 32 and 64 bacilli, as obtained from experimental data. Related with the tolerability of the infected AMs to a certain bacillary load.
- Drain-alveoli or BAM: 0.1, 0.2 and 0.3 patch/h (equivalent to maximum velocities of 0.03, 0.06 and 0.09 mm/h, respectively). Related with the the breathing amplitude, that is smaller in the upper lobe of human lungs.
- AntiTh17-factor: 1 and 10. Related with the quality of the immune response.
- Encapsulation: 0 (no encapsulation) and 1. Related with the structure of the parenchyma.


This IBM was designed and implemented by Dr. Pere-Joan Cardona (Unitat de Tuberculosi Experimental (UTE). Fundació Institut d’Investigació en Ciències de la Salut Germans Trias i Pujol, Universitat Autònoma de Barcelona, CIBERES, Badalona, Catalonia, Spain) and Dr. Clara Prats (Escola Superior d'Agricultura de Barcelona, Departament de Física. Universitat Politècnica de Catalunya – BarcelonaTech, Castelldefels, Catalonia, Spain).

### References

Cardona, Pere-Joan and Clara Prats. 2016. "The small breathing amplitude at the upper lobes favours the attraction of polymorphonuclear neutrophils to Mycobacterium tuberculosis lesions and helps to understand the evolution towards active disease in an individual-based model". Frontiers in Microbiology 7:354. doi: 10.3389/fmicb.2016.00354.

Lee, Jinhee, Heinz G Remold, Michael H Ieong, and Hardy Kornfeld. 2006. “Macrophage Apoptosis in Response to High Intracellular Burden of Mycobacterium tuberculosis Is Mediated by a Novel Caspase-Independent Pathway.” Journal of Immunology (Baltimore, Md. : 1950) 176 (7): 4267–74.

Tissue, Seth, and Uri Wilensky. 2004. “Netlogo: A Simple Environment for Modeling Complexity.” In Proceedings of the International Conference on Complex Systems, 1–10. Boston: The Pennsylvania State University.

(back to the NetLogo User Community Models)