# Class LandscapeMetricsCalculator¶

## Class Documentation¶

class LandscapeMetricsCalculator : public necsim::Map<double>

Calculates a variety of landscape metrics from an imported tif file.

Public Functions

LandscapeMetricsCalculator()
virtual ~LandscapeMetricsCalculator()
double calculateMNN()

Calculates the mean distance between nearest neighbours on a Map.

Return
the mean distance between every cell and its nearest neighbour

void checkMinDistance(Cell &home_cell, const long &x, const long &y, double &min_distance)

Checks if the minimum distance between cells is a new minimum.

Parameters
• home_cell: the cell to check the distance from
• x: the x coordinate of the new location
• y: the y coordinate of the new location
• min_distance: the previous minimum distance

double findNearestNeighbourDistance(const long &row, const long &col)

Determines the distance to the nearest neighbour of a cell.

Return
Parameters
• row:
• col:

void createCellList()

Creates a list containing all habitat cells in the landscape. List is stored in all_cells.

double calculateClumpiness()

Calculates the clumpiness metric, which measures the degree to which the focal habitat is aggregated or clumped given its total area.

Return
the clumpiness metric

unsigned long calculateNoAdjacencies()

Calculates the number of adjacencies in the landscape.

Adjacencies are habitat cells that are directly next to each other. Note that this uses the “double=count” method.

Return
the number of adjacent cells in the landscape.

double calculateMinPerimeter()

Calculates the minimum bounding perimeter for square cells on a landscape.

Return
the minimum bounding perimeter for cells on a landscape

void setCPLErrorHandler()
void removeCPLErrorHandler()
void open(const string &filename_in)

Opens the provided filename to the poDataset object.

Parameters
• filename: file to open in read-only mode.

void open()

Overloaded open for using the preset file name.

bool isOpen()

Checks if the connection to the map file has already been opened.

All this does is check if poDataset is a null pointer.

Return
true if poDataset is a null pointer.

void close()

Destroys the connection to the dataset.

void getRasterBand()

Sets the raster band to the first raster.

void getBlockSizes()

Obtains the x and y dimensions from the tif file for reading in blocks.

void getMetaData()

Sets the no data, data type and data type name values from the tif file.

double getUpperLeftX() const

Gets the upper left x (longitude) coordinate.

Return
upper left x of the map

double getUpperLeftY() const

Gets the upper left y (latitude) coordinate.

Return
upper left y of the map

string getFileName() const

Gets the name of the file that has been imported from.

Return
the file name

void import(const string &filename)

Imports the matrix from a csv file.

Exceptions
• runtime_error: if type detection for the filename fails.
Parameters
• filename: the file to import.

bool importTif(const string &filename)

Imports the matrix from a tif file using the gdal library functions.

Note
Opens a connection to the file object, which should be closed.
Parameters
• filename: the path to the file to import.

bool openOffsetMap(Map &offset_map)

Opens the offset map and fetches the metadata.

Return
true if the offset map is opened within this function
Parameters
• offset_map: the offset map to open (should be the larger map).

void closeOffsetMap(Map &offset_map, const bool &opened_here)
void calculateOffset(Map &offset_map, long &offset_x, long &offset_y)

Calculates the offset between the two maps.

The offset_map should be larger and contain this map, otherwise returned values will be negative

Note
Opens a connection to the tif file (if it has not already been opened), which is then closed. If the connection is already open, then it will not be closed and it is assumed logic elsewhere achieves this.
Note
Offsets are returned as rounded integers at the resolution of the smaller map.
Parameters
• offset_map: the offset map to read from
• offset_x: the x offset variable to fill
• offset_y: the y offset variable to fill

unsigned long roundedScale(Map &offset_map)

Calculates the relative scale of this map compared to the offset map.

The offset map should be larger and contain this map.

Note
Only the x resolution is checked, it is assumed the x and y resolutions of both maps is the same (i.e. each cell on the map is a square.
Return
the relative scale of the offset map
Parameters
• offset_map: the offset map object to read from

void internalImport()

Default importer when we rely on the default gdal method of converting between values. Note that importing doubles to ints results in the values being rounded down.

Return
true if a tif file exists and can be imported, false otherwise.

void internalImport()

Overloaded imported for handling conversion of types to boolean. This function should only be once elsewhere, so inlining is fine, allowing this file to remain header only.

void internalImport()

Overloaded functions for importing from tifs and matching between gdal and C types.

void internalImport()
void internalImport()
void internalImport()
void internalImport()
void internalImport()
void internalImport()
void internalImport()
void defaultImport()

Default import routine for any type. Provided as a separate function so implementation can be called from any template class type.

void importFromDoubleAndMakeBool()

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

void importUsingBuffer(GDALDataType dt_buff)

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

Parameters
• dt_buff: the buffer type for the data
Template Parameters
• T2: the template type for data reading.

void printNumberComplete(const uint32_t &j, unsigned int &number_printed)

Print the percentage complete during import.

Parameters
• j: the reference for the counter
• number_printed: the number of previously printed lines

void checkTifImportFailure()

Checks the error code of the CPLErr object and formats the error.

void setSize(unsigned long rows, unsigned long cols)

Sets the matrix size. Similar concept to that for Rows.

Parameters
• rows: the number of rows.
• cols: the number of columns.

unsigned long getCols() const

Getter for the number of columns.

Return
the number of columns.

unsigned long getRows() const

Getter for the number of rows.

Return
the number of rows.

void fill(double val)

Fills the matrix with the given value.

Parameters
• val: the value to fill

unsigned long index(const unsigned long &row, const unsigned long &col) const

Gets the index of a particular row and column in the matrix.

Return
the index of row and column within the matrix
Parameters
• row: the row number to index
• col: the column number to index

double &get(const unsigned long &row, const unsigned long &col)

Gets the value at a particular index.

Return
the value at the specified row and column
Parameters
• row: the row number to get the value at
• col: the column number to get the value at

const double &get(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return
the value at the specified row and column
Parameters
• row: the row number to get the value at
• col: the column number to get the value at

double getCopy(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return
the value at the specified row and column
Parameters
• row: the row number to get the value at
• col: the column number to get the value at

vector<double>::iterator begin()

Returns iterators for range-based for loops.

Return
iterator to the start of the vector

vector<double>::const_iterator begin() const

Returns iterators for range-based for loops.

Return
iterator to the start of the vector

vector<double>::iterator end()

Returns end iterators for range-based for loops.

Return
iterator to the end of the vector

vector<double>::const_iterator end() const

Returns end iterators for range-based for loops.

Return
iterator to the end of the vector

double getMean() const

Gets the arithmetic mean of the Matrix.

Return
the mean value in the matrix

double sum() const
Matrix operator+(const Matrix &m) const

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Return
the matrix object which is the sum of the two matrices.
Parameters
• m: the matrix to add to this matrix.

Matrix operator-(const Matrix &m) const

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Return
the matrix object which is the subtraction of the two matrices.
Parameters
• m: the matrix to subtract from this matrix.

Matrix &operator+=(const Matrix &m)

Overloading the += operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to add to this matrix.

Matrix &operator-=(const Matrix &m)

Overloading the -= operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to subtract from this matrix.

Matrix operator*(const double s) const

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Return
the scaled matrix.
Parameters
• s: the constant to scale the matrix by.

Matrix operator*(Matrix &m) const

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension. Multiplies each value in the matrix with its corresponding value in the other matrix.
Return
the product of each ith,jth value of the matrix.
Parameters
• m: the matrix to multiply with

Matrix &operator*=(const double s)

Overloading the *= operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to add to this matrix.

Matrix &operator*=(const Matrix &m)

Overloading the *= operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to add to this matrix.

Matrix operator/(const double s) const

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Return
the scaled matrix.
Parameters
• s: the constant to scale the matrix by.

Matrix &operator/=(const double s)

Overloading the /= operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to add to this matrix.

Matrix &operator/=(const Matrix &m)

Overloading the /= operator so that the new object is written to the current object.

Note
If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.
Parameters
• m: the Matrix object to add to this matrix.

void setValue(const unsigned long &row, const unsigned long &col, const char *value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters
• row: the row index.
• col: the column index.
• value: the value to set

void setValue(const unsigned long &row, const unsigned long &col, const double &value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters
• row: the row index.
• col: the column index.
• value: the value to set

bool importCsv(const string &filename)

Imports the matrix from a csv file using the fast-csv-parser method.

Return
true if the csv can be imported.
Parameters
• filename: the path to the file to import.Imports the matrix from a csv file using the standard, slower method.
Parameters
• filename: the path to the file to import.

Protected Attributes

shared_ptr<GDALDataset *> po_dataset
shared_ptr<GDALRasterBand *> po_band
unsigned long block_x_size
unsigned long block_y_size
double no_data_value
string file_name
GDALDataType gdal_data_type
CPLErr cpl_error
double upper_left_x
double upper_left_y
double x_res
double y_res
bool cpl_error_set
unsigned long num_cols
unsigned long num_rows
vector<double> matrix