Class DispersalCoordinator¶
- Defined in File DispersalCoordinator.h
Class Documentation¶
-
class
DispersalCoordinator
¶ Class for generating dispersal distances and provide routines for reading dispersal distance maps as a unwound map-of-maps. This class also handles reading density maps for rejection sampling.
It requires linking to a density map, random number generator and a generation counter from the Tree class.
Note that no element of this object is recorded during a paused simulation, as all objects pointed to are stored elsewhere and behaviours are recalculated upon simulation resume.
Public Functions
-
DispersalCoordinator
()¶
-
~DispersalCoordinator
()¶
Sets the random number pointer to an NRrand instance.
- Parameters
NR_ptr
: the random number object to set to
-
bool
isFullDispersalMap
() const¶ Checks if using a full dispersal map.
“Full” dispersal maps are those which are not “none”, “null” and correspond to an file path.
- Return
- true if using a full dispersal map
Sets the pointer to the Landscape object.
- Parameters
landscape_ptr
: pointer to a Landscape objectrepr_map_ptr
: pointer to the reproduction probability map
-
void
setGenerationPtr
(double *generation_ptr)¶ Sets the generation pointer to the provided double.
- Parameters
generation_ptr
: pointer to the generation double
-
void
setDispersal
(const string &dispersal_method, const string &dispersal_file, const unsigned long &dispersal_x, const unsigned long &dispersal_y, const double &m_probin, const double &cutoffin, const double &sigmain, const double &tauin, const bool &restrict_self)¶ Sets the dispersal method and parameters.
- Parameters
dispersal_method
: string containing the dispersal type. Can be one of [normal, fat-tail, norm-uniform]dispersal_file
: string containing the dispersal file, or “none” if using dispersal kerneldispersal_x
: the x dimensions of the dispersal filedispersal_y
: the y dimensions of the dispersal filem_probin
: the probability of drawing from the uniform distribution. Only relevant for uniform dispersalscutoffin
: the maximum value to be drawn from the uniform dispersal. Only relevant for uniform dispersalssigmain
: the fatness of the fat-tailed dispersal kerneltauin
: the width of the fat-tailed dispersal kernelrestrict_self
: if true, denies possibility that dispersal comes from the same cell as the parent
Sets the dispersal parameters from the SimParameters object.
- Parameters
simParameters
: pointer to the simulation parameters to set
-
void
importDispersal
(const unsigned long &dispersal_dim, const string &dispersal_file)¶ Imports the dispersal map and fixes the values based on the density and reproduction probabilities.
- Parameters
dispersal_dim
: pointer x and y dimension of the dispersal mapdispersal_file
: name of the dispersal file
-
void
setRawDispersalMap
()¶ Saves the raw dispersal data to another memory object to save reading from disk multiple times later on. This is slightly more RAM intensive which may cause issues for certain simulations.
-
void
addDensity
()¶ Adds the density values to the dispersal map.
- Parameters
generation
: the current generation counter
-
void
addReproduction
()¶ Adds the reproduction rates to the dispersal map.
-
void
fixDispersal
()¶ Fixes the dispersal map by generating cumulative probability distributions across each row.
-
void
fixDispersalRow
(unsigned long row)¶ Sums probabilities across the given row and divides by the total probability, so that the cumulative probabilities sum to one.
- Parameters
row
: the row index to check over
-
bool
checkDispersalRow
(unsigned long row)¶ Checks if the provided row index requires re-scaling to a cumulative probability in the dispersal map.
- Return
- true if re-scaling of the row is required
- Parameters
row
: the row index to check
-
void
verifyDispersalMapDensity
()¶ Ensures that the dispersal map makes sense given the density.
-
void
verifyDispersalMapSetup
()¶ Checks that the dispersal map makes sense with dispersal to and from only cells which have a non-zero density.
-
void
updateDispersalMap
()¶ Updates the dispersal map, if there is one, to reflect changes in landscape density.
-
void
disperseNullDispersalMap
(Step &this_step)¶ Picks a random cell from the whole map and stores the value in the step object.
- Parameters
this_step
: the step object to store end points in
-
void
disperseDispersalMap
(Step &this_step)¶ Picks a random dispersal distance from the dispersal map.
- Parameters
this_step
: the step object to store end points in
-
void
calculateCellCoordinates
(Step &this_step, const unsigned long &col_ref)¶ Calculates the new coordinates for a column reference. This includes converting between the fine map and sample map. New coordinates are saved in this_step.
- Parameters
this_step
: the step to save new coordinates in.col_ref
: the column reference for
-
unsigned long
calculateCellReference
(Step &this_step) const¶ Calculates the cell reference for a particular coordinate.
The formula for this calculation is x + (y * xdim) where xdim is the x dimension of the fine map, and x and y are the coordinates for the fine map
- Return
- the cell reference from the dispersal_prob_map which corresponds to the required cell
- Parameters
this_step
: the step object containing the x, y location, and x,y wrapping
-
unsigned long
calculateCellIndex
(const Cell &cell) const¶ Calculates the cell index in the dispersal map from the given cell.
- Return
- the cell index
- Parameters
cell
: the cell to calculate the index for
-
void
disperseDensityMap
(Step &this_step)¶ Calls the dispersal kernel from the supplied dispersal distribution.
- Parameters
this_step
: the step object to store end points in
-
void
disperseNearestHabitat
(Step &this_step)¶ Disperses to the nearest habitat cell from a given location.
- Parameters
this_step
: teh step object to store end points in
-
void
setEndPointFptr
(const bool &restrict_self)¶ Sets the end point function pointer correctly, based on whether it is restricted or not.
- Parameters
restrict_self
: if true, denies possibility that dispersal comes from the same cell as the parent
-
bool
checkEndPoint
(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶ Check the end point for the given coordinates and density.
- Return
- true if the end point passes the density and restricted checks
- Parameters
density
: the density at the end point - avoids an extra call to Map::getVal()oldx
: the old x positionoldy
: the old y positionoldxwrap
: the old x wrapoldywrap
: the old y wrapstartx
: the starting x positionstarty
: the starting y positionstartxwrap
: the starting x wrapstartywrap
: the ending y wrap
-
bool
checkEndPointDensity
(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶ Check the end point for the given coordinates and density.
- Return
- true if the end point passes the density and restricted checks
- Parameters
density
: the density at the end point - avoids an extra call to Map::getVal()oldx
: the old x positionoldy
: the old y positionoldxwrap
: the old x wrapoldywrap
: the old y wrapstartx
: the starting x positionstarty
: the starting y positionstartxwrap
: the starting x wrapstartywrap
: the ending y wrap
-
bool
checkEndPointRestricted
(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶ Check the end point for the given coordinates and density.
- Return
- true if the end point passes the density and restricted checks
- Parameters
density
: the density at the end point - avoids an extra call to Map::getVal()oldx
: the old x positionoldy
: the old y positionoldxwrap
: the old x wrapoldywrap
: the old y wrapstartx
: the starting x positionstarty
: the starting y positionstartxwrap
: the starting x wrapstartywrap
: the ending y wrap
-
bool
checkEndPointDensityReproduction
(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶ Check the end point for the given coordinates and density.
- Return
- true if the end point passes the density and restricted checks
- Parameters
density
: the density at the end point - avoids an extra call to Map::getVal()oldx
: the old x positionoldy
: the old y positionoldxwrap
: the old x wrapoldywrap
: the old y wrapstartx
: the starting x positionstarty
: the starting y positionstartxwrap
: the starting x wrapstartywrap
: the ending y wrap
-
bool
checkEndPointDensityRestrictedReproduction
(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶ Check the end point for the given coordinates and density.
- Return
- true if the end point passes the density and restricted checks
- Parameters
density
: the density at the end point - avoids an extra call to Map::getVal()oldx
: the old x positionoldy
: the old y positionoldxwrap
: the old x wrapoldywrap
: the old y wrapstartx
: the starting x positionstarty
: the starting y positionstartxwrap
: the starting x wrapstartywrap
: the ending y wrap
-
void
disperse
(Step &this_step)¶ Performs the dispersal routine using the Step object to read starting positions and record the end positions.
- Parameters
this_step
: the Step object for reading starting position and storing output distances and angles
-
double
getSelfDispersalValue
(const Cell &cell) const¶ Gets the probability of dispersing from the given cell to itself.
- Return
- the probability of self-dispersal
- Parameters
cell
: the cell to check the probability of self-dispersal from
-
double
sumDispersalValues
(const Cell &cell) const¶ Sums the dispersal values from a given cell to all other cells in the landscape.
- Return
- the sum of all dispersal values
- Parameters
cell
:
-
void
reimportRawDispersalMap
()¶ If required, reimports the raw dispersal map from disk.
-
void
removeSelfDispersal
()¶ Removes all self-dispersal events and recalculates the cumulative dispersal map.
Protected Types
-
typedef bool (
DispersalCoordinator
::*end_fptr
)(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)¶
-