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, algebra, statistics, aggregation, neighbor, focal statistics,
12 filter
13
15 r.neighbors
16 r.neighbors --help
17 r.neighbors [-ac] input=name [selection=name] output=name[,name,...]
18 [method=string[,string,...]] [size=integer] [title=phrase]
19 [weight=name] [gauss=float] [quantile=float[,float,...]] [--over‐
20 write] [--help] [--verbose] [--quiet] [--ui]
21 Flags:
23 -a
24 Do not align output with the input
25 -c
27 Use circular neighborhood
28 --overwrite
30 Allow output files to overwrite existing files
31 --help
33 Print usage summary
34 --verbose
36 Verbose module output
37 --quiet
39 Quiet module output
40 --ui
42 Force launching GUI dialog
43 Parameters:
45 input=name [required]
46 Name of input raster map
47 selection=name
49 Name of an input raster map to select the cells which should be
50 processed
51 output=name[,name,...] [required]
53 Name for output raster map
54 method=string[,string,...]
56 Neighborhood operation
57 Options: average, median, mode, minimum, maximum, range, stddev,
58 sum, count, variance, diversity, interspersion, quart1, quart3,
59 perc90, quantile
60 Default: average
61 size=integer
63 Neighborhood size
64 Default: 3
65 title=phrase
67 Title for output raster map
68 weight=name
70 Text file containing weights
71 gauss=float
73 Sigma (in cells) for Gaussian filter
74 quantile=float[,float,...]
76 Quantile to calculate for method=quantile
77 Options: 0.0-1.0
78
80 r.neighbors looks at each cell in a raster input file, and examines the
81 values assigned to the cells in some user-defined "neighborhood" around
82 it. It outputs a new raster map layer in which each cell is assigned a
83 value that is some (user-specified) function of the values in that
84 cell’s neighborhood. For example, each cell in the output layer might
85 be assigned a value equal to the average of the values appearing in its
86 3 x 3 cell "neighborhood" in the input layer. Note that the centre cell
87 is also included in the calculation.
88 OPTIONS
90 The user must specify the names of the raster map layers to be used for
91 input and output, the method used to analyze neighborhood values (i.e.,
92 the neighborhood function or operation to be performed), and the size
93 of the neighborhood.
94 The user can optionally specify a selection map, to compute new values
96 only where the raster cells of the selection map are not NULL. In case
97 of a NULL cells, the values from the input map are copied into the out‐
98 put map. This may useful to smooth only parts of an elevation map
99 (pits, peaks, ...).
100 Example how to use a selection map with method=average:
102 input map:
103 1 1 1 1 1
104 1 1 1 1 1
105 1 1 10 1 1
106 1 1 1 1 1
107 1 1 1 1 1
108 selection map, NULL values are marked as *:
109 * * * * *
110 * * 1 * *
111 * 1 1 1 *
112 * * 1 * *
113 * * * * *
114 The output map:
115 1 1 1 1 1
116 1 1 2 1 1
117 1 2 2 2 1
118 1 1 2 1 1
119 1 1 1 1 1
120 Without using the selection map, the output map would look like this:
121 1 1 1 1 1
122 1 2 2 2 1
123 1 2 2 2 1
124 1 2 2 2 1
125 1 1 1 1 1
126 Optionally, the user can also specify the TITLE to be assigned to the
128 raster map layer output, elect to not align the resolution of the out‐
129 put with that of the input (the -a option), and run r.neighbors with a
130 custom matrix weights with the weight option. These options are
131 described further below.
132 Neighborhood Operation Methods: The neighborhood operators determine
134 what new value a center cell in a neighborhood will have after examin‐
135 ing values inside its neighboring cells. Each cell in a raster map
136 layer becomes the center cell of a neighborhood as the neighborhood
137 window moves from cell to cell throughout the map layer. r.neighbors
138 can perform the following operations:
139 average
141 The average value within the neighborhood. In the following exam‐
142 ple, the result would be:
143 (7*4 + 6 + 5 + 4*3)/9 = 5.6667
144 The result is rounded to the nearest integer (in this case 6).
145 Raw Data Operation New Data
146 +---+---+---+ +---+---+---+
147 | 7 | 7 | 5 | | | | |
148 +---+---+---+ average +---+---+---+
149 | 4 | 7 | 4 |--------->| | 6 | |
150 +---+---+---+ +---+---+---+
151 | 7 | 6 | 4 | | | | |
152 +---+---+---+ +---+---+---+
153 median
155 The value found half-way through a list of the neighborhood’s val‐
156 ues, when these are ranged in numerical order.
157 mode
159 The most frequently occurring value in the neighborhood.
160 minimum
162 The minimum value within the neighborhood.
163 maximum
165 The maximum value within the neighborhood.
166 range
168 The range value within the neighborhood.
169 stddev
171 The statistical standard deviation of values within the neighbor‐
172 hood (rounded to the nearest integer).
173 sum
175 The sum of values within the neighborhood.
176 count
178 The count of filled (not NULL) cells.
179 variance
181 The statistical variance of values within the neighborhood (rounded
182 to the nearest integer).
183 diversity
185 The number of different values within the neighborhood. In the
186 above example, the diversity is 4.
187 interspersion
189 The percentage of cells containing values which differ from the
190 values assigned to the center cell in the neighborhood, plus 1. In
191 the above example, the interspersion is:
192 5/8 * 100 + 1 = 63.5
193 The result is rounded to the nearest integer (in this case 64).
194 quart1, quart3
196 The result will be the first or the third quartile (equal of 25th
197 and 75th percentiles).
198 perc90
200 The result will be the 90th percentile of neighborhood.
201 quantile
203 Any quantile as specified by "quantile" input parameter.
204 Neighborhood Size: The neighborhood size specifies which cells sur‐
206 rounding any given cell fall into the neighborhood for that cell. The
207 size must be an odd integer and represent the length of one of moving
208 window edges in cells. For example, a size value of 3 will result in
209 _ _ _
210 |_|_|_|
211 3 x 3 neighborhood ---> |_|_|_|
212 |_|_|_|
213 Matrix weights: A custom matrix can be used if none of the neighborhood
215 operation methods are desirable by using the weight. This option must
216 be used in conjunction with the size option to specify the matrix size.
217 The weights desired are to be entered into a text file. For example,
218 to calculate the focal mean with a matrix size of 3,
219 r.neigbors in=input.map out=output.map size=3 weight=weights.txt
220 The contents of the weight.txt file:
221 3 3 3
222 1 4 8
223 9 5 3
224 This corresponds to the following 3x3 matrix:
225 +-+-+-+
226 |3|3|3|
227 +-+-+-+
228 |1|4|8|
229 +-+-+-+
230 |9|5|3|
231 +-+-+-+
232 To calculate an annulus shaped neighborhood the contents of weight.txt
233 file may be e.g. for size=5:
234 0 1 1 1 0
235 1 0 0 0 1
236 1 0 0 0 1
237 1 0 0 0 1
238 0 1 1 1 0
239 The way that weights are used depends upon the specific aggregate
240 (method) being used. However, most of the aggregates have the property
241 that multiplying all of the weights by the same factor won’t change the
242 final result (an exception is method=count). Also, most (if not all)
243 of them have the properties that an integer weight of N is equivalent
244 to N occurrences of the cell value, and having all weights equal to one
245 produces the same result as when weights are not used. When weights
246 are used, the calculation for method=average is:
247 sum(w[i]*x[i]) / sum(w[i])
248 In the case where all weights are zero, this will end up with both the
249 numerator and denominator to zero, which produces a NULL result.
250 FLAGS
252 -a
253 If specified, r.neighbors will not align the output raster map
254 layer with that of the input raster map layer. The r.neighbors
255 program works in the current geographic region. It is recommended,
256 but not required, that the resolution of the geographic region be
257 the same as that of the raster map layer. By default, if unspeci‐
258 fied, r.neighbors will align these geographic region settings.
259 -c
261 This flag will use a circular neighborhood for the moving analysis
262 window, centered on the current cell.
263 The exact masks for the first few neighborhood sizes are as follows:
265 3x3 . X . 5x5 . . X . . 7x7 . . . X . . .
266 X O X . X X X . . X X X X X .
267 . X . X X O X X . X X X X X .
268 . X X X . X X X O X X X
269 . . X . . . X X X X X .
270 . X X X X X .
271 . . . X . . .
272 9x9 . . . . X . . . . 11x11 . . . . . X . . . . .
273 . . X X X X X . . . . X X X X X X X . .
274 . X X X X X X X . . X X X X X X X X X .
275 . X X X X X X X . . X X X X X X X X X .
276 X X X X O X X X X . X X X X X X X X X .
277 . X X X X X X X . X X X X X O X X X X X
278 . X X X X X X X . . X X X X X X X X X .
279 . . X X X X X . . . X X X X X X X X X .
280 . . . . X . . . . . X X X X X X X X X .
281 . . X X X X X X X . .
282 . . . . . X . . . . .
283
285 The r.neighbors program works in the current geographic region with the
286 current mask, if any. It is recommended, but not required, that the
287 resolution of the geographic region be the same as that of the raster
288 map layer. By default, r.neighbors will align these geographic region
289 settings. However, the user can select to keep original input and out‐
290 put resolutions which are not aligned by specifying this (e.g., using
291 the -a option).
292 r.neighbors doesn’t propagate NULLs, but computes the aggregate over
294 the non-NULL cells in the neighborhood.
295 The -c flag and the weights parameter are mutually exclusive. Any use
297 of the two together will produce an error. Differently-shaped neighbor‐
298 hood analysis windows may be achieved by using the weight= parameter to
299 specify a weights file where all values are equal. The user can also
300 vary the weights at the edge of the neighborhood according to the pro‐
301 portion of the cell that lies inside the neighborhood circle, effec‐
302 tively anti-aliasing the analysis mask.
303 For aggregates where a weighted calculation isn’t meaningful (specifi‐
305 cally: minimum, maximum, diversity and interspersion), the weights are
306 used to create a binary mask, where zero causes the cell to be ignored
307 and any non-zero value causes the cell to be used.
308 r.neighbors copies the GRASS color files associated with the input
310 raster map layer for those output map layers that are based on the
311 neighborhood average, median, mode, minimum, and maximum. Because
312 standard deviation, variance, diversity, and interspersion are indices,
313 rather than direct correspondents to input values, no color files are
314 copied for these map layers. (The user should note that although the
315 color file is copied for average neighborhood function output, whether
316 or not the color file makes sense for the output will be dependent on
317 the input data values.)
318 Propagation of output precision
320 The following logic has been implemented: For any aggregate, there are
321 two factors affecting the output type:
322 1 Whether the input map is integer or floating-point.
324 2 Whether the weighted or unweighted version of the aggregate is
326 used.
327 These combine to create four possibilities:
329 input type/weight integer float
331 no yes no yes
333 average float float float float
335 median [1] [1] float float
337 mode integer integer [2] [2]
339 minimum integer integer float float
343 maximum integer integer float float
345 range integer integer float float
347 stddev float float float float
349 sum integer float float float
351 count integer float integer float
353 variance float float float float
355 diversity integer integer integer integer
357 interspersion integer integer integer integer
359 quart1 [1] [1] float float
361 quart3 [1] [1] float float
363 perc90 [1] [1] float float
365 quantile [1] [1] float float
367 [1] For integer input, quantiles may produce float results from inter‐
370 polating between adjacent values.
371 [2] Calculating the mode of floating-point data is essentially meaning‐
372 less.
373 With the current aggregates, there are 5 cases:
375 1 Output is always float: average, variance, stddev, quantiles
377 (with interpolation).
378 2 Output is always integer: diversity, interspersion.
380 3 Output is integer if unweighted, float if weighted: count.
382 4 Output matches input: minimum, maximum, range, mode (subject to
384 note 2 above), quantiles (without interpolation).
385 5 Output is integer for integer input and unweighted aggregate,
387 otherwise float: sum.
388
390 Measure occupancy of neighborhood
391 Set up 10x10 computational region to aid visual inspection of results
392 g.region rows=10 cols=10
393 Fill 50% of computational region with randomly located cells. "dis‐
394 tance=0" will allow filling adjacent cells.
395 r.random.cells output=random_cells distance=0 ncells=50
396 Count non-empty (not NULL) cells in 3x3 neighborhood
397 r.neighbors input=random_cells output=counts method=count
398 Optionally - exclude centre cell from the count (= only look around)
399 r.mapcalc "cound_around = if( isnull(random_cells), counts, counts - 1)"
400
402 g.region
403 r.clump
404 r.mapcalc
405 r.mfilter
406 r.statistics
407 r.support
408
410 Original version: Michael Shapiro, U.S.Army Construction Engineering
411 Research Laboratory
412 Updates for GRASS GIS 7 by Glynn Clements and others
413 Last changed: $Date: 2017-12-01 15:48:19 +0100 (Fri, 01 Dec 2017) $
415
417 Available at: r.neighbors source code (history)
418 Main index | Raster index | Topics index | Keywords index | Graphical
420 index | Full index
421 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
423GRASS 7.4.4 r.neighbors(1)