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 analyze neighborhood values (i.e.,
       the neighborhood function or operation to be performed), and  the  _s_i_z_e
       of  the	neighborhood.  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 quietly (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  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_._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 neighborhood.

       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	neigh-
	      borhood (rounded to the nearest integer).

       ssuumm    The sum of values within the neighborhood.

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

       ddiivveerrssiittyy
	      The number of different values within the neighborhood.  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  sur-
       rounding  any given cell fall into the neighborhood 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 current geographic region.  It is recom-
	      mended, 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  out-
       put  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, variance, 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 neighborhood 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_3_/_0_2_/_0_9 _1_2_:_0_7_:_2_3 _$



GRASS 5.0							r.neighbors(1)
