## Class Documentation¶

class DataMask

Contains the DataMask object, a Matrix of booleans describing the spatial sampling pattern.

Subclassed by necsim::Samplematrix

Public Functions

DataMask()

~DataMask()
bool isNull()

Returns if the simulation is using the a null samplemask, and therefore does not need to store the full sample grid in memory.

Return
true if using a null samplemask

void setup(shared_ptr<SimParameters> sim_parameters)

Sets the parameters for the datamask, including the dimensions of the map, the offsets from the grid and the dimensions of the grid itself for recalculating coordinates.

Parameters
• sim_parameters: Simulation parameter to set the data mask from

bool checkCanUseDefault(shared_ptr<SimParameters> sim_parameters)
void importBooleanMask(unsigned long xdim, unsigned long ydim, unsigned long mask_xdim, unsigned long mask_ydim, unsigned long xoffset, unsigned long yoffset, string inputfile_in)

Imports the sample mask as a boolean mask and sets the relevant sample mask dimensions. Should only be called if the import is actually required (i.e. the map is not null or none).

Parameters
• xdim: the x dimension of the grid area
• ydim: the y dimension of the grid area
• mask_xdim: the x dimension of the sample map file
• mask_ydim: the y dimension of the sample map file
• xoffset: the x offset of the grid area from the sample map file
• yoffset: the y offset of the grid area from the sample map file
• inputfile_in: the path to the sample map file

void doImport()

Imports the boolean map object.

void completeBoolImport()

Sets the map dimensions and the getVal function pointer.

void setupNull(shared_ptr<SimParameters> mapvarin)

Sets up the null sampling map.

void importSampleMask(shared_ptr<SimParameters> mapvarin)

Imports the specified file for the sampling percentage within each cell.

The map should consist of floating points representing the relative sampling rates in each cell. Note that the actual sampling proportion is equal to the cell value multiplied by global deme sampling proportion.

Parameters
• mapvarin: the SimParameters object containing the samplemask file location and dimensions

bool getVal(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Calculates the matrix value at the provided x, y location. If everywhere is sampled, simply returns true, as no sample_mask will be stored in memory. This is to save RAM where possible.

Return
the sample_mask value at x,y (or true if the file was “null”)
Parameters
• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps
• ywrap: the number of y wraps

double getNullProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Separate return function for always returning 1.0 as density value.

Return
the sample_mask_exact value at (x, y)
Parameters
• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getBoolProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note
this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.
Return
the sample_mask_exact value at (x, y)
Parameters
• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getSampleProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note
this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.
Return
the sample_mask_exact value at (x, y)
Parameters
• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getExactValue(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, as returned by the pointer function.

Return
the sample_mask_exact value at (x, y)
Parameters
• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

void convertBoolean(shared_ptr<Landscape> map1, const double &deme_sampling, const double &generation)

Converts the spatial map into the boolean grid required for continued simulation. This is done so that the faster boolean accesses are possible.

Parameters
• map1: the map object to obtain density values from
• deme_sampling: the proportion of individuals to sample
• generation: the generation individuals are added at

void clearSpatialMask()

Removes the spatial mask from memory. This should be performed if no more map expansions are required.

void recalculateCoordinates(long &x, long &y, long &x_wrap, long &y_wrap)

Converts the coordinates back into the grid format. Changes the values in the provided variables to be correct.

Parameters
• x: the x value to convert
• y: the y value to convert
• x_wrap: the xwrap variable to place the value into
• y_wrap: the ywrap variable to place the value into

Public Members

Map<bool> sample_mask

A binary grid telling whether or not the cell should be sampled.

Map<double> sample_mask_exact

Exact grid for determining sampling proportion.

Protected Types

typedef double (DataMask::*fptr)(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Protected Attributes

string inputfile
bool isNullSample
bool isGridOffset
unsigned long x_offset
unsigned long y_offset
unsigned long x_dim
unsigned long y_dim
unsigned long mask_x_dim
unsigned long mask_y_dim
fptr getProportionfptr