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 output 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

* * * * * * * 1 * * * 1 1 1 * * * 1 * * * * * * *

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

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 output with that of the
input (the **-a** option), and run * r.neighbors*
with a custom matrix weights with the

*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.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 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.
**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.
**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 surrounding 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

3 3 3 1 4 8 9 5 3

+-+-+-+ |3|3|3| +-+-+-+ |1|4|8| +-+-+-+ |9|5|3| +-+-+-+

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

sum(w[i]*x[i]) / sum(w[i])

**-a**- If specified,
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.**r.neighbors** **-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 . . . . .

* 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

- Whether the input map is integer or floating-point.
- Whether the weighted or unweighted version of the aggregate is used.

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
interpolating between adjacent values.

[2] Calculating the mode of floating-point data is essentially
meaningless.

With the current aggregates, there are 5 cases:

- Output is always float: average, variance, stddev, quantiles (with interpolation).
- Output is always integer: diversity, interspersion.
- Output is integer if unweighted, float if weighted: count.
- Output matches input: minimum, maximum, range, mode (subject to note 2 above), quantiles (without interpolation).
- Output is integer for integer input and unweighted aggregate, otherwise float: sum.

g.region rows=10 cols=10

r.random.cells output=random_cells distance=0 ncells=50

r.neighbors input=random_cells output=counts method=count

r.mapcalc "cound_around = if( isnull(random_cells), counts, counts - 1)"

Updates for GRASS GIS 7 by Glynn Clements and others

*Last changed: $Date$*