Class DispersalCoordinator

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()
void setRandomNumber(shared_ptr<RNGController> NR_ptr)

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

void setMaps(const shared_ptr<Landscape> &landscape_ptr, shared_ptr<ActivityMap> repr_map_ptr)

Sets the pointer to the Landscape object.

Parameters
  • landscape_ptr: pointer to a Landscape object
  • repr_map_ptr: pointer to the reproduction probability map

void setMaps(const shared_ptr<Landscape> &landscape_ptr)

Sets the pointer to the Landscape object.

Parameters
  • landscape_ptr: pointer to a Landscape object

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 kernel
  • dispersal_x: the x dimensions of the dispersal file
  • dispersal_y: the y dimensions of the dispersal file
  • m_probin: the probability of drawing from the uniform distribution. Only relevant for uniform dispersals
  • cutoffin: the maximum value to be drawn from the uniform dispersal. Only relevant for uniform dispersals
  • sigmain: the fatness of the fat-tailed dispersal kernel
  • tauin: the width of the fat-tailed dispersal kernel
  • restrict_self: if true, denies possibility that dispersal comes from the same cell as the parent

void setDispersal(shared_ptr<SimParameters> simParameters)

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 map
  • dispersal_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 position
  • oldy: the old y position
  • oldxwrap: the old x wrap
  • oldywrap: the old y wrap
  • startx: the starting x position
  • starty: the starting y position
  • startxwrap: the starting x wrap
  • startywrap: 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 position
  • oldy: the old y position
  • oldxwrap: the old x wrap
  • oldywrap: the old y wrap
  • startx: the starting x position
  • starty: the starting y position
  • startxwrap: the starting x wrap
  • startywrap: 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 position
  • oldy: the old y position
  • oldxwrap: the old x wrap
  • oldywrap: the old y wrap
  • startx: the starting x position
  • starty: the starting y position
  • startxwrap: the starting x wrap
  • startywrap: 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 position
  • oldy: the old y position
  • oldxwrap: the old x wrap
  • oldywrap: the old y wrap
  • startx: the starting x position
  • starty: the starting y position
  • startxwrap: the starting x wrap
  • startywrap: 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 position
  • oldy: the old y position
  • oldxwrap: the old x wrap
  • oldywrap: the old y wrap
  • startx: the starting x position
  • starty: the starting y position
  • startxwrap: the starting x wrap
  • startywrap: 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 void (DispersalCoordinator::*dispersal_fptr)(Step &this_step)
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)

Protected Attributes

Map<double> dispersal_prob_map
Map<double> raw_dispersal_prob_map
shared_ptr<RNGController> NR
shared_ptr<Landscape> landscape
shared_ptr<ActivityMap> reproduction_map
double *generation
dispersal_fptr doDispersal
end_fptr checkEndPointFptr
unsigned long xdim
unsigned long ydim
bool full_dispersal_map