1r.neighbors(1)              GRASS GIS User's Manual             r.neighbors(1)
2
3
4

NAME

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

KEYWORDS

11       raster,  algebra,  statistics, aggregation, neighbor, focal statistics,
12       filter, parallel
13

SYNOPSIS

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
24   Flags:
25       -a
26           Do not align output with the input
27
28       -c
29           Use circular neighborhood
30
31       --overwrite
32           Allow output files to overwrite existing files
33
34       --help
35           Print usage summary
36
37       --verbose
38           Verbose module output
39
40       --quiet
41           Quiet module output
42
43       --ui
44           Force launching GUI dialog
45
46   Parameters:
47       input=name [required]
48           Name of input raster map
49
50       selection=name
51           Name  of  an  input  raster map to select the cells which should be
52           processed
53
54       output=name[,name,...] [required]
55           Name for output raster map
56
57       size=integer
58           Neighborhood size
59           Default: 3
60
61       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
68       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
77       weighting_factor=float
78           Factor used in the selected weighting function  (ignored  for  none
79           and file)
80
81       weight=name
82           Text file containing weights
83
84       quantile=float[,float,...]
85           Quantile to calculate for method=quantile
86           Options: 0.0-1.0
87
88       title=phrase
89           Title for output raster map
90
91       nprocs=integer
92           Number of threads for parallel computing
93           Default: 1
94
95       memory=memory in MB
96           Maximum memory to be used (in MB)
97           Cache size for raster rows
98           Default: 300
99

DESCRIPTION

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
110       Figure: Illustration for an 3x3 average neighborhood
111
112   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
118       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
124       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
150       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
154       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
158       Alternatively,  gaussian and exponential weighting functions can be se‐
159       lected as weighting function.
160
161       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
167       exp(-(x*x+y*y)/(2*σ^2))/(2*π*σ^2)
168
169       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
173       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
178       exp(factor*sqrt(x*x+y*y))
179
180       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
184       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
189       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
196       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
210       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
214       mode
215           The most frequently occurring value in the neighborhood.
216
217       minimum
218           The minimum value within the neighborhood.
219
220       maximum
221           The maximum value within the neighborhood.
222
223       range
224           The range value within the neighborhood.
225
226       stddev
227           The  statistical  standard deviation of values within the neighbor‐
228           hood (rounded to the nearest integer).
229
230       sum
231           The sum of values within the neighborhood.
232
233       count
234           The count of filled (not NULL) cells.
235
236       variance
237           The statistical variance of values within the neighborhood (rounded
238           to the nearest integer).
239
240       diversity
241           The  number  of  different  values within the neighborhood.  In the
242           above example, the diversity is 4.
243
244       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
251       quart1, quart3
252           The result will be the first or the third quartile (equal  of  25th
253           and 75th percentiles).
254
255       perc90
256           The result will be the 90th percentile of neighborhood.
257
258       quantile
259           Any quantile as specified by "quantile" input parameter.
260
261       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
270       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
309   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
318       -c
319           This  flag will use a circular neighborhood for the moving analysis
320           window, centered on the current cell.
321
322       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

NOTES

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
351       r.neighbors doesn’t propagate NULLs, but computes  the  aggregate  over
352       the non-NULL cells in the neighborhood.
353
354       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
362       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
367       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
377   Propagation of output precision
378       The following logic has been implemented: For any aggregate, there  are
379       two factors affecting the output type:
380
381       1      Whether the input map is integer or floating-point.
382
383       2      Whether  the  weighted or unweighted version of the aggregate is
384              used.
385
386       These combine to create four possibilities:
387
388       input type/weight                                            integer                                                      float
389
390       no                                                           yes                                                          no                                                           yes
391
392       average                                                      float                                                        float                                                        float                                                        float
393
394       median                                                       [1]                                                          [1]                                                          float                                                        float
395
396
397
398       mode                                                         integer                                                      integer                                                      [2]                                                          [2]
399
400       minimum                                                      integer                                                      integer                                                      float                                                        float
401
402       maximum                                                      integer                                                      integer                                                      float                                                        float
403
404       range                                                        integer                                                      integer                                                      float                                                        float
405
406       stddev                                                       float                                                        float                                                        float                                                        float
407
408       sum                                                          integer                                                      float                                                        float                                                        float
409
410       count                                                        integer                                                      float                                                        integer                                                      float
411
412       variance                                                     float                                                        float                                                        float                                                        float
413
414       diversity                                                    integer                                                      integer                                                      integer                                                      integer
415
416       interspersion                                                integer                                                      integer                                                      integer                                                      integer
417
418       quart1                                                       [1]                                                          [1]                                                          float                                                        float
419
420       quart3                                                       [1]                                                          [1]                                                          float                                                        float
421
422       perc90                                                       [1]                                                          [1]                                                          float                                                        float
423
424       quantile                                                     [1]                                                          [1]                                                          float                                                        float
425
426
427       [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
432       With the current aggregates, there are 5 cases:
433
434       1      Output is always float:  average,  variance,  stddev,  quantiles
435              (with interpolation).
436
437       2      Output is always integer: diversity, interspersion.
438
439       3      Output is integer if unweighted, float if weighted: count.
440
441       4      Output  matches input: minimum, maximum, range, mode (subject to
442              note 2 above), quantiles (without interpolation).
443
444       5      Output is integer for integer input  and  unweighted  aggregate,
445              otherwise float: sum.
446
447   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
459       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

EXAMPLES

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

SEE ALSO

476        g.region, r.clump, r.mapcalc, r.mfilter, r.statistics, r.support
477

AUTHORS

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

SOURCE CODE

484       Available at: r.neighbors source code (history)
485
486       Accessed: Mon Jun 20 16:46:12 2022
487
488       Main  index  | Raster index | Topics index | Keywords index | Graphical
489       index | Full index
490
491       © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
492
493
494
495GRASS 8.2.0                                                     r.neighbors(1)
Impressum