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 weight 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:
Raw Data Operation New Data +---+---+---+ +---+---+---+ | 7 | 7 | 5 | | | | | +---+---+---+ average +---+---+---+ | 4 | 7 | 4 |--------->| | 6 | | +---+---+---+ +---+---+---+ | 7 | 6 | 4 | | | | | +---+---+---+ +---+---+---+
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])
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 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.)
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:
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)"
Last changed: $Date$