## NAME

r.stats - Generates area statistics for raster map.

## KEYWORDS

raster, statistics

## SYNOPSIS

r.stats
r.stats --help
r.stats [-acpl1gxArnNCi] input=name[,name,...] [output=name] [separator=character] [null_value=string] [nsteps=integer] [sort=string] format=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

### Flags:

-a
  Print area totals in square meters
-c
  Print cell counts (sortable)
-p
  Print approximate (total percent may not be 100%) percents
-l
  Print category labels
-1
  One cell (range) per line
-g
  Print grid coordinates (east and north)
-x
  Print x and y (column and row)
  Indexing starts with 1: first column and row are 1
-A
  Print averaged values instead of intervals (floating-point maps only)
-r
  Print raw indexes of floating-point ranges (floating-point maps only)
-n
  Do not report no data value
-N
  Do not report cells where all maps have no data
-C
  Report for cats floating-point ranges (floating-point maps only)
-i
  Read floating-point map as integer (use map's quant rules)
--overwrite
  Allow output files to overwrite existing files
--help
  Print usage summary
--verbose
  Verbose module output
--quiet
  Quiet module output
--ui
  Force launching GUI dialog

### Parameters:

input=name[,name,...] [required]
  Name of raster map(s) to report on
output=name
  Name for output file (if omitted or "-" output to stdout)
separator=character
  Field separator
  Special characters: pipe, comma, space, tab, newline
null_value=string
  String representing NULL value
  Default: *
nsteps=integer
  Number of floating-point subranges to collect stats from
  Default: 255
sort=string
  Sort output statistics by cell counts
  Default: sorted by categories or intervals
  Options: asc, desc
  asc: Sort by cell counts in ascending order
  desc: Sort by cell counts in descending order
format=name [required]
  Output format
  Options: plain, csv, json
  Default: plain
  plain: Human readable text output
  csv: CSV (Comma Separated Values)
  json: JSON (JavaScript Object Notation)

## DESCRIPTION

r.stats calculates the area present in each of the categories or floating-point intervals of user-selected input raster map. Area statistics are given in units of square meters and/or cell counts. This analysis uses the current geographic region (g.region) and mask settings (r.mask). The output statistics can be saved to a output file.

Area statistics is printed in square meters for each category when -a is given. Similarly if -c flag is chosen, areas will be stated also in number of cells.

## NOTES

If a single raster map is specified, a list of categories will be printed. The -x flag will print x and y (column and row) starting with 1 (both first row and first column are indexed with 1). If multiple raster maps are specified, a cross-tabulation table for each combination of categories in the raster maps will be printed.

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

    1 1350000.00
    2 4940000.00
    3 8870000.00

If three raster maps 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 first raster map, the second represents the category values associated with second raster map, the third represents category values for third raster map, and the last field gives the area in square meters for the particular combination of these three raster maps' categories. For example, above, combination 3,1,1 covered 2500 square meters. Fields are separated by the separator option. The output from r.stats is sorted by category or category intervals (for floating-point raster maps).

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

## EXAMPLES

### Report area for each category

Report area for each category in the single raster map:

    g.region raster=geology_30m
    r.stats -a in=geology_30m nv=no-data sep=tab

    217     71960000.000000
    262     19760000.000000
    270     67760000.000000
    405     25120000.000000
    583     2520000.000000
    720     480000.000000
    766     840000.000000
    862     6560000.000000
    910     4360000.000000
    921     1200000.000000
    946     360000.000000
    948     80000.000000
    no-data 33375200000.000004

### Report sorted number of cells for each category

Report sorted number of cells for each category in the single raster map (suppress NULL data):

    g.region raster=geology_30m
    r.stats -cn input=geology_30m sort=desc

    217 1799
    270 1694
    405 628
    262 494
    862 164
    910 109
    583 63
    921 30
    766 21
    720 12
    946 9
    948 2

### Report area, number of cells, and percents in multiple raster maps

Report area, number of cells, and percents (separated by tabs) for each category in multiple raster maps (suppress NULL data):

    g.region raster=towns
    r.stats -nacp input=towns,urban separator=tab

    1       55      23840000.000000 596     11.89%
    2       55      13680000.000000 342     6.82%
    3       55      1360000.000000  34      0.68%
    4       55      16040000.000000 401     8.00%
    5       55      98240000.000000 2456    48.98%
    6       55      19760000.000000 494     9.85%

### Report sorted area intervals of floating-point raster map

Report sorted area for each interval of floating-point input raster map. Number of intervals are given by nsteps option.

    g.region raster=elevation
    r.stats -an input=elevation nsteps=10 sort=desc separator=tab

    95.879221-105.954329    36440000.000000
    85.804114-95.879221     30800000.000000
    105.954329-116.029436   30080000.000000
    116.029436-126.104543   27960000.000000
    126.104543-136.17965    26440000.000000
    136.17965-146.254757    20880000.000000
    75.729007-85.804114     15880000.000000
    65.6539-75.729007       6040000.000000
    146.254757-156.329865   5720000.000000
    55.578793-65.6539       760000.000000

### JSON Format

    g.region raster=elevation
    r.stats -an input=elevation nsteps=10 sort=desc format=json

    [
        {
            "categories": [
                {
                    "range": {
                        "from": 116.02943572998046,
                        "to": 126.10454292297364
                    }
                }
            ],
            "area": 1188100
        },
        {
            "categories": [
                {
                    "range": {
                        "from": 105.9543285369873,
                        "to": 116.02943572998046
                    }
                }
            ],
            "area": 857300
        },
        {
            "categories": [
                {
                    "range": {
                        "from": 126.10454292297364,
                        "to": 136.17965011596681
                    }
                }
            ],
            "area": 504700
        },
        {
            "categories": [
                {
                    "range": {
                        "from": 95.879221343994146,
                        "to": 105.9543285369873
                    }
                }
            ],
            "area": 336900
        },
        {
            "categories": [
                {
                    "range": {
                        "from": 85.804114151000974,
                        "to": 95.879221343994146
                    }
                }
            ],
            "area": 66500
        }
    ]

### Report raster cell counts in multiple raster maps

Report raster cell counts of landuse and geological categories within zipcode areas:

    g.region raster=zipcodes
    # landuse/landcover and zipcodes
    r.stats -c input=landclass96,zipcodes separator=comma

    # landuse/landcover, geology and zipcodes with category labels
    r.stats -c input=landclass96,zipcodes,geology_30m separator=comma -l

## SEE ALSO

g.region, r.report, r.coin, r.describe, r.stats.quantile, r.stats.zonal, r.statistics, r.univar

## AUTHORS

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
Sort option by Martin Landa, Czech Technical University in Prague, 2013

## SOURCE CODE

Available at: r.stats source code (history)

Latest change: Thursday Oct 02 14:39:13 2025 in commit: 1850489bf42c72d8dcfe2e4db1738441b4a7dc43

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual