Nature submodel

nature.jl

This file is responsible for managing the animal modules.

Persefone.AnimalType
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.
  • territory A vector of coordinates that comprise the individual's territory.
source
Persefone.animalidMethod
animalid(animal)

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

source
Persefone.create!Method
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.

source
Persefone.stepagent!Method
stepagent!(animal, model)

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

source

macros.jl

This file contains all the macros that can be used in the species DSL.

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

source
Persefone.@countanimalsMacro
@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.

source
Persefone.@createMacro
@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.

source
Persefone.@cropcoverMacro
@cropcover

Return the percentage ground cover of the crop at this position, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.

source
Persefone.@cropheightMacro
@cropheight

Return the height of the crop at this position, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.

source
Persefone.@cropnameMacro
@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.

source
Persefone.@directiontoMacro
@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.

source
Persefone.@distancetoMacro
@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.

source
Persefone.@followMacro
@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.

source
Persefone.@habitatMacro
@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.

source
Persefone.@hereMacro
@here()

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

source
Persefone.@isaliveMacro
@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).

source
Persefone.@isoccupiedMacro
@isoccupied(position)

Test whether this position is already occupied by an animal of this species. This can only be used nested within @phase.

source
Persefone.@killMacro
@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.

source
Persefone.@lastyearMacro
@lastyear(annualdate)

Construct a date object referring to the last year in the model from an AnnualDate. Only use in scopes where model is available.

source
Persefone.@migrateMacro
@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.

source
Persefone.@moveMacro
@move(position)

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

source
Persefone.@neighboursMacro
@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.

source
Persefone.@nextyearMacro
@nextyear(annualdate)

Construct a date object referring to the next year in the model from an AnnualDate. Only use in scopes where model is available.

source
Persefone.@occupyMacro
@occupy(position)

Add the given position to this animal's territory. Use @vacate to remove positions from the territory again. This can only be used nested within @phase.

source
Persefone.@phaseMacro
@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, @occupy, @rand.

source
Persefone.@populateMacro
@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 
source
Persefone.@randompixelMacro
@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.

source
Persefone.@respondMacro
@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.

source
Persefone.@speciesMacro
@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.

source
Persefone.@thisyearMacro
@thisyear(annualdate)

Construct a date object referring to the current model year from an AnnualDate. Only use in scopes where model is available.

source
Persefone.@vacateMacro
@vacate(position)

Remove the given position from this animal's territory. This can only be used nested within @phase.

source
Persefone.@walkMacro
@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.

source

individuals.jl

This file contains life-history and other ecological functions that apply to all animal individuals, such reproduction, death, and movement.

Persefone.followanimal!Function
followanimal!(follower, leader, model, distance=0)

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

source
Persefone.kill!Function
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.

source
Persefone.migrate!Method
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.

source
Persefone.move!Method
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.

source
Persefone.occupy!Method
occupy!(animal, model, position)

Add the given location to the animal's territory. Returns true if successful (i.e. if the location was not already occupied by a conspecific), false if not.

source
Persefone.reproduce!Function
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.

source
Persefone.vacate!Method
vacate!(animal, model, position)

Remove this position from the animal's territory.

source
Persefone.walk!Function
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.

source
Persefone.walk!Function
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").

source

populations.jl

This file contains functions that apply to all animal populations, such as for initialisation, or querying for neighbours.

Persefone.PopInitParamsType
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)

source
Persefone.countanimalsMethod
countanimals(pos, model; radius=0, species="")

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

source
Persefone.initindividuals!Method
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!().)

source
Persefone.initpopulation!Method
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.

source
Persefone.isoccupiedMethod
isoccupied(model, position, species)

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

source
Persefone.nearby_animalsMethod
nearby_animals(pos, model; radius= 0, species="")

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

source
Persefone.nearby_idsMethod
nearby_ids(pos, model, radius)

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

source
Persefone.neighboursFunction
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.

source
Persefone.populationparametersMethod
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.

source
Persefone.territorysizeFunction
territorysize(animal, model, stripunits=false)

Calculate the size of this animal's territory in the given unit. If stripunits is true, return the size as a plain number.

source

ecologicaldata.jl

This file contains a set of life-history related utility functions needed by species.

Persefone.saveindividualdataMethod
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!

source
Persefone.savepopulationdataMethod
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.

source
Persefone.skylarkabundanceMethod
skylarkabundance(model)

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

source
Persefone.skylarkterritoriesMethod
skylarkterritories(model)

Return a list of all coordinates occupied by a skylark territory, and the ID of the individual holding the territory. WARNING: produces very big files.

source