Skip to content

r3.forestfrag

Computes the forest fragmentation index (Riitters et al. 2000)

r3.forestfrag [-rta] input=name output=name size=number [pf=name] [pff=name] transitional_limit=float patch_limit=float [interior_limit=float] [color=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r3.forestfrag input=name output=name size=3 transitional_limit=0.6 patch_limit=0.4

grass.script.run_command("r3.forestfrag", input, output, size=3, pf=None, pff=None, transitional_limit=0.6, patch_limit=0.4, interior_limit=None, color="sambale", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r3.forestfrag", input="name", output="name", size=3, transitional_limit=0.6, patch_limit=0.4)

Parameters

input=name [required]
    Name of forest raster map (where forest=1, non-forest=0)
output=name [required]
    Name for output 3D raster map
size=number [required]
    Moving window size (odd number)
    Allowed values: 3-
    Default: 3
pf=name
    Name for output Pf (forest area density) raster map
    Proportion of area which is forested (amount of forest)
pff=name
    Name for output Pff (forest connectivity) raster map
    Conditional probability that neighboring cell is forest
transitional_limit=float [required]
    transitional_limit
    Default: 0.6
patch_limit=float [required]
    patch_limit
    Default: 0.4
interior_limit=float
    interior_limit
color=string
    Source raster for colorization
    Input and color_input are taken from input and color_input options respectively. The rest is computed using r.slope.aspect
    Allowed values: sambale, riitters, perceptual
    Default: sambale
    sambale: Sambale, Stefan Sylla
    riitters: Riitters et. al 2000
    perceptual: Perceptually uniform
-r
    Set computational region to input raster map
-t
    Keep Pf and Pff maps
-a
    Trim the output map to avoid border effects
--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 forest raster map (where forest=1, non-forest=0)
    Used as: input, raster_3d, name
output : str, required
    Name for output 3D raster map
    Used as: output, raster_3d, name
size : int, required
    Moving window size (odd number)
    Used as: number
    Allowed values: 3-
    Default: 3
pf : str, optional
    Name for output Pf (forest area density) raster map
    Proportion of area which is forested (amount of forest)
    Used as: output, raster_3d, name
pff : str, optional
    Name for output Pff (forest connectivity) raster map
    Conditional probability that neighboring cell is forest
    Used as: output, raster_3d, name
transitional_limit : float, required
    transitional_limit
    Default: 0.6
patch_limit : float, required
    patch_limit
    Default: 0.4
interior_limit : float, optional
    interior_limit
color : str, optional
    Source raster for colorization
    Input and color_input are taken from input and color_input options respectively. The rest is computed using r.slope.aspect
    Allowed values: sambale, riitters, perceptual
    sambale: Sambale, Stefan Sylla
    riitters: Riitters et. al 2000
    perceptual: Perceptually uniform
    Default: sambale
flags : str, optional
    Allowed values: r, t, a
    r
        Set computational region to input raster map
    t
        Keep Pf and Pff maps
    a
        Trim the output map to avoid border effects
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

TODO: Create a description specific for 3D version r.forestfrag Computes the forest fragmentation following the methodology proposed by Riitters et. al (2000). See this article for a detailed explanation.

It follows a "sliding window" algorithm with overlapping windows. The amount of forest and its occurence as adjacent forest pixels within fixed- area "moving-windows" surrounding each forest pixel is measured. The window size is user-defined. The result is stored at the location of the center pixel. Thus, a pixel value in the derived map refers to "between-pixel" fragmentation around the corresponding forest location.

As input it requires a binary map with (1) forest and (0) non-forest. Obviously, one can replace forest any other land cover type. If one wants to exclude the influence of a specific land cover type, e.g., water bodies, it should be classified as no-data (NA) in the input map. See e.g., blog post.

Let Pf be the proportion of pixels in the window that are forested. Define Pff (strictly) as the proportion of all adjacent (cardinal directions only) pixel pairs that include at least one forest pixel, for which both pixels are forested. Pff thus (roughly) estimates the conditional probability that, given a pixel of forest, its neighbor is also forest. The classification model then identifies six fragmentation categories as:

interior:       Pf = 1.0
patch:          Pf < 0.4
transitional:   0.4 ≤ Pf < 0.6
edge:           Pf ≥ 0.6 and Pf - Pff < 0
perforated:     Pf ≥ 0.6 and Pf - Pff > 0
undetermined:   Pf ≥ 0.6 and Pf = Pff

NOTES

  • The moving window size is user-defined (default=3) and must be an odd number. If an even number is given the function will stop with an error message.
  • No-data cells are ignored. This means that statistics at the raster edges are based on fewer cells (smaller) moving windows. If this is a problem, the user can choose to have the output raster trimmed with a number of raster cells equal to 1/2 * the size of the moving window.
  • The function respects the region. The user has however the option to set the region to match the input layer.

REFERENCES

Petras, V., Newcomb D. J., Mitasova, H. 2017. Generalized 3D fragmentation index derived from lidar point clouds. Open Geospatial Data, Software and Standards 2017 2:9 DOI: 10.1186/s40965-017-0021-8
Riitters, K., J. Wickham, R. O'Neill, B. Jones, and E. Smith. 2000. Global-scale patterns of forest fragmentation. Conservation Ecology 4(2): 3. [online] URL: http://www.consecol.org/vol4/iss2/art3/

SEE ALSO

r3.count.categories, g.region, r.forestfrag

AUTHORS

Vaclav Petras, NCSU GeoForAll Lab
Paulo van Breugel, main author of the 2D version (r.forestfrag)

SOURCE CODE

Available at: r3.forestfrag source code (history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf