Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
r.neighbors(1)		    GRASS GIS User's Manual		r.neighbors(1)

NAME
       r.neighbors   -	Makes each cell	category value a function of the cate-
       gory values assigned to the cells around	it, and	stores new cell	values
       in an output raster map layer.

KEYWORDS
       raster,	algebra,  statistics, aggregation, neighbor, focal statistics,
       filter

SYNOPSIS
       r.neighbors
       r.neighbors --help
       r.neighbors [-ac] input=name  [selection=name]	output=name[,name,...]
       [method=string[,string,...]]	   [size=integer]	[title=phrase]
       [weight=name]   [gauss=float]   [quantile=float[,float,...]]   [--over-
       write]  [--help]	 [--verbose]  [--quiet]	 [--ui]

   Flags:
       -a
	   Do not align	output with the	input

       -c
	   Use circular	neighborhood

       --overwrite
	   Allow output	files to overwrite existing files

       --help
	   Print usage summary

       --verbose
	   Verbose module output

       --quiet
	   Quiet module	output

       --ui
	   Force launching GUI dialog

   Parameters:
       input=nameA [required]
	   Name	of input raster	map

       selection=name
	   Name	 of  an	 input	raster map to select the cells which should be
	   processed

       output=name[,name,...]A [required]
	   Name	for output raster map

       method=string[,string,...]
	   Neighborhood	operation
	   Options: average, median, mode, minimum,  maximum,  range,  stddev,
	   sum,	 count,	 variance,  diversity,	interspersion, quart1, quart3,
	   perc90, quantile
	   Default: average

       size=integer
	   Neighborhood	size
	   Default: 3

       title=phrase
	   Title for output raster map

       weight=name
	   Text	file containing	weights

       gauss=float
	   Sigma (in cells) for	Gaussian filter

       quantile=float[,float,...]
	   Quantile to calculate for method=quantile
	   Options: 0.0-1.0

DESCRIPTION
       r.neighbors looks at each cell in a raster input	file, and examines the
       values assigned to the cells in some user-defined "neighborhood"	around
       it.  It outputs a new raster map	layer in which each cell is assigned a
       value  that  is	some  (user-specified)	function of the	values in that
       cell's neighborhood.  For example, each cell in the output layer	 might
       be assigned a value equal to the	average	of the values appearing	in its
       3 x 3 cell "neighborhood" in the	input layer. Note that the centre cell
       is also included	in the calculation.

   OPTIONS
       The user	must specify the names of the raster map layers	to be used for
       input and output, the method used to analyze neighborhood values	(i.e.,
       the  neighborhood  function or operation	to be performed), and the size
       of the neighborhood.

       The user	can optionally specify a selection map,	to compute new	values
       only  where the raster cells of the selection map are not NULL. In case
       of a NULL cells,	the values from	the input map are copied into the out-
       put  map.   This	 may  useful  to smooth	only parts of an elevation map
       (pits, peaks, ...).

       Example how to use a selection map with method=average:
       input map:
       1 1  1 1	1
       1 1  1 1	1
       1 1 10 1	1
       1 1  1 1	1
       1 1  1 1	1
       selection map, NULL values are marked as	*:
       * * * * *
       * * 1 * *
       * 1 1 1 *
       * * 1 * *
       * * * * *
       The output map:
       1 1 1 1 1
       1 1 2 1 1
       1 2 2 2 1
       1 1 2 1 1
       1 1 1 1 1
       Without using the selection map,	the output map would look like this:
       1 1 1 1 1
       1 2 2 2 1
       1 2 2 2 1
       1 2 2 2 1
       1 1 1 1 1

       Optionally, the user can	also specify the TITLE to be assigned  to  the
       raster  map layer output, elect to not align the	resolution of the out-
       put with	that of	the input (the -a option), and run r.neighbors with  a
       custom  matrix  weights	with the weight	option.	 These options are de-
       scribed further below.

       Neighborhood Operation Methods: The  neighborhood  operators  determine
       what  new value a center	cell in	a neighborhood will have after examin-
       ing values inside its neighboring cells.	 Each cell  in	a  raster  map
       layer  becomes  the  center  cell of a neighborhood as the neighborhood
       window moves from cell to cell throughout the map  layer.   r.neighbors
       can perform the following operations:

       average
	   The	average	value within the neighborhood.	In the following exam-
	   ple,	the result would be:
	   (7*4	+ 6 + 5	+ 4*3)/9 = 5.6667
	   The result is rounded to the	nearest	integer	(in this case 6).
	      Raw Data	   Operation	 New Data
	      +---+---+---+	     +---+---+---+
	      |	7 | 7 |	5 |	     |	 |   |	 |
	      +---+---+---+ average  +---+---+---+
	      |	4 | 7 |	4 |--------->|	 | 6 |	 |
	      +---+---+---+	     +---+---+---+
	      |	7 | 6 |	4 |	     |	 |   |	 |
	      +---+---+---+	     +---+---+---+

       median
	   The value found half-way through a list of the neighborhood's  val-
	   ues,	when these are ranged in numerical order.

       mode
	   The most frequently occurring value in the neighborhood.

       minimum
	   The minimum value within the	neighborhood.

       maximum
	   The maximum value within the	neighborhood.

       range
	   The range value within the neighborhood.

       stddev
	   The	statistical  standard deviation	of values within the neighbor-
	   hood	(rounded to the	nearest	integer).

       sum
	   The sum of values within the	neighborhood.

       count
	   The count of	filled (not NULL) cells.

       variance
	   The statistical variance of values within the neighborhood (rounded
	   to the nearest integer).

       diversity
	   The	number	of  different  values within the neighborhood.	In the
	   above example, the diversity	is 4.

       interspersion
	   The percentage of cells containing values  which  differ  from  the
	   values assigned to the center cell in the neighborhood, plus	1.  In
	   the above example, the interspersion	is:
	   5/8 * 100 + 1 = 63.5
	   The result is rounded to the	nearest	integer	(in this case 64).

       quart1, quart3
	   The result will be the first	or the third quartile (equal  of  25th
	   and 75th percentiles).

       perc90
	   The result will be the 90th percentile of neighborhood.

       quantile
	   Any quantile	as specified by	"quantile" input parameter.

       Neighborhood  Size:  The	 neighborhood  size specifies which cells sur-
       rounding	any given cell fall into the neighborhood for that cell.   The
       size  must  be an odd integer and represent the length of one of	moving
       window edges in cells.  For example, a size value of 3 will result in
				     _ _ _
				    |_|_|_|
	   3 x 3 neighborhood --->  |_|_|_|
				    |_|_|_|

       Matrix weights: A custom	matrix can be used if none of the neighborhood
       operation  methods are desirable	by using the weight.  This option must
       be used in conjunction with the size option to specify the matrix size.
       The  weights  desired are to be entered into a text file.  For example,
       to calculate the	focal mean with	a matrix size of 3,
       r.neigbors in=input.map out=output.map size=3 weight=weights.txt
       The contents of the weight.txt file:
       3 3 3
       1 4 8
       9 5 3
       This corresponds	to the following 3x3 matrix:
       +-+-+-+
       |3|3|3|
       +-+-+-+
       |1|4|8|
       +-+-+-+
       |9|5|3|
       +-+-+-+
       To calculate an annulus shaped neighborhood the contents	of  weight.txt
       file may	be e.g.	for size=5:
	0 1 1 1	0
	1 0 0 0	1
	1 0 0 0	1
	1 0 0 0	1
	0 1 1 1	0
       The  way	 that  weights	are  used  depends upon	the specific aggregate
       (method)	being used.  However, most of the aggregates have the property
       that multiplying	all of the weights by the same factor won't change the
       final result (an	exception is method=count).  Also, most	(if  not  all)
       of  them	 have the properties that an integer weight of N is equivalent
       to N occurrences	of the cell value, and having all weights equal	to one
       produces	 the  same  result as when weights are not used.  When weights
       are used, the calculation for method=average is:
	 sum(w[i]*x[i])	/ sum(w[i])
       In the case where all weights are zero, this will end up	with both  the
       numerator and denominator to zero, which	produces a NULL	result.

   FLAGS
       -a
	   If  specified,  r.neighbors	will  not  align the output raster map
	   layer with that of the input	raster	map  layer.   The  r.neighbors
	   program works in the	current	geographic region.  It is recommended,
	   but not required, that the resolution of the	geographic  region  be
	   the	same as	that of	the raster map layer.  By default, if unspeci-
	   fied, r.neighbors will align	these geographic region	settings.

       -c
	   This	flag will use a	circular neighborhood for the moving  analysis
	   window, centered on the current cell.

       The exact masks for the first few neighborhood sizes are	as follows:
       3x3     . X .	   5x5	. . X .	. 7x7  . . . X . . .
	       X O X		. X X X	.      . X X X X X .
	       . X .		X X O X	X      . X X X X X .
			   . X X X .	  X X X	O X X X
			   . . X . .	  . X X	X X X .
					  . X X	X X X .
					  . . .	X . . .
       9x9  . .	. . X .	. . .	     11x11   . . . . . X . . . . .
	    . .	X X X X	X . .		  . . X	X X X X	X X . .
	       . X X X X X X X .	       . X X X X X X X X X .
	       . X X X X X X X .	       . X X X X X X X X X .
	       X X X X O X X X X	       . X X X X X X X X X .
	       . X X X X X X X .	       X X X X X O X X X X X
	       . X X X X X X X .	       . X X X X X X X X X .
	       . . X X X X X . .	       . X X X X X X X X X .
	       . . . . X . . . .	       . X X X X X X X X X .
				     . . X X X X X X X . .
				     . . . . . X . . . . .

NOTES
       The r.neighbors program works in	the current geographic region with the
       current mask, if	any.  It is recommended, but not  required,  that  the
       resolution  of  the geographic region be	the same as that of the	raster
       map layer.  By default, r.neighbors will	align these geographic	region
       settings.  However, the user can	select to keep original	input and out-
       put resolutions which are not aligned by	specifying this	 (e.g.,	 using
       the -a option).

       r.neighbors  doesn't  propagate	NULLs, but computes the	aggregate over
       the non-NULL cells in the neighborhood.

       The -c flag and the weights parameter are mutually exclusive.  Any  use
       of the two together will	produce	an error. Differently-shaped neighbor-
       hood analysis windows may be achieved by	using the weight= parameter to
       specify	a  weights  file where all values are equal. The user can also
       vary the	weights	at the edge of the neighborhood	according to the  pro-
       portion	of  the	 cell that lies	inside the neighborhood	circle,	effec-
       tively anti-aliasing the	analysis mask.

       For aggregates where a weighted calculation isn't meaningful  (specifi-
       cally:  minimum,	maximum, diversity and interspersion), the weights are
       used to create a	binary mask, where zero	causes the cell	to be  ignored
       and any non-zero	value causes the cell to be used.

       r.neighbors  copies  the	 GRASS	color  files associated	with the input
       raster map layer	for those output map layers  that  are	based  on  the
       neighborhood  average,  median,	mode,  minimum,	 and maximum.  Because
       standard	deviation, variance, diversity,	and interspersion are indices,
       rather  than  direct correspondents to input values, no color files are
       copied for these	map layers.  (The user should note that	 although  the
       color  file is copied for average neighborhood function output, whether
       or not the color	file makes sense for the output	will be	 dependent  on
       the input data values.)

   Propagation of output precision
       The  following logic has	been implemented: For any aggregate, there are
       two factors affecting the output	type:

       1      Whether the input	map is integer or floating-point.

       2      Whether the weighted or unweighted version of the	 aggregate  is
	      used.

       These combine to	create four possibilities:

       input type/weight					    integer							 float

       no							    yes								 no							      yes

       average							    float							 float							      float							   float

       median							    [1]								 [1]							      float							   float

       mode							    integer							 integer						      [2]							   [2]

       minimum							    integer							 integer						      float							   float

       maximum							    integer							 integer						      float							   float

       range							    integer							 integer						      float							   float

       stddev							    float							 float							      float							   float

       sum							    integer							 float							      float							   float

       count							    integer							 float							      integer							   float

       variance							    float							 float							      float							   float

       diversity						    integer							 integer						      integer							   integer

       interspersion						    integer							 integer						      integer							   integer

       quart1							    [1]								 [1]							      float							   float

       quart3							    [1]								 [1]							      float							   float

       perc90							    [1]								 [1]							      float							   float

       quantile							    [1]								 [1]							      float							   float

       [1]  For	integer	input, quantiles may produce float results from	inter-
       polating	between	adjacent values.
       [2] Calculating the mode	of floating-point data is essentially meaning-
       less.

       With the	current	aggregates, there are 5	cases:

       1      Output  is  always  float:  average, variance, stddev, quantiles
	      (with interpolation).

       2      Output is	always integer:	diversity, interspersion.

       3      Output is	integer	if unweighted, float if	weighted: count.

       4      Output matches input: minimum, maximum, range, mode (subject  to
	      note 2 above), quantiles (without	interpolation).

       5      Output  is  integer  for integer input and unweighted aggregate,
	      otherwise	float: sum.

EXAMPLES
   Measure occupancy of	neighborhood
       Set up 10x10 computational region to aid	visual inspection of results
       g.region	rows=10	cols=10
       Fill 50%	of computational region	with randomly  located	cells.	 "dis-
       tance=0"	will allow filling adjacent cells.
       r.random.cells output=random_cells distance=0 ncells=50
       Count non-empty (not NULL) cells	in 3x3 neighborhood
       r.neighbors input=random_cells output=counts method=count
       Optionally - exclude centre cell	from the count (= only look around)
       r.mapcalc "cound_around = if( isnull(random_cells), counts, counts - 1)"

SEE ALSO
       g.region
       r.clump
       r.mapcalc
       r.mfilter
       r.statistics
       r.support

AUTHORS
       Original	 version:  Michael  Shapiro, U.S.Army Construction Engineering
       Research	Laboratory
       Updates for GRASS GIS 7 by Glynn	Clements and others

SOURCE CODE
       Available at: r.neighbors source	code (history)

       Main index | Raster index | Topics index	| Keywords index  |  Graphical
       index | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.4 Reference	Manual

GRASS 7.8.4							r.neighbors(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLES | SEE ALSO | AUTHORS | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=r.neighbors&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help