Provided by: grass-doc_7.8.2-1build3_all

**NAME**

r.neighbors- Makes each cell category value a function of the category 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.neighborsr.neighbors--helpr.neighbors[-ac]input=name[selection=name]output=name[,name,...] [method=string[,string,...]] [size=integer] [title=phrase] [weight=name] [gauss=float] [quantile=float[,float,...]] [--overwrite] [--help] [--verbose] [--quiet] [--ui]Flags:-aDo not align output with the input-cUse circular neighborhood--overwriteAllow output files to overwrite existing files--helpPrint usage summary--verboseVerbose module output--quietQuiet module output--uiForce launching GUI dialogParameters:input=name[required]Name of input raster mapselection=nameName of an input raster map to select the cells which should be processedoutput=name[,name,...][required]Name for output raster mapmethod=string[,string,...] Neighborhood operation Options:average,median,mode,minimum,maximum,range,stddev,sum,count,variance,diversity,interspersion,quart1,quart3,perc90,quantileDefault:averagesize=integerNeighborhood size Default:3title=phraseTitle for output raster mapweight=nameText file containing weightsgauss=floatSigma (in cells) for Gaussian filterquantile=float[,float,...] Quantile to calculate for method=quantile Options:0.0-1.0

**DESCRIPTION**

r.neighborslooks 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.OPTIONSThe user must specify the names of the raster map layers to be used forinputandoutput, themethodused to analyze neighborhood values (i.e., the neighborhood function or operation to be performed), and thesizeof the neighborhood. The user can optionally specify aselectionmap, 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 output map. This may useful to smooth only parts of an elevation map (pits, peaks, ...).Examplehowtouseaselectionmapwithmethod=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 theTITLEto be assigned to the raster map layeroutput, elect to not align the resolution of the output with that of the input (the-aoption), and runr.neighborswith a custom matrix weights with theweightoption. These options are described further below.NeighborhoodOperationMethods:Theneighborhoodoperators determine what new value a center cell in a neighborhood will have after examining 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.neighborscan perform the following operations:averageThe average value within the neighborhood. In the following example, 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 | | | | | +---+---+---+ +---+---+---+medianThe value found half-way through a list of the neighborhood’s values, when these are ranged in numerical order.modeThe most frequently occurring value in the neighborhood.minimumThe minimum value within the neighborhood.maximumThe maximum value within the neighborhood.rangeThe range value within the neighborhood.stddevThe statistical standard deviation of values within the neighborhood (rounded to the nearest integer).sumThe sum of values within the neighborhood.countThe count of filled (not NULL) cells.varianceThe statistical variance of values within the neighborhood (rounded to the nearest integer).diversityThe number of different values within the neighborhood. In the above example, the diversity is 4.interspersionThe 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,quart3The result will be the first or the third quartile (equal of 25th and 75th percentiles).perc90The result will be the 90th percentile of neighborhood.quantileAny quantile as specified by "quantile" input parameter.NeighborhoodSize:The neighborhoodsizespecifies which cells surrounding any given cell fall into the neighborhood for that cell. Thesizemust 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 ---> |_|_|_| |_|_|_|Matrixweights:A custom matrix can be used if none of the neighborhood operation methods are desirable by using theweight. This option must be used in conjunction with thesizeoption 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 matrixsizeof 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 ismethod=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 formethod=averageis: 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-aIf specified,r.neighborswill not align the output raster map layer with that of the input raster map layer. Ther.neighborsprogram 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 unspecified,r.neighborswill align these geographic region settings.-cThis 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**

Ther.neighborsprogram 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.neighborswill align these geographic region settings. However, the user can select to keep original input and output resolutions which are not aligned by specifying this (e.g., using the-aoption).r.neighborsdoesn’t propagate NULLs, but computes the aggregate over the non-NULL cells in the neighborhood. The-cflag and theweightsparameter are mutually exclusive. Any use of the two together will produce an error. Differently-shaped neighborhood analysis windows may be achieved by using theweight=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 proportion of the cell that lies inside the neighborhood circle, effectively anti-aliasing the analysis mask. For aggregates where a weighted calculation isn’t meaningful (specifically: 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.neighborscopies the GRASScolorfiles 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, nocolorfiles are copied for these map layers. (The user should note that although thecolorfile is copied foraverageneighborhood function output, whether or not the color file makes sense for the output will be dependent on the input data values.)PropagationofoutputprecisionThe following logic has been implemented: For any aggregate, there are two factors affecting the output type:1Whether the input map is integer or floating-point.2Whether 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 interpolating between adjacent values. [2] Calculating the mode of floating-point data is essentially meaningless. With the current aggregates, there are 5 cases:1Output is always float: average, variance, stddev, quantiles (with interpolation).2Output is always integer: diversity, interspersion.3Output is integer if unweighted, float if weighted: count.4Output matches input: minimum, maximum, range, mode (subject to note 2 above), quantiles (without interpolation).5Output is integer for integer input and unweighted aggregate, otherwise float: sum.

**EXAMPLES**

MeasureoccupancyofneighborhoodSet 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. "distance=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.regionr.clumpr.mapcalcr.mfilterr.statisticsr.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 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual