From 555e3564cecb0cba67b1243ca73d6c48d0916378 Mon Sep 17 00:00:00 2001
From: Daniel Vedder <daniel.vedder@idiv.de>
Date: Mon, 29 Jul 2024 18:01:37 +0200
Subject: [PATCH] Started writing skylark ODD
---
docs/src/skylark.md | 187 ++++++++++++++++++++++++++++++++--
src/nature/energy.jl | 3 +
src/nature/insects.jl | 3 +
src/nature/nature.jl | 2 +-
src/nature/species/skylark.jl | 10 +-
5 files changed, 190 insertions(+), 15 deletions(-)
diff --git a/docs/src/skylark.md b/docs/src/skylark.md
index 28bc10c..09ac908 100644
--- a/docs/src/skylark.md
+++ b/docs/src/skylark.md
@@ -1,15 +1,103 @@
# Skylark
*Alauda arvensis* is a common and charismatic species of agricultural landscapes.
-At the moment, this implementation is still in development.
+This animal model is one component of the [`nature`](architecture) submodel of Persefone.jl.
-**ODD?**
+The model description follows the ODD (Overview, Design concepts, Details) protocol (Grimm et al., [2006](https://doi.org/10.1016/j.ecolmodel.2006.04.023); [2010](https://doi.org/10.1016/j.ecolmodel.2010.08.019); [2020](https://doi.org/10.18564/jasss.4259)):
-## Life cycle
-*TODO*
+## 1. Purpose
+
+The purpose of this animal model is to simulate the abundance and distribution of a population of
+*Alauda arvensis* in response to farm management in Central European agricultural landscapes.
+
+## 2. Entities, state variables, and scales
+
+### 2.1 Landscape
+
+The [simulated landscape](gis) consists of a grid of pixels with a resolution of 10m and
+can have an extent of 20km²-200km² (approximately; depending on the chosen input map).
+Each pixel is assigned a land cover class. It may also be associated with a farm plot,
+in which case it will contain information about the type and growth stage of the crop
+planted here. [Farm management](management) determines which crops are grown when, and
+when disturbance (e.g. mowing, harvesting, tillage) takes place.
+
+### 2.2 Animals
+
+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
+ and its offspring.
+
+- **sex:** Male or female.
+
+- **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.
+
+- **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
+ claims as its nesting and feeding territory.
+
+- **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
+ currently raising.
+
+
+## 3. Process overview and scheduling
+
+The simulation proceeds in time steps of one day. Every day, each individual executes the function
+associated with their current life phase:
+
+- `migration`: The individual is held in a separate data structure (apart from the model landscape)
+ and does nothing until its return date is reached. Then, it is re-introduced to the landscape
+ and assigned the phase `territorysearch` (for males) or `matesearch` (for females).
+
+- `territorysearch`: Males return first from migration. If they already have a territory from a
+ previous year, they return to this. Otherwise, they move randomly through the landscape until
+ they find a contiguous territory that satisfies their habitat requirements. Once a male has a
+ territory, it changes its phase to `occupation`.
+
+- `matesearch`: Females return later than males from their winter migration. If they already had
+ a partner the previous year, they have a given probability of remaining with this partner.
+ Otherwise, they move randomly through the landscape, looking for a male with a territory and
+ without a partner. Once the female has a partner, it changes its phase to `nesting`.
+
+If an individual fails to find a territory or a mate, it changes its phase to `nonbreeding` once the
+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.)
+
+- `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.
+ Then, she changes her phase to `breeding`.
+
+- `breeding`: The female checks for mortality. The probability of brood loss varies with the age
+ of the clutch and the nesting habitat. If and when the chicks reach independence (30 days after
+ hatching), they are instantiated as new individuals in the `nonbreeding` phase.
+
+If a nest fails due to predation or disturbance, or a brood leaves the nest successfully, the
+female resets her phase to `nesting` and begins again if the breeding season is not yet over.
+If it is, she changes her phase to `nonbreeding`.
+
+- `nonbreeding`: Non-breeding mature birds move randomly around the landscape, keeping close
+ to other individuals (flocking behaviour). Once their individual migration date is reached,
+ they are removed from the landscape until the following year (see above). Mature birds have
+ a mortality probability for their first summer, and others thereafter for each winter.
+
+## 4. Design concepts
+
+### 4.1 Basic principles
+
+### 4.2 Emergence
-## Patterns
Patterns that can be used for validation with POM:
@@ -17,6 +105,79 @@ Patterns that can be used for validation with POM:
- *TODO*
+
+### 4.3 Adaptation
+
+- habitat choice
+
+### 4.4 Objectives
+
+### 4.5 Learning
+
+### 4.6 Prediction
+
+### 4.7 Sensing
+
+- habitat quality (type, height, cover)
+
+- proximity of conspecifics
+
+### 4.8 Interaction
+
+- mating
+
+- flocking
+
+### 4.9 Stochasticity
+
+### 4.10 Collectives
+
+### 4.11 Observation
+
+## 5. Initialisation
+
+## 6. Input data
+
+The general input to Persefone (i.e. 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:
+
+```julia
+@species Skylark begin
+ const movementrange::Length = 500m #XXX arbitrary
+ const visionrange::Length = 200m #XXX arbitrary
+
+ const eggtime::Int64 = 11 # days from laying to hatching
+ const nestlingtime::Int64 = 9 # days from hatching to leaving nest
+ const fledglingtime::Int64 = 21 # days from leaving the nest to independence
+
+ #XXX predation mortality should be habitat-dependent
+ const eggpredationmortality::Float64 = 0.03 # per-day egg mortality from predation
+ const nestlingpredationmortality::Float64 = 0.03 # per-day nestling mortality from predation
+ const fledglingpredationmortality::Float64 = 0.01 # per-day fledgling mortality from predation
+ const firstyearmortality::Float64 = 0.38 # total mortality in the first year after independence
+ const migrationmortality::Float64 = 0.33 # chance of dying during the winter
+
+ const minimumterritory = 5000m² # size of territory under ideal conditions
+ const mindistancetoedge = 60m # minimum distance of habitat to vertical structures
+ const maxforageheight = 50cm # maximum preferred vegetation height for foraging
+ const maxforagecover = 0.7 # maximum preferred vegetation cover for foraging
+ const nestingheight = (15cm, 25cm) # min and max preferred vegetation height for nesting
+ const nestingcover = (0.2, 0.5) # min and max preferred vegetation cover for nesting
+
+ const matefaithfulness = 0.5 # chance of a female retaining her previous partner
+ const nestingbegin::Tuple{Int64,Int64} = (April, 10) # begin nesting in the middle of April
+ const nestbuildingtime::UnitRange{Int64} = 4:5 # 4-5 days needed to build a nest (doubled for first nest)
+ const eggsperclutch::UnitRange{Int64} = 2:5 # eggs laid per clutch
+ const nestingend::Int64 = July # last month of nesting
+end
+```
+
+## 7. Submodels
+
+
+
## Sources
- Bauer, H.-G., Bezzel, E., & Fiedler, W. (Eds.). (2012). Das Kompendium
@@ -25,20 +186,24 @@ Patterns that can be used for validation with POM:
Aufl. 2005). AULA-Verlag
- Delius, J. D. (1965). A Population Study of Skylarks Alauda Arvensis.
- Ibis, 107(4), 466–492. https://doi.org/10.1111/j.1474-919X.1965.tb07332.x
+ [Ibis, 107(4), 466–492.](https://doi.org/10.1111/j.1474-919X.1965.tb07332.x)
- Donald et al. (2002). Survival rates, causes of failure and productivity
- of Skylark Alauda arvensis nests on lowland farmland. Ibis, 144(4), 652–664.
- https://doi.org/10.1046/j.1474-919X.2002.00101.x
+ of Skylark Alauda arvensis nests on lowland farmland.
+ [Ibis, 144(4), 652–664.](https://doi.org/10.1046/j.1474-919X.2002.00101.x)
- Glutz von Blotzheim, Urs N. (Ed.). (1985). Handbuch der Vögel Mitteleuropas.
Bd. 10. Passeriformes (Teil 1) 1. Alaudidae - Hirundidae. AULA-Verlag, Wiesbaden.
ISBN 3-89104-019-9
- Jenny, M. (1990). Territorialität und Brutbiologie der Feldlerche Alauda
- arvensis in einer intensiv genutzten Agrarlandschaft. Journal für Ornithologie,
- 131(3), 241–265. https://doi.org/10.1007/BF01640998
+ arvensis in einer intensiv genutzten Agrarlandschaft. [Journal für Ornithologie,
+ 131(3), 241–265.](https://doi.org/10.1007/BF01640998)
+
+- Jeromin, K. (2002). Zur Ernährungsökologie der Feldlerche (Alauda arvensis L. 1758)
+ in der Reproduktionsphase [Doctoral thesis].
+ [Christian-Albrechts-Universität zu Kiel.](https://macau.uni-kiel.de/receive/diss_mods_00000968)
- Püttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks
indicate no seasonal decrease in food availability in heterogeneous farmland.
- Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461
+ [Ecology and Evolution, 12(1), e8461.](https://doi.org/10.1002/ece3.8461)
diff --git a/src/nature/energy.jl b/src/nature/energy.jl
index 1d2c46a..790a134 100644
--- a/src/nature/energy.jl
+++ b/src/nature/energy.jl
@@ -3,6 +3,9 @@
### This file contains structs and functions for implementing Dynamic Energy Budgets.
###
+## XXX THE CODE IN THIS FILE IS CURRENTLY NOT USED AND LIKELY WON'T BE IN FUTURE.
+## HOWEVER, I PREFER TO KEEP IT FOR NOW IN CASE WE EVER DO. (DV, 29th July 2024)
+
#TODO add units
## STRUCTS
diff --git a/src/nature/insects.jl b/src/nature/insects.jl
index 6651496..f281763 100644
--- a/src/nature/insects.jl
+++ b/src/nature/insects.jl
@@ -3,6 +3,9 @@
### This file contains the submodel that calculates insect biomass
###
+## XXX THE CODE IN THIS FILE IS CURRENTLY NOT USED AND LIKELY WON'T BE IN FUTURE.
+## HOWEVER, I PREFER TO KEEP IT FOR NOW IN CASE WE EVER DO. (DV, 29th July 2024)
+
"""
insectbiomass(pixel, model)
diff --git a/src/nature/nature.jl b/src/nature/nature.jl
index 317a19f..8344bd1 100644
--- a/src/nature/nature.jl
+++ b/src/nature/nature.jl
@@ -112,7 +112,7 @@ function updatenature!(model::SimulationModel)
# Update all animals. Dead animals are replaced by `nothing`, we can skip these.
#XXX I assume that keeping all those `nothing`s in the animal vector won't lead
# to memory bloat, but I will have to check that.
- for a in model.animals
+ for a in model.animals #XXX randomise the order?
!isnothing(a) && stepagent!(a, model)
end
# The migrant pool is sorted by date of return, so we can simply look at the top
diff --git a/src/nature/species/skylark.jl b/src/nature/species/skylark.jl
index 6da2935..6ec6835 100644
--- a/src/nature/species/skylark.jl
+++ b/src/nature/species/skylark.jl
@@ -120,8 +120,11 @@ adjusting it to new conditions when and as necessary.
@phase Skylark occupation begin
#move to a random location in the territory
@move(@rand(self.territory))
- if month(model.date) > self.nestingend #XXX check that all the young have left the nest
- @setphase(nonbreeding)
+ if month(model.date) > self.nestingend
+ # once the breeding season is over and all the young have left the nest, stop breeding
+ if self.mate == -1 || @animal(self.mate).clutch == 0
+ @setphase(nonbreeding)
+ end
end
#TODO adjust territory as needed (e.g. once a week, or when a brood is done?)
end
@@ -211,7 +214,7 @@ chicks are independent or in case of brood loss.
#XXX Schachtelbruten - sometimes skylarks start a new nest before the previous young are gone
# wait for eggs to hatch & chicks to mature, checking for predation and disturbance mortality
self.timer += 1
- #XXX this should be habitat-dependent!
+ #TODO this should be habitat-dependent!
if self.timer <= self.eggtime
@chance(self.eggpredationmortality) && destroynest!(self, "predation")
elseif self.timer <= self.eggtime + self.nestlingtime
@@ -220,6 +223,7 @@ chicks are independent or in case of brood loss.
@chance(self.fledglingpredationmortality) && destroynest!(self, "predation")
else
# create new young, reset timer and clutch counter
+ #TODO first year mortality
@reproduce(self.clutch, self.mate)
self.clutch = 0
end
--
GitLab