Practical 1 - Full Version

Practical 1 - NetLogo Basics

This practical will take you through the first steps to creating a model in NetLogo. By the end you will have an understanding for the main components that make a NetLogo program.

To start, move on to the first part: 1. Running an example model

Practical 1, Part 1 - Running Two Example Models

To start off, we'll just look at two models so that you can get an idea about how NetLogo works.

Example 1: Schelling's Model of Residential Segregation

The first thing to do is start NetLogo. You can find the it by going to Start - All Programs - Departmental Software - Environment - Geography - NetLogo 5.0.2 > NetLogo 5.0.2 (or type 'NetLogo' into the search box).

NetLogo ships with a variety of ready-made models in the 'Models Library'. To see a list of the models that are available go to File -> Models Library.

To begin, we will use a version of Schelling's famous model of residential segregation. The model is listed under Social Science -> Segregation. Start that model now. At each iteration of the model, each agent looks at its 8 neighbours and works out how many are the same colour as itself. If fewer than a certain percentage.

The model has the following graphical elements:

• Two buttons start and stop the model. 'Setup' initialises it by creating the agents and configuring the environment. 'Go' then starts the model running.
• Two sliders that set number of people in the model and their preference for living next to someone of the same type (in this case 'green' or 'red').
• Two graphs show the average percentage of same-colour neighbours for each person and the percent of turtles that have fewer same-colour neighbours than they want (and thus want to move).

For more information about the model, or the function of the sliders and graphs, you can click on the 'Info' tab.

Spend a few minutes experimenting with the model and think about the following questions:

1. Slowly increase the peoples' preference for living next to the same type ('%-similar-wanted'). What happens to the spatial structure of the population as it increases?
2. What would you expect to see if '%-similar-wanted' was set to 100%? What actually happens?
3. How does the amount of time taken to reach equilibrium change as you increase and decrease the number of people in the model (e.g. the residential density)?

Finally, have a look at the code that underpins the model (click on the 'Code' tab). NetLogo code has been designed to be easy to use; you can accomplish a lot without having to become a fully-fledged computer programmer. The whole Schelling model has been written using only 79 lines.

Example 2: Virus!

Now have a look at another model called 'Virus' which is under 'Biology'. This model simulates the spread of a virus through a population as people come into contact with each other. Start by clicking on the Info tab and reading about how the model works.

Over the next few practicals we are going to build a model that looks similar to this one so play around with some of the settings to see how the model behaves.

1. What happens as the chance of recovering decreases? What happens when it gets to 0 (i.e. everyone who becomes infected dies)?
2. Does the same thing happen every time you run the model? If not, what might account for these differences?

When you have finished experimenting with different parameter values, move onto the next part of this practical to learn more about the basics of the NetLogo program.

Practical 1, Part 2 - NetLogo basics and commands

In this part of the practical you will see how the basic elements of the NetLogo program fit together.

The NetLogo Program

Firstly, it's important to understand how the program itself works. The main display consists of the following components:

The Command Centre and Basic Commands

Before starting, recall from the lecture that a model in NetLogo consists of 'patches', 'turtles' and the 'observer' (look at the lecture slide to refresh yourself if you have forgotten).

The command centre can be used to send commands to the model. There are two parts: the top part shows outputs from the model and the bottom part allows you to enter commands that are sent to the model. NetLogo has a fantastic user manual, so if it isn't clear what a command does, or how it should be used, look it up. The NetLogo Dictionary is particularly useful. Each time a new command is introduced, I have included a link to the official documentation.

1. Load the 'Wolf Sheep Predation' model from the models library (under 'Biology').
2. Press the setup button to initialise the model. You should see some sheep, wolves and green grass
3. Switch the 'grass' slider to 'On'. This tells the model to simulate the sheep eating grass - we'll need this feature later.

The show command

4. The first command that we will experiment with is show. Type the following into the command centre:show "Hello World" You should see NetLogo repeat "Hello World" back to you, like this: observer> show "hello world"
observer: "hello world" Try this again with some other text (don't forget to put quotes around the text).

This might not seem particularly useful, but the show command comes into its own when you combine it with other commands.

The count command

5. Now combine two commands: show and count as follows: show count turtles What does this show you? Try this as well: show count patches What does that tell you?

Two things are actually happening when you run those commands. The count command is counting something (in this case the number of turtles or patches). The show command is behaving the same way as it was before, except now it is showing us the number provided by the count command, rather than the "Hello World" text.

The with command


6. We can use the with command to influence a group of all the turtles or patches. Try the following: show count patches with [pcolor = green] show count patches with [pcolor = brown]

What is happening with those two commands?

7. Now run the model for a few seconds (press 'Go' to start it, then press it again to stop). Repeat the two commands above. What result do you get now? (Note, if none of the grass turned brown you need to flick the 'grass?' slider to 'On').

The with command actually needs two pieces of information. It needs a group of agents or patches on the left, and a test on the right (in this case we test the colour of the patches). You can find more information about all the commands available in the NetLogo documentation (click on 'NetLogo Dictionary' and then look for the 'with' command.)

Variables

In NetLogo, it is possible to save values in things called 'variables' (for info, see the documentation on variables). Different parts of the model can check the values of the variables to decide what they should do. For example, in the Wolf Sheep Predation model, each of the sliders changes the value of a variable. So, if you move the wolf-gain-from-food slider from 20 to 40, that will change the value of a variable called wolf-gain-from-food. Each time a wolf eats a sheep it checks the value of that variable to decide how much new 'energy' it will gain. In this case, it will now get 40 units rather than only 20.

Individual turtles and patches can also have their own variables; this is one of the ways that models can account for heterogeneity (we'll cover this in more detail in later lectures). For example, in the Wolf Sheep Predation model, the wolves and sheep have a variable called energy. This records how much energy each individual wolf or sheep will have at any given time. If this reaches zero, then they will die. We'll look at variables in more detail in the next section.

The set command

The last command we'll look at is set. This command can be used to manually change the values of variables without having to use a slider. You tell the command which variable to change, and what to change it to.

8. See what happens when you use the following set commands. Before running each command, setup the model. Then execute the command and then let the model run for 10-20 seconds. set sheep-gain-from-food 12
set sheep-gain-from-food 50
set initial-number-wolves 100
set wolf-reproduce 10

Once you have finished this, move onto the next part to learn about some more commands.

Practical 1, Part 3 - Using ask

In this part, we will start to use an extremely useful command: ask. There is more information about the command in the official NetLogo documentation (http://ccl.northwestern.edu/netlogo/docs/programming.html#ask). But first, we'll look at the different contexts in a bit more detail.

Contexts: Observer, Turtle, Patch (and Link)



Recall from the lecture that there are three different contexts (actually there are four, but we won't look at the 'link' context in this course). Also, remember that turtles, patches and the observer each have different variables that store pieces of information about them. The figure below gives examples of some of the different variables that patches, turtles and the observer have access to (this example is from the Wolf Sheep Predation model, but the ideas are the same for all models). Note that patches and turtles both have variables that store their (x,y) coordinates and colour (xcor, ycor, color). To stop us from getting confused, the equivalent patch variables have a 'p' in front of them (pxcor, pycor, pcolor).



There is also more information in the NetLogo User Manual.

• Variables in general: http://ccl.northwestern.edu/netlogo/docs/programming.html#variables
• Commands and procedures etc.: http://ccl.northwestern.edu/netlogo/docs/dictionary.html
• Built-in variables: http://ccl.northwestern.edu/netlogo/docs/dictionary.html#builtinvariables

So far, all the commands that have been issued have been sent to the observer context. This is the 'God' context that oversees the model. In order to give commands to turtles or patches, and to change the values of their variables, commands need to be sent to the turtle and patch contexts respectively. One way to do this, is to tell the command centre specifically to send commands to the turtles or patches, rather than the observer. We will do this now.

1. Re-open the 'Virus' model from the Models Library (under 'Biology').
2. Initialise the model (either by using the 'setup' button or by issuing the setup command in the Command Centre).
3. Try entering the following command into the Command Centre to change the value of the patches' pcolor variable. This should cause the patches to change colour: set pcolor blueWhat happens?


If everything worked 'correctly' (or at least as it is supposed to) you should have seen the following error in the Command Centre: ERROR: You can't use PCOLOR in an observer context, because PCOLOR is turtle/patch-only. The message is saying that you cannot change the value of the pcolor variable, because that variable belongs to turtles and patches only. The observer has no variable called pcolor.

To get round this problem, we can tell the Command Centre to send the command to the patches instead of the observer.

4. Click on 'observer' text in the bottom-left corner of the NetLogo screen (see the right image for example) and select 'patches'. This tells the Command Centre to send commands to the patches context, rather than the observer.
5. Now try the command again: set pcolor blueWhat happens this time?
6. Now change the context again, this time to 'turtles'. Issue the following command (note that we're setting a variable called color, not pcolor). set color brownWhat happens this time?

You should see all the turtles turn brown. This is because we have just changed the value of their color variable which, like pcolor for patches, controls their colour.

7. Finally, issue the following command to the turtles (note that this time we do use pcolor): set pcolor blackWhat happens this time?

Did some of the patches turn black? Which ones?

What's happening here is really, really useful in models. Turtles are given direct access to the patch that they are currently standing on. Don't worry if you don't understand this straight away, as you start to use NetLogo in earnest you will see how useful this is.

Using ask

Although changing contexts using the command centre is OK, it would be better if there was a way to send commands to turtles or patches directly, without re-configuring the commands centre. We can do this using the ask command.

8. Click on the bottom-left corner of the NetLogo Command Centre and tell it to send commands to the 'observer' again (it should be sending commands to the turtles at the moment). This is the normal behaviour.
9. Re-initialise the model, either by using the 'setup' button or by issuing setup in the Command Centre.
10. As you did before, try changing the colours of the patches with this command: set pcolor blue Again, you should get an error telling you that the 'observer' context has no variable called pcolor. This is to be expected, because the command is being sent to the observer, not the patches.
11. Now, issue the same command, but use ask to send it to the patches, rather than the observer: ask patches [ set pcolor blue ]


Did the patches turn blue? There are a few things happening here:

• The ask command expects two inputs, both on the right hand side of the command.
• The first input is the turtles or patches that we want to do something to. In this case, we ask to do something to all patches.
• The second input is a command, or a number of commands, that will be sent to those turtles or patches. So in the example above, the command set pcolor blue tells every patch to set their pcolor variable to the value blue.
12. Now try this command: ask turtles [ set color brown ] What happens?
13. Now try two commands to set the x and y coordinates of the turtles: ask turtles [ set xcor 1 set ycor 5] Where have all the turtles moved to? Try this as well ask turtles [ set xcor -10 set ycor -5] The people will move again. If you're not sure why this is happening, ask someone!

Using ask and with

The previous examples of ask have been applied to all the turtles or patches in the model. However, most of the time it is more useful to execute a command on a smaller group. To do this, we can use the with command.

14. First reset the model, either by clicking on 'setup' or by issuing the setup command.
15. Execute the following command, that will have an affect only on the people that have been infected by a virus ask turtles with [ sick? = true ] [ set color brown ]

Here, instead of giving all the turtles to the ask command, we give it the group of turtles who have a value of true stored in their variable called sick (this is a special variable created specifically for the 'virus' model).

Visually, these two commands are constructed like so:


16. Now try it again, but change the colour of those who aren't ill ask turtles with [ sick? = false ] [ set color blue ]
17. Each person also has a variable that remembers their age (you wouldn't know this without looking at the code - we'll get onto this next). So we can use ask to run commands on people of different ages: ask turtles with [ age > 20 ] [ set color yellow ]

Finally, we will use a combination of ask and some other commands to do something more interesting than changing colours.


18. Move the 'people' slider from 150 down to 10. This will reduce the number of people in the model and make it easier to see the impact that the following commands will have.
19. Setup the model. You should now see only a few people in the world.
20. Issue the following command: ask turtles [ forward 1 ] What is happening? What happens if a negative number is sent to the forward command? ask turtles [ forward -1 ]
21. Now try these commands and see what happens (they have to be entered into the Command Centre one by one): ask turtles [ facexy 0 0 ]
ask turtles [ forward 1 ]
ask turtles [ forward 1 ]
ask turtles [ forward 1 ]


You can probably see that the first command (ask turtles [ facexy 0 0 ]) tells each turtle to spin round and face the coordinate (0,0) (which happens to be in the middle of the world in this model). The commands that follow (ask turtles [ forward 1 ]) tell the agents to move forward one step in the direction that they are facing. This might seem trivial, but you now have covered the main commands that you need to create an agent-based model!

Remember, information about all the different commands that are available can be found in the NetLogo documentation. In particular, the NetLogo Dictionary lists every command that is available.

Activities (Practical 1, Part 3)

For this activity, continue to use the 'Virus' model. Make sure that the Command Centre is going to send commands to the observer context (you should see 'observer' just next to the commands box, as in the right image). Also, press 'setup' to initialise the model.

Note the commands that you would use to do the following things. Try running them in the Command Centre to check that you are correct.

1. Write a command to change the colour of all of the patches to brown. Command:
2. Write a command that will ask all agents to move forward one step. Command:
3. Write a command that will ask all blue turtles to move forward five steps. (Hint, use a combination of ask and with). Command:
4. Write a command that will ask the turtles to change the colour of the patch that they are standing on to blue. Command:
5. Write a command that will ask all of the red turtles to change the colour of the patch that they are standing on to orange. Hint: remember that turtle colour is stored in a variable called color and patch colour is stored in a variable called pcolor. Command:

That is quite a lot to take in, so don't worry if it seems a bit overwhelming. As with anything new, as you practice it will become familiar. That's all for this practical, if you're really keen you can move straight on to Practical 2, or go and have a well deserved cup of tea.