Select Git revision
nature.html
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
nature.html 36.42 KiB
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Nature · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li class="is-active"><a class="tocitem" href="nature.html">Nature</a><ul class="internal"><li><a class="tocitem" href="#nature.jl"><span>nature.jl</span></a></li><li><a class="tocitem" href="#populations.jl"><span>populations.jl</span></a></li><li><a class="tocitem" href="#insects.jl"><span>insects.jl</span></a></li><li><a class="tocitem" href="#ecologicaldata.jl"><span>ecologicaldata.jl</span></a></li></ul></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="nature.html">Nature</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="nature.html">Nature</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/nature.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Nature"><a class="docs-heading-anchor" href="#Nature">Nature</a><a id="Nature-1"></a><a class="docs-heading-anchor-permalink" href="#Nature" title="Permalink"></a></h1><h2 id="nature.jl"><a class="docs-heading-anchor" href="#nature.jl">nature.jl</a><a id="nature.jl-1"></a><a class="docs-heading-anchor-permalink" href="#nature.jl" title="Permalink"></a></h2><p>This file is responsible for managing the animal modules.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.Animal" href="#Persefone.Animal"><code>Persefone.Animal</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Animal</code></pre><p>This is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation. (Note that each trait variable can still be accessed as if it were a normal field name, i.e. the trait <code>phase</code> can be accessed and modified with <code>animal.phase</code>.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L12-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.animalid-Tuple{Animal}" href="#Persefone.animalid-Tuple{Animal}"><code>Persefone.animalid</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">animalid(animal)</code></pre><p>A small utility function to return a string with the species name and ID of an animal.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L57-L61">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initnature!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initnature!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initnature!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initnature!(model)</code></pre><p>Initialise the model with all simulated animal populations.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L76-L80">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(animal, model)</code></pre><p>Update an animal by one day, executing it's currently active phase function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L66-L70">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@countanimals-Tuple" href="#Persefone.@countanimals-Tuple"><code>Persefone.@countanimals</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@countanimals(species="", radius=0)</code></pre><p>Count the number of animals of the given species in this location. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L379-L385">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@cropheight-Tuple{}" href="#Persefone.@cropheight-Tuple{}"><code>Persefone.@cropheight</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@cropheight</code></pre><p>Return the height of the crop at this position, or 0 if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L346-L352">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@croptype-Tuple{}" href="#Persefone.@croptype-Tuple{}"><code>Persefone.@croptype</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@croptype</code></pre><p>Return the local croptype, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L335-L341">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distanceto-Tuple{Any}" href="#Persefone.@distanceto-Tuple{Any}"><code>Persefone.@distanceto</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distanceto(habitat)</code></pre><p>Calculate the distance to the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L357-L363">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distancetoedge-Tuple{}" href="#Persefone.@distancetoedge-Tuple{}"><code>Persefone.@distancetoedge</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distancetoedge</code></pre><p>Calculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L368-L374">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@habitat-Tuple{Any}" href="#Persefone.@habitat-Tuple{Any}"><code>Persefone.@habitat</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@habitat</code></pre><p>Specify habitat suitability for spatial ecological processes.</p><p>This macro works by creating an anonymous function that takes in a model object and a position, and returns <code>true</code> or <code>false</code> depending on the conditions specified in the macro body.</p><p>Several utility macros can be used within the body of <code>@habitat</code> as a short-hand for common expressions: <a href="nature.html#Persefone.@landcover-Tuple{}"><code>@landcover</code></a>, <a href="nature.html#Persefone.@croptype-Tuple{}"><code>@croptype</code></a>, <a href="nature.html#Persefone.@cropheight-Tuple{}"><code>@cropheight</code></a>, <a href="nature.html#Persefone.@distanceto-Tuple{Any}"><code>@distanceto</code></a>, <a href="nature.html#Persefone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>, <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a>. The variables <code>model</code> and <code>pos</code> can be used for checks that don't have a macro available.</p><p>Two example uses of <code>@habitat</code> might look like this:</p><pre><code class="language-julia hljs">movementhabitat = @habitat(@landcover() in (grass agriculture soil))
nestinghabitat = @habitat((@landcover() == grass ||
(@landcover() == agriculture && @croptype() != maize &&
@cropheight() < 10)) &&
@distanceto(forest) > 20)</code></pre><p>For more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L280-L307">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@initialise-Tuple{Any, Vararg{Any}}" href="#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>Persefone.@initialise</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@initialise(habitatdescriptor; kwargs...)</code></pre><p>Call this macro within the body of <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>. It passes the given habitat descriptor function and keyword arguments on to <a href="nature.html#Persefone.initpopulation-Tuple{Function}"><code>initpopulation</code></a> when setting up the simulation.</p><p>Note: if this macro is not used, the variable <code>initialise!</code> must be set manually in the species definition.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L152-L160">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@kill-Tuple" href="#Persefone.@kill-Tuple"><code>Persefone.@kill</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@kill</code></pre><p>Kill this animal (and immediately abort its current update). This is a thin wrapper around <a href="nature.html#Persefone.kill!"><code>kill!</code></a>, and passes on any arguments. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L245-L251">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@landcover-Tuple{}" href="#Persefone.@landcover-Tuple{}"><code>Persefone.@landcover</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@landcover</code></pre><p>Returns the local landcover. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L325-L330">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@neighbours-Tuple{Any}" href="#Persefone.@neighbours-Tuple{Any}"><code>Persefone.@neighbours</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@neighbours(radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L269-L274">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@phase-Tuple{Any, Any}" href="#Persefone.@phase-Tuple{Any, Any}"><code>Persefone.@phase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@phase(name, body)</code></pre><p>This macro is designed to be used within a species definition block (i.e. within the body of a call to <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>).</p><p>The idea behind this is that species show very different behaviour during different phases of their lives. Therefore, <code>@phase</code> can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.</p><p><code>@phase</code> works by creating a function that will be called by the model if the animal is in the relevant phase. When it is called, it has access to the following variables:</p><ul><li><code>animal</code> a reference to the animal itself. This provides access to <code>animal.age</code>, <code>animal.sex</code>, and <code>animal.<trait></code> (where <trait> is a variable that was defined in the top part of the species definition body).</li><li><code>pos</code> gives the animal's current position as a coordinate tuple.</li><li><code>model</code> a reference to the model world (an object of type <code>AgentBasedModel</code>). This allows access to <code>model.date</code> (the current simulation date) and <code>model.landscape</code> (a two-dimensional array of pixels containing geographic information).</li></ul><p>Several utility macros can be used within the body of <code>@phase</code> as a short-hand for common expressions: <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persefone.@setphase-Tuple{Any}"><code>@setphase</code></a>, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, <a href="nature.html#Persefone.@kill-Tuple"><code>@kill</code></a>, <a href="nature.html#Persefone.@reproduce-Tuple"><code>@reproduce</code></a>, <a href="nature.html#Persefone.@neighbours-Tuple{Any}"><code>@neighbours</code></a>, <a href="io.html#Persefone.@rand-Tuple"><code>@rand</code></a>, <a href="io.html#Persefone.@shuffle!-Tuple{Any}"><code>@shuffle!</code></a>.</p><p>Note that the first phase that is defined in a species definition block will be the phase that animals are assigned at birth, unless the variable <code>phase</code> is explicitly defined by the user in the species definition block.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L165-L195">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@reproduce-Tuple" href="#Persefone.@reproduce-Tuple"><code>Persefone.@reproduce</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@reproduce</code></pre><p>Let this animal reproduce. This is a thin wrapper around <a href="energy.html#Persefone.reproduce!-Tuple{Persefone.EnergyBudget}"><code>reproduce!</code></a>, and passes on any arguments. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L259-L264">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@respond-Tuple{Any, Any}" href="#Persefone.@respond-Tuple{Any, Any}"><code>Persefone.@respond</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@respond(eventname, body)</code></pre><p>Define how an animal responds to a landscape event that affects its current position. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L231-L236">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@setphase-Tuple{Any}" href="#Persefone.@setphase-Tuple{Any}"><code>Persefone.@setphase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@setphase(newphase)</code></pre><p>Switch this animal over to a different phase. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L221-L225">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@species-Tuple{Any, Any}" href="#Persefone.@species-Tuple{Any, Any}"><code>Persefone.@species</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@species(name, body)</code></pre><p>A macro used to create new species definitions for the nature model. This is effectively a simple domain-specific language, establishing a custom syntax to describe species' biology:</p><pre><code class="language-julia hljs">@species name begin
@initialise(@habitat(...))
speciesvar1 = 3.14
...
@phase phase1 begin
...
end
end</code></pre><p>The definition body (enclosed in the begin/end block) has two sections. First comes a call to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, and optionally a list of species-specific parameters, which are assigned just like normal variables. Second come one or more phase definitions, that describe the behaviour of the species during various parts of its life cycle. (See the documentation to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> and <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> for details).</p><p>Code in a species definition block can access the rest of the model using the <code>model</code> variable (an object of type <code>AgentBasedModel</code>).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L99-L128">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@trait-Tuple{Any}" href="#Persefone.@trait-Tuple{Any}"><code>Persefone.@trait</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@trait(traitname)</code></pre><p>A utility macro to quickly access an animal's trait value. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L207-L212">source</a></section></article><h2 id="populations.jl"><a class="docs-heading-anchor" href="#populations.jl">populations.jl</a><a id="populations.jl-1"></a><a class="docs-heading-anchor-permalink" href="#populations.jl" title="Permalink"></a></h2><p>This file contains a set of utility functions for species, including initialisation, reproduction, and mortality.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.countanimals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">countanimals(pos, model; species="", radius=0)</code></pre><p>Count the number of animals in this location (optionally supplying a species name and radius).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L137-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initpopulation-Tuple{Function}" href="#Persefone.initpopulation-Tuple{Function}"><code>Persefone.initpopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initpopulation(habitatdescriptor; popsize=-1, pairs=false, asexual=false)</code></pre><p>Creates a function that initialises individuals at random locations across the landscape. This can be used to create the <code>initialise!</code> variable in a species definition block.</p><ul><li><p><code>habitatdescriptor</code> is a function that determines whether a given location is suitable or not (create this using <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>).</p></li><li><p><code>phase</code> determines which life phase individuals will be assigned to. If this is <code>nothing</code>, the species' default post-natal life stage will be used (although note that this is probably not what you want).</p></li><li><p><code>popsize</code> determines the number of individuals that will be created. If this is zero or negative, one individual will be created in every suitable location in the landscape. If <code>popsize</code> is greater than the number of suitable locations, multiple individuals will be created in one place. (Maximum population density can be set in the habitat descriptor using the <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a> macro.)</p></li><li><p>If <code>pairs</code> is true, a male and a female individual will be created in each selected location, otherwise, only one individual will be created at a time.</p></li><li><p>If <code>asexual</code> is true, all created individuals are assigned the sex <code>hermaphrodite</code>, otherwise, they are randomly assigned male of female. (If <code>pairs</code> is true, <code>asexual</code> is ignored.)</p></li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L7-L32">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initrandompopulation-Tuple{Int64}" href="#Persefone.initrandompopulation-Tuple{Int64}"><code>Persefone.initrandompopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initrandompopulation(popsize; kwargs...)</code></pre><p>A simplified version of <a href="nature.html#Persefone.initpopulation-Tuple{Function}"><code>initpopulation</code></a>. Creates a function that initialises <code>popsize</code> individuals, spread at random across the landscape.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L70-L75">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.kill!" href="#Persefone.kill!"><code>Persefone.kill!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">kill(animal, model, probability=1.0, cause="")</code></pre><p>Kill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L99-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(animal, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L126-L130">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(pos, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this position.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L115-L119">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.reproduce!" href="#Persefone.reproduce!"><code>Persefone.reproduce!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">reproduce!(animal, model, n=1)</code></pre><p>Produce one or more offspring for the given animal at its current location.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L84-L88">source</a></section></article><h2 id="insects.jl"><a class="docs-heading-anchor" href="#insects.jl">insects.jl</a><a id="insects.jl-1"></a><a class="docs-heading-anchor-permalink" href="#insects.jl" title="Permalink"></a></h2><p>This file contains the insect submodel, which calculates the likely insect biomass in a given location at a given time.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}" href="#Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}"><code>Persefone.insectbiomass</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">insectbiomass(pixel, model)</code></pre><p>Calculate the insect biomass in this location, using the factors configured in the <code>nature.insectmodel</code> settings (any combination of: "season", "habitat", "weather", "pesticides"). Returns a float value in g/m².</p><p><strong>Biological note:</strong> this is a very approximate calculation! Insect biomass varies wildly in time and space and is hard to measure. This calculation is based on the idea of a parabolic seasonal development of insect abundance, modified by habitat suitability, weather, and pesticide application. Although it is based on empirical studies, it can only deliver a rough, order-of-magnitude estimation of likely insect biomass in a given location.</p><p><strong>Sources:</strong></p><ul><li>Odderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.</li><li>Grüebler et al. (2008). A predictive model of the density of airborne insects in agricultural environments. Agriculture, Ecosystems & Environment, 123(1), 75–80. https://doi.org/10.1016/j.agee.2007.05.001</li><li>Paquette et al. (2013). Seasonal patterns in Tree Swallow prey (Diptera) abundance are affected by agricultural intensification. Ecological Applications, 23(1), 122–133. https://doi.org/10.1890/12-0068.1</li><li>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</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/insects.jl#L6-L26">source</a></section></article><h2 id="ecologicaldata.jl"><a class="docs-heading-anchor" href="#ecologicaldata.jl">ecologicaldata.jl</a><a id="ecologicaldata.jl-1"></a><a class="docs-heading-anchor-permalink" href="#ecologicaldata.jl" title="Permalink"></a></h2><p>This file contains a set of life-history related utility functions needed by species.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}" href="#Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}"><code>Persefone.initecologicaldata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initecologicaldata()</code></pre><p>Create output files for each data group collected by the nature model.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L9-L13">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.saveindividualdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">saveindividualdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>individuals.csv</code>), listing all properties of all animal individuals in the model. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.indoutfreq</code>. WARNING: Produces very big files!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L42-L49">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.savepopulationdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">savepopulationdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>populations.csv</code>), giving the current date and population size for each animal species. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.popoutfreq</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L21-L28">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="io.html">« Input, Output, and Settings</a><a class="docs-footer-nextpage" href="energy.html">Dynamic Energy Budgets »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>