NAME

r.stats - Generates area statistics for raster map layers.
(GRASS Raster Program)

SYNOPSIS

r.stats
r.stats help
r.stats [-1aclmqzgxnNCri] input=name[,name,...] [fs=character|space] [output=name]

DESCRIPTION

r.stats 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 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

r.stats [-1aclmqzgxnNCri] input=name[,name,...] [fs=character|space] [output=name]

where each input name is the name of a raster map layer on which area/cell statistics are to be generated, the (optional) output name is the name of a file to contain program output (sent to the user's current working directory), the fs character 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 r.stats 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 interface described in the manual entry for parser.

OPTIONS

Flags:

-1
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.
-a
Print area totals in square meters.
-c
Print total cell counts.
-m
Report all zero values present in the input map layer(s), whether or not they fall inside or outside the current mask (see r.mask). When a mask is present, r.stats will only report zero values falling within the mask area unless the user runs r.stats with the -m option. When the user runs r.stats with the -m option, r.stats will report zero values falling outside the mask area, in addition to those within the mask.
-l
Prints the category label(s) as well as the category number(s).
-q
Run quietly, and suppress printing of percent complete messages to standard output.
-z
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 category values occur in any map layer (along with zeros in others), the non-zero values along with the zero values will be reported.
-g
Print the grid coordinates (easting and northing), for each cell. This option works only if the -1 option is also specified.
-x
Print the x and y (column and row) values, for each cell. This option works only if the -1 option is also specified.
-n
Suppress reporting of any nulls.
-N
Suppress reporting of nulls when all values are null.
-C
Report for cats fp ranges (fp maps only).
-r
Print raw indexes of fp ranges (fp maps only).
-i
Read fp map as integer (use map's quant rule).

Parameters:

input=name
The name(s) of one or more existing raster map layer(s) whose cell counts or area statistics are to be calculated.
"fs=character or fs=space"
The field separator (fs) to be used to separate data fields in the output file.
Options: a character or space
Default: a space
output=name
The name to be assigned to the ASCII output file.

NON-INTERACTIVE PROGRAM USE

If users invoke program options on the command line, r.stats will print out area statistics for the user-specified raster map layers in a columnar format suitable for input to UNIX programs like awk and sed. Output can be saved by specifying the name of an output 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 combination of these three map layers' categories. For example, above, combination 3,1,1 covered 2500 square meters. Fields are separated by colons.

NOTES

r.stats 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:

r.stats input=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.stats 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.report.

SEE ALSO

g.region, r.coin, r.describe, r.mask, r.report, parser

AUTHOR

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

Last changed: $Date$