i.segment.stats

Calculates statistics describing raster areas.

i.segment.stats [-rnsc] map=name [rasters=name [,name,...]] [raster_statistics=string [,string,...]] [area_measures=string [,string,...]] [csvfile=name] [separator=character] [vectormap=name] [processes=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

i.segment.stats map=name csvfile=name

grass.script.run_command("i.segment.stats", map, rasters=None, raster_statistics="mean,stddev,sum", area_measures="area,perimeter,compact_circle,fd", csvfile=None, separator="pipe", vectormap=None, processes=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("i.segment.stats", map="name", csvfile="name")

Parameters

Command linePython (grass.script)

map=name [required]
    Name for input raster map with areas
    Raster map with areas (all pixels of an area have same id), such as the output of i.segment
rasters=name [,name,...]
    Name of input raster maps for statistics
raster_statistics=string [,string,...]
    Statistics to calculate for each input raster map
    Allowed values: min, max, range, mean, mean_of_abs, stddev, variance, coeff_var, sum, sum_abs, first_quart, median, third_quart, perc_90
    Default: mean,stddev,sum
area_measures=string [,string,...]
    Area measurements to include in the output
    Allowed values: area, perimeter, compact_circle, compact_square, fd, xcoords, ycoords
    Default: area,perimeter,compact_circle,fd
csvfile=name
    Name for output CSV file containing statistics
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
vectormap=name
    Name for optional vector output map with statistics as attributes
processes=integer
    Number of processes to run in parallel (for multiple rasters)
    Default: 1
-r
    Adjust region to input map
-n
    Calculate neighborhood statistics
-s
    Do not calculate any shape statistics
-c
    Do not check rasters for null cells
--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

map : str, required
    Name for input raster map with areas
    Raster map with areas (all pixels of an area have same id), such as the output of i.segment
    Used as: input, raster, name
rasters : str | list[str], optional
    Name of input raster maps for statistics
    Used as: input, raster, name
raster_statistics : str | list[str], optional
    Statistics to calculate for each input raster map
    Allowed values: min, max, range, mean, mean_of_abs, stddev, variance, coeff_var, sum, sum_abs, first_quart, median, third_quart, perc_90
    Default: mean,stddev,sum
area_measures : str | list[str], optional
    Area measurements to include in the output
    Allowed values: area, perimeter, compact_circle, compact_square, fd, xcoords, ycoords
    Default: area,perimeter,compact_circle,fd
csvfile : str, optional
    Name for output CSV file containing statistics
    Used as: output, file, name
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
vectormap : str, optional
    Name for optional vector output map with statistics as attributes
    Used as: output, vector, name
processes : int, optional
    Number of processes to run in parallel (for multiple rasters)
    Default: 1
flags : str, optional
    Allowed values: r, n, s, c
    r
        Adjust region to input map
    n
        Calculate neighborhood statistics
    s
        Do not calculate any shape statistics
    c
        Do not check rasters for null cells
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

i.segment.stats calculates statistics for areas in a raster map. Areas are defined by adjacent pixels with the same value. Such areas can be the output of i.segment or r.clump.

Available statistics are those related to the shape, size and position of the areas (see the r.object.geometry man page for more information on the statistics) and aggregated statistics of pixel values of other raster maps (see r.univar for details).

In addition, for each of the above statistics, the -n flag allows the user to request the output of the mean and the standard deviation of the values of the neighboring objects (all direct neighbors, diagonal neighbors included), which allows gathering some context information for each object. For this feature, the r.neighborhoodmatrix addon has to be installed. Currently, the module calculates these context statistics for all available shape and spectral statistics.

The user can chose between output in the form of a vector map of the areas with the statistics in the attribute table (vectormap) and/or in the form of a CSV text file (csvfile).

Because of the way r.univar functions, it is difficult to handle cases where in some raster maps values are all null in some of the areas. Because of this, i.segment.stats checks the raster maps for existing null values and excludes them if it find any, emitting a warning to inform the user. The user can decide to ignore this check using the c flag, for example when there are only a few null cells and no complete areas with only null cells (i.e. the module can calculate statistics for areas with some null cells in them).

NOTES

The module respects the current region settings. The -r flag allows to force the module to adjust the region to the input raster map before calculating the statistics.

This module is a simple front-end to r.univar and r.object.geometry. If other statistics are desired, these should probably be implemented in those (or other) modules which can then be called from this module.

Problems can arise in the calculation of some form statistics for certain segment forms. If errors arise, the user might want to try to run r.clump on the input raster file before running i.segment.stats.

When treating files with a large number objects, creating the vector map can be very time-consuming. In that case, it might be easier to only work with the csvfile output.

The processing of several raster input files for which to calculate per-segment statistics can be parallelized by setting the processes parameter to the number of desired parallel processes, with at most one process per raster to be treated.

EXAMPLE

i.group group=landsat_pan input=lsat7_2002_80
g.region rast=lsat7_2002_80 -p
i.segment group=landsat_pan output=ls_pan_seg01 threshold=0.1 memory=4000 minsize=50
i.segment.stats map=ls_pan_seg01 csvfile=segstats.csv vectormap=ls_pan_seg01 \
  rasters=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 \
  processes=4

AUTHOR

Moritz Lennert

SOURCE CODE

Available at: i.segment.stats source code (history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819