Newer
Older
This is an example project to demonstrate Literate Programming to create [NetLogo](https://ccl.northwestern.edu/netlogo/) models from ODD+C protocols using [Yarner](https://github.com/mlange-42/yarner).
The document you are currently reading contains the ODD protocol ([Grimm et al. 2006, 2010](#references)) of a model for Rabies in red foxes. The ODD description is interleaved with code blocks showing the NetLogo code used for the described aspect. Using the Literate Programming tool [Yarner](https://github.com/mlange-42/yarner), these code blocks are extracted from the document and arranged into a working NetLogo model.
## How it works
Yarner scans the document for code blocks and puts them together using macros. Each code block has a name, given in its first line and prefixed with `;-`:
```netlogo
;- A code block
let x 0
```
When a code block is referenced by another code block using a macro with `; ==>`, it is placed inside the referencing code block:
```netlogo
;- Outer code block
; ==> A code block.
let y 1
```
The resulting extracted code would look like this:
```netlogo
let x 0
let y 1
```
For a comprehensive guide and a description of all features, see the [Yarner documentation](https://mlange-42.github.io/yarner/).
## How to use it
The purpose of this model is to demonstrate how NetLogo models can be created from ODD protocols, using Literate Programming with Yarner.
### Entities, state variables, and scales
The model landscape is represented by a grid of 1km x 1km cells, each representing a potential home range of a fox family.
The only entity in the model are fox families. Each fox family is represented by the NetLogo patches (i.e. grid cells).
Each patch (i.e. each potential fox family) has four state variables:
```netlogo
;- State variables
patches-own [
state
The disease state (`state`) represents the state of the patch. Possible states are `EMPTY`, `S`usceptible, `I`nfected and `R`ecovered:
```netlogo
;- Disease states
globals [
EMPTY
S
I
R
]
```
Disease states are internally represented by whole numbers 0-3:
;- Setup disease states
set EMPTY 0
set S 1
set I 2
set R 3
State variable `infected-neighbours` is a counter for the number of infected neighbouring families. `ticks-to-death` is a count-down timer for infected families until death. `dispersal-tick` indicates the month of the year (index [0..11]) of the family's next dispersal event.
### Process overview and scheduling
Processes simulated by the model are [Dispersal](#dispersal), [Infection](#infection) and [Disease course](#disease-course). Processes are executed on every monthly time step in the above order.
After to model processes, the patch colour is updated for [Visualization](#visualization).
if ticks mod 12 = 0 [
assign-dispersal
]
disperse
Fox families as the only model entities live on a rectangular grid of habitat patches. Patches can be empty or occupied.
Reproduction and juvenile dispersal are subsumed under a single process [Dispersal](#dispersal). Once a year, a certain number of female offspring disperses from each fox family. Time and target location of dispersal are stochastic. Dispersal is restricted by a maximum dispersal radius.
Fox families can become infected with Rabies. Rabies can be transmitted to the 8 immediate neighbouring families. Infection is stochastic and infection probability depends on the number of infected neighbours.
The model is initialized by populating each habitat patch with a `S`usceptible fox family. One randomly selected family is infected.
clear-all
; ==> Setup disease states.
ask patches [
set state S
]
ask one-of patches [
The model uses no input data.
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
```netlogo
;- Submodels
; ==> Dispersal.
; ==> Infection.
; ==> Disease course.
; ==> Update patches.
```
#### Dispersal
```netlogo
;- Dispersal
to assign-dispersal
ask patches with [ state != EMPTY ] [
set dispersal-tick (ticks + start-dispersal + random length-dispersal)
]
end
```
```netlogo
;- Dispersal
to disperse
ask patches with [ state != EMPTY and dispersal-tick = ticks ] [
let candidates other patches
in-radius dispersal-radius
with [ state = EMPTY ]
let num-candidates num-offspring
if count candidates < num-candidates [
set num-candidates count candidates
]
ask n-of num-candidates candidates [
set state S ; no dispersal of infected
; alternative:
; set state [state] of myself
; set ticks-to-death [ticks-to-death] of myself
]
]
end
```
#### Infection
```netlogo
;- Infection
to infect-patches
ask patches [
set infected-neighbours 0
]
ask patches with [ state = I ] [
ask neighbors [
set infected-neighbours infected-neighbours + 1
]
]
ask patches with [ state = S ] [
if random-float 1 < calc-infection-prob [
]
]
end
; ==> Infection probability.
```
```netlogo
;- Infection probability
to-report calc-infection-prob
report 1 - (1 - beta) ^ infected-neighbours
end
```
```netlogo
;- Infect patch
to infect-patch
set state I
set ticks-to-death ticks-infected
end
```
#### Disease course
```netlogo
;- Disease course
to age-infection
ask patches with [ state = I ] [
if ticks-to-death = 0 [
set state EMPTY
]
set ticks-to-death ticks-to-death - 1
]
end
```
#### Visualization
```netlogo
;- Update patches
to update-patches
ask patches [
ifelse state = EMPTY [ set pcolor white ]
[ ifelse state = S [ set pcolor blue ]
[ ifelse state = I [ set pcolor red ]
[ set pcolor green ] ] ]
]
end
```
## References
Grimm V, Berger U, Bastiansen F, Eliassen S, Ginot V, Giske J, Goss-Custard J, Grand T, Heinz S, Huse G, Huth A, Jepsen JU, Jørgensen C, Mooij WM, Müller B, Pe’er G, Piou C, Railsback SF, Robbins AM, Robbins MM, Rossmanith E, Rüger N, Strand E, Souissi S, Stillman RA, Vabø R, Visser U, DeAngelis DL. 2006. **A standard protocol for describing individual-based and agent-based models**. *Ecological Modelling* 198:115-126.
Grimm V, Berger U, DeAngelis DL, Polhill G, Giske J, Railsback SF. 2010. **The ODD protocol: a review and first update**. *Ecological Modelling* 221: 2760-2768.
### Code
```netlogo
;- file:Code.nls
; ==> Disease states.
; ==> State variables.
; ==> Setup.
; ==> Go.
```
### NetLogo file
In the main `nlogo` file, we only "include" an `nls` file to allow for the reverse mode.
The file `Model.nlogo` is simply copied from the `nlogo` directory via option `code_files` in the `[paths]` section of the `Yarner.toml`.
This separation of model code and user interface also allows to edit the model's UI elements in NetLogo's GUI builder tool, while using Literate Programming for the code.