README.md

Literate NetLogo

This is an example project to demonstrate Literate Programming to create NetLogo models from ODD+C protocols using Yarner.

How to use this project

TODO

Rabies model - ODD protocol

Purpose

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:

;- State variables
patches-own [
  state
  infected-neighbours
  ticks-to-death
  dispersal-tick
]

The disease state (state) represents the state of the patch. Possible states are EMPTY, Susceptible, Infected and Recovered:

;- 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, Infection and 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.

;- Go
to go
  if ticks mod 12 = 0 [
    assign-dispersal
  ]
  disperse

  infect-patches
  age-infection
  update-patches
  tick
end

; ==> Submodels.

Design concepts

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. 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.

Initialization

The model is initialized by populating each habitat patch with a Susceptible fox family. One randomly selected family is infected.

;- Setup
to setup
  clear-all
  ; ==> Setup disease states.

  ask patches [
    set state S
  ]
  ask one-of patches [
    infect-patch
  ]

  update-patches
  reset-ticks
end

Input data

The model uses no input data.

Submodels

;- Submodels
; ==> Dispersal.
; ==> Infection.
; ==> Disease course.
; ==> Update patches.

Dispersal

;- Dispersal
to assign-dispersal
  ask patches with [ state != EMPTY ] [
    set dispersal-tick (ticks + start-dispersal + random length-dispersal)
  ]
end

;- 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

;- 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 [
      infect-patch
    ]
  ]
end

; ==> Infection probability.
; ==> Infect patch.

;- Infection probability
to-report calc-infection-prob
  report 1 - (1 - beta) ^ infected-neighbours
end

;- Infect patch
to infect-patch
  set state I
  set ticks-to-death ticks-infected
end

Disease course

;- 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

;- 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

Appendix

Code

;- 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.