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.
(GRASS Raster Program)
SYNOPSIS
r.neighbors
r.neighbors help
r.neighbors [-aq]
input=name output=name
method=name size=value
[title="phrase"]
DESCRIPTION
r.neighbors looks at each cell in a raster input
file, and examines the category 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 category 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
category value equal to the average of the category 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 category
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), 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
category value a center cell in a neighborhood will have after examining
category 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 category 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 category value found half-way through a list of the
neighborhood's category values,
when these are ranged in numerical order.
mode
The most frequently occurring category value in the neighborhood.
minimum
The minimum category value within the neighborhood.
maximum
The maximum category value within the neighborhood.
Raw Data Operation New Data
---------------- ----------------
| 7 | 7 | 5 | | | | |
|----|----|----| average |----|----|----|
| 4 | 7 | 4 |--------->| | 6 | |
|----|----|----| |----|----|----|
| 7 | 6 | 4 | | | | |
|----|----|----| |----|----|----|
stddev
The statistical standard deviation of category values
within the neighborhood (rounded to the nearest integer).
variance
The statistical variance of category values
within the neighborhood (rounded to the nearest integer).
diversity
The number of different category values within the neighborhood.
In the above example, the diversity is 4.
interspersion
The percentage of cells containing categories which differ from the category
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).
ERROR .RE
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.
Options are: 1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, and 25.
For example,
_ _ _
|_|_|_|
3 x 3 neighborhood ---> |_|_|_|
|_|_|_|
-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.
-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 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 category values,
no color files are copied for these map layers.
(The user should note that although the color file is copied
for averaged 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.mask
r.mfilter
r.support
AUTHOR
Michael Shapiro,
U.S.Army Construction Engineering Research Laboratory