m.clump(1)	       Grass User's Manual	       m.clump(1)



NNAAMMEE
       _m_._c_l_u_m_p - Aggregates point data into clusters of like data
       using a Voronoi tesselation.

SSYYNNOOPPSSIISS
       mm..cclluummpp

       mm..cclluummpp hheellpp

       mm..cclluummpp	  [[--rrqq]]    iinnppuutt_=_n_a_m_e	 oouuttppuutt_=_n_a_m_e	[ffss_=_c_h_a_r]
       [aattttrriibbuutteess_=_f_i_e_l_d_#_[_,_f_i_e_l_d_#_,_._._._]] 	 [bbaarrrriieerrss_=_v_e_c_t_o_r
       _f_i_l_e_[_,_v_e_c_t_o_r_f_i_l_e_,_._._._]]

DDEESSCCRRIIPPTTIIOONN
       _m_._c_l_u_m_p clusters points together based on points'  proxim-
       ity,  point  attributes, and the presence of physical con-
       straints (vector barriers)  dividing  such  clusters.   It
       first  triangulates the points using a Voronoi tesselation
       to determine the proximity of points to one another.  Con-
       nections among points are maintained where adjacent points
       have same attribute values; connections are  broken  where
       adjacent   points   have  different  values  for  a  given
       attribute (field).  Connections	between  adjacent  points
       will  also  be broken where points fall on different sides
       of arcs in user-specified vector maps.

OOPPTTIIOONNSS
       The user can run the program by specifying input and  out-
       put  file  names  and  any  desired options on the command
       line, using the form:


       _m_._c_l_u_m_p	  _[_-_r_q_]    _i_n_p_u_t_=_n_a_m_e	 _o_u_t_p_u_t_=_n_a_m_e	_[_f_s_=_c_h_a_r_]
       _[_a_t_t_r_i_b_u_t_e_s_=_f_i_e_l_d_#_[_,_f_i_e_l_d_#_,_._._._]_] 	_[_b_a_r_r_i_e_r_s_=_v_e_c_t_o_r_-
       _f_i_l_e_[_,_v_e_c_t_o_r_f_i_l_e_,_._._._]_]


       where parameters and flags have the meanings given  below.

   FFllaaggss::
       --rr     Only  process  points  in  the input file that fall
	      within the user's current geographic region.

       --qq     Run quietly (without sending  comments  on  program
	      progress to stdout).


   PPaarraammeetteerrss::
       iinnppuuttnnaammee
	      Name of an existing file containing, minimally, the
	      easting and northing of the  points  to  be  formed
	      into  clusters, and having the format given in sec-
	      tion "INPUT FILE FORMAT".

       oouuttppuuttnnaammee
	      Name to be assigned the  file  to  contain  program
	      output.	Output	will have the format specified in
	      section "OUTPUT FILE FORMAT".

       ffsscchhaarraacctteerr
	      A single character, specifying the field	separator
	      used  in	the  input  file (also used in the output
	      file).  The default delimiter used, if unspecified,
	      is any white space.

       aattttrriibbuutteessffiieelldd##[[,,ffiieelldd##,,......]]
	      One  or more attributes to be compared in the input
	      file, to determine which	data  points  are  to  be
	      grouped.	This is a list of field numbers (columns)
	      in the input file which are to be used when forming
	      clumps.	Different  points  which  do not have the
	      same attributes in all  fields  specified  will  be
	      placed  in  distinct  clumps.   Fields are numbered
	      starting with 1.	(For example, the x,y coordinates
	      are in fields 1 and 2 respectively.)

       bbaarrrriieerrssvveeccttoorrffiillee[[,,vveeccttoorrffiillee,,......]]
	      One  or  more vector files to constrain points from
	      joining the same clump.	Points	which  appear  on
	      different  sides	of  any  line  or area edges in a
	      user-specified vectorfile will be  placed  in  dis-
	      tinct clumps in the output file.


IINNPPUUTT FFIILLEE FFOORRMMAATT
       Each line of the input file minimally should have the for-
       mat:


       _x_,_y_[_,_t_e_x_t_,_t_e_x_t_,_._._._]


       The input file is required only to contain the easting (x)
       and  northing  (y)  values for each point, unless the user
       has specified use of the attributes parameter.  The  field
       delimiter  (indicated here by a comma) between x and y and
       between y and text can be any single character  as  speci-
       fied  by  the  'fs'  parameter.	 The default delimiter is
       white space if 'fs' is  not  specified.	 Additional  data
       fields  (columns)  may  also be present in the input file,
       and will be preserved in the output.


       Leading spaces in the  input  are  automatically  removed.
       Blanks lines and lines starting with # are treated as com-
       ment and ignored.

OOUUTTPPUUTT FFIILLEE FFOORRMMAATT
       The output file has the general format:



		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]

		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]
		      x,y[,text,text,...]

		      x,y[,text,text,...]

       The comma here represents the field delimiter and will  be
       the  same  character as the delimiter specified to be used
       in the input file.


       The output format is structured.  Lines with  the  'x'  at
       the left margin are the original input points.  Lines with
       the 'x' indented one space are the points that are 'neigh-
       bors' of the non-indented point.  Empty lines indicate the
       end of a clump.


       Clumps are groups of points either or both: (1) having the
       same attribute(s) values in the data field(s) specified by
       the user with the attributes parameter, and/or (2) falling
       within polygons formed by the vector barriers specified by
       the user with the barriers parameter.

EEXXAAMMPPLLEESS
       In the following example the  comma-delimited  input  file
       treepecker is of the form:

		     #	  x,y,treeid,treespp,woodpeckersuit,wood-
       peckeruse
		     432222.22,4651095.23,8074,loblolly
       pine,high,0
		     432618.65,4651156.30,8075,loblolly
       pine,medium,0
		     432702.67,4651169.82,8076,sugar maple,low,0
		     432702.63,4651165.72,8077,loblolly
       pine,high,1
		     432702.57,4651159.61,8078,loblolly
       pine,high,1
		     432702.79,4651173.82,8079,loblolly
       pine,high,1
		     432177.53,4651072.01,8080,peach,low,0
		     432181.50,4650466.25,8081,loblolly
       pine,high,0
		     432169.82,4650466.03,8082,loblolly
       pine,low,0
		     432235.76,4650467.18,8083,loblolly
       pine,high,1
		     432274.53,4650467.81,8084,loblolly
       pine,medium,1
		     432216.47,4650225.19,8085,loblolly
       pine,medium,0
		     432381.46,4651077.28,8086,loblolly
       pine,low,1
		     432640.08,4651005.86,8087,loblolly
       pine,low,0
		     432972.11,4651095.98,8088,loblolly
       pine,high,1

       where:

		     field 1 = x (easting)
		     field 2 = y (northing)
		     field 3 = tree identification number
		     field 4 = tree species
		     field  5  = suitability for use as red-cock-
       aded woodpecker habitat
		     field 6 =	current  red-cockaded  woodpecker
       nesting site

       Assume  constraints imposed on clustering include a vector
       map of roadways and a vector map of waterways.	The  fol-
       lowing  command	will  produce an output file in which all
       trees  having  both  the  same  suitability  for  use   as
       wookpecker  habitat  and  the  same  nesting  use  status,
       bounded by roads and waterways, will appear as clusters of
       points in the output.


       _m_._c_l_u_m_p	 _i_n_p_u_t_=_t_r_e_e_p_e_c_k_e_r  _o_u_t_p_u_t_=_t_r_e_e_p_e_c_k_e_r_._c_l_u_m_p_s  _f_s_=_,
       _a_t_t_r_i_b_u_t_e_s_=_5_,_6 _b_a_r_r_i_e_r_s_=_r_o_a_d_s_,_w_a_t_e_r_s


       In this case, program output might look like:

		     432222.22,4651095.23,8074,loblolly
       pine,high,0

		     432618.65,4651156.30,8075,loblolly
       pine,medium,0

		     432702.67,4651169.82,8076,sugar maple,low,0

		     432702.63,4651165.72,8077,loblolly
       pine,high,1
		      432972.11,4651095.98,8088,loblolly
       pine,high,1
		      432702.57,4651159.61,8078,loblolly
       pine,high,1
		     432972.11,4651095.98,8088,loblolly
       pine,high,1
		      432702.79,4651173.82,8079,loblolly
       pine,high,1
		      432702.63,4651165.72,8077,loblolly
       pine,high,1
		      432702.57,4651159.61,8078,loblolly
       pine,high,1
		     432702.79,4651173.82,8079,loblolly
       pine,high,1
		      432972.11,4651095.98,8088,loblolly
       pine,high,1
		     432702.57,4651159.61,8078,loblolly
       pine,high,1
		      432972.11,4651095.98,8088,loblolly
       pine,high,1
		      432702.63,4651165.72,8077,loblolly
       pine,high,1

		     432177.53,4651072.01,8080,peach,low,0
		      432169.82,4650466.03,8082,loblolly
       pine,low,0
		     432169.82,4650466.03,8082,loblolly
       pine,low,0
		      432177.53,4651072.01,8080,peach,low,0

		     432181.50,4650466.25,8081,loblolly
       pine,high,0

		     432235.76,4650467.18,8083,loblolly
       pine,high,1

		     432274.53,4650467.81,8084,loblolly
       pine,medium,1

		     432216.47,4650225.19,8085,loblolly
       pine,medium,0

		     432381.46,4651077.28,8086,loblolly
       pine,low,1

		     432640.08,4651005.86,8087,loblolly
       pine,low,0


UUTTIILLIITTIIEESS
       The user can display program output  using  GRASS  display
       functions  like	_d_._m_a_p_g_r_a_p_h  and  _d_._p_o_i_n_t_s.  The following
       Bourne shell script allows the user to graph the  cluster-
       ing of points output by _m_._c_l_u_m_p.

			  : ${GISRC?}
			  file=
			  label=0
			  for arg
			  do
			      case "$arg" in
				   fs=*)    F=-F"`echo	 $arg|sed
       s/fs=//`";;
				 label=*) eval $arg ;;
				 file=*) eval $arg;;
				 *)
				  echo	  "Usage:    $0    [fs=c]
       file=filename [label=#]" >& 2
				  exit 1
				  ;;
			      esac
			  done
			  if [ "$file" = "" ]
			  then
			      echo  "Usage:  $0 [fs=c] file=file-
       name [label=#]" >& 2
			      exit 1
			  fi

			  awk "$F" "BEGIN {label=$label}"'
			  NF == 0 {next}
			  /^ / {next}
			       {if (label!=0) print $1,$2,$label
				else print $1,$2}
			  ' $file | d.points size=10

			  awk "$F" '
			  NF == 0 {next}
			  /^ /{  print	"move",east,north;  print
       "draw",$1,$2; next}
			      { east=$1; north=$2}
			  ' $file | d.mapgraph color=red


NNOOTTEESS
       If  the user specifies neither 'attributes' nor 'barriers'
       parameters, the resultant output file will have	only  one
       clump  (because	there  will  be no basis for breaking any
       proximity connections among points).


       Input lines that _m_._c_l_u_m_p doesn't understand  are  ignored.
       This  means that if a line in the input file is not a com-
       ment but doesn't have (or doesn't appear to have)  an  x,y
       coordinate-pair	as its first two fields, the line will be
       ignored.  The most common cause of ignored lines  will  be
       user  error (e.g., the user's failure to specify the input
       file field separator).  If unrecognized lines in the input
       file  exist,  _m_._c_l_u_m_p  will  print one message (to stderr)
       noting that some unrecognized lines were found.

BBUUGGSS
       Input lines which are longer that 4095 characters will  be
       silently  truncated.   Fields  which  are longer than 1023
       characters will probably cause _m_._c_l_u_m_p to  core	dump  (at
       best) or to produce invalid results (not so great).

SSEEEE AALLSSOO
       UNIX Manual entries for awk and sed.


       _p_a_r_s_e_r


       Example Bourne-shell scripts which process the output from
       _m_._c_l_u_m_p can be found with the source code for _m_._c_l_u_m_p:



       mapgraph.sh:
	      Tool to graph the  connections  among  data  points
	      found by _m_._c_l_u_m_p.

       points.sh:
	      Tool  to display the centroids of clumps created by
	      _m_._c_l_u_m_p.

       area.sh:
	      Tool to sum the area of points associated with each
	      clump  created  by  _m_._c_l_u_m_p, using data stored in a
	      user-specified field of the input data file.


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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0					       m.clump(1)
