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



NNAAMMEE
       rr..ssttaattss	- Generates area statistics for raster map layers.

       _(_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	 [--11aaccllmmqqggxxnnNNCCrrii]  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 categories of  user-
       selected  raster  map  layer(s).  Area statistics are given in units of
       square meters and/or cell counts. This analysis uses the  current  geo-
       graphic	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	[--11aaccllmmqqggxxnnNNCCrrii]  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 cur-
       rent working directory), the fs _c_h_a_r_a_c_t_e_r or space is the field separa-
       tor 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,
       _-_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	command  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 dis-
	      tinct 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 outside 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 addition to those within the mask.

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

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

       --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 character 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-specified  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
       command line.


       If a single map layer is specified on the command line, a list of areas
       in square meters (assuming the map's coordinate 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 category  value of
       map layer _a, the second represents the category values associated  with
       map  layer _b, the third represents category values for map layer _c, and
       the last field gives the area in square meters for the particular  com-
       bination  of  these  three map layers' categories.  For example, 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 dif-
       ferent 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_/_1_0_/_1_0 _2_1_:_0_6_:_3_8 _$



GRASS 5.0							    r.stats(1)
