v.rast.bufferstats

Calculates statistics of raster map(s) for buffers around vector geometries.

v.rast.bufferstats [-tpurl] input=name raster=name [,name,...] buffers=integer [,integer,...] type=string [,string,...] [layer=string] column_prefix=string [,string,...] [methods=string [,string,...]] [percentile=integer] [output=name] [separator=character] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.rast.bufferstats input=name raster=name buffers=integer type=points,lines,areas column_prefix=string

grass.script.run_command("v.rast.bufferstats", input, raster, buffers, type="points,lines,areas", layer="1", column_prefix, methods="number,number_null,minimum,maximum,range,sum,average,average_abs,stddev,variance,coeff_var,first_quartile,median,third_quartile", percentile=None, output=None, separator="|", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("v.rast.bufferstats", input="name", raster="name", buffers=integer, type="points,lines,areas", column_prefix="string")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of input vector map
    Vector map containing geometries to compute buffer statistics for
raster=name [,name,...] [required]
    Raster map(s) to calculate statistics from
buffers=integer [,integer,...] [required]
    Buffer distance(s) in map units
type=string [,string,...] [required]
    Vector type to work on
    Allowed values: points, lines, areas
    Default: points,lines,areas
layer=string
    Layer number or name
    Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
    Default: 1
column_prefix=string [,string,...] [required]
    Column prefix for new attribute columns
methods=string [,string,...]
    The methods to use
    Allowed values: number, number_null, minimum, maximum, range, sum, average, average_abs, stddev, variance, coeff_var, first_quartile, median, third_quartile
    Default: number,number_null,minimum,maximum,range,sum,average,average_abs,stddev,variance,coeff_var,first_quartile,median,third_quartile
percentile=integer
    Percentile to calculate
    Allowed values: 0-100
output=name
    Name for output file (if "-" output to stdout)
separator=character
    Field separator
    Field separator in output file
    Default: |
-t
    Tabulate area within buffers for categories in raster map(s)
-p
    Used with -t flag will return percentage of area for categories
-u
    Update columns if they already exist
-r
    Remove columns without data
-l
    Use labels for column names if possible
--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 vector map
    Vector map containing geometries to compute buffer statistics for
    Used as: input, vector, name
raster : str | list[str], required
    Raster map(s) to calculate statistics from
    Used as: input, raster, name
buffers : int | list[int] | str, required
    Buffer distance(s) in map units
type : str | list[str], required
    Vector type to work on
    Allowed values: points, lines, areas
    Default: points,lines,areas
layer : str, optional
    Layer number or name
    Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
    Used as: input, layer
    Default: 1
column_prefix : str | list[str], required
    Column prefix for new attribute columns
methods : str | list[str], optional
    The methods to use
    Allowed values: number, number_null, minimum, maximum, range, sum, average, average_abs, stddev, variance, coeff_var, first_quartile, median, third_quartile
    Default: number,number_null,minimum,maximum,range,sum,average,average_abs,stddev,variance,coeff_var,first_quartile,median,third_quartile
percentile : int, optional
    Percentile to calculate
    Allowed values: 0-100
output : str, optional
    Name for output file (if "-" output to stdout)
    Used as: output, file, name
separator : str, optional
    Field separator
    Field separator in output file
    Used as: input, separator, character
    Default: |
flags : str, optional
    Allowed values: t, p, u, r, l
    t
        Tabulate area within buffers for categories in raster map(s)
    p
        Used with -t flag will return percentage of area for categories
    u
        Update columns if they already exist
    r
        Remove columns without data
    l
        Use labels for column names if possible
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

The purpose of the v.rast.bufferstats module is to provide local environmental context to a series of input geometries. It computes statistics from multiple input raster maps within multiple buffers around selected geometries in the input vector map.

Available statistics are either

statistics provided by r.univar or
if the t-flag is checked - area of, number of and/or the most frequent (mode) raster categories within the buffers using r.stats.

If the output option is specified, results are written to a text file or stdout instead of the attribute table of the input map. The output file is produced with the following column order:
cat | prefix | buffer| statistic/measure | value
separated by the user defined separator (default is |).

NOTE

The module temporarily modifies the computational region. The region is set to the extent of the respective buffers, while the alignment of the current region is kept.

EXAMPLES

# Preparations
g.region -p raster=elevation,geology_30m
v.clip -r input=bridges output=bridges_wake

# Tabulate area of land cover map
g.region -p raster=elevation,geology_30m align=geology_30m
v.rast.bufferstats -t input=bridges_wake raster=geology_30m buffers=100,250,500 column_prefix=geology

# Compute terrain statistics and update vector attribute table
g.region -p raster=elevation,geology_30m align=elevation
r.slope.aspect elevation=elevation slope=slope aspect=aspect
v.rast.bufferstats input=bridges_wake raster=altitude,slope,aspect buffers=100,250,500 column_prefix=altitude,slope,aspect methods=minimum,maximum,average,stddev percentile=5,95

KNOWN ISSUES

In order to avoid topological issues with overlapping buffers, the module loops over the input geometries. However, this comes at costs with regards to performance. For a larger number of geometries in the vector map, it can be therefore more appropriate to compute neighborhood statistics with r.neighbors and to extract (v.what.rast, r.what) or aggregate (v.rast.stats) from those maps with neighborhood statistics.

The module is affected by the following underlying library issue: Currently, the module uses GRASS native buffering through pygrass which should be replaced by buffering using GEOS: https://trac.osgeo.org/grass/ticket/3628

AUTHOR

Stefan Blumentrath, Norwegian Institute for Nature Research, Oslo, Norway

SOURCE CODE

Available at: v.rast.bufferstats source code (history)
Latest change: Friday Feb 21 12:27:42 2025 in commit 8fce680