Model Domain
A popdyn model Model Domain provides a framework for simulations so they may be spatially and temporally discretized,
and parameterized. The primary purposes of a Model Domain are to:
- Manage a file to store study area data in HDF5 format, and act as a quasi-database for the model domain attributes.
The file will be automatically created with the extension
.popdyn, and can be used to instantiate Domain
instances.
- The Model Domain has a consistent spatial extent and anisotropic grid resolution
- Data added to a domain are automatically read, spatially transformed, converted, and stored on the disk.
- Data are commonly added with Species (Populations) or Parameters instances to add them and corresponding data to the
Model Domain
- Domain instances are provided to selected Numerical Solvers to calculate derived parameters and simulate populations in
the model
- Computation “chunks” are also specified in the domain to make use of distributed schedulers that allow parallel
computation and make memory (RAM) usage predictable
Species (and accompanying data) are added to a model domain using parameters or population data using one of the
following methods:
Attention
All parameters or data that are added to a model domain must be in the same spatial and temporal units
Data associated with Species (Populations) or Parameters may be added to the model domain using one of the following
formats:
- A raster dataset. If the raster spatial reference and geotransform do not match the domain, it will be automatically
resampled using nearest neighbour interpolation when added to the domain.
- A numpy array-like object with a shape matching the
model domain, or in a shape that can be
broadcasted to the shape of the model domain.
- A scalar that is repeated over all domain elements.
Data added to a model domain may also be distributed using any of the following keyword arguments:
distribute: If the input data are scalars, the value will be divided evenly among all domain elements:
\[param/n\]
where \(param\) is the value, and \(n\) is the number of domain elements).
If data are arrays, the sum will
be evenly divided among all domain elements:
\[\frac{\sum_{i=1}^{n}param(i)}{n}\]
distribute_by_habitat: Use habitat quality to linearly distribute the input parameter data. Data that are
scalars or arrays are aggregated using the same method as distribute. The \(param\) value is distributed over
habitat (\(k\)) using the following:
\[param\cdot \frac{k(i)[k(i)\neq 0]}{\sum_{i=1}^{n}k(i)[k(i)\neq 0]}\]
Once added to a domain, species with the same name automatically become stratified by their name, sex, and age groups,
and are able to inherit mortality and fecundity based on a species - sex - age group hierarchy.
Note
Remember, for inheritance to work, the members of the same species added to the model domain must have matching names
Time is also discretized in the model domain. Data related to species and parameters are tied to a specific time, which
is used in the solvers. Time is always represented as whole numbers, although these numbers are not constrained to any
interval or time format. For example, a model domain that is solved annually will contain data that is tied to a specific
year. A model domain that is solved every second will have data added at a specific second over the duration of the model.
The start and end times are specified in the solvers.
-
class
popdyn.Domain(popdyn_path, domain_raster=None, **kwargs)
Population dynamics simulation domain, which is used to define a study area for a popdyn simulation
Species, Parameters, and datasets are added to the model domain, which creates a file to _save and store all information
To create a Model Domain, one of either an existing .popdyn file, a raster, or construct the domain
using the keyword arguments
| Parameters: |
- path (str) – Path to a new (new Domain) or existing (existing Domain)
.popdyn file on the disk
- domain_raster (str) – Path to an existing raster on the disk that defines the domain extent and resolution
|
|---|
| Keyword Arguments: |
|---|
| |
- shape (tuple) –
Number of rows and columns of the study area [(rows, cols)]
- csx (float) –
Grid spacing (cell size) in the x-direction
- csy (float) –
Grid spacing (cell size) in the y-direction
- top (float) –
The northernmost coordinate of the study area
- left (float) –
The westernmost coordinate of the study area
- projection (int) –
Spatial Reference of the study area, which must be an EPSG code
|
-
add_population(species, data, time, **kwargs)
Add population data for a given species at a specific time slice in the domain.
| Parameters: |
- species (Species) – A Species instance
- data – Population data. This may be a scalar, raster, or vector/matrix (broadcastable to the domain)
- time – The time slice to insert the population data into
|
|---|
| Keyword Arguments: |
|---|
| |
- distribute_by_habitat (bool) –
Divide the sum of the input population linearly among domain elements using the covariate
carrying capacity (Default: False)
- discrete_age (int) –
Apply the input population to a single discrete age in the age group (Default: None)
- distribute (bool) –
Divide the sum of the input data evenly among all domain nodes (grid cells) (default: True)
- overwrite (str) –
Overwrite method for replacing existing data. Use one of ['replace', 'add'] (Default ‘replace’)
|
-
add_mortality(species, mortality, time, data=None, **kwargs)
Mortality is added to the domain with species and Mortality objects in tandem.
Multiple mortality datasets may added to a single species,
as they are stacked in the domain for each species (or sex/age group).
| Parameters: |
- species (Species) – Species instance
- mortality (Morality) – Mortality instance.
- data – Mortality data. This may be a scalar, raster, or vector/matrix (broadcastable to the domain)
- time – The time slice to insert mortality
|
|---|
| Keyword Arguments: |
|---|
| |
- distribute (bool) –
Divide the sum of the input data evenly among all domain nodes (grid cells) (default: True)
- overwrite (str) –
Overwrite method for replacing existing data. Use one of ['replace', 'add'] (Default ‘replace’)
|
-
add_carrying_capacity(species, carrying_capacity, time, data=None, **kwargs)
Carrying capacity is added to the domain with species and CarryingCapacity objects in tandem.
Multiple carrying capacity datasets may added to a single species, as they are stacked in the domain for each species (or sex/age group).
| Parameters: |
- species (Species) – Species instance
- carrying_capacity (CarryingCapacity) – Carrying capacity instance.
- time – The time slice to insert the carrying capacity
- data – Carrying Capacity data. This may be a scalar, raster, or vector/matrix (broadcastable to the domain)
|
|---|
| Keyword Arguments: |
|---|
| |
- is_density (bool) –
The input data are a density, and not an absolute population (Default: False)
- distribute (bool) –
Divide the sum of the input data evenly among all domain nodes (grid cells) (default: True)
- overwrite (str) –
Overwrite method for replacing existing data. Use one of ['replace', 'add'] (Default ‘replace’)
|
-
add_fecundity(species, fecundity, time, data=None, **kwargs)
Fecundity is added to the domain with species and Fecundity objects in tandem.
Multiple fecundity datasets may added to a single species, as they are stacked in the domain for each
species (or sex/age group).
| Parameters: |
- species (Species) – Species instance
- fecundity (Fecundity) – Fecundity instance.
- data – Fecundity data. This may be a scalar, raster, or vector/matrix (broadcastable to the domain)
- time – The time slice to insert fecundity
|
|---|
| Keyword Arguments: |
|---|
| |
- distribute (bool) –
Divide the sum of the input data evenly among all domain nodes (grid cells) (default: True)
- overwrite (str) –
Overwrite method for replacing existing data. Use one of ['replace', 'add'] (Default ‘replace’)
|
-
add_mask(species, time, data=None, **kwargs)
A mask is a general-use dataset associated with a species. It is currently only used for masked density-based
dispersal. Only one mask may exist for a species - sex - age group.
| Parameters: |
- species (Species) – Species instance
- data – Mask data. This may be a scalar, raster, or vector/matrix (broadcastable to the domain)
- time – The time slice to insert fecundity
|
|---|
| Keyword Arguments: |
|---|
| |
- distribute (bool) –
Divide the sum of the input data evenly among all domain nodes (grid cells) (default: True)
- overwrite (str) –
Overwrite method for replacing existing data. Use one of ['replace', 'add'] (Default ‘replace’)
|
-
age_from_group(species_key, sex, gp)
Collect all ages from a group
| Parameters: |
- species_key (str) – Species.name_key
- sex – sex (‘male’ or ‘female’)
- gp – group name
|
|---|
| Return list: | All ages
|
|---|
-
all_carrying_capacity(species_key, time, sex=None, group_key=None, snap_to_time=True)
Collect all carrying capacity for all children in the given query
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- snap_to_time (bool) – If the dataset queried does not exist, it can be snapped backwards in time to the nearest available dataset
|
|---|
| Return list: | All Carrying Capacity instances - h5py.Dataset key pairs
|
|---|
-
all_population(species_key, time, sex=None, group_key=None)
Collect the population keys of a species at a given time. Datasets from all children keys are returned.
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- age (int) – Absolute age
|
|---|
| Returns: | list of :class:’h5py.Dataset` keys
|
|---|
-
carrying_capacity_instances
Collect all k instances in the model domain
| Return list: | CarryingCapacity instances |
|---|
-
discrete_ages(species_key, sex)
Collect all discrete ages for a species in the model domain
| Parameters: |
- species_key (str) – Species.name_key
- sex – sex (‘male’ or ‘female’)
|
|---|
| Return list: | Ordered sequence of ages
|
|---|
-
fecundity_instances
Collect all fecundity instances in the model domain
| Return list: | Fecundity instances |
|---|
-
get_carrying_capacity(species_key, time, sex=None, group_key=None, snap_to_time=True, inherit=False)
Collect the carrying capacity instance - key pairs
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- snap_to_time – If the dataset queried does not exist, it can be snapped backwards in time to the nearest available dataset
- inherit (bool) – Collect data from parent species if they do not exist for the input. Used primarily for distributing by a covariate,
and should not be used during simulations (the values may change during pre-solving inheritance)
|
|---|
| Returns: | list of instance - h5py.Dataset keys
|
|---|
-
get_fecundity(species_key, time, sex, group_key, snap_to_time=True, inherit=True)
Collect the fecundity instance - HDF5 Dataset pairs
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- snap_to_time – If the dataset queried does not exist, it can be snapped backwards in time to the nearest available dataset
- avoid_inheritance – Do not inherit a dataset from the sex or species
|
|---|
| Returns: | list of instance - h5py.dataset key pairs
|
|---|
-
get_mask(species_key, time, sex, group_key, function='masked dispersal', snap_to_time=True, inherit=True)
Collect the key associated with the mask query
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- function (str) – The purposed of the mask being retrieved
- snap_to_time – If the dataset queried does not exist, it can be snapped backwards in time to the
nearest available dataset
- inherit – Do not inherit a dataset from the sex or species
|
|---|
| Returns: | Dataset key
|
|---|
-
get_mortality(species_key, time, sex, group_key, snap_to_time=True, inherit=True)
Collect the mortality instance - dataset pairs
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- snap_to_time – If the dataset queried does not exist, it can be snapped backwards in time to the nearest available dataset
- avoid_inheritance – Do not inherit a dataset from the sex or species
|
|---|
| Returns: | list of instance - h5py.dataset key pairs
|
|---|
-
get_population(species_key, time, sex=None, group_key=None, age=None, inherit=False)
Collect the population key of a species/sex/group at a given time if it exists
| Parameters: |
- species_key (str) – Species.name_key
- sex (str) – sex (‘male’, or ‘female’)
- group_key (str) – AgeGroup.group_key
- time (int) – Time slice
- age (int) – Absolute age
- inherit (bool) – Collect data from parent species if they do not exist for the input. Used primarily for distributing by a covariate,
and should not be used during simulations (the values may change during pre-solving inheritance)
|
|---|
| Returns: | Dataset key or None if non-existent
|
|---|
-
get_species_instance(species_key, sex, gp)
Collect a species instance
| Parameters: |
- species_key (str) – Species.name_key
- sex – sex (‘male’ or ‘female’)
- gp – group name
|
|---|
| Return Species: | instance
|
|---|
-
group_from_age(species, sex, age)
Collect the group of a discrete age
| Parameters: |
- species (str) – Species.name_key
- sex – sex (‘male’ or ‘female’)
- age (int) – Age within a group age range
|
|---|
| Return str: | group name
|
|---|
-
group_names(species_key)
Collect all group names within a specific species
| Parameters: | species_key (str) – Species.name_key |
|---|
| Return list: | Strings of group names |
|---|
-
mortality_instances
Collect all mortality instances in the model domain
| Return list: | Mortality instances |
|---|
-
species_instances
Collect all species instances added to the model domain
| Return list: | Species instances |
|---|
-
species_names
Property of all species names in the Domain
| Return list: | Sorted strings of all species names |
|---|
-
youngest_group(species, sex)
Collect the group with the youngest age in the domain
| Parameters: |
- species_key (str) – Species.name_key
- sex – sex (‘male’ or ‘female’)
|
|---|
| Return str: | group name
|
|---|