Nature

nature.jl

This file is responsible for managing the animal modules.

Persephone.AnimalType
Animal

This is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation.

Persephone.animalidMethod
animalid(animal)

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

Persephone.initnature!Method
initnature!(model)

Initialise the model with all simulated animal populations.

Persephone.stepagent!Method
stepagent!(animal, model)

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

Persephone.@hereMacro
@here(property)

A utility macro to quickly access a property of the animal's current position. This can only be used nested within @phase.

Persephone.@killMacro
@kill

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

Persephone.@phaseMacro
@phase(name, body)

This macro is designed to be used within a species definition block (i.e. within the body of a call to @species).

The idea behind this is that species show very different behaviour during different phases 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:

  • animal a reference to the animal itself. This provides access to animal.age, animal.sex, and animal.traits (a dict that gives access to all species parameters).
  • model a reference to the model world (an object of type AgentBasedModel). This allows access to model.date (the current simulation date) and model.landscape (a two-dimensional array of pixels containing geographic information).

Several utility macros can be used within the body of @phase as a short-hand for common expressions: @respond, @trait, @here, @kill, @reproduce

To transition an individual to another phase, simply redefine its phase variable: @trait(phase) = "newphase".

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

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

Persephone.@speciesMacro
@species(name, body)

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:

@species name begin
    initialise! = initpopulation()
    phase = "phase1"
    ...
    @phase phase1 begin
        ...
    end
end

The definition body (enclosed in the begin/end block) has two sections. First comes 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 @phase for details).

There are two parameters that all species must define:

  • initialise! should specify a function that will be used to create the starting population for this species. This function must take two arguments, a species dict and an AgentBasedModel object. The easiest way to create this function is by using initpopultion().
  • phase should be a string specifying the name of the first phase that individuals of this species will be assigned to on birth.

Access to the rest of the model is given by the model variable (an object of type AgentBasedModel).

Persephone.@traitMacro
@trait(traitname)

A utility macro to quickly access an animal's trait value. This can only be used nested within @phase.

lifehistory.jl

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

Persephone.initrandompopulationFunction
initrandompopulation(popsize, asexual=true)

A simplified version of initpopulation(). Creates a function that initialises popsize individuals, spread at random across the landscape. If popsize is less than 1, it is interpreted as a population density (i.e. 1 animal per popsize pixels).

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

Persephone.reproduce!Function
reproduce!(animal, model, n=1)

Produce one or more offspring for the given animal at its current location.

ecologicaldata.jl

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

Persephone.saveindividualdataMethod
saveindividualdata(model)

Print a comma-separated set of lines 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!

Persephone.savepopulationdataMethod
savepopulationdata(model)

Print a comma-separated set of lines 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.