Quick NetLogo Tutorial: dispersal

You might have noticed that Netlogo has three tabs: Interface, Info and Code. In the first one you see the display showing the simulation as well as buttons with variable values. The code tab does what it says on the tin ­ you write your code there. For now we will leave the middle tab which contains the documentation of your work, however, it is not to say that recording of what you did and why you did it, is not important. As with any other project, it is good to keep a log of changes and decisions, annotate the code as much as possible and have a short description of what the model is about. The standard template for describing Netlogo models is called ODD (http://bio.uib.no/te/papers/Grimm_2010_The_ODD_protocol_.pdf) and was designed to help other people as well as ‘the future you’ to understand the model. It may be tedious at first but believe me, you will thank yourself for the effort very soon. Let’s get started.

Make sure you are in the interface tab. Right click anywhere on the white background

and choose “button”. A dialog box for editing the button appears.

Type setup in the box labeled Commands. Click on the OK button. Create another button but this time type goin

the Commands box and tick Forever. This will let the gocommand iterate over time steps; leaving it unticked will only run the go command once, when the button is pushed.

You might have noticed that the interface at the top of the screen changed to red. This indicates that something is wrong. Click on the button to see what the error message says.

Build to-go and to-setup procedures Right, let‘s move to the code tab. We have created two buttons: setup and gowhich correspond to the two most common procedures in Netlogo models. The setup procedure initialises the world while the goprocedure is the main body of the simulation. Every procedure in Netlogo starts with to and finishes with end. Type the following:

to setup __clear­all­and­reset­ticks

end

1

The __clear­all­and­reset­ticks is a standard command which ensures that there is no leftovers from the previous runs of your simulation. Type the following beneath the code for the setup procedure:

to go tick

end The tickcommand is a time step, just like a clock tick ­ it marks the end of all procedures in this time step and starts a new one. It’s generally a good idea to hit the check button (top left corner) after every piece of code you add to your simulation ­ it’s NetLogo’s built­in debugger which will raise an error if there is a problem with your code. If you click on it and it goes grey you’re ok. Try it now. The setup and gocommands are the two procedures which create the spine of almost every simulation in NetLogo.

Setup procedures Create turtles We’re working on an agent­based simulation so we’ll start with creating some agents. Copy the following code into the setup procedure:

crt 20 [ set color random 140 set size 2 set shape "turtle" setxy random 10 random 10 ]

crt stands for ‘create’ and the number after it (20) tells you how many turtles to create. crtis a “primitive”, and is part of the NetLogo programming language. You can find all of the NetLogo primitives in the NetLogo dictionary under the Help menu. The brackets enclose additional features of the agents such as the color, size, shapeand the location (xy) where the agent is to appear. In this case we choose a random location within a square of 10 by 10 patches (grid squares) close to the world’s centre. These are built­in variables, and will have default values if none are assigned.

2

If you’re all done, hit the check button and move to the interface tab. Click on your setup button and see what happens. You can change the parameters of the display. Click on the setting button in top right corner. It should give you a window in which you can change the point of origin, the size of the world and the size of each patch (cell). Change the point of origin to the bottom left corner and unclick the world wraps horizontally and world wraps vertically boxes.

Go procedures

Let turtles move Add the following to the go procedure, before tick.

ask turtles [ rt random 360

fd 1 ]

fdstands for forward and the number after indicates how far the turtle should move (the unit is a patch, i.e. grid square) while rtmeans turn right by a given angle. In this piece of code, we are asking all turtles to turn right by a random number of degrees and go forward one step. Hit the check button and move to the interface tab to see what happens. You can use the speed slider in the top menu to toggle the speed at which the model is running.

Introducing the if-statement Using the code we have now, the simulation could go on forever. If we want our simulation to end, we need to give the goprocedure a reason to stop. Move back to the code tab and add the following to your go procedure:

if ticks >= 30 [stop] Did you put it at the beginning of the procedure or at the end? Do you think there’s a difference? Go back to the interface tab and run the simulation. Stopping the simulation after 30 times steps (ticks) is a bit arbitrary.. Instead we can stop it after one of the turtles reaches the top left corner (or any other place). Change the previous command to the following:

ifany?turtleswith[xcor>(max­pxcor­1)andycor>(max­pycor ­ 1)] [stop]

Here we ask the simulation to stop if any of the turtles has a location that would be within the patch with maximum x and y coordinates i.e. the top right corner.

Extending the model Let’s assume now that we want to work on a larger scale, and instead of having our agents roaming aimlessly around the landscape, we want to see how population growth coupled with spatial spreading process could produce dispersal. Delete the move command (the one with fd, rt) in the go procedure.

3

Let turtles reproduce Many things are non­deterministic and very often events are dependent on factors not accounted for in our simulation, following a probabilistic distribution or may even be inherently random. You’ve already seen the use of random value generation in the move and crt commands. To simulate the likelihood of reproduction occurring in a given time step, we can draw values from a random number generator. Add the following statement to your go procedure:

ask turtles [ if random­float 1 <= child_prob [ reproduce ] ]

What happens in this procedure is: the generator produces a floating point number (floating point numbers have decimal

values, e.g.: 0.15, 2.4, 798.452 as opposed to integers such as 1, 27, 301) between 0 and 1: random­float 1

We compare this with a variable we define as probability of having a child: child_prob And if the random number is lower than the value of fertility rate we imposed in the

simulation the procedure (in this case reproduce) is executed. To translate that into English, each turtle draws a random number between 0 and 1, and all of those whose number turn out to be within their probability of having a child (which you may recognise as the good ol’ ‘population fertility rate’) are allowed to reproduce. Because we may be quite interested in how the probability of having a child affects our results we will create a handy slider which will allow us to monitor it. Go back to the interface tab, right­click anywhere on the white area and choose slider. Enter the same values as below into the window and click “OK”:

Go back to the code tab and type the following:

to reproduce if any? patches with [count turtles­here = 0] in­radius 1 [

4

let empty­patch one­of patches with [count turtles­here = 0 ] in­radius 1

hatch 1 move­to empty­patch ] end

This code asks each turtle if there is an empty space[countturtles­here=0] on any of his/her neighbouring patches in­radius1and if there is we identify one of those patches one­of patches with [count turtles­here = 0 ] in­radius 1 as empty­patchand allow the turtle to produce a new, offspring turtlehatch1 onto that patch ( move­toempty­patch). The built­in variables of the offspring turtle, such as color and size, are the same as those of the parent.

Specify a turtle variable If we want to give our turtles characteristics beyond the built­in variables like color, we need to declare that variable at the beginning of the simulation. Let’s say we want to give our turtles some value that keeps track of their age. To do this, add this to the top of the code tab: turtles­own [ age ] This associates the variable agewith turtles. As a default, all turtles will begin with age 1. You have to specify it in the setupprocedure when you create turtles (and again in the hatch procedure when a new turtle is born): crt 20 [ set color random 140 set size 1 set shape "turtle" setxy random 10 random 10 set age 1 ] If we model the process of aging, we can simply add 1 to each turtles’ age by adding this code to the go procedure before the turtle reproduction : ask turtles [ set age age + 1 ]

5

What if we allow the turtles to die as well? Create a new slider identical to child_probbut fill the global variable box with death_prob and add to the go procedure the following code:

ask turtles [ if random­float 1 <= death_prob [die] ]

What if we made the death dependent on the age? Can you add age to the code above so that older turtles have increasingly higher chance of dying? From here on you can take the simulation in pretty much any direction you want. Here are a few suggestions:

Try out different starting points (eg. change the world origins to centre). Tracking what is going on in the simulation is a non­trivial matter. You can add a plot to

your interface. Right click anywhere on the white background and choose the plot option. Try different values of child_prob and death_prob. g You can also add the following line set color [color] of myself+1 to the

hatch procedure, this will make each new generation of turtles change the tone of their colour.

Make the world smaller or bigger ­ do you see any patterns emerging out of the stochasticity of the model? This can be a problem for the reproducibility of your research. Check the NetLogo dictionary’s entry on random­seed (ccl.northwestern.edu/netlogo/docs/).

The go procedure currently gives turtles commands three times: can this be condensed down to one? Does it make a difference when turtles reproduce or age?

For more information, click on the Help menu. The NetLogo manual has a programming guide and additional tutorials, as well as a programming dictionary.

To see other models in action, you can access the built­in NetLogo model library under the File menu.

You can find the full code of this tutorial on the next page (keep in mind that it won’t work if you don’t have all the necessary sliders and buttons in the interface tab).

6

turtles­own [ age ] to setup

__clear­all­and­reset­ticks

crt 20 [ set color random 140 set size 1 set age 1 set shape "turtle" setxy random 10 random 10 ]

end

to go ask turtles [ set age age + 1 ]

ask turtles [ if random­float 1 <= child_prob [ reproduce ] ]

ask turtles [ if random­float 1 <= death_prob + age / 100 [ die ] ]

if any? turtles with [xcor > (max­pxcor ­ 1) and ycor > (max­pycor ­ 1) [ stop ] tick end to reproduce

if any? patches with [count turtles­here = 0] in­radius 1 [ let empty­patch one­of patches with [count turtles­here = 0] in­radius 1 hatch 1

[ set color [color] of myself + 1 set age 1 ]

move­to empty­patch ] end

7