Largely completed skylark ODD

closes #19

docs/src/odd.md

@@ -40,4 +40,4 @@ The  model  description follows  the  ODD  (Overview,  Design  concepts, Details
 ## 7. Submodels
 
 
-## Sources
+## 8. References

docs/src/skylark.md

@@ -27,24 +27,24 @@ when disturbance (e.g. mowing, harvesting, tillage) takes place.
 The simulated individuals (a.k.a. agents) are mature [skylarks](species#Skylark). Each skylark 
 is characterised by the following variables:
 
-- **ID:** A unique identifier for this individual, which can be used to link it to its parents
+- `ID` A unique identifier for this individual, which can be used to link it to its parents
   and its offspring.
 
-- **sex:** Male or female.
+- `sex` Male or female.
 
-- **phase:** The individual's current stage in the annual/life cycle. May be one of: `migration`, 
+- `phase` The individual's current stage in the annual/life cycle. May be one of: `migration`, 
   `nonbreeding`, `territorysearch`, `occupation`, `matesearch`, `nesting`, `breeding`.
 
-- **position** The individual's position in the simulated landscape.
+- `position` The individual's position in the simulated landscape.
 
-- **mate** The ID of the individual with which this individual has mated this year, if any.
+- `mate` The ID of the individual with which this individual has mated this year, if any.
 
-- **territory** A list of coordinates of the positions in the landscape that this individual
+- `territory` A list of coordinates of the positions in the landscape that this individual
   claims as its nesting and feeding territory.
   
-- **nest** A coordinate giving the location of the currently active nest.
+- `nest` A coordinate giving the location of the currently active nest.
 
-- **clutch** The number of juvenile (i.e. not yet independent) skylarks that this individual is
+- `clutch` The number of juvenile (i.e. not yet independent) skylarks that this individual is
   currently raising.
 
 
@@ -73,7 +73,7 @@ breeding season is over.
 - `occupation`: The male moves at random about its territory until the breeding season is over.
   Then it changes its phase to `nonbreeding`. (*Note:* Skylark males actively help with feeding
   their chicks. However, feeding is only modelled indirectly here, through the process of habitat
-  selection when the male forms its territory.)
+  selection when the male forms its territory - see section 4.1.)
   
 - `nesting`: The female selects a suitable location within the male's territory for the nest.
   Building the nest and laying eggs takes a number of days, during which she does nothing else.
@@ -96,52 +96,120 @@ If it is, she changes her phase to `nonbreeding`.
 
 ### 4.1 Basic principles
 
-### 4.2 Emergence
-
+This model assumes that the two most important drivers of skylark distribution and abundance
+are **habitat availability** and **juvenile mortality** (see literature below). The factors 
+and processes affecting these are therefore given the most attention in the model, while other 
+factors and processes are only included superficially, indirectly, or not at all. Specifically, 
+this means that the phases `territorysearch`, `nesting`, and `breeding` are the most relevant 
+and detailed parts of the model, as these determine the selection of habitat and the survival of 
+offspring.
+
+Furthermore, the model concentrates on predation and anthropogenic disturbance (through management
+actions such as mowing) as the main causes of juvenile mortality. Other causes, such as hunger
+or bad weather, are currently ignored as they are usually not significant.
+
+The focus on habitat availability and juvenile mortality opens up two avenues by which agricultural
+management influences skylark populations. First, the farmers' choice of crops and date of sowing
+determines the quality of the habitat when skylarks select a territory. (For example, unlike summer
+grain, winter grain is already so high and dense in spring that it is generally avoided for nesting.)
+Secondly, the frequency and timing of management actions (especially mowing) is a major cause of
+brood loss. This means that there are direct causal links between agriculture and population trends.
+
+Concentrating on these two drivers allows the rest of the model to be kept simple, reducing both the
+scientific complexity and computational costs. Thus, foraging movement (both during and after the
+breeding season) can be ignored or represented as random movement, as it does not directly impact
+either of the drivers. Likewise, chick growth and winter migration are represented very simply.
 
-Patterns that can be used for validation with POM:
+### 4.2 Emergence
 
-- territory size
+Multiple patterns emerge from the basic principles outlined above. The most important are listed here:
 
-- *TODO*
+- **Territory size and population density:** The model assumes that skylarks occupy only as much
+  area as they need to satisfy their nesting and foraging requirements, and that population size is
+  limited by the amount of available habitat. This means that territories in high-quality habitat 
+  are smaller than in low-quality habitat. Scaling up, this leads to a pattern whereby population 
+  densities are highest in open landscapes with a diversity of crops, grassland, semi-natural habitat,
+  and lower in landscapes with low habitat diversity or many woody features.
+  
+- **Ecological traps:** Jenny (1990) describes a strong ecological trap effect whereby skylarks avoid
+  winter grain crops, preferentially nesting in more open grassland sites. However, the mowing
+  frequency associated with modern agriculture means that nest loss in grassland is almost assured,
+  since there is insufficient time between two mowing dates to raise a brood. This means that landscape
+  composition leads skylarks to breed in habitats that have a high mortality, resulting in population
+  declines.
 
 
 ### 4.3 Adaptation
 
-- habitat choice
+In the model, skylarks primarily adapt to their surroundings by choosing suitable territories.
+These are chosen by evaluating the quality of surrounding habitats for breeding and foraging, 
+and occupying as much area as needed to satisfy requirements (see section 7.1).
 
 ### 4.4 Objectives
 
+Skylarks' main objective in the model is to have sufficient habitat available to raise a brood.
+Habitat quality is calculated as a function of habitat type, vegetation height, vegetation cover,
+and distance to vertical structures (see section 7.1).
+
 ### 4.5 Learning
 
+The model includes no learning by individuals.
+
 ### 4.6 Prediction
 
-### 4.7 Sensing
+The model includes no predictions by individuals.
 
-- habitat quality (type, height, cover)
+### 4.7 Sensing
 
-- proximity of conspecifics
+Skylarks can perceive the landscape structure in a given radius around them (habitat type,
+vegetation height and cover). They can also see nearby conspecifics and are aware of the territories
+claimed by other individuals. When mating, they recognise whether another individual already has a
+mate, and mated individuals share information about their territory and brood status.
 
 ### 4.8 Interaction
 
-- mating
+The model includes two direct forms of interaction. First, during mating, females move around the
+landscape looking for males who have a territory but no mate yet. Once they have found one, the
+two individuals set each other as their mate. Secondly, after the breeding seasons, individuals
+move around the landscape, keeping close to other individuals in their vicinity (flocking behaviour).
 
-- flocking
+There are also indirect interactions, in that there is a competition for habitat (territory that has
+been claimed by one male cannot be occupied by another) and males (males that have mated with one
+female will not mate with another in the same season).
 
 ### 4.9 Stochasticity
 
+Stochasticity is used when modelling mortality and movement. Predation mortality is modelled as an 
+age- and habitat-dependent probability, while migration mortality is a simple probability. Dispersal 
+movement (when searching for a territory or a mate) is modelled as a random walk, as it is assumed 
+that skylarks are not significantly impeded in their long-range movement by habitats that are 
+unsuitable for foraging or nesting. Foraging movement by the male and by non-breeding individuals is 
+also random, as it is desirable to show movement (to help model analysis) but unimportant to model 
+this exactly.
+
 ### 4.10 Collectives
 
+After the breeding season, skylarks move around in loose agglomerations (flocking behaviour). However,
+this has no relevant ecological effect.
+
 ### 4.11 Observation
 
+*TODO*
+
 ## 5. Initialisation
 
+At the beginning of a model run, pairs of skylarks are created on grassland and agricultural land,
+keeping a distance of 60m to vertical structures and allowing each pair approximately 3ha of
+suitable habitat (an average territory size in agricultural landscapes).
+
+For details, see the [source code](https://git.idiv.de/persefone/persefone-model/-/blob/master/src/nature/species/skylark.jl?ref_type=heads) and the associated [documentation](nature#populations.jl).
+
 ## 6. Input data
 
-The general input to Persefone (i.e. maps and weather data) is described [here](gis).
+The general input to Persefone (i.e. land use maps and weather data) is described [here](gis).
 
 The following extract from the [source code](https://git.idiv.de/persefone/persefone-model/-/blob/master/src/nature/species/skylark.jl?ref_type=heads)
-lists the species parameters and their values as used by the Skylark model:
+lists the species parameters and values used by the Skylark model, based on the literature cited below:
 
 ```julia
 @species Skylark begin
@@ -176,9 +244,15 @@ end
 
 ## 7. Submodels
 
+### 7.1 Territory formation
+
+*TODO*
+
+### 7.2 Juvenile mortality
 
+*TODO*
 
-## Sources
+## 8. References
 
 - Bauer, H.-G., Bezzel, E., & Fiedler, W. (Eds.). (2012). Das Kompendium
   der Vögel Mitteleuropas: Ein umfassendes Handbuch zu Biologie, Gefährdung