Animal submodel

Animal

This is the generic agent type for all animals. Animal behaviour is defined for each taxon using @create and @phase. Species-specific parameter values are loaded from data files, as specified using the animal.animaldirectory and animal.targetspecies configuration parameters.

In addition to the taxon-specific fields defined by @create, all animals have the following fields:

• id An integer unique identifier for this individual.
• species A string giving the name of the species.
• sex male, female, or hermaphrodite.
• pos An (x, y) coordinate tuple of the individual's current position.
• landelem A pointer to the landscape element this individual currently occupies.
• age The age of the individual in days.
• phase The name of the update function to be called during the current life phase.
• homerange A geometry delimiting this individual's home range or territory.

addanimal!(speciesname, sex, position, model, phase="")

Initialise a new animal individual. Instantiates the object and calls the species' "create" function on it. If phase is empty, it is set to the configured birth phase. Then adds the new animal to the model and returns the animal object.

initanimals!(model)

Initialise the model with all simulated animal populations.

stepagent!(animal, model)

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

updateanimals!(model)

Run processes that affect all animals.

PHASES is a dict that is used to store all phases defined in the model code (by taxon).

@create(taxon, body)

This is a special case of @phase that is used to instantiate animal individuals at birth. Use this to define taxon-specific variables and to initialise their values.

@create <name> begin
    self.<var1> = <value>
    self.<var2> = <value>
    ...
end

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.

@phase(taxon, 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. Species sharing a similar life cycle are grouped together in a taxon. Each phase definition is used for all species belonging to this taxon, with species-specific behaviour encoded using user-configured parameters.

@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 file, as well as all standard Animal variables (e.g. self.age, self.sex, self.offspring).
• 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, @occupy, @rand.

After the phase definition, use phasedoc to document which parameters this phase uses (this is needed to check the validity of species parameter files).

@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).

@checkhabitat(pos=self.landelem, habitatdescriptor)

Check whether the given habitatdescriptor fits the given position. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@cropcover(pos=self.landelem)

Returns the local cropcover. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@cropgroup(pos=self.landelem)

Returns the local cropgroup. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@cropheight(pos=self.landelem)

Returns the local cropheight. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@cropname(pos=self.landelem)

Returns the local cropname. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@destroynest(reason)

Utility wrapper for destroynest!() in the Skylark model.

@directionto(pos=self.pos)

Calculate the direction to a position, 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 (if used with no arguments), or wherever model is available.

@distanceto(pos=self.pos)

Calculate the distance to a position, 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 (if used with no arguments), or wherever model is available.

@distancetoedge(pos=self.pos)

Calculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@findnearest(pos=self.pos)

Calculate the direction to a position, 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 (if used with no arguments), or wherever model is available.

@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.

@inextent(pos)

Check whether the given position is within the extent of the landscape.

@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).

@isoccupied(geom)

Test whether this geometry is already occupied by an animal of this species. This can only be used 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(pos=self.landelem)

Returns the local landcover. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@landelem(pos=self.pos)

Return the landscape element at this position, or the element with id == pos. This is a utility wrapper that can only be used nested within @phase (if used with no arguments), or wherever model is available.

@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.

@neighbours([radius], conspecifics=true)

Return an iterator over all (by default conspecific) animals in the animal's landscape element or within a given radius around its position, excluding itself. This can only be used nested within @phase.

@occupy(geom)

Set the given geometry as the animal's home range. Use @vacate to remove the home range again. This 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.

@vacate()

Remove this animal's home range. This can only be used nested within @phase.

@walk(direction, distance)

Walk the animal in a given direction, which is either specified by a bearing (0-359°), or by a direction string (e.g. "northwest", or "random"). This is a utility wrapper that can only be used nested within @phase.

followanimal!(follower, leader, distance, model)

Move the following animal to a location at most distance away from the leading animal.

isoccupied(geometry, species, model)

Check whether the given geometry could be inserted as a home range without overlapping any other home ranges of the given species.

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.

occupy!(animal, model, geom, exclusive=true)

Create a new HomeRange for the animal with the given geometry. If exclusive is true, this function fails if the given Geom overlaps with an existing HomeRange belonging to a conspecific. Returns true if successful, or false in case of conflicts.

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

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

vacate!(animal, model)

Remove the animal's home range.

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

The animal moves to the point defined by the bearing and distance from its current location.

walk!(animal, model, direction, distance)

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

animal(id, model)

Return the animal with the given ID, or nothing if it's no longer alive.

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

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

countanimals(model, landelem, species="")

Return the number of animals in this landscape element, optionally filtering by species.

homerangesize(animal)

Calculate the size of this animal's home range in m² (utility wrapper).

initindividuals!(species, landelem, model)

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

initpopulation!(speciestype, popinitparams, model)

Initialise the population of the given species, based on the configured initialisation parameters.

isalive(id, model)

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

isoccupied(model, position, species)

Test whether this location is part of the home range of an animal of the given species.

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

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

nearby_animals(model, landelem, species="")

Return a list of animals in this landscape element, optionally filtering by species.

neighbours(animal, model, conspecifics=true)

Return a list of animals in the same landscape element as this animal, excluding itself. By default, only return conspecific animals.

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

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

populationdensity(landelem, model, species="")

Calculate the population density for a given species ("" -> all animals) in a given patch. Returns individuals/hectare.

populationdensity(model, landelem, species="")

Return the population density in individuals/ha of this landscape element, optionally filtering by species.

birdabundance(speciesname, model)

Save bird abundance data, including total abundance and demographic data (abundances of breeding/non-breeding/juvenile/migrated individuals).

butterflyabundance(speciesname, model)

Save butterfly abundance data, including total abundance and demographic data (abundances of breeding/non-breeding/juvenile/migrated individuals).

butterflytrends(speciesname, model)

Save butterfly abundance data, including total abundance and demographic data (abundances of breeding/non-breeding/juvenile/migrated individuals).

initecologicaldata()

Create output files for each data group collected by the animal 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 animal.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 animal.popoutfreq.

SPECIESPARAMS is a dict that stores all species parameters used by phases in the code.

SpeciesParameter

A struct to define a species parameter. This contains not just the parameter name and a short docstring, but also information about the expected type and a function to convert the type as returned by the TOML input file into the required type. In addition, it can contain a dict that returns further species parameters that are required depending on the values chosen for this parameter, as well as a list of value options for this parameter.

addspeciesparam!(name, docstring, type=String, convert=(x)->x; options=[])

Add a new SpeciesParameter to the internal reference system.

checkspeciesdict(params)

Verify that the species dict contains all needed parameters. Returns a vector of missing parameters, or an empty vector if the check is successful. (Note: call this after convertparametertypes!(), as it needs the correct parameter types.)

convertparametertypes!(speciedict)

Convert all parameter values to their specified types, using the metadata stored in SpeciesParameter. Gives a warning when conversion fails. Returns the converted dict (with keys changed from strings to symbols for performance).

initspeciesdicts(animaldir, targetspecies)

Load the species definition files into a dict.

requiredparams(baseparam, value="")

Return the list of parameters that must defined if the baseparam has the given value.

requireparams!(baseparam, value, requiredparams, condition=(x)->true)

Stipulate species parameters that must be defined if the baseparam takes on the given value. Pass an empty string as the value to denote parameters that are always required.

HabitatExpression

The internal type representing habitat descriptors (as created by parsehabitat() and @h_str). Creates a tree structure, consisting of one or two branches joined by a boolean link. The nodes of the tree are HabitatPropertys or nothing.

HabitatProperty

A helper struct for HabitatExpression, storing information about which aspect of the environment is to be tested, what the reference value is, and which comparison to apply.

checkhabitat(position, habitatexpression, model)

Evaluate the given habitat expression with regards to a given position in the model landscape. Returns true or false.

checkhabitat(landelem, habitatexpression)

Evaluate the given habitat expression on a landscape element, recursively evaluating all component expressions and linking them with the relevant boolean operators. Returns true or false.

checkhabitat(landelem, habitatproperty)

Evaluate the given habitat property, returning true if it applies to the given position in the model landscape and false if not.

directionto(pos, model, habitattype)

Calculate the direction from the given location to the closest habitat of the specified type. Returns a coordinate tuple (target - position), or nothing if no matching habitat is found. Caution: can be computationally expensive!

distanceto(pos, model, habitattype)

Calculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!

parsehabitat(descriptor)

Parse a habitat string and return the resulting HabitatExpression. HabitatExpressions can consist of multiple subexpressions, joined by either AND or OR. At the lowest level, each subexpression is parsed using parsehabitatproperty().

Examples: "Fallow", "Orchard OR FruitPlantation", "Grassland OR (GRAIN AND NATURAL)", "ExtensiveGrassland AND (cropheight<=50cm AND cropheight>20cm)", "GRAIN AND (!SilageMaize AND !CornMaize)"

parsehabitatproperty(descriptor)

Parse a HabitatProperty from a string (helper function for parsehabitat()). HabitatProperties may consist of either a single word (which must be a valid instance of a LandCover, LandCoverCategory, CropName, or CropGroup), or a word specifying an aspect and the associated value, separated by one of ==, !=, >=, <=, >, < (and no spaces!). The aspect may be one of "landcover", "landcovercategory", "cropname", "cropgroup", "cropheight", "cropcover". If the property is a single word, a preceding exclamation point may be used to negate it.

Examples: "Arable", "!WinterWheat", "cropgroup==LEGUME", "cropheight<50"

@h_str(s)

A string macro for constructing habitat descriptors. Allows syntax like the following: h"Arable OR Grassland", h"WinterWheat AND height>5cm" Calls parsehabitat().