r.neighbors(1)	       Grass User's Manual	   r.neighbors(1)



NNAAMMEE
       rr..nneeiigghhbboorrss   -	Makes  each  cell value a function of the
       values assigned to the cells around  it,  and  stores  new
       cell values in an output raster map layer.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..nneeiigghhbboorrss
       rr..nneeiigghhbboorrss hheellpp
       rr..nneeiigghhbboorrss   [--aaqq]   iinnppuutt==_n_a_m_e  oouuttppuutt==_n_a_m_e  mmeetthhoodd==_n_a_m_e
       ssiizzee==_v_a_l_u_e [TTIITTLLEE==_"_p_h_r_a_s_e_"]

DDEESSCCRRIIPPTTIIOONN
       _r_._n_e_i_g_h_b_o_r_s 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  rr..nneeiigghhbboorrss
       on  the	command line, without program arguments.  In this
       case, the user will be  prompted  for  flag  settings  and
       parameter values.

OOPPTTIIOONNSS
       The  user  must specify the names of the raster map layers
       to be used for _i_n_p_u_t and _o_u_t_p_u_t, the _m_e_t_h_o_d used  to  ana-
       lyze  neighborhood values (i.e., the neighborhood function
       or operation to be performed), and the _s_i_z_e of the  neigh-
       borhood.   Optionally, the user can also specify the _T_I_T_L_E
       to be assigned to the raster map layer  _o_u_t_p_u_t,	elect  to
       not  align  the	resolution of the output with that of the
       input (the _-_a option), and elect to run	_r_._n_e_i_g_h_b_o_r_s  qui-
       etly (the _-_q option).  These options are described further
       below.


       _N_e_i_g_h_b_o_r_h_o_o_d _O_p_e_r_a_t_i_o_n _M_e_t_h_o_d_s_: The _n_e_i_g_h_b_o_r_h_o_o_d 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_._n_e_i_g_h_b_o_r_s
       can perform the following operations:



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

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

       mmooddee   The most frequently occurring value in  the  neigh-
	      borhood.

       mmiinniimmuumm
	      The minimum value within the neighborhood.

       mmaaxxiimmuumm
	      The maximum value within the neighborhood.

		     Raw Data	  Operation	New Data
		 ----------------	   ----------------
		 | 7  | 7  |  5 |	   |	|    |	  |
		 |----|----|----| average  |----|----|----|
		 | 4  | 7  |  4 |-------|    |	6 |    |
		 |----|----|----|	   |----|----|----|
		 | 7  | 6  |  4 |	   |	|    |	  |
		 |----|----|----|	   |----|----|----|


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

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

       ddiivveerrssiittyy
	      The number of different values within the neighbor-
	      hood.  In the above example, the diversity is 4.

       iinntteerrssppeerrssiioonn
	      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).  ERROR .RE


       _N_e_i_g_h_b_o_r_h_o_o_d  _S_i_z_e_:  The neighborhood size specifies which
       cells surrounding any given cell fall into  the	neighbor-
       hood  for  that	cell.	The  size must be an odd integer.
       Options are:  1, 3, 5, 7, 9, 11, 13, 15, 17, 19,  21,  23,
       and 25.	For example,

				     _ _ _
				    |_|_|_|
	   3 x 3 neighborhood -  |_|_|_|
				    |_|_|_|



       --aa     If specified, _r_._n_e_i_g_h_b_o_r_s will not align the output
	      raster map layer with that of the input raster  map
	      layer.   The  _r_._n_e_i_g_h_b_o_r_s program works in the cur-
	      rent 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_._n_e_i_g_h_b_o_r_s will align
	      these geographic region settings.

       --qq     If  specified,  _r_._n_e_i_g_h_b_o_r_s  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.


NNOOTTEESS
       The _r_._n_e_i_g_h_b_o_r_s 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_._n_e_i_g_h_b_o_r_s 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_._n_e_i_g_h_b_o_r_s  copies  the GRASS _c_o_l_o_r 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,  vari-
       ance,  diversity,  and  interspersion  are indices, rather
       than direct correspondents to input values, no _c_o_l_o_r files
       are  copied  for  these map layers.  (The user should note
       that although the _c_o_l_o_r file is copied for _a_v_e_r_a_g_ed neigh-
       borhood	function  output,  whether  or not the color file
       makes sense for the output will be dependent on the  input
       data values.)

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_l_u_m_p

       _r_._m_a_p_c_a_l_c

       _r_._m_a_s_k

       _r_._m_f_i_l_t_e_r

       _r_._s_u_p_p_o_r_t

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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_1_6 _0_5_:_1_3_:_2_2 _$



GRASS 5.0					   r.neighbors(1)
