1r.neighbors(1) GRASS GIS 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, parallel
13
15 r.neighbors
16 r.neighbors --help
17 r.neighbors [-ac] input=name [selection=name] output=name[,name,...]
18 [size=integer] [method=string[,string,...]] [weighting_func‐
19 tion=string] [weighting_factor=float] [weight=name] [quan‐
20 tile=float[,float,...]] [title=phrase] [nprocs=integer] [mem‐
21 ory=memory in MB] [--overwrite] [--help] [--verbose] [--quiet]
22 [--ui]
23 Flags:
25 -a
26 Do not align output with the input
27 -c
29 Use circular neighborhood
30 --overwrite
32 Allow output files to overwrite existing files
33 --help
35 Print usage summary
36 --verbose
38 Verbose module output
39 --quiet
41 Quiet module output
42 --ui
44 Force launching GUI dialog
45 Parameters:
47 input=name [required]
48 Name of input raster map
49 selection=name
51 Name of an input raster map to select the cells which should be
52 processed
53 output=name[,name,...]Â [required]
55 Name for output raster map
56 size=integer
58 Neighborhood size
59 Default: 3
60 method=string[,string,...]
62 Neighborhood operation
63 Options: average, median, mode, minimum, maximum, range, stddev,
64 sum, count, variance, diversity, interspersion, quart1, quart3,
65 perc90, quantile
66 Default: average
67 weighting_function=string
69 Weighting function
70 Options: none, gaussian, exponential, file
71 Default: none
72 none: No weighting
73 gaussian: Gaussian weighting function
74 exponential: Exponential weighting function
75 file: File with a custom weighting matrix
76 weighting_factor=float
78 Factor used in the selected weighting function (ignored for none
79 and file)
80 weight=name
82 Text file containing weights
83 quantile=float[,float,...]
85 Quantile to calculate for method=quantile
86 Options: 0.0-1.0
87 title=phrase
89 Title for output raster map
90 nprocs=integer
92 Number of threads for parallel computing
93 Default: 1
94 memory=memory in MB
96 Maximum memory to be used (in MB)
97 Cache size for raster rows
98 Default: 300
99
101 r.neighbors looks at each cell in a raster input map, and examines the
102 values assigned to the cells in some user-defined "neighborhood" around
103 it. It outputs a new raster map layer in which each cell is assigned a
104 value that is some (user-specified) function of the values in that
105 cell’s neighborhood. For example, each cell in the output layer might
106 be assigned a value equal to the average of the values appearing in its
107 3 x 3 cell "neighborhood" in the input layer. Note that the centre cell
108 is also included in the calculation.
109 Figure: Illustration for an 3x3 average neighborhood
111 OPTIONS
113 The user must specify the names of the raster map layers to be used for
114 input and output, the method used to analyze neighborhood values (i.e.,
115 the neighborhood function or operation to be performed), and the size
116 of the neighborhood.
117 The user can optionally specify a selection map, to compute new values
119 only where the raster cells of the selection map are not NULL. In case
120 of a NULL cells, the values from the input map are copied into the out‐
121 put map. This may useful to smooth only parts of an elevation map
122 (pits, peaks, ...).
123 Example how to use a selection map with method=average:
125 input map:
126 1 1 1 1 1
127 1 1 1 1 1
128 1 1 10 1 1
129 1 1 1 1 1
130 1 1 1 1 1
131 selection map, NULL values are marked as *:
132 * * * * *
133 * * 1 * *
134 * 1 1 1 *
135 * * 1 * *
136 * * * * *
137 The output map:
138 1 1 1 1 1
139 1 1 2 1 1
140 1 2 2 2 1
141 1 1 2 1 1
142 1 1 1 1 1
143 Without using the selection map, the output map would look like this:
144 1 1 1 1 1
145 1 2 2 2 1
146 1 2 2 2 1
147 1 2 2 2 1
148 1 1 1 1 1
149 It is also possible to weigh cells within the neighborhood. This can be
151 either done with a custom weights matrix or by specifying a weighting
152 function.
153 In order to use a custom weights matrix, file needs to be specified as
155 a weighting_function and a path to a text file containing the weights
156 needs to be given in the weight option.
157 Alternatively, gaussian and exponential weighting functions can be se‐
159 lected as weighting function.
160 For the gaussian weighting function, the user specifies the sigma value
162 (Ï) for the gauss filter in the weighting_factor option. The sigma
163 value represents the standard deviation of the gaussian distribution,
164 where the weighting formula for the gaussian filter is defined as fol‐
165 lows:
166 exp(-(x*x+y*y)/(2*Ï^2))/(2*Ï*Ï^2)
168 Lower values for sigma result in a steeper curve, so that more weight
170 is put on cells close to the center of the moving window with a steeper
171 decrease in weights with distance from the center.
172 For the exponential weighting function, the user specifies a factor for
174 an exponential kernel in the weighting_factor. Negative factors result
175 in negative exponential decrease in weights from the center cell. The
176 weighting formula for the exponential kernel is defined as follows:
177 exp(factor*sqrt(x*x+y*y))
179 Stronger negative values for the factor result in a steeper curve, so
181 that more weight is put on cells close to the center of the moving win‐
182 dow with a steeper decrease in weights with distance from the center.
183 Optionally, the user can also run r.neighbors specify the TITLE to be
185 assigned to the raster map layer output, select to not align the reso‐
186 lution of the output with that of the input (the -a option). These op‐
187 tions are described further below.
188 Neighborhood Operation Methods: The neighborhood operators determine
190 what new value a center cell in a neighborhood will have after examin‐
191 ing values inside its neighboring cells. Each cell in a raster map
192 layer becomes the center cell of a neighborhood as the neighborhood
193 window moves from cell to cell throughout the map layer. r.neighbors
194 can perform the following operations:
195 average
197 The average value within the neighborhood. In the following exam‐
198 ple, the result would be:
199 (7*4 + 6 + 5 + 4*3)/9 = 5.6667
200 The result is rounded to the nearest integer (in this case 6).
201 Raw Data Operation New Data
202 +---+---+---+ +---+---+---+
203 | 7 | 7 | 5 | | | | |
204 +---+---+---+ average +---+---+---+
205 | 4 | 7 | 4 |--------->| | 6 | |
206 +---+---+---+ +---+---+---+
207 | 7 | 6 | 4 | | | | |
208 +---+---+---+ +---+---+---+
209 median
211 The value found half-way through a list of the neighborhood’s val‐
212 ues, when these are ranged in numerical order.
213 mode
215 The most frequently occurring value in the neighborhood.
216 minimum
218 The minimum value within the neighborhood.
219 maximum
221 The maximum value within the neighborhood.
222 range
224 The range value within the neighborhood.
225 stddev
227 The statistical standard deviation of values within the neighbor‐
228 hood (rounded to the nearest integer).
229 sum
231 The sum of values within the neighborhood.
232 count
234 The count of filled (not NULL) cells.
235 variance
237 The statistical variance of values within the neighborhood (rounded
238 to the nearest integer).
239 diversity
241 The number of different values within the neighborhood. In the
242 above example, the diversity is 4.
243 interspersion
245 The percentage of cells containing values which differ from the
246 values assigned to the center cell in the neighborhood, plus 1. In
247 the above example, the interspersion is:
248 5/8 * 100 + 1 = 63.5
249 The result is rounded to the nearest integer (in this case 64).
250 quart1, quart3
252 The result will be the first or the third quartile (equal of 25th
253 and 75th percentiles).
254 perc90
256 The result will be the 90th percentile of neighborhood.
257 quantile
259 Any quantile as specified by "quantile" input parameter.
260 Neighborhood Size: The neighborhood size specifies which cells sur‐
262 rounding any given cell fall into the neighborhood for that cell. The
263 size must be an odd integer and represent the length of one of moving
264 window edges in cells. For example, a size value of 3 will result in
265 _ _ _
266 |_|_|_|
267 3 x 3 neighborhood ---> |_|_|_|
268 |_|_|_|
269 Matrix weights: A custom matrix can be used if none of the neighborhood
271 operation methods are desirable by using the weight. This option must
272 be used in conjunction with the size option to specify the matrix size
273 and file needs to be specified as weighting_function. The weights de‐
274 sired are to be entered into a text file. For example, to calculate the
275 focal mean with a matrix size of 3,
276 r.neigbors in=input.map out=output.map size=3 weighting_function=file \
277 weight=weights.txt
278 The contents of the weight.txt file:
279 3 3 3
280 1 4 8
281 9 5 3
282 This corresponds to the following 3x3 matrix:
283 +-+-+-+
284 |3|3|3|
285 +-+-+-+
286 |1|4|8|
287 +-+-+-+
288 |9|5|3|
289 +-+-+-+
290 To calculate an annulus shaped neighborhood the contents of weight.txt
291 file may be e.g. for size=5:
292 0 1 1 1 0
293 1 0 0 0 1
294 1 0 0 0 1
295 1 0 0 0 1
296 0 1 1 1 0
297 The way that weights are used depends upon the specific aggregate
298 (method) being used. However, most of the aggregates have the property
299 that multiplying all of the weights by the same factor won’t change the
300 final result (an exception is method=count). Also, most (if not all)
301 of them have the properties that an integer weight of N is equivalent
302 to N occurrences of the cell value, and having all weights equal to one
303 produces the same result as when weights are not used. When weights
304 are used, the calculation for method=average is:
305 sum(w[i]*x[i]) / sum(w[i])
306 In the case where all weights are zero, this will end up with both the
307 numerator and denominator to zero, which produces a NULL result.
308 FLAGS
310 -a
311 If specified, r.neighbors will not align the output raster map
312 layer with that of the input raster map layer. The r.neighbors
313 program works in the current geographic region. It is recommended,
314 but not required, that the resolution of the geographic region be
315 the same as that of the raster map layer. By default, if unspeci‐
316 fied, r.neighbors will align these geographic region settings.
317 -c
319 This flag will use a circular neighborhood for the moving analysis
320 window, centered on the current cell.
321 The exact masks for the first few neighborhood sizes are as follows:
323 3x3 . X . 5x5 . . X . . 7x7 . . . X . . .
324 X O X . X X X . . X X X X X .
325 . X . X X O X X . X X X X X .
326 . X X X . X X X O X X X
327 . . X . . . X X X X X .
328 . X X X X X .
329 . . . X . . .
330 9x9 . . . . X . . . . 11x11 . . . . . X . . . . .
331 . . X X X X X . . . . X X X X X X X . .
332 . X X X X X X X . . X X X X X X X X X .
333 . X X X X X X X . . X X X X X X X X X .
334 X X X X O X X X X . X X X X X X X X X .
335 . X X X X X X X . X X X X X O X X X X X
336 . X X X X X X X . . X X X X X X X X X .
337 . . X X X X X . . . X X X X X X X X X .
338 . . . . X . . . . . X X X X X X X X X .
339 . . X X X X X X X . .
340 . . . . . X . . . . .
341
343 The r.neighbors program works in the current geographic region with the
344 current mask, if any. It is recommended, but not required, that the
345 resolution of the geographic region be the same as that of the raster
346 map layer. By default, r.neighbors will align these geographic region
347 settings. However, the user can select to keep original input and out‐
348 put resolutions which are not aligned by specifying this (e.g., using
349 the -a option).
350 r.neighbors doesn’t propagate NULLs, but computes the aggregate over
352 the non-NULL cells in the neighborhood.
353 The -c flag and the weights parameter are mutually exclusive. Any use
355 of the two together will produce an error. Differently-shaped neighbor‐
356 hood analysis windows may be achieved by using the weight= parameter to
357 specify a weights file where all values are equal. The user can also
358 vary the weights at the edge of the neighborhood according to the pro‐
359 portion of the cell that lies inside the neighborhood circle, effec‐
360 tively anti-aliasing the analysis mask.
361 For aggregates where a weighted calculation isn’t meaningful (specifi‐
363 cally: minimum, maximum, diversity and interspersion), the weights are
364 used to create a binary mask, where zero causes the cell to be ignored
365 and any non-zero value causes the cell to be used.
366 r.neighbors copies the GRASS color files associated with the input
368 raster map layer for those output map layers that are based on the
369 neighborhood average, median, mode, minimum, and maximum. Because
370 standard deviation, variance, diversity, and interspersion are indices,
371 rather than direct correspondents to input values, no color files are
372 copied for these map layers. (The user should note that although the
373 color file is copied for average neighborhood function output, whether
374 or not the color file makes sense for the output will be dependent on
375 the input data values.)
376 Propagation of output precision
378 The following logic has been implemented: For any aggregate, there are
379 two factors affecting the output type:
380 1 Whether the input map is integer or floating-point.
382 2 Whether the weighted or unweighted version of the aggregate is
384 used.
385 These combine to create four possibilities:
387 input type/weight integer float
389 no yes no yes
391 average float float float float
393 median [1] [1] float float
395 mode integer integer [2] [2]
399 minimum integer integer float float
401 maximum integer integer float float
403 range integer integer float float
405 stddev float float float float
407 sum integer float float float
409 count integer float integer float
411 variance float float float float
413 diversity integer integer integer integer
415 interspersion integer integer integer integer
417 quart1 [1] [1] float float
419 quart3 [1] [1] float float
421 perc90 [1] [1] float float
423 quantile [1] [1] float float
425 [1] For integer input, quantiles may produce float results from inter‐
428 polating between adjacent values.
429 [2] Calculating the mode of floating-point data is essentially meaning‐
430 less.
431 With the current aggregates, there are 5 cases:
433 1 Output is always float: average, variance, stddev, quantiles
435 (with interpolation).
436 2 Output is always integer: diversity, interspersion.
438 3 Output is integer if unweighted, float if weighted: count.
440 4 Output matches input: minimum, maximum, range, mode (subject to
442 note 2 above), quantiles (without interpolation).
443 5 Output is integer for integer input and unweighted aggregate,
445 otherwise float: sum.
446 Performance
448 To enable parallel processing, the user can specify the number of
449 threads to be used with the nprocs parameter (default 1). The memory
450 parameter (default 300) can also be provided to determine the size of
451 the buffer for computation.
452 Figure: Benchmark on the left shows execution time for different number
453 of cells, benchmark in the middle shows execution time for different
454 sizes of neighborhood for a 10000x10000 raster and benchmark on the
455 right shows execution time for different memory size for a 10000x10000
456 raster. See benchmark scripts in source code. (Intel Core i9-10940X
457 CPU @ 3.30GHz x 28)
458 To reduce the memory requirements to minimum, set option memory to
460 zero. To take advantage of the parallelization, GRASS GIS needs to be
461 compiled with OpenMP enabled.
462
464 Measure occupancy of neighborhood
465 Set up 10x10 computational region to aid visual inspection of results
466 g.region rows=10 cols=10
467 Fill 50% of computational region with randomly located cells. "dis‐
468 tance=0" will allow filling adjacent cells.
469 r.random.cells output=random_cells distance=0 ncells=50
470 Count non-empty (not NULL) cells in 3x3 neighborhood
471 r.neighbors input=random_cells output=counts method=count
472 Optionally - exclude centre cell from the count (= only look around)
473 r.mapcalc "count_around = if( isnull(random_cells), counts, counts - 1)"
474
476 g.region, r.clump, r.mapcalc, r.mfilter, r.statistics, r.support
477
479 Original version: Michael Shapiro, U.S.Army Construction Engineering
480 Research Laboratory
481 Updates for GRASS GIS 7 by Glynn Clements and others
482
484 Available at: r.neighbors source code (history)
485 Accessed: Saturday Jan 21 21:14:48 2023
487 Main index | Raster index | Topics index | Keywords index | Graphical
489 index | Full index
490 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
492GRASS 8.2.1 r.neighbors(1)