Guides‎ > ‎


BehaviourComposer: ignore everything before this.
February, 2013 version.

Here we will model a disease by building interactions of individuals rather than modelling mathematically with variables that represent entire populations. This is variously called Individual-based modelling (IBM) or Agent-based modelling (ABM).

In the first part (1-6), you will build a model equivalent to the SIR model (Susceptible, Infected, and Recovered). Next we model vaccination and explore the influence of social heterogeneity on the spread of diseases. In the final part of the practical you'll model a vaccination policy that targets super-spreaders.  This would be very hard to model analytically with equations that model populations.

Please go through the instructions carefully, step-by-step. There might be slight differences depending upon the web browser that you are using. You can use the browser's back and forward buttons to undo and redo. You can refresh the page to restart everything (only the open tabs will be lost -- your model will be restored).

Everything you'll need to construct the model is in this page. If you want to explore other behaviours visit the library of micro-behaviours.

Getting started

You'll be constructing the IBM using a tool called the BehaviourComposer that you access via a web browser. The software enables you to build a computer model by pulling together (or composing) blocks of computer code called micro-behaviours - web pages that contain NetLogo code and explanatory text. 

  1. First, you might find it easier to go through this guide using the split screen functionality. Scroll down to the bottom of this page and click on the check box labelled Split screen between this panel and everything else
  2. Now click on the INITIAL MODEL button and select Replace current model from the menu. This will load a model containing only a population of susceptible individuals and some technical machinery. This model has no infected individuals nor a mechanism for spreading an infection. You'll build on this initial model in the steps below.

Explore the initial model

The micro-behaviours you have just brought into the Build area of the BehaviourComposer can be compiled into a computer program using the Run  tab. Clicking this tab causes the BehaviourComposer to strip the NetLogo code from each micro-behaviour web pages and combine the code into a single computer program. The program runs inside a Java Applet. 

    Image of composer panel
    Image of run panel
    You compose your model by assembling micro-behaviours Code embedded in each micro-behaviours is assembled into a computer program. The program is served to your browser as a Java applet.

  1. Click on the Run tab in the Composer Area
  2. Your browser may ask you to allow the Java plugin to run. Please confirm this request.
  3. Once the Applet has loaded (might take a few seconds the first time) click on the SETUP button to initialise the model. 
  4. Change the slider labelled the-initial-susceptible-population and click on the SETUP button again to see what happens. 


  • To change the slider by small increments use the mouse to click on the slider to the left or right of its current value.
  • Only the Person prototype is an agent within the model, the others contain micro-behaviours that support the model or create graphs and sliders.

Create some infected individuals

  1. Open the Initial infection cases micro-behaviour web page (by clicking this link) and add it to the Observer prototype by:
    1. Click on the button at the top of the page labelled Initial infection cases 
    2. Select the menu item Add to a Prototype which will take you to the Composer tab
    3. Click on the upper area of the prototype called Observer to drop the Initial infection cases micro-behaviour onto the Observer prototype
  2. Click the Run tab in the Composer Area and you'll see an infected individual displayed in yellow after clicking the SETUP button. 
  • It is important that Infect initial cases be added to a prototype with only one instance (e.g. Observer) since it selects the-initial-infected-population number of individuals from the set of Persons and sets their state to infected and hence should only happen once.

Create a social network

Rather than model perfect mixing of individuals within the population we will model a network where each person has a limited number of contacts. Here we model each individual to have the same number of potential contacts, called acquaintances. Diseases can be transmitted between individuals that are acquaintances in our model.

  1. Open the Constant social network micro-behaviour web page and add it to the Observer prototype (the position in list does not matter). This gives every individual the same number of acquaintances.
  2. Run your model in the Composer Area and click the SETUP button. You should see grey lines that represent the acquaintance relationships between individuals.
  • You may wish to take some time to read the micro-behaviour pages you add to your model. The micro-behaviour you just added has important information about how the NetLogo code works e.g. see the section "How this works" at the bottom of the page.

Spread the infection

  1. Add the Contact acquaintances micro-behaviour to the To do when infected prototype.
  2. Now for one of the more tricky actions  (at least to explain) - adding a micro-behaviour to a list inside another micro-behaviour:
    1. Click the Contact acquaintances micro-behaviour you just added and select Open As Tab from the menu
    2. Inside the Contact acquaintances micro-behaviour page you will see the Possibly become infected micro-behaviour - click it and select Customise from the menu that pops up. 
    3. Now open Change colour of link with infector micro-behaviour, click on the button at the top of the page and select the menu item Add to a list
    4. Go back to the Possibly become infected micro-behaviour and click on the Behaviours list to add it to the list inside this micro-behaviour. (You should see something like the screenshot below.)

Run your model from the Composer Area, click SETUP then GO and you should see the infection spread. The links that transmitted the disease should turn red because you added Change colour of link with infector. The model is programmed to stop when either no one is infected or no one is susceptible. You can manually stop the simulation by either pressing the PAUSE button or pressing GO a second time.

  • Contact acquaintances works by multiplying the value from the-encounter-fraction slider with the number of acquaintances to determine the individual's contact rate. Since at this point we are modelling a population where every individual has the same number of acquaintances the contact rate is a constant and is very similar to the aggregate SIR model's contact rate. If the value is not an exact integer then the fractional part is used to determine the odds of contacting an additional person. E.g. a contact rate of 1.2 will contact one acquaintance 80% of the time and two 20% of the time. The odds of a contact between an infected and susceptible person resulting in a new infection is determined by the-infection-odds slider.

Add recovery

  1. Add the Schedule recovery micro-behaviour to the To do when infected behaviour list in the Composer Area
  2. Run your model, click the SETUP and GO buttons.
  • The Schedule recovery micro-behaviour models recovery by adding three micro-behaviours that change the state, change the display colour, and stop contacting acquaintances. Of course, real people will continue to contact people after recovery but it will have no effect on the spread of the disease. 
  • In reality when someone is infected there is, of course, no mechanism that sets a timer for when the person will recover. Since we are modelling recovery as a process that does not depend upon any interactions or later events (e.g. taking a drug) this is a simple way of implementing recovery that is equivalent to more detailed modelling. 
  • Note that graphs are being produced when you run the model - you may need to  scroll down or move the divider to see it.

Add vaccination

Next we model a public health authority with only a limited amount of a vaccine. 

  1. Add the Randomly vaccinate a proportion of the population and log event  micro-behaviour to the Public Health Authority prototype. 
  2. Run your model and experiment with different values. Even when all the parameters are left unchanged do you see different outcomes for different runs?
  • Depending on the value set on the-fraction-vaccinated slider a random fraction of the population will be vaccinated. This is modelled as setting the state to vaccinated (instead of susceptible) and changes the colour used to display the individual to green.

Build a different social network

In reality, individuals differ in the number of other individuals with whom they are likely to be in infectious contact. Here we shall investigate how different networks can affect the spread of a disease (note, the average number of contacts will remain the same). 

  1. Go to the Composer Area and click on the Constant social network micro-behaviour and select Inactivate from the menu. 
  2. Add the Power law social network micro-behaviour to the Observer prototype.
  3. Add the Size proportional to number of acquaintances micro-behaviour to Person. Inactivate the Small size micro-behaviour.
  4. Run the model and click SETUP a few times to see a variety of starting conditions.
  • The Power law social network micro-behaviour implements a power law distribution of the number of acquaintances each individual has i.e. a some have many acquaintances while most have few. 
  • The power law distribution approximates the situation in sexually transmitted diseases such as HIV where some individuals have many sexual encounters while others have very few or none. 

Using the model to study different approaches to vaccination

In the Public Health Authority prototype there is a micro-behaviour called Vaccinate random proportion of population which, as the name suggests vaccinates a proportion of the population randomly so that these individuals do not become infected. This behaviour can be contrasted with the  Vaccinate most highly connected individuals micro-behaviour (add it to the  Public Health Authority prototype!) to see the effect of targeting vaccination towards the most connected individuals in the network. 

Conduct four sets of experiments to allow us to contrast targeted and random vaccination in the different social networks:
  1. Random vaccination of the constant social network
  2. Targeted vaccination of the constant social network
  3. Random vaccination of the power law social network
  4. Targeted vaccination of the power law social network

Make sure the slider settings are:
  • initial susceptible population = 100
  • initial infected population = 1
  • infection odds  = 0.1
  • encounter fraction = 0.25
  • fraction vaccinated = 0.2
  • average recovery time = 20
Record the number of recovered individuals when the simulation stops i.e. when there are no longer any infected people and the pathogen has stopped spreading. Do this 5 times for each experiment. 
The table below summarizes what you need to do to the micro-behaviours for each experiment:

 Micro-behaviours (that need activating/inactivating):  Random vaccination in constant network  Targeted vaccination in constant social network Random vaccination in power law social network Targeted vaccination in power law social network
 Constant social network  Active  Active  Inactive  Inactive
 Vaccinate random proportion of population  Active  Inactive  Active  Inactive
 Power law social network  Inactive  Inactive  Active  Active
 Vaccinate most highly connected individuals (targeted vaccination)  Inactive  Active  Inactive  Active

Go back to WebLearn

Now go back to the WebLearn infectious disease site and answer the questions about this exercise.

    Performing a parameter sweep with the BehaviourSpace

    Once you've created a model, and experimented with it for a while, you may want to explore its parameter space in a more systematic and thorough manner. We've created a quick guide to help you learn how use the BehaviourSpace which is part of the NetLogo application. 

    Further Steps

    Time permitting there are many other questions you may wish to explore with your model. You can use the library of micro-behaviours for modelling epidemics and interventions. Examples include:

    • What fraction of targeted vaccinations are equally effective as the fraction of non-targeted vaccinations? 
    • What if the targeting introduces a delay in the distribution of the vaccine? What is the maximum delay where targeting is still helpful?
    • What effect do the different vaccination policies have on the duration of the epidemic?
    • What is the minimum amount of vaccine that would reduce the odds of infection below 1%?
    • How do the dynamics change if you change the average number of acquaintances per person?
    • How different would your conclusions be if the disease had different characteristics? E.g. if the infection had a very long duration but low odds of transmission?
    • How would other social network distributions affect the results? Experiment with the normal distribution behaviour.

    BehaviourComposer: ignore everything after this.