Skip to content

t.rast.neighbors

Performs a neighborhood analysis for each map in a space time raster dataset.

t.rast.neighbors [-cenr] input=name output=name [where=sql_query] [region_relation=string] [selection=name] [size=integer] method=string [weighting_function=string] [weighting_factor=float] [weight=name] [quantile=float [,float,...]] basename=string [suffix=string] [semantic_labels=string] [nprocs=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.rast.neighbors input=name output=name method=average basename=string

grass.script.run_command("t.rast.neighbors", input, output, where=None, region_relation=None, selection=None, size=3, method="average", weighting_function="none", weighting_factor=None, weight=None, quantile=None, basename, suffix="gran", semantic_labels="input", nprocs=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("t.rast.neighbors", input="name", output="name", method="average", basename="string")

Parameters

input=name [required]
    Name of the input space time raster dataset
output=name [required]
    Name of the output space time raster dataset
where=sql_query
    WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
    Example: start_time > '2001-01-01 12:30:00'
region_relation=string
    Process only maps with this spatial relation to the current computational region
    Allowed values: overlaps, contains, is_contained
selection=name
    Name of an input raster map to select the cells which should be processed
size=integer
    Neighborhood size
    Default: 3
method=string [required]
    Aggregate operation to be performed on the raster maps
    Allowed values: average, median, mode, minimum, maximum, range, stddev, sum, count, variance, diversity, interspersion, quart1, quart3, perc90, quantile
    Default: average
weighting_function=string
    Weighting function
    Allowed values: none, gaussian, exponential, file
    Default: none
    none: No weighting
    gaussian: Gaussian weighting function
    exponential: Exponential weighting function
    file: File with a custom weighting matrix
weighting_factor=float
    Factor used in the selected weighting function (ignored for weighting_function=none and file)
weight=name
    Text file containing weights
quantile=float [,float,...]
    Quantile to calculate for method=quantile
    Allowed values: 0.0-1.0
basename=string [required]
    Basename of the new generated output maps
    A numerical suffix separated by an underscore will be attached to create a unique identifier
suffix=string
    Suffix to add at basename: set 'gran' for granularity, 'time' for the full time format, 'num' for numerical suffix with a specific number of digits (default %05)
    Default: gran
semantic_labels=string
    Set semantic labels
    Allowed values: input, method
    Default: input
    input: copy semantic labels from input to output
    method: append method name to input label if existing, otherwise use method name
nprocs=integer
    Number of r.neighbor processes to run in parallel
    Default: 1
-c
    Use circular neighborhood
-e
    Extend existing space time raster dataset
-n
    Register Null maps
-r
    Ignore the current region settings and use the raster map regions
--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 the input space time raster dataset
    Used as: input, strds, name
output : str, required
    Name of the output space time raster dataset
    Used as: output, strds, name
where : str, optional
    WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
    Example: start_time > '2001-01-01 12:30:00'
    Used as: sql_query
region_relation : str, optional
    Process only maps with this spatial relation to the current computational region
    Allowed values: overlaps, contains, is_contained
selection : str, optional
    Name of an input raster map to select the cells which should be processed
    Used as: input, raster, name
size : int, optional
    Neighborhood size
    Default: 3
method : str, required
    Aggregate operation to be performed on the raster maps
    Allowed values: average, median, mode, minimum, maximum, range, stddev, sum, count, variance, diversity, interspersion, quart1, quart3, perc90, quantile
    Default: average
weighting_function : str, optional
    Weighting function
    Allowed values: none, gaussian, exponential, file
    none: No weighting
    gaussian: Gaussian weighting function
    exponential: Exponential weighting function
    file: File with a custom weighting matrix
    Default: none
weighting_factor : float, optional
    Factor used in the selected weighting function (ignored for weighting_function=none and file)
weight : str, optional
    Text file containing weights
    Used as: input, file, name
quantile : float | list[float] | str, optional
    Quantile to calculate for method=quantile
    Allowed values: 0.0-1.0
basename : str, required
    Basename of the new generated output maps
    A numerical suffix separated by an underscore will be attached to create a unique identifier
suffix : str, optional
    Suffix to add at basename: set 'gran' for granularity, 'time' for the full time format, 'num' for numerical suffix with a specific number of digits (default %05)
    Default: gran
semantic_labels : str, optional
    Set semantic labels
    Allowed values: input, method
    input: copy semantic labels from input to output
    method: append method name to input label if existing, otherwise use method name
    Default: input
nprocs : int, optional
    Number of r.neighbor processes to run in parallel
    Default: 1
flags : str, optional
    Allowed values: c, e, n, r
    c
        Use circular neighborhood
    e
        Extend existing space time raster dataset
    n
        Register Null maps
    r
        Ignore the current region settings and use the raster map regions
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

t.rast.neighbors performs r.neighbors computations on the maps of a space time raster dataset (STRDS). This module supports the options that are available in r.neighbors.

The user must provide an input and an output space time raster dataset and the basename of the resulting raster maps. The resulting STRDS will have the same temporal resolution as the input dataset. With the -e flag, resulting maps can be registered in an existing STRDS, that e.g. may have been created with a previous run of t.rast.neighbors. All maps will be processed using the current region settings unless the -r flag is selected. In the latter case, the computaional region is set to each raster map selected from the input STRDS.

The user can select a subset of the input space time raster dataset for processing using a SQL WHERE statement or using the region_relation for spatial selection of raster maps. For the spatial map selection the current computational region is used, even when the -r flag is given. The number of CPU's to be used for parallel processing can be specified with the nprocs option to speedup the computation on multi-core system.

Semantic labels are needed to relate output raster maps to input raster maps. E.g. with method=stddev, the user needs to know the spatial extent, the time stamp and the semantic label to determine which stddev map corresponds to which input map.

EXAMPLE

To smooth the maps contained in a space time dataset run:

t.rast.neighbors input=tempmean_monthly output=smooth_tempmean_monthly \
                 basename=tmean_smooth size=5 method=average nprocs=4

# show some info about the new space time dataset
t.info smooth_tempmean_monthly
 +-------------------- Space Time Raster Dataset -----------------------------+
 |                                                                            |
 +-------------------- Basic information -------------------------------------+
 | Id: ........................ smooth_tempmean_monthly@climate_2000_2012
 | Name: ...................... smooth_tempmean_monthly
 | Mapset: .................... climate_2000_2012
 | Creator: ................... lucadelu
 | Temporal type: ............. absolute
 | Creation time: ............. 2014-11-27 11:41:36.444579
 | Modification time:.......... 2014-11-27 11:41:39.978232
 | Semantic type:.............. mean
 +-------------------- Absolute time -----------------------------------------+
 | Start time:................. 2009-01-01 00:00:00
 | End time:................... 2013-01-01 00:00:00
 | Granularity:................ 1 month
 | Temporal type of maps:...... interval
 +-------------------- Spatial extent ----------------------------------------+
 | North:...................... 320000.0
 | South:...................... 10000.0
 | East:.. .................... 935000.0
 | West:....................... 120000.0
 | Top:........................ 0.0
 | Bottom:..................... 0.0
 +-------------------- Metadata information ----------------------------------+
 | Raster register table:...... raster_map_register_ea1c9a83524e41a784d72744b08c6107
 | North-South resolution min:. 500.0
 | North-South resolution max:. 500.0
 | East-west resolution min:... 500.0
 | East-west resolution max:... 500.0
 | Minimum value min:.......... -6.428905
 | Minimum value max:.......... 18.867296
 | Maximum value min:.......... 4.247691
 | Maximum value max:.......... 28.767953
 | Aggregation type:........... None
 | Number of registered maps:.. 48
 |
 | Title:
 | Monthly precipitation
 | Description:
 | Dataset with monthly precipitation
 | Command history:
 | # 2014-11-27 11:41:36
 | t.rast.neighbors input="tempmean_monthly"
 |     output="smooth_tempmean_monthly" basename="tmean_smooth" size="5"
 |     method="average" nprocs="4"
 |
 +----------------------------------------------------------------------------+


# now compare the values between the original and the smoothed dataset

t.rast.list input=smooth_tempmean_monthly columns=name,start_time,min,max
name|start_time|min|max
tmean_smooth_1|2009-01-01 00:00:00|-3.361714|7.409861
tmean_smooth_2|2009-02-01 00:00:00|-1.820261|7.986794
tmean_smooth_3|2009-03-01 00:00:00|2.912971|11.799684
...
tmean_smooth_46|2012-10-01 00:00:00|9.38767|18.709297
tmean_smooth_47|2012-11-01 00:00:00|1.785653|10.911189
tmean_smooth_48|2012-12-01 00:00:00|1.784212|11.983857

t.rast.list input=tempmean_monthly columns=name,start_time,min,max
name|start_time|min|max
2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
2009_02_tempmean|2009-02-01 00:00:00|-1.820261|8.006386
2009_03_tempmean|2009-03-01 00:00:00|2.656992|11.819274
...
2012_10_tempmean|2012-10-01 00:00:00|9.070884|18.709297
2012_11_tempmean|2012-11-01 00:00:00|1.785653|10.911189
2012_12_tempmean|2012-12-01 00:00:00|1.761019|11.983857

SEE ALSO

r.neighbors, t.rast.aggregate.ds, t.rast.extract, t.info, g.region, r.mask

AUTHOR

Sören Gebbert, Thünen Institute of Climate-Smart Agriculture

SOURCE CODE

Available at: t.rast.neighbors source code (history)
Latest change: Wednesday Apr 02 17:48:37 2025 in commit 571253a