r.neighbors(1grass) GRASS GIS User's Manual r.neighbors(1grass)
NAME
r.neighbors - Makes each cell category value a function of the cate-
gory values assigned to the cells around it, and stores new cell values
in an output raster map layer.
KEYWORDS
raster, algebra, statistics, aggregation, neighbor, focal statistics,
filter
SYNOPSIS
r.neighbors
r.neighbors --help
r.neighbors [-ac] input=name [selection=name] output=name[,name,...]
[method=string[,string,...]] [size=integer] [title=phrase]
[weight=name] [gauss=float] [quantile=float[,float,...]] [--over-
write] [--help] [--verbose] [--quiet] [--ui]
Flags:
-a
Do not align output with the input
-c
Use circular neighborhood
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=name [required]
Name of input raster map
selection=name
Name of an input raster map to select the cells which should be
processed
output=name[,name,...] [required]
Name for output raster map
method=string[,string,...]
Neighborhood operation
Options: average, median, mode, minimum, maximum, range, stddev,
sum, count, variance, diversity, interspersion, quart1, quart3,
perc90, quantile
Default: average
size=integer
Neighborhood size
Default: 3
title=phrase
Title for output raster map
weight=name
Text file containing weights
gauss=float
Sigma (in cells) for Gaussian filter
quantile=float[,float,...]
Quantile to calculate for method=quantile
Options: 0.0-1.0
DESCRIPTION
r.neighbors looks at each cell in a raster input file, and examines the
values assigned to the cells in some user-defined "neighborhood" around
it. It outputs a new raster map layer in which each cell is assigned a
value that is some (user-specified) function of the values in that
cell’s neighborhood. For example, each cell in the output layer might
be assigned a value equal to the average of the values appearing in its
3 x 3 cell "neighborhood" in the input layer. Note that the centre cell
is also included in the calculation.
OPTIONS
The user must specify the names of the raster map layers to be used for
input and output, the method used to analyze neighborhood values (i.e.,
the neighborhood function or operation to be performed), and the size
of the neighborhood.
The user can optionally specify a selection map, to compute new values
only where the raster cells of the selection map are not NULL. In case
of a NULL cells, the values from the input map are copied into the out-
put map. This may useful to smooth only parts of an elevation map
(pits, peaks, ...).
Example how to use a selection map with method=average:
input map:
1 1 1 1 1
1 1 1 1 1
1 1 10 1 1
1 1 1 1 1
1 1 1 1 1
selection map, NULL values are marked as *:
* * * * *
* * 1 * *
* 1 1 1 *
* * 1 * *
* * * * *
The output map:
1 1 1 1 1
1 1 2 1 1
1 2 2 2 1
1 1 2 1 1
1 1 1 1 1
Without using the selection map, the output map would look like this:
1 1 1 1 1
1 2 2 2 1
1 2 2 2 1
1 2 2 2 1
1 1 1 1 1
Optionally, the user can also specify the TITLE to be assigned to the
raster map layer output, elect to not align the resolution of the out-
put with that of the input (the -a option), and run r.neighbors with a
custom matrix weights with the weight option. These options are de-
scribed further below.
Neighborhood Operation Methods: The neighborhood operators determine
what new value a center cell in a neighborhood will have after examin-
ing values inside its neighboring cells. Each cell in a raster map
layer becomes the center cell of a neighborhood as the neighborhood
window moves from cell to cell throughout the map layer. r.neighbors
can perform the following operations:
average
The average value within the neighborhood. In the following exam-
ple, the result would be:
(7*4 + 6 + 5 + 4*3)/9 = 5.6667
The result is rounded to the nearest integer (in this case 6).
Raw Data Operation New Data
+---+---+---+ +---+---+---+
| 7 | 7 | 5 | | | | |
+---+---+---+ average +---+---+---+
| 4 | 7 | 4 |--------->| | 6 | |
+---+---+---+ +---+---+---+
| 7 | 6 | 4 | | | | |
+---+---+---+ +---+---+---+
median
The value found half-way through a list of the neighborhood’s val-
ues, when these are ranged in numerical order.
mode
The most frequently occurring value in the neighborhood.
minimum
The minimum value within the neighborhood.
maximum
The maximum value within the neighborhood.
range
The range value within the neighborhood.
stddev
The statistical standard deviation of values within the neighbor-
hood (rounded to the nearest integer).
sum
The sum of values within the neighborhood.
count
The count of filled (not NULL) cells.
variance
The statistical variance of values within the neighborhood (rounded
to the nearest integer).
diversity
The number of different values within the neighborhood. In the
above example, the diversity is 4.
interspersion
The percentage of cells containing values which differ from the
values assigned to the center cell in the neighborhood, plus 1. In
the above example, the interspersion is:
5/8 * 100 + 1 = 63.5
The result is rounded to the nearest integer (in this case 64).
quart1, quart3
The result will be the first or the third quartile (equal of 25th
and 75th percentiles).
perc90
The result will be the 90th percentile of neighborhood.
quantile
Any quantile as specified by "quantile" input parameter.
Neighborhood Size: The neighborhood size specifies which cells sur-
rounding any given cell fall into the neighborhood for that cell. The
size must be an odd integer and represent the length of one of moving
window edges in cells. For example, a size value of 3 will result in
_ _ _
|_|_|_|
3 x 3 neighborhood ---> |_|_|_|
|_|_|_|
Matrix weights: A custom matrix can be used if none of the neighborhood
operation methods are desirable by using the weight. This option must
be used in conjunction with the size option to specify the matrix size.
The weights desired are to be entered into a text file. For example,
to calculate the focal mean with a matrix size of 3,
r.neigbors in=input.map out=output.map size=3 weight=weights.txt
The contents of the weight.txt file:
3 3 3
1 4 8
9 5 3
This corresponds to the following 3x3 matrix:
+-+-+-+
|3|3|3|
+-+-+-+
|1|4|8|
+-+-+-+
|9|5|3|
+-+-+-+
To calculate an annulus shaped neighborhood the contents of weight.txt
file may be e.g. for size=5:
0 1 1 1 0
1 0 0 0 1
1 0 0 0 1
1 0 0 0 1
0 1 1 1 0
The way that weights are used depends upon the specific aggregate
(method) being used. However, most of the aggregates have the property
that multiplying all of the weights by the same factor won’t change the
final result (an exception is method=count). Also, most (if not all)
of them have the properties that an integer weight of N is equivalent
to N occurrences of the cell value, and having all weights equal to one
produces the same result as when weights are not used. When weights
are used, the calculation for method=average is:
sum(w[i]*x[i]) / sum(w[i])
In the case where all weights are zero, this will end up with both the
numerator and denominator to zero, which produces a NULL result.
FLAGS
-a
If specified, r.neighbors will not align the output raster map
layer with that of the input raster map layer. The r.neighbors
program works in the current geographic region. It is recommended,
but not required, that the resolution of the geographic region be
the same as that of the raster map layer. By default, if unspeci-
fied, r.neighbors will align these geographic region settings.
-c
This flag will use a circular neighborhood for the moving analysis
window, centered on the current cell.
The exact masks for the first few neighborhood sizes are as follows:
3x3 . X . 5x5 . . X . . 7x7 . . . X . . .
X O X . X X X . . X X X X X .
. X . X X O X X . X X X X X .
. X X X . X X X O X X X
. . X . . . X X X X X .
. X X X X X .
. . . X . . .
9x9 . . . . X . . . . 11x11 . . . . . X . . . . .
. . X X X X X . . . . X X X X X X X . .
. X X X X X X X . . X X X X X X X X X .
. X X X X X X X . . X X X X X X X X X .
X X X X O X X X X . X X X X X X X X X .
. X X X X X X X . X X X X X O X X X X X
. X X X X X X X . . X X X X X X X X X .
. . X X X X X . . . X X X X X X X X X .
. . . . X . . . . . X X X X X X X X X .
. . X X X X X X X . .
. . . . . X . . . . .
NOTES
The r.neighbors program works in the current geographic region with the
current mask, if any. It is recommended, but not required, that the
resolution of the geographic region be the same as that of the raster
map layer. By default, r.neighbors will align these geographic region
settings. However, the user can select to keep original input and out-
put resolutions which are not aligned by specifying this (e.g., using
the -a option).
r.neighbors doesn’t propagate NULLs, but computes the aggregate over
the non-NULL cells in the neighborhood.
The -c flag and the weights parameter are mutually exclusive. Any use
of the two together will produce an error. Differently-shaped neighbor-
hood analysis windows may be achieved by using the weight= parameter to
specify a weights file where all values are equal. The user can also
vary the weights at the edge of the neighborhood according to the pro-
portion of the cell that lies inside the neighborhood circle, effec-
tively anti-aliasing the analysis mask.
For aggregates where a weighted calculation isn’t meaningful (specifi-
cally: minimum, maximum, diversity and interspersion), the weights are
used to create a binary mask, where zero causes the cell to be ignored
and any non-zero value causes the cell to be used.
r.neighbors copies the GRASS color files associated with the input
raster map layer for those output map layers that are based on the
neighborhood average, median, mode, minimum, and maximum. Because
standard deviation, variance, diversity, and interspersion are indices,
rather than direct correspondents to input values, no color files are
copied for these map layers. (The user should note that although the
color file is copied for average neighborhood function output, whether
or not the color file makes sense for the output will be dependent on
the input data values.)
Propagation of output precision
The following logic has been implemented: For any aggregate, there are
two factors affecting the output type:
1 Whether the input map is integer or floating-point.
2 Whether the weighted or unweighted version of the aggregate is
used.
These combine to create four possibilities:
input type/weight integer float
no yes no yes
average float float float float
median [1] [1] float float
mode integer integer [2] [2]
minimum integer integer float float
maximum integer integer float float
range integer integer float float
stddev float float float float
sum integer float float float
count integer float integer float
variance float float float float
diversity integer integer integer integer
interspersion integer integer integer integer
quart1 [1] [1] float float
quart3 [1] [1] float float
perc90 [1] [1] float float
quantile [1] [1] float float
[1] For integer input, quantiles may produce float results from inter-
polating between adjacent values.
[2] Calculating the mode of floating-point data is essentially meaning-
less.
With the current aggregates, there are 5 cases:
1 Output is always float: average, variance, stddev, quantiles
(with interpolation).
2 Output is always integer: diversity, interspersion.
3 Output is integer if unweighted, float if weighted: count.
4 Output matches input: minimum, maximum, range, mode (subject to
note 2 above), quantiles (without interpolation).
5 Output is integer for integer input and unweighted aggregate,
otherwise float: sum.
EXAMPLES
Measure occupancy of neighborhood
Set up 10x10 computational region to aid visual inspection of results
g.region rows=10 cols=10
Fill 50% of computational region with randomly located cells. "dis-
tance=0" will allow filling adjacent cells.
r.random.cells output=random_cells distance=0 ncells=50
Count non-empty (not NULL) cells in 3x3 neighborhood
r.neighbors input=random_cells output=counts method=count
Optionally - exclude centre cell from the count (= only look around)
r.mapcalc "cound_around = if( isnull(random_cells), counts, counts - 1)"
SEE ALSO
g.region
r.clump
r.mapcalc
r.mfilter
r.statistics
r.support
AUTHORS
Original version: Michael Shapiro, U.S.Army Construction Engineering
Research Laboratory
Updates for GRASS GIS 7 by Glynn Clements and others
SOURCE CODE
Available at: r.neighbors source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.neighbors(1grass)
Generated by dwww version 1.14 on Sun Dec 29 18:57:16 CET 2024.