r.pi.corearea
Variable edge effects and core area analysis
r.pi.corearea [-a] input=name costmap=string [propmap=string] output=name keyval=integer buffer=integer distance=float angle=float stats=string propmethod=string [dist_weight=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.pi.corearea input=name costmap=string output=name keyval=0 buffer=0 distance=0.0 angle=0.0 stats=average propmethod=linear
grass.script.run_command("r.pi.corearea", input, costmap, propmap=None, output, keyval, buffer, distance, angle, stats, propmethod, dist_weight=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.pi.corearea", input="name", costmap="string", output="name", keyval=0, buffer=0, distance=0.0, angle=0.0, stats="average", propmethod="linear")
grass.tools.Tools.r_pi_corearea(input, costmap, propmap=None, output, keyval, buffer, distance, angle, stats, propmethod, dist_weight=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_pi_corearea(input="name", costmap="string", output="name", keyval=0, buffer=0, distance=0.0, angle=0.0, stats="average", propmethod="linear")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
input=name [required]
Name of input raster map
costmap=string [required]
Name of the cost map raster file
propmap=string
Name of the propagation cost map raster file
output=name [required]
Name for output raster map
keyval=integer [required]
Key value
buffer=integer [required]
Buffer size
distance=float [required]
Cone of effect radius
angle=float [required]
Cone of effect angle
stats=string [required]
Statistical method to perform on the values
Allowed values: average, median
propmethod=string [required]
Propagation method
Allowed values: linear, exponential
dist_weight=float
Parameter for distance weighting. <0.5 - rapid decrease; 0.5 - linear decrease; > 0.5 - slow decrease; 1 - no decrease
-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 the cost map raster file
Used as: input, raster
propmap : str, optional
Name of the propagation cost map raster file
Used as: input, raster
output : str, required
Name for output raster map
Used as: output, raster, name
keyval : int, required
Key value
buffer : int, required
Buffer size
distance : float, required
Cone of effect radius
angle : float, required
Cone of effect angle
stats : str, required
Statistical method to perform on the values
Allowed values: average, median
propmethod : str, required
Propagation method
Allowed values: linear, exponential
dist_weight : float, optional
Parameter for distance weighting. <0.5 - rapid decrease; 0.5 - linear decrease; > 0.5 - slow decrease; 1 - no decrease
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: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
input : str | np.ndarray, required
Name of input raster map
Used as: input, raster, name
costmap : str | np.ndarray, required
Name of the cost map raster file
Used as: input, raster
propmap : str | np.ndarray, optional
Name of the propagation cost map raster file
Used as: input, raster
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Name for output raster map
Used as: output, raster, name
keyval : int, required
Key value
buffer : int, required
Buffer size
distance : float, required
Cone of effect radius
angle : float, required
Cone of effect angle
stats : str, required
Statistical method to perform on the values
Allowed values: average, median
propmethod : str, required
Propagation method
Allowed values: linear, exponential
dist_weight : float, optional
Parameter for distance weighting. <0.5 - rapid decrease; 0.5 - linear decrease; > 0.5 - slow decrease; 1 - no decrease
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: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
Raises:
grass.tools.ToolError: When the tool ended with an error.
DESCRIPTION
Edge effects and core area analysis of landcover fragments. This module can compute static edge effects (defined edge depth) and dynamic edge effects (based on surrounding landscape). The impact of the surrounding landscape can be accounted for and the resulting core area is provided.
NOTES
This module is generating core areas based on defined edge depths. The edge depths can be increased by the values of a costmap (e.g. urban areas could have a more severe impact than secondary forest on forest fragments). Moreover a friction map ( propmap within the fragments can lower the impact of surrounding landcover types and hence an increased edge depth (e.g. a river or escarpment which might lower the edge effects). Moreover a dist_weight can be assigned in order to increase the weight of closer pixel values.
Distance weight
The assigned distance weight is computed as:
w(d) = 1 - (d / d_max)^(tan(dist_weight * 0.5 * pi))
where:
- d = Distance of the respective cell
- d_max - the defined maximum distance
- dist_weight - the parameter how to weight the pixel values in the landscape depending on the distance
the dist_weight has a range between 0 and 1 and results in:
- 0 \< dist_weight \< 0.5: the weighting curve decreases at low distances to the fragment and lowers to a weight of 0 at d=d_max
- dist_weight = 0.5: linear decrease of weight until weight of 0 at d = d_max
- 0.5 \< dist_weight \< 1: the weighting curve decreases slowly at low distances and approaches weight value of 0 at higher distances from the fragment, the weight value 0 is reached at d = d_max
- dist_weight = 1: no distance weight applied, common static edge depth used
propmap
The propmap minimizes the effect of the edge depth and the surrounding
matrix. This has an ecological application if certain landscape features
inside a e.g. forest fragment hamper the human impact (edge effects).
two methods exist:
- propmethod=linear: propagated value = actual value - (propmap value at this position)
- propmethod=exponential: propagated value = actual value / (propmap value at this position)
If 0 is chosen using the linear method, then propagated value=actual value which results in a buffering of the whole region. In order to minimize the impact the value must be larger than 1. For the exponential method a value of below 1 should not be chosen, otherwise it will be propagated infinitely.
EXAMPLE
An example for the North Carolina sample dataset using class 5 (forest): For the computation of variable edge effects a costmap is necessary which need to be defined by the user. Higher costs are resulting in higher edge depths:
# class - type - costs
# 1 - developed - 3
# 2 - agriculture - 2
# 3 - herbaceous - 1
# 4 - shrubland - 1
# 5 - forest - 0
# 6 - water - 0
# 7 - sediment - 0
r.mapcalc "costmap_for_corearea = if(landclass96==1,3,if(landclass96==2,2,if(landclass96==3,1,if(landclass96==4,1,if(landclass96==5,0,if(landclass96==6,0,if(landclass96==7,0)))))))"
now the edge depth and the resulting core area can be computed:
r.pi.corearea input=landclass96 costmap=costmap_for_corearea output=landcover96_corearea keyval=5 buffer=5 distance=5 angle=90 stats=average propmethod=linear
the results consist of 2 files:
landclass96_corearea: the actual resulting core areas
landclass96_corearea_map: a map showing the edge depths
SEE ALSO
r.pi.grow, r.pi.import, r.pi.index, r.pi
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.corearea source code
(history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3