.TH r.neighbors 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
\fI\fBr.neighbors\fR\fR  - 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.
.SH KEYWORDS
raster, statistics
.SH SYNOPSIS
\fBr.neighbors\fR
.br
\fBr.neighbors help\fR
.br
\fBr.neighbors\fR [\-\fBaqc\fR] \fBinput\fR=\fIname\fR \fBoutput\fR=\fIname\fR  [\fBmethod\fR=\fIstring\fR]   [\fBsize\fR=\fIinteger\fR]   [\fBtitle\fR=\fI"phrase"\fR]   [\fBweight\fR=\fIstring\fR]   [\fBgauss\fR=\fIfloat\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR] 
.SS Flags:
.IP "\fB\-a\fR" 4m
.br
Do not align output with the input
.IP "\fB\-q\fR" 4m
.br
Run quietly
.IP "\fB\-c\fR" 4m
.br
Use circular neighborhood
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR" 4m
.br
Name of input raster map
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output raster map
.IP "\fBmethod\fR=\fIstring\fR" 4m
.br
Neighborhood operation
.br
Options: \fIaverage,median,mode,minimum,maximum,range,stddev,sum,variance,diversity,interspersion\fR
.br
Default: \fIaverage\fR
.IP "\fBsize\fR=\fIinteger\fR" 4m
.br
Neighborhood size
.br
Default: \fI3\fR
.IP "\fBtitle\fR=\fI"phrase"\fR" 4m
.br
Title of the output raster map
.IP "\fBweight\fR=\fIstring\fR" 4m
.br
File containing weights
.IP "\fBgauss\fR=\fIfloat\fR" 4m
.br
Sigma (in cells) for Gaussian filter
.PP
.SH DESCRIPTION
\fI\fBr.neighbors\fR\fR 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.
.PP
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
\fI\fBr.neighbors\fR\fR on the command line, without program
arguments.  In this case, the user will be prompted for
flag settings and parameter values.
.SS OPTIONS
The user must specify the names of the raster map layers to
be used for \fBinput\fR and \fBoutput\fR, the
\fBmethod\fR used to analyze neighborhood
values (i.e., the neighborhood function or operation to be
performed), and the \fBsize\fR of the neighborhood.
Optionally, the user can also specify the \fBTITLE\fR to
be assigned to the raster map layer \fBoutput\fR, elect
to not align the resolution of the output with that of the
input (the \fB-a\fR option), run \fI\fBr.neighbors\fR\fR with
a custom matrix weights with the \fIweight\fR option, and
elect to run \fI\fBr.neighbors\fR\fR quietly (the \fB-q\fR option).
These options are described further below.
.PP
\fINeighborhood Operation Methods:\fR
The \fBneighborhood\fR 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.
\fI\fBr.neighbors\fR\fR can perform the following operations:
.PP
.IP "\fBaverage\fR 
.br
The average value within the neighborhood.
In the following example, the result would be:
.br
(7*4 + 6 + 5 + 4*3)/9 = 5.66
.br
The result is rounded to the nearest integer (in this case 6).
.IP "\fBmedian\fR 
.br
The value found half-way through a list of the
neighborhood's values,
when these are ranged in numerical order.
.IP "\fBmode\fR 
.br
The most frequently occurring value in the neighborhood.
.IP "\fBminimum\fR 
.br
The minimum value within the neighborhood.
.IP "\fBmaximum\fR 
.br
The maximum value within the neighborhood.
\fC
.DS
.br
       Raw Data     Operation     New Data
.br
   ----------------          ----------------
.br
   | 7  | 7  |  5 |          |    |    |    |
.br
   |----|----|----| average  |----|----|----|
.br
|    |  6 |    |
.br
   |----|----|----|          |----|----|----|
.br
   | 7  | 6  |  4 |          |    |    |    |
.br
   |----|----|----|          |----|----|----|
.br
.DE
\fR
.IP "\fBrange\fR
.br
The range value within the neighborhood.
.IP "\fBstddev\fR 
.br
The statistical standard deviation of values
within the neighborhood (rounded to the nearest integer).
.IP "\fBsum\fR 
.br
The sum of values within the neighborhood.
.IP "\fBvariance\fR 
.br
The statistical variance of values
within the neighborhood (rounded to the nearest integer).
.IP "\fBdiversity\fR 
.br
The number of different values within the neighborhood.
In the above example, the diversity is 4.
.IP "\fBinterspersion\fR 
.br
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:
.br
5/8 * 100 + 1 = 63.5
.br
The result is rounded to the nearest integer (in this case 64).
.PP
.PP
.br
\fINeighborhood Size:\fR
.br
The neighborhood \fBsize\fR specifies which cells surrounding any given
cell fall into the neighborhood for that cell.
The \fBsize\fR must be an odd integer.
For example,
\fC
.DS
.br
                              _ _ _
.br
                             |_|_|_| 
.br
  |_|_|_|
.br
                             |_|_|_|
.br
.br
.DE
\fR
.PP
\fIMatrix weights:\fR
.br
A custom matrix can be used if none of the neighborhood operation
methods are desirable by using the \fBweight\fR.  This option must
be used in conjunction with the \fBsize\fR 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 \fBsize\fR of
3,
\fC
.DS
.br
r.neigbors in=input.map out=output.map size=3 weight=weights.txt
.br
.DE
\fR
The contents of the weight.txt file:
\fC
.DS
.br
3 3 3
.br
1 4 8
.br
9 5 3
.br
.DE
\fR
This corresponds to the following 3x3 matrix:
\fC
.DS
.br
    -------
.br
    |3|3|3|
.br
    -------
.br
    |1|4|8|
.br
    -------
.br
    |9|5|3|
.br
    -------
.br
.DE
\fR
.PP
.SS FLAGS
.IP "\fB\-a\fR 
.br
If specified, \fI\fBr.neighbors\fR\fR will not align the output
raster map layer with that of the input raster map layer.
The \fI\fBr.neighbors\fR\fR 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,
\fI\fBr.neighbors\fR\fR will align these geographic region settings.
.PP
.IP "\fB\-c\fR
This flag will use a circular neighborhood for the moving analysis window,
centered on the current cell. 
.PP
The exact masks for the first few neighborhood sizes are as follows:
\fC
.DS
.br
3x3     . X .		5x5	. . X . .	7x7	. . . X . . . 
.br
        X O X			. X X X .		. X X X X X .
.br
        . X .			X X O X X		. X X X X X .
.br
				. X X X .		X X X O X X X
.br
 				. . X . .		. X X X X X .
.br
							. X X X X X .
.br
        						. . . X . . .							
.br
.br
9x9	. . . . X . . . .		11x11   . . . . . X . . . . .
.br
	. . X X X X X . .			. . X X X X X X X . .
.br
        . X X X X X X X .			. X X X X X X X X X .
.br
        . X X X X X X X .			. X X X X X X X X X .
.br
        X X X X O X X X X			. X X X X X X X X X .
.br
        . X X X X X X X .			X X X X X O X X X X X
.br
        . X X X X X X X .			. X X X X X X X X X .	
.br
        . . X X X X X . .			. X X X X X X X X X .
.br
        . . . . X . . . .			. X X X X X X X X X .
.br
				        	. . X X X X X X X . .
.br
				        	. . . . . X . . . . .	
.br
.DE
\fR
.PP
.IP "\fB\-q\fR 
.br
If specified, \fI\fBr.neighbors\fR\fR 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.
.SH NOTES
The \fI\fBr.neighbors\fR\fR 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, \fI\fBr.neighbors\fR\fR 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 \fB-a\fR option).
.PP
\fI\fBr.neighbors\fR\fR doesn't propagate NULLs, but computes the
aggregate over the non-NULL cells in the neighborhood.
.PP
The \fB-c\fR flag and the \fBweights\fR 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 \fBweight=\fR 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.
.PP
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.
.PP
\fI\fBr.neighbors\fR\fR copies the GRASS \fIcolor\fR 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 \fIcolor\fR files are copied for these map layers.
(The user should note that although the \fIcolor\fR file is copied
for \fIaverage\fR neighborhood function output,
whether or not the color file makes sense for the output
will be dependent on the input data values.)
.SH SEE ALSO
\fIg.region\fR
.br
\fIr.clump\fR
.br
\fIr.mapcalc\fR
.br
\fIr.mfilter\fR
.br
\fIr.statistics\fR
.br
\fIr.support\fR
.SH AUTHOR
Michael Shapiro,
U.S.Army Construction Engineering Research Laboratory 
.PP
\fILast changed: $Date: 2010-09-21 14:53:31 +0200 (Tue, 21 Sep 2010) $\fR  
.PP
Full index
.PP
© 2003-2014 GRASS Development Team