Class Landscape¶
- Defined in File Landscape.h
Class Documentation¶
-
class
Landscape
¶ Contains all maps and provides the functions for accessing a grid cell in the correct temporal and spacial location.
The function runDispersal() also provides the move routine, provided two alternative methods for moving individuals. Contains routines for easy setting up and switching between the different coordinate systems required. Set the map parameters with setDims(), import the map files with calcFineMap(), calcCoarseMap() etc, then set up the landscape type using setLandscape() and sethistorical(). Usage is then by runDispersal() for running a dispersal kernel on the landscape, and then getVal() to obtain the density at the desired coordinates. All coordinates should be given in reference to the simulation grid, and offsets for the fine and coarse map are calculated automatically.
Public Functions
-
Landscape
()¶ The default constructor.
-
unsigned long
getHabitatMax
()¶ Gets the maximum habitat value from any map.
- Return
- the maximum habitat value
-
bool
hasHistorical
()¶ Returns if the simulation is using historical maps.
- Return
- true if using historical maps
-
Map<uint32_t> &
getFineMap
()¶ Gets the fine map object.
- Return
- reference to the fine map
-
Map<uint32_t> &
getCoarseMap
()¶ Gets the coarse map object.
- Return
- reference to the coarse map
-
const Map<uint32_t> &
getFineMap
() const¶ Gets the fine map object.
- Return
- reference to the fine map
-
const Map<uint32_t> &
getCoarseMap
() const¶ Gets the coarse map object.
- Return
- reference to the coarse map
Sets the dimensions of the grid, the area where the species are initially sampled from. This function must be run before any of the calc map functions to allow for the correct deme allocation.
- Parameters
mapvarsin
: the SimParameters object containing the map variables to import
-
bool
checkMapExists
()¶ Checks that the map files exist (or are none/null).
- Return
- true if all the paths exist in configs
-
void
calcFineMap
()¶ Imports the fine map object from file and calculates the correct values at each point. Without a map to input, the fine map will simply be a matrix of 1s.
-
void
calcHistoricalFineMap
()¶ Imports the historical fine map object from file and calculates the correct values at each point. Without a map to input, the historical fine map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.
-
void
calcCoarseMap
()¶ Imports the coarse map object from file and calculates the correct values at each point. Without a map to input, the coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.
-
void
calcHistoricalCoarseMap
()¶ Imports the historical coarse map object from file and calculates the correct values at each point. Without a map to input, the historical coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.
-
void
setTimeVars
(double gen_since_historical_in, double habitat_change_rate_in)¶ Sets the time variables.
- Parameters
gen_since_historical_in
: the time (in generations) since a historical habitat state was achieved.habitat_change_rate_in
: the rate of transform of the habitat up until the historical time. A value of 0.2 would mean 20% of the change occurs linearlly up until the historical time and the remaining 80% occurs in a jump to the historical state.
-
void
calcOffset
()¶ Calculates the offset and extremeties of the fine map.
Note that setting dispersal_relative_cost to a value other than 1 can massively increase simulation time.
-
bool
checkAllDimensionsZero
()¶ Checks that all dimensions for all maps are zero.
If this is true, then it means we can calculate actual offsets and dimensions from the maps, otherwise the values from the parameters will be used.
- Return
- true if all map offsets are zero
-
void
calculateOffsetsFromMaps
()¶ Calculates the offsets from the map files directly.
Assumes that all required maps have been imported.
-
void
calculateOffsetsFromParameters
()¶ Uses the inputted parameters to set the offsets for the map files.
-
void
validateMaps
()¶ Checks that the map file sizes are correct and that each value on the fragmented maps is less than the historical maps. This should be disabled in simulations where habitat sizes are expected to shrink as well as grow.
-
bool
updateMap
(double generation)¶ Checks if an update needs to be performed to the map configuration, and if it does, performs the update.
- Return
- true if the map has been updated
- Parameters
generation
: the current generation timer
-
bool
requiresUpdate
()¶ Checks if the map will require another update.
- Return
- true if another update will be performed
-
void
doUpdate
()¶ Updates the historical map configuration.
-
void
resetHistorical
()¶ Resets the historical variables to recalculate historical maps.
Required for rcoalescence compatability.
-
bool
isHistorical
()¶ Gets the historical boolean.
- Return
- the historical map state.
-
void
setHistorical
(const bool &historical_in)¶ Sets the historical state of the system.
- Parameters
historical_in
: the historical state.
-
double
getHistorical
()¶ Get the historical map time.
- Return
- double the historical map time
-
string
getLandscapeType
()¶
-
void
checkHistorical
(double generation)¶ Checks if the historical state has been reached.
If there are no historical maps, this function will do nothing.
- Parameters
generation
: the time to check at.
-
void
setLandscape
(const string &is_infinite)¶ Sets the landscape functions to either infinite or finite.
- Parameters
is_infinite
: a string of either closed, infinite, tiled_fine or tiled_coarse, corresponding to the relevant landscape type.
-
unsigned long
getVal
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version involves a call to the function pointer, *getValFunc, so that the correct call to either getValFinite() or getValInfinite is made.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValCoarse
(const double &xval, const double &yval, const double ¤t_generation)¶ Gets the value from the coarse maps, including linear interpolating between the historical and present maps.
- Return
- the value of the map at the given coordinates and time
- Parameters
xval
: the x coordinateyval
: the y coordinatecurrent_generation
: the current generation timer
-
unsigned long
getValFine
(const double &xval, const double &yval, const double ¤t_generation)¶ Gets the value from the fine maps, including linear interpolating between the historical and present maps.
- Return
- the value of the map at the given coordinates and time
- Parameters
xval
: the x coordinateyval
: the y coordinatecurrent_generation
: the current generation timer
-
unsigned long
getValFinite
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes finite landscape.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValInfinite
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValCoarseTiled
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled coarse maps.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValFineTiled
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled fine maps.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValCoarseClamped
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped coarse maps.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
getValFineClamped
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double ¤t_generation)¶ Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped fine maps.
- Return
- the value on the correct map at the correct space.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension..ywrap
: the number of wraps in the y dimension..current_generation
: the current generation time.
-
unsigned long
convertSampleXToFineX
(const unsigned long &x, const long &xwrap) const¶ Gets the x position on the fine map, given an x and x wrapping.
Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.
- Return
- the x location on the fine map
- Parameters
x
: the x coordinate on the sample maskxwrap
: the x wrapping of the sample mask.
-
unsigned long
convertSampleYToFineY
(const unsigned long &y, const long &ywrap) const¶ Gets the y position on the fine map, given a y and y wrapping.
Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.
- Return
- the y location on the fine map
- Parameters
y
: the y coordinate on the sample maskywrap
: the y wrapping of the sample mask.
-
void
convertFineToSample
(long &x, long &xwrap, long &y, long &ywrap)¶ Converts the fine map coordinates to the sample grid coordinates. Main conversion is in a call to convertCoordinates, but also makes sure the returned types are long integers.
- Parameters
x
: the x coordinate to modifyxwrap
: the x wrapping to modifyy
: the y coordinate to modifyywrap
: the y wrapping to modify
-
unsigned long
getInitialCount
(double dSample, DataMask &samplemask)¶ Counts the number of spaces available in the initial species space. Requires the samplemask to check the sampling area.
- Return
- the total number of individuals predicted to initially exist on the map.
- Parameters
dSample
: the sample proportion (from 0 to 1).samplemask
: the DataMask object to sample from.
-
shared_ptr<SimParameters>
getSimParameters
()¶ Gets the mapvars object pointer for referencing simulation parameters.
- Return
-
bool
checkMap
(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &generation)¶ Checks whether the point is habitat or non-habitat.
- Return
- a boolean of whether the map is habitat or non-habitat.
- Parameters
x
: the x position on the grid.y
: the y position on the grid.xwrap
: the number of wraps in the x dimension.ywrap
: the number of wraps in the y dimension.generation
: the current generation time.
-
bool
isOnFine
(const double &x, const double &y, const long &xwrap, const long &ywrap)¶ Checks whether the point comes from the fine grid.
- Return
- a boolean of whether the location is on the fine map
- Parameters
x
: the x positiony
: the y positionxwrap
: the number of wraps in the x dimensionywrap
: the number of wraps in the y dimension
-
bool
isOnCoarse
(const double &x, const double &y, const long &xwrap, const long &ywrap)¶ Checks whether the point comes from the coarse grid.
- Return
- a boolean of whether the location is on the fine map
- Parameters
x
: the x positiony
: the y positionxwrap
: the number of wraps in the x dimensionywrap
: the number of wraps in the y dimension
-
bool
isOnMap
(const double &x, const double &y, const long &xwrap, const long &ywrap)¶ Checks that the point supplied is within map limits. If the map is inifite, returns true.
- Return
- a boolean of whether the location is on the fine map
- Return
- true if the point is within the map limits
- Parameters
x
: the x positiony
: the y positionxwrap
: the number of wraps in the x dimensionywrap
: the number of wraps in the y dimension
-
void
fixGridCoordinates
(double &x, double &y, long &xwrap, long &ywrap)¶ Fixes the coordinates to be correctly within the original grid, altering the xwrap and ywrap consequently.
- Parameters
x
: the x position.y
: the y position.xwrap
: the number of wraps in the x dimension.ywrap
: the number of wraps in the y dimension.
-
unsigned long
runDispersal
(const double &dist, const double &angle, long &startx, long &starty, long &startxwrap, long &startywrap, bool &disp_comp, const double &generation)¶ The function that actually performs the dispersal. It is included here for easier programming and efficiency as the function doesn’t need to perform all the checks until the edge of the fine grid.
- Return
- the density value at the end dispersal point
- Parameters
dist
: the distance travelled (or “distance energy” if dispersal_relative_cost is not 1).angle
: the angle of movement.startx
: the start x position.starty
: the start y position.startxwrap
: the start number of wraps in the x dimension.startywrap
: the start number of wraps in the y dimension.disp_comp
: a boolean of whether the dispersal was complete or not. This value is returned false if dispersal is to habitat, false otherwise.generation
: the time in generations since the start of the simulation.
-
double
distanceToNearestHabitat
(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, const double &generation)¶ Calculates the distance from the start position to the nearest habitat cell.
- Return
- the distance from the start position to the nearest habitat cell
- Parameters
start_x
: the start x coordinatestart_y
: the start y coordinatestart_x_wrap
: the starting x wrappingstart_y_wrap
: the starting y wrappinggeneration
: the generation timer
-
void
findNearestHabitatCell
(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)¶ Gets the nearest habitat cells from a particular point, spiraling outwards.
- Parameters
start_x
: the start x coordinatestart_y
: the start y coordinatestart_x_wrap
: the starting x wrappingstart_y_wrap
: the starting y wrappingend_x
: the end x coordinate value to modifyend_y
: the end y coordinate value to modifygeneration
: the generation timer
-
bool
findAnyHabitatCell
(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)¶ Finds the nearest habitat cell using a much slower method (scanning the entire map for cells.
- Return
- true if a habitat cell is found
- Parameters
start_x
: the start x coordinatestart_y
: the start y coordinatestart_x_wrap
: the starting x wrappingstart_y_wrap
: the starting y wrappingend_x
: the end x coordinate value to modifyend_y
: the end y coordinate value to modifygeneration
: the generation timer
-
string
printVars
()¶ Prints some selected Map variables to the terminal.
- Return
- the string containing the map variables to print
-
void
clearMap
()¶ Wipes the map of all variables. Only really useful for testing purposes.
-
void
recalculateHabitatMax
()¶ Recalculates the habitat map maximum by checking the maximums for each of the relevant map files (fine, coarse and historicals).
Protected Types
-
typedef unsigned long (
Landscape
::*fptr
)(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &dCurrentGen)¶
Protected Attributes
-
Map<uint32_t>
fine_map
¶
-
Map<uint32_t>
historical_fine_map
¶
-
Map<uint32_t>
coarse_map
¶
-
Map<uint32_t>
historical_coarse_map
¶
-
shared_ptr<SimParameters>
mapvars
¶
-
long
fine_x_min
= {}¶
-
long
fine_y_min
= {}¶
-
long
coarse_x_min
= {}¶
-
long
coarse_y_min
= {}¶
-
long
fine_x_max
= {}¶
-
long
fine_y_max
= {}¶
-
long
coarse_x_max
= {}¶
-
long
coarse_y_max
= {}¶
-
long
fine_x_offset
= {}¶
-
long
fine_y_offset
= {}¶
-
long
coarse_x_offset
= {}¶
-
long
coarse_y_offset
= {}¶
-
unsigned long
scale
= {}¶
-
long
x_dim
= {}¶
-
long
y_dim
= {}¶
-
double
deme
= {}¶
-
bool
check_set_dim
¶
-
double
dispersal_relative_cost
= {}¶
-
double
update_time
= {}¶
-
double
habitat_change_rate
= {}¶
-
double
gen_since_historical
= {}¶
-
double
current_map_time
¶
-
bool
is_historical
¶
-
bool
has_historical
¶
-
unsigned long
habitat_max
¶
-
unsigned long
fine_max
¶
-
unsigned long
coarse_max
¶
-
unsigned long
historical_fine_max
¶
-
unsigned long
historical_coarse_max
¶
-
string
landscape_type
¶
-
bool
infinite_boundaries
¶
-
string
NextMap
¶
-
bool
has_coarse
¶
-