1r.neighbors(1) Grass User's Manual r.neighbors(1)
2
6 r.neighbors - Makes each cell category value a function of the cate‐
7 gory values assigned to the cells around it, and stores new cell values
8 in an output raster map layer.
9
11 raster
12
14 r.neighbors
15 r.neighbors help
16 r.neighbors [-aqc] input=name output=name [method=string]
17 [size=integer] [title="phrase"] [weight=string] [--overwrite]
18 [--verbose] [--quiet]
19 Flags:
21 -a
22 Do not align output with the input
23 -q
25 Run quietly
26 -c
28 Use circular neighborhood
29 --overwrite
31 Allow output files to overwrite existing files
32 --verbose
34 Verbose module output
35 --quiet
37 Quiet module output
38 Parameters:
40 input=name
41 Name of input raster map
42 output=name
44 Name for output raster map
45 method=string
47 Neighborhood operation
48 Options: average,median,mode,minimum,maximum,stddev,sum,vari‐
49 ance,diversity,interspersion
50 Default: average
51 size=integer
53 Neighborhood size
54 Default: 3
55 title=
57 Title of the output raster map
58 weight=string
60 File containing weights
61
63 r.neighbors looks at each cell in a raster input file, and examines the
64 values assigned to the cells in some user-defined "neighborhood" around
65 it. It outputs a new raster map layer in which each cell is assigned a
66 value that is some (user-specified) function of the values in that
67 cell's neighborhood. For example, each cell in the output layer might
68 be assigned a value equal to the average of the values appearing in its
69 3 x 3 cell "neighborhood" in the input layer.
70 The program will be run non-interactively if the user specifies program
72 arguments (see OPTIONS) on the command line. Alternately, the user can
73 simply type r.neighbors on the command line, without program arguments.
74 In this case, the user will be prompted for flag settings and parameter
75 values.
76 OPTIONS
78 The user must specify the names of the raster map layers to be used for
79 input and output, the method used to analyze neighborhood values (i.e.,
80 the neighborhood function or operation to be performed), and the size
81 of the neighborhood. Optionally, the user can also specify the TITLE
82 to be assigned to the raster map layer output, elect to not align the
83 resolution of the output with that of the input (the -a option), run
84 r.neighbors with a custom matrix weights with the weight option, and
85 elect to run r.neighbors quietly (the -q option). These options are
86 described further below.
87 Neighborhood Operation Methods: The neighborhood operators determine
89 what new value a center cell in a neighborhood will have after examin‐
90 ing values inside its neighboring cells. Each cell in a raster map
91 layer becomes the center cell of a neighborhood as the neighborhood
92 window moves from cell to cell throughout the map layer. r.neighbors
93 can perform the following operations:
94 average
96 The average value within the neighborhood. In the following
97 example, the result would be:
98 (7*4 + 6 + 5 + 4*3)/9 = 5.66
99 The result is rounded to the nearest integer (in this case 6).
100 median
102 The value found half-way through a list of the neighborhood's
103 values, when these are ranged in numerical order.
104 mode
106 The most frequently occurring value in the neighborhood.
107 minimum
109 The minimum value within the neighborhood.
110 maximum
112 The maximum value within the neighborhood.
113 Raw Data Operation New Data
114 ---------------- ----------------
115 | 7 | 7 | 5 | | | | |
116 |----|----|----| average |----|----|----|
117 | | 6 | |
118 |----|----|----| |----|----|----|
119 | 7 | 6 | 4 | | | | |
120 |----|----|----| |----|----|----|
121 stddev
124 The statistical standard deviation of values within the neigh‐
125 borhood (rounded to the nearest integer).
126 sum
128 The sum of values within the neighborhood.
129 variance
131 The statistical variance of values within the neighborhood
132 (rounded to the nearest integer).
133 diversity
135 The number of different values within the neighborhood. In the
136 above example, the diversity is 4.
137 interspersion
139 The percentage of cells containing values which differ from the
140 values assigned to the center cell in the neighborhood, plus 1.
141 In the above example, the interspersion is:
142 5/8 * 100 + 1 = 63.5
143 The result is rounded to the nearest integer (in this case 64).
144 Neighborhood Size:
146 The neighborhood size specifies which cells surrounding any given cell
147 fall into the neighborhood for that cell. The size must be an odd
148 integer. For example,
149 _ _ _
150 |_|_|_|
151 |_|_|_|
152 |_|_|_|
153 Matrix weights:
156 A custom matrix can be used if none of the neighborhood operation meth‐
157 ods are desirable by using the weight. This option must be used in
158 conjunction with the size option to specify the matrix size. The
159 weights desired are to be entered into a text file. For example, to
160 calculate the focal mean with a matrix size of 3,
161 r.neigbors in=input.map out=output.map size=3 weight=weights.txt
162 The contents of the weight.txt file:
163 3 3 3
164 1 4 8
165 9 5 3
166 This corresponds to the following 3x3 matrix:
167 -------
168 |3|3|3|
169 -------
170 |1|4|8|
171 -------
172 |9|5|3|
173 -------
174 FLAGS
177 -a
178 If specified, r.neighbors will not align the output raster map
179 layer with that of the input raster map layer. The r.neighbors
180 program works in the current geographic region. It is recom‐
181 mended, but not required, that the resolution of the geographic
182 region be the same as that of the raster map layer. By default,
183 if unspecified, r.neighbors will align these geographic region
184 settings.
185 -c This flag will use a circular neighborhood for the moving analy‐
187 sis window, centered on the current cell.
188 The exact masks for the first few neighborhood sizes are as follows:
190 3x3 . X . 5x5 . . X . . 7x7 . . . X . . .
191 X O X . X X X . . X X X X X .
192 . X . X X O X X . X X X X X .
193 . X X X . X X X O X X X
194 . . X . . . X X X X X .
195 . X X X X X .
196 . . . X . .
197 .
198 9x9 . . . . X . . . . 11x11 . . . . . X . . . . .
199 . . X X X X X . . . . X X X X X X X . .
200 . X X X X X X X . . X X X X X X X X X .
201 . X X X X X X X . . X X X X X X X X X .
202 X X X X O X X X X . X X X X X X X X X .
203 . X X X X X X X . X X X X X O X X X X X
204 . X X X X X X X . . X X X X X X X X X .
205 . . X X X X X . . . X X X X X X X X X .
206 . . . . X . . . . . X X X X X X X X X .
207 . . X X X X X X X . .
208 . . . . . X . . . . .
209 -q
212 If specified, r.neighbors will run relatively quietly (i.e.,
213 without printing to standard output notes on the program's
214 progress). If unspecified, the program will print messages to
215 standard output by default.
216
218 The r.neighbors program works in the current geographic region with the
219 current mask, if any. It is recommended, but not required, that the
220 resolution of the geographic region be the same as that of the raster
221 map layer. By default, r.neighbors will align these geographic region
222 settings. However, the user can elect to keep original input and out‐
223 put resolutions which are not aligned by specifying this (e.g., using
224 the -a option).
225 The -c flag and the weights parameter are mutually exclusive. Any use
227 of the two together will produce an error. Differently-shaped neighbor‐
228 hood analysis windows may be achieved by using the weight= parameter to
229 specify a weights file where all values are equal (for method=sum, the
230 sum of the weights should be 1). The user can also vary the weights at
231 the edge of the neighborhood according to the proportion of the cell
232 that lies inside the neighborhood circle, effectively anti-aliasing the
233 analysis mask.
234 For aggregates where a weighted calculation isn't meaningful (specifi‐
236 cally: minimum, maximum, diversity and interspersion), the weights are
237 used to create a binary mask, where zero causes the cell to be ignored
238 and any non-zero value causes the cell to be used.
239 r.neighbors copies the GRASS color files associated with the input
241 raster map layer for those output map layers that are based on the
242 neighborhood average, median, mode, minimum, and maximum. Because
243 standard deviation, variance, diversity, and interspersion are indices,
244 rather than direct correspondents to input values, no color files are
245 copied for these map layers. (The user should note that although the
246 color file is copied for average neighborhood function output, whether
247 or not the color file makes sense for the output will be dependent on
248 the input data values.)
249
251 g.region
252 r.clump
253 r.mapcalc
254 r.mfilter
255 r.statistics
256 r.support
257
259 Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
260 Last changed: $Date: 2008-02-26 04:11:00 +0100 (Tue, 26 Feb 2008) $
262 Full index
264 © 2003-2008 GRASS Development Team
266GRASS 6.3.0 r.neighbors(1)