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
13

SYNOPSIS

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
22   Flags:
23       -a
24           Do not align output with the input
25
26       -c
27           Use circular neighborhood
28
29       --overwrite
30           Allow output files to overwrite existing files
31
32       --help
33           Print usage summary
34
35       --verbose
36           Verbose module output
37
38       --quiet
39           Quiet module output
40
41       --ui
42           Force launching GUI dialog
43
44   Parameters:
45       input=name [required]
46           Name of input raster map
47
48       selection=name
49           Name  of  an  input  raster map to select the cells which should be
50           processed
51
52       output=name[,name,...] [required]
53           Name for output raster map
54
55       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
62       size=integer
63           Neighborhood size
64           Default: 3
65
66       title=phrase
67           Title for output raster map
68
69       weight=name
70           Text file containing weights
71
72       gauss=float
73           Sigma (in cells) for Gaussian filter
74
75       quantile=float[,float,...]
76           Quantile to calculate for method=quantile
77           Options: 0.0-1.0
78

DESCRIPTION

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
89   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
95       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
101       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
127       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
133       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
140       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
154       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
158       mode
159           The most frequently occurring value in the neighborhood.
160
161       minimum
162           The minimum value within the neighborhood.
163
164       maximum
165           The maximum value within the neighborhood.
166
167       range
168           The range value within the neighborhood.
169
170       stddev
171           The  statistical  standard deviation of values within the neighbor‐
172           hood (rounded to the nearest integer).
173
174       sum
175           The sum of values within the neighborhood.
176
177       count
178           The count of filled (not NULL) cells.
179
180       variance
181           The statistical variance of values within the neighborhood (rounded
182           to the nearest integer).
183
184       diversity
185           The  number  of  different  values within the neighborhood.  In the
186           above example, the diversity is 4.
187
188       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
195       quart1, quart3
196           The result will be the first or the third quartile (equal  of  25th
197           and 75th percentiles).
198
199       perc90
200           The result will be the 90th percentile of neighborhood.
201
202       quantile
203           Any quantile as specified by "quantile" input parameter.
204
205       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
214       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
251   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
260       -c
261           This flag will use a circular neighborhood for the moving  analysis
262           window, centered on the current cell.
263
264       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

NOTES

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
293       r.neighbors  doesn’t  propagate  NULLs, but computes the aggregate over
294       the non-NULL cells in the neighborhood.
295
296       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
304       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
309       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
319   Propagation of output precision
320       The  following logic has been implemented: For any aggregate, there are
321       two factors affecting the output type:
322
323       1      Whether the input map is integer or floating-point.
324
325       2      Whether the weighted or unweighted version of the  aggregate  is
326              used.
327
328       These combine to create four possibilities:
329
330       input type/weight                                            integer                                                      float
331
332       no                                                           yes                                                          no                                                           yes
333
334       average                                                      float                                                        float                                                        float                                                        float
335
336       median                                                       [1]                                                          [1]                                                          float                                                        float
337
338       mode                                                         integer                                                      integer                                                      [2]                                                          [2]
339
340
341
342       minimum                                                      integer                                                      integer                                                      float                                                        float
343
344       maximum                                                      integer                                                      integer                                                      float                                                        float
345
346       range                                                        integer                                                      integer                                                      float                                                        float
347
348       stddev                                                       float                                                        float                                                        float                                                        float
349
350       sum                                                          integer                                                      float                                                        float                                                        float
351
352       count                                                        integer                                                      float                                                        integer                                                      float
353
354       variance                                                     float                                                        float                                                        float                                                        float
355
356       diversity                                                    integer                                                      integer                                                      integer                                                      integer
357
358       interspersion                                                integer                                                      integer                                                      integer                                                      integer
359
360       quart1                                                       [1]                                                          [1]                                                          float                                                        float
361
362       quart3                                                       [1]                                                          [1]                                                          float                                                        float
363
364       perc90                                                       [1]                                                          [1]                                                          float                                                        float
365
366       quantile                                                     [1]                                                          [1]                                                          float                                                        float
367
368
369       [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
374       With the current aggregates, there are 5 cases:
375
376       1      Output  is  always  float:  average, variance, stddev, quantiles
377              (with interpolation).
378
379       2      Output is always integer: diversity, interspersion.
380
381       3      Output is integer if unweighted, float if weighted: count.
382
383       4      Output matches input: minimum, maximum, range, mode (subject  to
384              note 2 above), quantiles (without interpolation).
385
386       5      Output  is  integer  for integer input and unweighted aggregate,
387              otherwise float: sum.
388

EXAMPLES

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

SEE ALSO

402       g.region
403       r.clump
404       r.mapcalc
405       r.mfilter
406       r.statistics
407       r.support
408

AUTHORS

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

SOURCE CODE

415       Available at: r.neighbors source code (history)
416
417       Main index | Raster index | Topics index | Keywords index  |  Graphical
418       index | Full index
419
420       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
421
422
423
424GRASS 7.8.5                                                     r.neighbors(1)
Impressum