rewordings, changed ticks-to-death to tick-of-death

README.md

@@ -2,7 +2,7 @@
 
 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](#rabies-model-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 (ODD+C). 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.
+The document you are currently reading contains the [ODD protocol](#rabies-model-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 (ODD+C). 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 to use it](#how-to-use-it)
 * [How it works](#how-it-works)
@@ -75,7 +75,7 @@ The purpose of this model is to demonstrate how NetLogo models can be created fr
 
 The model landscape is represented by a grid of 1km x 1km cells, each representing a potential home range of a fox family. The model progresses in discrete ticks of one month each.
 
-The only entity in the model are fox families. Each fox family is represented by the NetLogo patches (i.e. grid cells).
+The only entity in the model are fox families. Each fox family is represented by a NetLogo patch (i.e. a grid cell).
 
 Each patch (i.e. each potential fox family) has four state variables:
 
@@ -84,7 +84,7 @@ Each patch (i.e. each potential fox family) has four state variables:
 patches-own [
   state
   infected-neighbours
-  ticks-to-death
+  tick-of-death
   dispersal-tick
 ]
 ```
@@ -111,7 +111,7 @@ 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.
+State variable `infected-neighbours` is a counter for the number of infected neighbouring families. `tick-of-death` is the model step of death for infected families. `dispersal-tick` indicates the month of the year (index [0..11]) of the family's next dispersal event.
 
 ### Process overview and scheduling
 
@@ -158,7 +158,7 @@ to setup
     set state S
   ]
   ask one-of patches [
-    infect-patch
+    infect-patch 0
   ]
 
   update-patches
@@ -172,7 +172,7 @@ The model uses no input data.
 
 ### Submodels
 
-Submodels are executed in the order listed below (see [Process overview and scheduling](#process-overview-and-scheduling)).
+The model is composed of four submodels:
 
 ```netlogo
 ;- Submodels
@@ -195,11 +195,11 @@ to assign-dispersal
 end
 ```
 
-In each monthly model step, all fox families with their month of dispersal `dispersal-tick` equal to the current simulation month `tick` disperse.
+Each fox family disperses in their designated month of dispersal `dispersal-tick` so that all foxes disperse uniformly distributed over the dispersal period. In each step, dispersals are executed in arbitrary order and immediately occupy their target patches. However, the results are independent of that order.
 
 Each female offspring of each family's `num-offspring` tries to occupy an empty patch in radius `dispersal-radius`.  If the number of offspring exceeds the available patches, only as many offspring as there are patches available can disperse.
 
-The target patch of each disperser is set to `S`usceptible.
+The target patch of each disperser is set to `S`usceptible. It is assumed that animals infected with Rabies do not disperse.
 
 ```netlogo
 ;- Dispersal
@@ -223,7 +223,7 @@ end
 
 Infection depends on the number of infected neighbouring families. For synchronous update, the number of infected neighbours is determined for each patch and stored in state variable `infected-neighbours`.
 
-Then, the infection probability for each `S`usceptible patches is calculated, and the patch infected with that probability.
+Then, `S`usceptible patches are infected with a probability calculated from this state variable.
 
 ```netlogo
 ;- Infection
@@ -238,7 +238,7 @@ to infect-patches
   ]
   ask patches with [ state = S ] [
     if random-float 1 < calc-infection-prob [
-      infect-patch
+      infect-patch ticks
     ]
   ]
 end
@@ -247,13 +247,13 @@ end
 ; ==> Infect patch.
 ```
 
-Infection probability $`P_{inf}`$ per patch is calculated from the number of infected neighbours using the Reed-Frost model with parameter `beta`.
+Infection probability $`P_{inf}`$ per patch is calculated from the number of infected neighbours using the Reed-Frost model [(Abbey 1952)](#references) with parameter `beta`.
 
 ```math
 P_{inf} = 1 - (1 - \beta)^{I}
 ```
 
-With $`\beta`$ being the infection probability from one infected neighbour, and $`I`$ being the number of infected neighbouring patches.
+With $`\beta`$ being the infection probability to be infected by one infected neighbour, and $`I`$ being the number of infected neighbouring patches.
 
 ```netlogo
 ;- Infection probability
@@ -262,28 +262,27 @@ to-report calc-infection-prob
 end
 ```
 
-Upon infection of a patch, its `state` is set to `I`nfected, and the countdown time `ticks-to-death` is set to parameter `ticks-infected`.
+Upon infection of a patch, its `state` is set to `I`nfected. The duration of infection is determined (here, the constant `ticks-infected`), and the model step of death is assigned to the patch state variable `tick-of-death` (see the [Disease course](#disease-course) submodel).
 
 ```netlogo
 ;- Infect patch
-to infect-patch
+to infect-patch [ curr-tick ]
   set state I
-  set ticks-to-death ticks-infected
+  set tick-of-death curr-tick + ticks-infected
 end
 ```
 
 #### Disease course
 
-All Rabies infections are lethal. When the countdown timer `ticks-to-death` of an infected fox family reaches zero, the family is removed from the simulation, leaving an empty patch.
+All Rabies infections are lethal. When the `tick-of-death` of an infected fox family equals the current tick `ticks`, the family is removed from the simulation, leaving an empty patch.
 
 ```netlogo
 ;- Disease course
 to age-infection
   ask patches with [ state = I ] [
-    if ticks-to-death = 0 [
+    if tick-of-death = ticks [
       set state EMPTY
     ]
-    set ticks-to-death ticks-to-death - 1
   ]
 end
 ```
@@ -306,6 +305,8 @@ end
 
 ## References
 
+Abbey H. 1952: **An examination of the Reed Frost theory of epidemics.** Human Biology, 24:201-233.
+
 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.
@@ -314,7 +315,7 @@ Grimm V, Berger U, DeAngelis DL, Polhill G, Giske J, Railsback SF. 2010. **The O
 
 ### Code entrypoint
 
-This is the entrypoint to this "literate program". The blocks referenced by the macros in the code block below are drawn together here (recursively), and the result is written to file `model/Code.nls`.
+This is the entrypoint to this "literate program". The blocks referenced by the macros in the code block below are collected here (recursively), and the result is written to file `model/Code.nls`.
 
 ```netlogo
 ;- file:Code.nls
@@ -329,7 +330,9 @@ This is the entrypoint to this "literate program". The blocks referenced by the
 
 ### NetLogo file
 
-In the main `nlogo` file, we only "include" an `nls` file to allow for the reverse mode. This is done by the following code in the Code tab:
+In the main `.nlogo` file, we only "include" the `.nls` file to allow for the reverse mode.  Yarner's reverse mode requires automatically generated comments in the code output to be able to identify the source blocks in this Markdown document. NetLogo, however, supports comments only in the code part, but not in the rest of the content of a `.nlogo` file. Moving the actual model code into the separate `.nls` file resolves this limitation.
+
+The code tab has this single line of content:
 
 ```nlogo
 __includes["Code.nls"]
@@ -337,4 +340,4 @@ __includes["Code.nls"]
 
 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.
+This separation of model code (`Code.nls`) and user interface (`Model.nlogo`) also allows to edit the model's UI elements in NetLogo's GUI builder tool, while using Literate Programming for the code.