Provided by: grass-doc_6.4.3-3_all 
NAME
r.neighbors - Makes each cell category value a function of the category values assigned to the cells
around it, and stores new cell values in an output raster map layer.
KEYWORDS
raster, statistics
SYNOPSIS
r.neighbors
r.neighbors help
r.neighbors [-aqc] input=name output=name [method=string] [size=integer] [title="phrase"]
[weight=string] [gauss=float] [--overwrite] [--verbose] [--quiet]
Flags:
-a
Do not align output with the input
-q
Run quietly
-c
Use circular neighborhood
--overwrite
Allow output files to overwrite existing files
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
input=name
Name of input raster map
output=name
Name for output raster map
method=string
Neighborhood operation
Options: average,median,mode,minimum,maximum,range,stddev,sum,variance,diversity,interspersion
Default: average
size=integer
Neighborhood size
Default: 3
title=
Title of the output raster map
weight=string
File containing weights
gauss=float
Sigma (in cells) for Gaussian filter
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.
The program will be run non-interactively if the user specifies program arguments (see OPTIONS) on the
command line. Alternately, the user can simply type r.neighbors on the command line, without program
arguments. In this case, the user will be prompted for flag settings and parameter values.
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. 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 output with that of the input (the -a option),
run r.neighbors with a custom matrix weights with the weight option, and elect to run r.neighbors quietly
(the -q option). These options are described further below.
Neighborhood Operation Methods: The neighborhood operators determine what new value a center cell in a
neighborhood will have after examining 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 example, the result would be:
(7*4 + 6 + 5 + 4*3)/9 = 5.66
The result is rounded to the nearest integer (in this case 6).
median
The value found half-way through a list of the neighborhood's values, 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.
Raw Data Operation New Data
---------------- ----------------
| 7 | 7 | 5 | | | | |
|----|----|----| average |----|----|----|
| | 6 | |
|----|----|----| |----|----|----|
| 7 | 6 | 4 | | | | |
|----|----|----| |----|----|----|
range
The range value within the neighborhood.
stddev
The statistical standard deviation of values within the neighborhood (rounded to the nearest
integer).
sum
The sum of values within the neighborhood.
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).
Neighborhood Size:
The neighborhood size specifies which cells surrounding any given cell fall into the neighborhood for
that cell. The size must be an odd integer. For example,
_ _ _
|_|_|_|
|_|_|_|
|_|_|_|
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|
-------
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 unspecified, 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 . . . . .
-q
If specified, r.neighbors will run relatively quietly (i.e., without printing to standard output
notes on the program's progress). If unspecified, the program will print messages to standard
output by default.
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 elect to keep original input and output 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 neighborhood 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 proportion of the cell that lies inside the neighborhood circle,
effectively anti-aliasing the analysis mask.
For aggregates where a weighted calculation isn't meaningful (specifically: 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.)
SEE ALSO
g.region
r.clump
r.mapcalc
r.mfilter
r.statistics
r.support
AUTHOR
Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
Last changed: $Date: 2010-09-21 05:53:31 -0700 (Tue, 21 Sep 2010) $
Full index
© 2003-2013 GRASS Development Team