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



NNAAMMEE
       rr..ssttaattss	 -  Generates area statistics for raster map lay-
       ers.

       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ssttaattss
       rr..ssttaattss hheellpp
       rr..ssttaattss [--11aaccllmmqqzzggxxnnNNCCrrii] iinnppuutt==_n_a_m_e[,_n_a_m_e,...]	[ffss==_c_h_a_r_-
       _a_c_t_e_r_|_s_p_a_c_e] [oouuttppuutt==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._s_t_a_t_s	calculates  the area present in each of the cate-
       gories of user-selected raster map layer(s). Area  statis-
       tics  are  given  in  units  of	square meters and/or cell
       counts. This analysis uses the current  geographic  region
       and  mask  settings.   Output can be sent to a file in the
       user's current working directory.


       The program will be  run  non-interactively  if	the  user
       specifies the program arguments and desired options on the
       command line, using the form


       rr..ssttaattss [--11aaccllmmqqzzggxxnnNNCCrrii] iinnppuutt==_n_a_m_e[,_n_a_m_e,...]	[ffss==_c_h_a_r_-
       _a_c_t_e_r_|_s_p_a_c_e] [oouuttppuutt==_n_a_m_e]


       where each input _n_a_m_e is the name of a raster map layer on
       which  area/cell  statistics  are  to  be  generated,  the
       (optional)  output  _n_a_m_e  is the name of a file to contain
       program output (sent to the user's current working  direc-
       tory), the fs _c_h_a_r_a_c_t_e_r or space is the field separator to
       be used	to  separate  data  fields  in	the  output  file
       (default  is  a	space if unspecified), and the (optional)
       flags _-_1, _-_a, _-_c, _-_l, _-_m, _-_q, _-_z, _-_g, _-_x, _-_n, _-_N, _-_C,  _-_r,
       and _-_i have the meanings described in the OPTIONS section.


       Alternately, the user can simply type rr..ssttaattss on the  com-
       mand  line,  without program arguments.	In this case, the
       user will be prompted for needed inputs and option choices
       using the standard GRASS parser.

OOPPTTIIOONNSS
   FFllaaggss::
       --11     The  data  for  each cell in the current geographic
	      region will be output, one cell  per  line,  rather
	      than the totals for each distinct combination.

       --aa     Print area totals in square meters.

       --cc     Print total cell counts.

       --mm     Report  all  zero  values  present in the _i_n_p_u_t map
	      layer(s), whether or not they fall inside  or  out-
	      side the current mask (see _r_._m_a_s_k).  When a mask is
	      present,	_r_._s_t_a_t_s  will  only  report  zero  values
	      falling  within  the mask area unless the user runs
	      _r_._s_t_a_t_s with the _-_m option.   When  the  user  runs
	      _r_._s_t_a_t_s  with  the  _-_m  option, _r_._s_t_a_t_s will report
	      zero values falling outside the mask area, in addi-
	      tion to those within the mask.

       --ll     Prints  the  category label(s) as well as the cate-
	      gory number(s).

       --qq     Run quietly, and suppress printing of percent  com-
	      plete messages to standard output.

       --zz     Report  only  non-zero  data values. Zero data will
	      not be reported.	However, for multiple map  layers
	      this  means  that if zero values occur in every map
	      layer, they will not be reported; if non-zero cate-
	      gory  values  occur  in  any  map layer (along with
	      zeros in others), the non-zero  values  along  with
	      the zero values will be reported.

       --gg     Print  the grid coordinates (easting and northing),
	      for each cell. This option works	only  if  the  _-_1
	      option is also specified.

       --xx     Print the x and y (column and row) values, for each
	      cell. This option works only if the  _-_1  option  is
	      also specified.

       --nn     Suppress reporting of any nulls.

       --NN     Suppress	reporting  of  nulls  when all values are
	      null.

       --CC     Report for cats fp ranges (fp maps only).

       --rr     Print raw indexes of fp ranges (fp maps only).

       --ii     Read fp map as integer (use map's quant rule).


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      The name(s) of one  or  more  existing  raster  map
	      layer(s)	whose  cell counts or area statistics are
	      to be calculated.

	      The field separator (fs) to  be  used  to  separate
	      data  fields in the _o_u_t_p_u_t file.	Options:  a char-
	      acter or space
	      Default:	a space

       oouuttppuutt==_n_a_m_e
	      The name to be assigned to the ASCII output file.


NNOONN--IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE
       If users invoke	program  options  on  the  command  line,
       _r_._s_t_a_t_s will print out area statistics for the user-speci-
       fied raster map layers in a columnar format  suitable  for
       input  to  UNIX	programs  like _a_w_k and _s_e_d. Output can be
       saved by specifying the name of an _o_u_t_p_u_t file on the com-
       mand line.


       If  a single map layer is specified on the command line, a
       list of areas in square meters (assuming the map's coordi-
       nate  system is in meters) for each category in the raster
       map layer will be printed. (If the _-_c  option  is  chosen,
       areas  will  be	stated	in  number of cells.) If multiple
       raster map layers are specified on  the	command  line,	a
       cross-tabulation  table	of  areas for each combination of
       categories in the map layers will be printed.


       For example, if one raster map layer were  specified,  the
       output would look like:

		 1:1350000.00
		 2:4940000.00
		 3:8870000.00

       If  three  raster  map layers _a_, _b, and _c, were specified,
       the output would look like:

		 0:0:0:8027500.00
		 0:1:0:1152500.00
		 1:0:0:164227500.00
		 1:0:1:2177500.00
		 1:1:0:140092500.00
		 1:1:1:3355000.00
		 2:0:0:31277500.00
		 2:0:1:2490000.00
		 2:1:0:24207500.00
		 2:1:1:1752500.00
		 3:0:0:17140000.00
		 3:1:0:11270000.00
		 3:1:1:2500.00

       Within each grouping, the first field represents the cate-
       gory  value of map layer _a, the second represents the cat-
       egory values associated with map layer _b, the third repre-
       sents  category values for map layer _c, and the last field
       gives the area in square meters for the particular  combi-
       nation  of  these three map layers' categories.	For exam-
       ple, above, combination 3,1,1 covered 2500 square  meters.
       Fields are separated by colons.

NNOOTTEESS
       _r_._s_t_a_t_s	works  in  the current geographic region with the
       current mask.


       If a nicely formatted output is desired, pipe  the  output
       into  a	command  which	can  create columnar output.  For
       example, the command:


       rr..ssttaattss iinnppuutt==a,b,c | pr -3 | cat -s


       will create a three-column output

       1:4:4:10000.00	    2:1:5:290000.00	 2:4:5:2090000.00
       1:4:5:1340000.00     2:2:5:350000.00	 3:1:2:450000.00
       2:1:1:1090000.00     2:4:1:700000.00	 3:1:3:5280000.00
       2:1:3:410000.00	    2:4:3:10000.00	 3:1:5:3140000.00

       The  output  from  _r_._s_t_a_t_s  on  more than one map layer is
       sorted.


       Note that the user has only the	option	of  printing  out
       cell  statistics  in  terms  of	cell  counts  and/or area
       totals. Users wishing to  use  different  units	than  are
       available here should use the GRASS program _r_._r_e_p_o_r_t.

SSEEEE AALLSSOO
       _p_a_r_s_e_r

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_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0					       r.stats(1)
