Nature

Animal

This is the generic agent type for all animals. Individual species are created using the @species macro. In addition to user-defined, species-specific fields, all species contain the following fields:

• id An integer unique identifier for this individual.
• sex male, female, or hermaphrodite.
• parents The IDs of the individual's parents.
• pos An (x, y) coordinate tuple.
• age The age of the individual in days.
• phase The update function to be called during the individual's current life phase.
• energy A DEBparameters struct for calculating energy budgets.
• offspring A vector containing the IDs of an individual's children.

animalid(animal)

A small utility function to return a string with the species name and ID of an animal.

create!(animal, model)

The create! function is called for every individual at birth or at model initialisation. Species must use @create to define a species-specific method. This is the fall- back method, in case none is implemented for a species.

initnature!(model)

Initialise the model with all simulated animal populations.

killallanimals!(model)

Remove all animal individuals from the simulation.

speciesof(animal)

Return the species name of this animal as a string.

speciestype(name)

Return the Type of this species.

stepagent!(animal, model)

Update an animal by one day, executing it's currently active phase function.

updatenature!(model)

Run processes that affect all animals.

@animal(id)

Return the animal object associated with this ID number. This can only be used in a context where the model object is available (e.g. nested within @phase).

@countanimals(radius=0, species="")

Count the number of animals at or near this location, optionally filtering by species. This can only be used nested within @phase or @habitat.

@create(species, body)

Define a special phase function (create!()) that will be called when an individual of this species is created, at the initialisation of the simulation or at birth.

As for @phase, the body of this macro has access to the variables self (the individual being created) and model (the simulation world), and can thus use all macros available in @phase.

@cropheight

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 @phase or @habitat.

@cropname

Return the name of the local croptype, or an empty string if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.

@directionto

Calculate the direction to an animal or the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within @phase or @habitat.

@distanceto

Calculate the distance to an animal or the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within @phase or @habitat.

@distancetoedge

Calculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within @phase or @habitat.

@follow(leader, distance)

Move to a location within the given distance of the leading animal. This is a utility wrapper that can only be used nested within @phase.

@habitat

Specify habitat suitability for spatial ecological processes.

This macro works by creating an anonymous function that takes in a model object and a position, and returns true or false depending on the conditions specified in the macro body.

Several utility macros can be used within the body of @habitat as a short-hand for common expressions: @landcover, @cropname, @cropheight, @distanceto, @distancetoedge, @countanimals. The variables model and pos can be used for checks that don't have a macro available.

Two example uses of @habitat might look like this:

movementhabitat = @habitat(@landcover() in (grass agriculture soil))

nestinghabitat = @habitat((@landcover() == grass || 
                           (@landcover() == agriculture && @cropname() != "maize" &&
                            @cropheight() < 10)) &&
                          @distanceto(forest) > 20)

For more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.

@here()

Return the landscape pixel of this animal's current location. This can only be used nested within @phase.

@isalive(id)

Test whether the animal with the given ID is still alive. This can only be used in a context where the model object is available (e.g. nested within @phase).

@kill

Kill this animal (and immediately abort its current update if it dies). This is a thin wrapper around kill!, and passes on any arguments. This can only be used nested within @phase.

@killother

Kill another animal. This is a thin wrapper around kill!, and passes on any arguments. This can only be used nested within @phase.

@landcover

Returns the local landcover. This is a utility wrapper that can only be used nested within @phase or @habitat.

@migrate(arrival)

Remove this animal from the map and add it to the migrant species pool. It will be returned to its current location at the specified arrival date. This can only be used nested within @phase.

@move(position)

Move the current individual to a new position. This is a utility wrapper that can only be used nested within @phase.

@nearby_animals(radius=0, species="")

Return an iterator over all animals in the given radius around the current position. This can only be used nested within @phase or @habitat.

@neighbours(radius=0, conspecifics=true)

Return an iterator over all (by default conspecific) animals in the given radius around this animal, excluding itself. This can only be used nested within @phase.

@phase(name, body)

Use this macro to describe a species' behaviour during a given phase of its life. The idea behind this is that species show very different behaviour at different times of their lives. Therefore, @phase can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.

@phase 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:

• self a reference to the animal itself. This provides access to all the variables defined in the @species definition, as well as all standard Animal variables (e.g. self.age, self.sex, self.offspring).
• pos gives the animal's current position as a coordinate tuple.
• model a reference to the model world (an object of type SimulationModel). This allows access, amongst others, to model.date (the current simulation date) and model.landscape (a two-dimensional array of pixels containing geographic information).

Many macros are available to make the code within the body of @phase more succinct. Some of the most important of these are: @setphase, @respond, @kill, @reproduce, @neighbours, @migrate, @move, @rand.

@populate(species, params)

Set the parameters that are used to initialise this species' population. For parameter options, see PopInitParams.

@populate <species> begin
    <parameter> = <value>
    ...
end 

@randomdirection(range=1)

Return a random direction tuple that can be passed to @walk. This is a utility wrapper that can only be used nested within @phase.

@randompixel(range, habitatdescriptor)

Find a random pixel within a given range of the animal's location that matches the habitatdescriptor (create this using @habitat). This is a utility wrapper that can only be used nested within @phase.

@reproduce

Let this animal reproduce. This is a thin wrapper around reproduce!, and passes on any arguments. This can only be used nested within @phase.

@respond(eventname, body)

Define how an animal responds to a landscape event that affects its current position. This can only be used nested within @phase.

@setphase(newphase)

Switch this animal over to a different phase. This can only be used nested within @phase.

@species(name, body)

A macro used to add new species types to the nature model. Use this to define species-specific variables and parameters.

The macro works by creating a keyword-defined mutable struct that contains the standard fields described for the Animal type, as well as any new fields that the user adds:

@species <name> begin
    <var1> = <value>
    <var2> = <value>
    ...
end

To complete the species definition, the @phase, @create, and @populate macros also need to be used.

@walk(direction, speed)

Walk the animal in a given direction, which is specified by a tuple of coordinates relative to the animal's current position (i.e. (2, -3) increments the X coordinate by 2 and decrements the Y coordinate by 3.) This is a utility wrapper that can only be used nested within @phase.

PopInitParams

A set of parameters used by initpopulation to initialise the population of a species at the start of a simulation. Define these parameters for each species using @populate.

• initphase determines which life phase individuals will be assigned to at model initialisation (required).

• birthphase determines which life phase individuals will be assigned to at birth (required).

• habitat is a function that determines whether a given location is suitable or not (create this using @habitat). By default, every cell will be occupied.

• popsize determines the number of individuals that will be created, dispersed over the suitable locations in the landscape. If this is zero or negative, one individual will be created in every suitable location. If it is greater than the number of suitable locations, multiple individuals will be created per location. Alternately, use indarea.

• indarea: if this is greater than zero, it determines the habitat area allocated to each individual or pair. To be precise, the chance of creating an individual (or pair of individuals) at a suitable location is 1/indarea. Use this as an alternative to popsize.

• If pairs 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. (default: false)

• If asexual is true, all created individuals are assigned the sex hermaphrodite, otherwise, they are randomly assigned male or female. If pairs is true, asexual is ignored. (default: false)

countanimals(pos, model; radius=0, species="")

Return the number of animals in the given radius around this position, optionally filtering by species.

directionto(pos, model, animal)

Calculate the direction from the given position to the animal.

distanceto(pos, model, animal)

Calculate the distance from the given position to the animal.

followanimal!(follower, leader, model, distance=0)

Move the follower animal to a location near the leading animal.

initindividuals!(species, pos, popinitparams, model)

Initialise one or two individuals (depending on the pairs parameter) in the given location. Returns the number of created individuals. (Internal helper function for initpopulation!().)

initpopulation!(speciesname, model)

Initialise the population of the given species, based on the parameters stored in PopInitParams. Define these using @populate.

initpopulation!(speciestype, popinitparams, model)

Initialise the population of the given species, based on the given initialisation parameters. This is an internal function called by initpopulation!(), and was split off from it to allow better testing.

isalive(id, model)

Test whether the animal with the given ID is still alive.

kill!(animal, model, probability=1.0, cause="")

Kill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.

migrate!(animal, model, arrival)

Remove this animal from the map and add it to the migrant species pool. It will be returned to its current location at the specified arrival date.

move!(animal, model, position)

Move the animal to the given position, making sure that this is in-bounds. If the position is out of bounds, the animal stops at the map edge.

nearby_animals(pos, model; radius= 0, species="")

Return a list of animals in the given radius around this position, optionally filtering by species.

nearby_ids(pos, model, radius)

Return a list of IDs of the animals within a given radius of the position.

neighbours(animal, model, radius=0, conspecifics=true)

Return a list of animals in the given radius around this animal, excluding itself. By default, only return conspecific animals.

populationparameters(type)

A function that returns a PopInitParams object for the given species type. Parametric methods for each species are defined with @populate. This is the catch-all method, which throws an error if no species-specific function is defined.

reproduce!(animal, model, mate, n=1)

Produce one or more offspring for the given animal at its current location. The mate argument gives the ID of the reproductive partner.

walk!(animal, model, direction, distance=-1)

Let the animal move in the given direction, where the direction is defined by an (x, y) tuple to specify the shift in coordinates. If maxdist >= 0, move no further than the specified distance.

walk!(animal, model, direction, distance=1pixel)

Let the animal move a given number of steps in the given direction ("north", "northeast", "east", "southeast", "south", "southwest", "west", "northwest", "random").

insectbiomass(pixel, model)

Calculate the insect biomass in this location, using the factors configured in the nature.insectmodel settings (any combination of: "season", "habitat", "weather", "pesticides"). Returns a float value in g/m².

Biological note: 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.

Sources:

• Odderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.
• 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
• 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
• 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

initecologicaldata()

Create output files for each data group collected by the nature model.

saveindividualdata(model)

Return a data table (to be printed to individuals.csv), 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 nature.indoutfreq. WARNING: Produces very big files!

savepopulationdata(model)

Return a data table (to be printed to populations.csv), 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 nature.popoutfreq.