r.pi.fnn

Determines patches of given value and performs a nearest-neighbor analysis.

r.pi.fnn [-a] input=name costmap=string output=name keyval=integer method=string [,string,...] number=num[-num] [,num[-num],...] statmethod=string [dmout=string] [adj_matrix=string] [title="phrase"] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.pi.fnn input=name costmap=string output=name keyval=integer method=string number=num[-num] statmethod=string

grass.script.run_command("r.pi.fnn", input, costmap, output, keyval, method, number, statmethod, dmout=None, adj_matrix=None, title=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.pi.fnn", input="name", costmap="string", output="name", keyval=integer, method="string", number="num[-num]", statmethod="string")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of input raster map
costmap=string [required]
    Name of existing raster file with path-cost information
output=name [required]
    Name for output raster map
keyval=integer [required]
    Key value
method=string [,string,...] [required]
    Operation to perform on fragments
    Allowed values: distance, path_distance, area, perimeter, shapeindex
number=num[-num] [,num[-num],...] [required]
    Number of nearest neighbors to analyse
statmethod=string [required]
    Statistical method to perform on the values
    Allowed values: average, variance, standard deviation, value, sum
dmout=string
    Output name for distance matrix and id-map (performed if not empty)
adj_matrix=string
    Output name for adjacency matrix (performed if not empty)
title="phrase"
    Title for resultant raster map
-a
    Set for 8 cell-neighbors. 4 cell-neighbors are default
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of input raster map
    Used as: input, raster, name
costmap : str, required
    Name of existing raster file with path-cost information
    Used as: input, raster
output : str, required
    Name for output raster map
    Used as: output, raster, name
keyval : int, required
    Key value
method : str | list[str], required
    Operation to perform on fragments
    Allowed values: distance, path_distance, area, perimeter, shapeindex
number : str | list[str], required
    Number of nearest neighbors to analyse
    Used as: num[-num]
statmethod : str, required
    Statistical method to perform on the values
    Allowed values: average, variance, standard deviation, value, sum
dmout : str, optional
    Output name for distance matrix and id-map (performed if not empty)
    Used as: output, raster
adj_matrix : str, optional
    Output name for adjacency matrix (performed if not empty)
    Used as: output, raster
title : str, optional
    Title for resultant raster map
    Used as: "phrase"
flags : str, optional
    Allowed values: a
    a
        Set for 8 cell-neighbors. 4 cell-neighbors are default
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

Determine the functional nearest-neighbor distance analysis. r.pi.fnn is a patch based ecological/functional nearest neighbour analysis module. It computes distance based on a friction map. This module is related to r.pi.enn but more adequate if the ecological connectivity should be analysed.

NOTES

The calculation of the ecolgogical nearest neighbour is based on a raster with start patches. The actual map can be categorical or continuous but the value defined in keyval will be the basis for the patches to calculate the methods defined below. These patches will also be in the output map. The calculation of the ecolgogical nearest neighbour is based on a costmap (* and 1-infinite) - this map can be binary or continous - high values are considered to have high cost issues and the shortest path is the one with the lowest amount of costs. "null" values can not be traversed, hence these values have to be bypassed. "0" values are not accepted and will result in "0" distance.

e.g. if a binary map(1 and 2) is used, the the path with the lowest amount of "1" is chosen The number is the amount of nearest neighbours to be taken and the calculated distances are processed as assigned in statmethod Operations which r.pi.fnn can perform are:

Distance
The Distance to Nearest computes the nearest edge-to-edge distance between patches. Counting from the focus patch.
path Distance
The Distance to Nearest computes the nearest edge-to-edge distance between patches. Unlike Distance the distance is computed based on subsequent NN not from the focus patch onwards. The 1th NN is the first patch with the minimal edge-to-edge distance from the focus patch, while 2th NN is the patch with the minimal edge-to-edge distance from the 1th NN patch and so on.
Area
The Area computes the size of the nearest edge-to-edge distance patch. It is based on Distance not on path Distance.
Perimeter
The Perimeter computes the Perimeter of the nearest edge-to-edge distance patch. It is based on Distance not on path Distance.
SHAPE
The SHAPE computes the SHAPE Index of the nearest edge-to-edge distance patch. It is based on Distance not on path Distance.

The statsmethod operators determine calculation is done on the distance. Average, Variance,Stddev and value can be used.

Average
The Average computes the average value defined in Operations to perform .
Variance
The Variance computes the variance defined in Operations to perform .
Stand. Dev.
The Stand. Dev. computes the stddev value defined in Operations to perform .
Value
The patch Distance computes the nearest edge-to-edge distance between two patches. The output of value is the actual value. E.g. NN==5 of area gives the size of the 5th NN while Average gives the average of the area of 1-5th NN.

The input options are either one NN: 1 or several NN separated by ,: 1,2,5,8 or a range of NN: 1-6.

Merging these options is possible as well: 1-5,8,9,13,15-19,22 etc.

EXAMPLE

An example for the North Carolina sample dataset: Computing the functional or ecological distance to the first to nth nearest neighrbours using a cost matrix:

r.mapcalc "cost_raster = if(landclass96==5,1,if(landclass96 == 1, 10, if (landclass96==3,2, if(landclass96==4,1,if(landclass96==6,100)))))"
r.pi.fnn input=landclass96 keyval=5 costmap=cost_raster output=fnn1 method=distance number=10 statmethod=average

AUTHORS

Programming: Elshad Shirinov
Scientific concept: Dr. Martin Wegmann
Department of Remote Sensing
Remote Sensing and Biodiversity Unit
University of Wuerzburg, Germany

Port to GRASS GIS 7: Markus Metz

SOURCE CODE

Available at: r.pi.fnn source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3