Provided by: grass-doc_6.4.3-3_all bug

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, statistics

SYNOPSIS

       r.neighbors
       r.neighbors help
       r.neighbors    [-aqc]    input=name    output=name     [method=string]      [size=integer]
       [title="phrase"]   [weight=string]   [gauss=float]   [--overwrite]  [--verbose]  [--quiet]

   Flags:
       -a
           Do not align output with the input

       -q
           Run quietly

       -c
           Use circular neighborhood

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=name
           Name of input raster map

       output=name
           Name for output raster map

       method=string
           Neighborhood operation
           Options:
           average,median,mode,minimum,maximum,range,stddev,sum,variance,diversity,interspersion
           Default: average

       size=integer
           Neighborhood size
           Default: 3

       title=
           Title of the output raster map

       weight=string
           File containing weights

       gauss=float
           Sigma (in cells) for Gaussian filter

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.

       The  program  will  be  run non-interactively if the user specifies program arguments (see
       OPTIONS) on the command line.  Alternately, the user can simply type  r.neighbors  on  the
       command line, without program arguments.  In this case, the user will be prompted for flag
       settings and parameter values.

   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.  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 output with that of the input (the -a option), run r.neighbors  with
       a  custom matrix weights with the weight option, and elect to run r.neighbors quietly (the
       -q option).  These options are described further below.

       Neighborhood Operation Methods: The neighborhood operators  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.neighbors can
       perform the following operations:

       average
              The average value within the neighborhood.  In the following  example,  the  result
              would be:
              (7*4 + 6 + 5 + 4*3)/9 = 5.66
              The result is rounded to the nearest integer (in this case 6).

       median
              The  value  found  half-way through a list of the neighborhood's values, 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.
                     Raw Data     Operation     New Data
                 ----------------          ----------------
                 | 7  | 7  |  5 |          |    |    |    |
                 |----|----|----| average  |----|----|----|
              |    |  6 |    |
                 |----|----|----|          |----|----|----|
                 | 7  | 6  |  4 |          |    |    |    |
                 |----|----|----|          |----|----|----|

       range
              The range value within the neighborhood.

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

       sum
              The sum of values within the neighborhood.

       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).

       Neighborhood Size:
       The  neighborhood  size  specifies  which  cells  surrounding any given cell fall into the
       neighborhood for that cell.  The size must be an odd integer.  For example,
                                     _ _ _
                                    |_|_|_|
         |_|_|_|
                                    |_|_|_|

       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|
           -------

   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
              unspecified, 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 . . . . .

       -q
              If specified, r.neighbors will run relatively quietly (i.e.,  without  printing  to
              standard output notes on the program's progress).  If unspecified, the program will
              print messages to standard output by default.

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 elect to keep original input and output
       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 neighborhood 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  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.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.)

SEE ALSO

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

AUTHOR

       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

       Last changed: $Date: 2010-09-21 05:53:31 -0700 (Tue, 21 Sep 2010) $

       Full index

       © 2003-2013 GRASS Development Team