Parameters

Table of Contents

• Parameters
  • Carrying Capacity
  • Mortality
    • Conversion
  • Fecundity

Sets of parameters may be customized and prepared prior to adding them to a Species (Populations) or a Model Domain. They may be created to be used with multiple Species (Populations) or Model Domain objects, and are usually accompanied by a gridded (or raster) dataset when added to the Model Domain. Inter-species relationships are also defined using Parameters, whereby tables of correlations between population density and parameter values or coefficients are provided.

Paramters consist of:

CarryingCapacity(name, **kwargs)	Carrying Capacity is used to define the maximum population that may be supported for one or more Species in a Domain.
Mortality(name, **kwargs)	Mortality drivers are used to define rates of population decline for one or more Species.
Fecundity(name, **kwargs)	Fecundity is used to define a set of reproductive attributes that may be tied to one or more Species.

When inter-species relationships are specified, the following describes the input lookup table format:

[(x1, y1), (x2, y2), ..., (xn, yn)]

Where x is the density of the affecting species, and y is the parameter value applied to the affected species. Parameter values \(y_m\) are linearly interpolated between lookup points, given the density \(x_m\):

\[y_m=y_0+\frac{x_m-x_0}{x_1-x_0}(y_1-y_0)\]

Stochastic processes may also be represented using Parameters. A single random number generator may be chosen to perturb parameter data in a Model Domain in one of two ways:

1. Random numbers are generated at each element (i.e. node or grid cell) in the domain during a simulation; or
2. A single random number is generated and applied evenly to all elements in the domain

The behaviour and type of the random number generators is flexible, and each of the Distributions available in the numpy.random module are available. For example, if random numbers (\(X\)) are chosen from a normal distribution, the input argument for the method would be the scale, or one standard deviation. Using method 1 (above), the value of each element \(param(i)\) would be used for the mean value in the normal distribution:

\[param_o(i)=X\sim\mathcal{N}(param(i),\sigma^2)\]

where,

\(param_o\) is the stochastic parameter

If using method 2 (above), the mean value of the entire study area (\(\mu\)) would be used as the mean in the normal distribution and a delta will be calculated at each element using the random value:

\[\mu=\frac{\sum_{i=1}^{n}param(i)[k_T(i)\neq0]}{n}\]

\[param_o(i)=param(i)+(X\sim\mathcal{N}(\mu,\sigma^2)-param(i))\]

\[param_o(i)=max\{0, param_o(i)\}\]

where,

\(k_T\) is the total carrying capacity of the species.

Carrying Capacity

Carrying Capacity is used in popdyn models to define means to enhance or reduce the ability for populations to exist in a model domain. It is used numerically to relate populations to density, which drives a number of model processes. When added to a model domain, Carrying Capacity data are effectively a population potential in the study area, and are expressed as a total population for each data point. Multiple Carrying Capacity instances may be added to a given Species (Populations) in a model Model Domain, and they will be summed to yield the total Carrying Capacity \(k\) at time \(t\) for each source \(i\):

\[k(t)=\sum_{i=1}^{n} k_i(t)\]

Carrying Capacity may also be derived using the density of another species and a lookup table (as outlined above), which may be invoked using the add_as_species() method. The \(y\) value in the lookup table is a coefficient that is applied to the Carrying Capacity of the affected species:

\[k=yk\]

class popdyn.CarryingCapacity(name, **kwargs)

Carrying Capacity is used to define the maximum population that may be supported for one or more Species in a Domain.

Carrying Capacity effectively represents habitat quality, and is added to a Species or Domain alongside data. Multiple types of Carrying Capacity may be added to a given species, as they are added together in the domain. When another species is added (using the add_as_species() method) to a Carrying Capacity instance, the affecting species will scale the Carrying Capacity using a coefficient specified in the lookup table.

Note

multiple Carrying Capacities may be tied to an individual species, and they are stacked in the domain

Parameters:name – Name of the Carrying Capacity (25 chars). Use something short and intuitive, such as “Marsh”.

add_as_species(species, lookup_table, population_type='density')

Inter-species relationships are specified using this method, whereby a parameter is calculated using an attribute of another species. The density of the input species is used to calculate either a value, or a coefficient that modifies the value using a table.

Parameters:

• species (Species) – Species instance
• lookup_table (iterable) – A table to define the relationship between the input species population type and the parameter. The lookup table x-values define the population type of the input species, and the y-values define this parameter, in the form: [(x1, y1), (x2, y2)...(xn, yn)]
• population_type (str) – Variable related to population of the input species to use to derive the parameter. choose from -'total population', which is the total population of the affecting species -'density', which is the density (n/k) of the affecting species -'global ratio', which is the ratio of this species of the global total population (n/n_global). See the Species attribute global_population.

random(type, **kwargs)

Apply a type of random variability to this parameter. Random numbers are generated using one of the available distributions from the numpy.random module.

Parameters:type – Variance type. Use one of the random distribution generator methods in numpy.random Keyword Arguments:  Keyword arguments should match all required arguments to the selected numpy.random method

Mortality

Mortality is used to define and constrain ways for Species populations to decline. Any number of mortality drivers may be created and added to a model domain. They are usually added to a model domain with rate data \(q\), which are used to calculate a number of deaths (\(m\)):

\[m=pop\cdot q\]

where \(pop\) is the population that mortality is applied to.

Mortality may also be derived using the density of another species and a lookup table (as outlined above), which may be invoked using the add_as_species() method. The \(y\) value in the lookup table is a mortality rate (\(q\) above) used on the affected species.

Conversion

One additional option when creating mortality is to define a recipient species to apply deaths to. This functionality was conceived to perform infection and disease modelling, whereby infected and non-infected populations are treated as separate species with their own unique traits. The rate of mortality in these cases would be the rate of infection, and individuals would be transferred from one species to another.

class popdyn.Mortality(name, **kwargs)

Mortality drivers are used to define rates of population decline for one or more Species.

Mortality is added to a Species and a Domain together, optionally with data. When another Species is added (using the add_as_species() method), the affecting species will impose a mortality rate using the included lookup table. Multiple mortality instances may be added to a given Species. The mortality name cannot be any of “mortality”, “density dependent”, or “old age” because of implicit mortality types used in solvers.

Mortality driver instance

Parameters:

• name (str) – Name of the mortality (25 chars). Use something short and intuitive, such as “Poaching”.
• is_rate – This mortality is defined as a rate, as opposed to an absolute number (default is True)

add_as_species(species, lookup_table, population_type='density')

Inter-species relationships are specified using this method, whereby a parameter is calculated using an attribute of another species. The density of the input species is used to calculate either a value, or a coefficient that modifies the value using a table.

Parameters:

• species (Species) – Species instance
• lookup_table (iterable) – A table to define the relationship between the input species population type and the parameter. The lookup table x-values define the population type of the input species, and the y-values define this parameter, in the form: [(x1, y1), (x2, y2)...(xn, yn)]
• population_type (str) – Variable related to population of the input species to use to derive the parameter. choose from -'total population', which is the total population of the affecting species -'density', which is the density (n/k) of the affecting species -'global ratio', which is the ratio of this species of the global total population (n/n_global). See the Species attribute global_population.

add_recipient_species(species)

The population that succumbs to this mortality may be added to another species. This is primarily used to track infection and disease, whereby infected individuals are treated as a different species.

Parameters:species (Species) – The recipient Species for populations that succumb to this mortality

add_time_based_mortality(rates, random_std=None)

Time-based mortality defines a set of mortality rates over a given duration

Using the Discrete Explicit solver, at any time when a species population is greater than 0, a counter accumulates the number of consecutive years that the species has a non-zero population. The input mortality rates are used consecutively over the counted duration when time-based mortality is used.

Parameters:

• rates – An iterable of mortality rates that applies from time 0 to time len(rates)
• random_std (float) – A standard deviation to generate random variation on rates using a normal distribution

random(type, **kwargs)

Apply a type of random variability to this parameter. Random numbers are generated using one of the available distributions from the numpy.random module.

Parameters:type – Variance type. Use one of the random distribution generator methods in numpy.random Keyword Arguments:  Keyword arguments should match all required arguments to the selected numpy.random method

Fecundity

Fecundity is used to create means for species to reproduce. Fecundity is used to specify:

• Whether a Species (Populations) is able to reproduce
• The effect of density on reproduction
• Allocation of offspring
• Effects another species may have on reproduction

Just as the other parameters, Fecundity can have stochasticity and may be derived using the density of another species, based on a lookup table (as outlined above). Inter-species effects on fecundity are specified using the add_as_species() method, where \(y\) in the lookup table is a Fecundity rate (\(q\)) used to determine the number of offspring per individual (\(n\)) of the affected species:

\[n=pop\cdot q\]

class popdyn.Fecundity(name, **kwargs)

Fecundity is used to define a set of reproductive attributes that may be tied to one or more Species.

Fecundity is added to a Species and a Domain together, optionally with data. When another Species is added (using the add_as_species() method), the affecting species will impose a fecundity value using the included lookup table.

Parameters:

name – Name of the Fecundity (25 chars). Use something short and intuitive, such as “Normal Adult”.

Keyword Arguments:  

birth_ratio (bool) –

The birth ratio is used to allocate offspring as a ratio of males to females. The birth ratio may also be random (use 'random'), which uses a uniform random number generator to select a ratio between 0 and 1 for each element in the domain. (Default: 0.5)

add_as_species(species, lookup_table, population_type='density')

Inter-species relationships are specified using this method, whereby a parameter is calculated using an attribute of another species. The density of the input species is used to calculate either a value, or a coefficient that modifies the value using a table.

Parameters:

• species (Species) – Species instance
• lookup_table (iterable) – A table to define the relationship between the input species population type and the parameter. The lookup table x-values define the population type of the input species, and the y-values define this parameter, in the form: [(x1, y1), (x2, y2)...(xn, yn)]
• population_type (str) – Variable related to population of the input species to use to derive the parameter. choose from -'total population', which is the total population of the affecting species -'density', which is the density (n/k) of the affecting species -'global ratio', which is the ratio of this species of the global total population (n/n_global). See the Species attribute global_population.

random(type, **kwargs)

Apply a type of random variability to this parameter. Random numbers are generated using one of the available distributions from the numpy.random module.

Parameters:type – Variance type. Use one of the random distribution generator methods in numpy.random Keyword Arguments:  Keyword arguments should match all required arguments to the selected numpy.random method