r.stats(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 r.stats — the manual, but make it make sense 💖

okay bestie, welcome to r.stats(1) from the GRASS GIS User's Manual. yes, the parentheses number is (1) and yes we are doing this. it generates area statistics for raster maps, and honestly? it ate. let's get into it. 🦋

✨ NAME ✨

r.stats — generates area statistics for raster map. that's the whole thing. short. iconic. no notes. 💅

🔑 KEYWORDS 🔑

raster, statistics — yeah that's the vibe check, she's a raster stats girlie. 📊

🌸 SYNOPSIS 🌸

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

not me flexing the flag soup -acpl1gxArnNCi like it's a vibe. it IS a vibe. 💀

🎀 FLAGS (they're inside SYNOPSIS but we're giving them a moment) 🎀

Flags:

  • -a — prints area totals, and they're in square meters. metric girlies rise. 📐
  • -c — prints cell counts, and they're sortable. yes, -c for sortable counting, we love a flag that's also a hint. 🔢
  • -p — prints approximate percents. and bestie, listen, the total percent may not be 100%. that's not a bug, that's just the math being math. 🙈
  • -l — prints category labels. labels on labels on labels. 🏷️
  • -1 — one cell (range) per line. literally just one per line. minimalism. 🧚
  • -g — prints grid coordinates (east and north). compass-girl behaviour. 🧭
  • -x — prints x and y (column and row). and heads up: indexing starts with 1, so the first column and the first row are 1. not 0. ONE. 🫶
  • -A — prints averaged values instead of intervals. floating-point maps only, so don't try it on your integer bestie. 🌊
  • -r — prints raw indexes of floating-point ranges. floating-point maps only again. raw. unfiltered. 🍓
  • -n — do NOT report no data value. she's hiding the nulls, mind your business. 🙅
  • -N — do NOT report cells where all maps have no data. so if every single map is empty at that spot, we skip it. bye. 👋
  • -C — report for cats floating-point ranges. floating-point maps only. cats = categories, iykyk. 🐈
  • -i — read floating-point map as integer, using the map's quant rules. pretending it's an int, respectfully. 🔄
  • --overwrite — allow output files to overwrite existing files. she will REPLACE things. consent matters, so this is opt-in. 💥
  • --help — print usage summary. when you're lost, ask for help, no shame. 🆘
  • --verbose — verbose module output. she's talking MORE. 🗣️
  • --quiet — quiet module output. she's talking LESS. 🤫
  • --ui — force launching GUI dialog. sometimes you want buttons, and that's valid. 🖱️

💜 PARAMETERS 💜

Parameters:

  • input=name[,name,...] — [required]. name of raster map(s) to report on. yes you can stack them with commas, it's a whole friend group. 👯
  • output=name — name for output file. if you omit it, or literally pass -, it goes to stdout. stdout is the default bestie. 🖨️
  • separator=character — the field separator. special characters you can use: pipe, comma, space, tab, newline. Default: space. yes it's spelled out in words, no you can't fight it. 🔤
  • null_value=string — the string representing a NULL value. Default: *. a little asterisk star, how cute. ⭐
  • nsteps=integer — number of floating-point subranges to collect stats from. Default: 255. yes, two hundred fifty-five. she's precise. 🎯
  • sort=string — sort output statistics by cell counts. Default: sorted by categories or intervals. Options: asc, desc. asc sorts by cell counts in ascending order, desc sorts by cell counts in descending order. pick a lane, pick a direction. ⬆️⬇️

🌈 DESCRIPTION 🌈

so r.stats calculates the area present in each of the categories or floating-point intervals of the user-selected input raster map. area statistics come out in units of square meters and/or cell counts. ✨

this analysis uses the current geographic region (g.region) and the mask settings (r.mask). so like, whatever your region and mask are set to? that's the reality she's reporting on. and yes, the output statistics can be saved to an output file. 📁

area statistics get printed in square meters for each category when you pass -a. similarly, if you choose the -c flag, areas will be stated also in number of cells. so you can have both. she contains multitudes. 💖

📝 NOTES 📝

if a single raster map is specified, a list of categories gets printed. the -x flag will print x and y (column and row) starting with 1 — both the first row and the first column are indexed with 1, we said it once and we'll say it again because it's important. if multiple raster maps are specified, a cross-tabulation table for each combination of categories in the raster maps gets printed. cross-tab girlies, this one's for you. 📋

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 the first raster map, the second represents the category values associated with the second raster map, the third represents category values for the third raster map, and the last field gives the area in square meters for that 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. and the output from r.stats is sorted by category or category intervals (for floating-point raster maps). periodt. 💅

heads up bestie: the user has only the option of printing out cell statistics in terms of cell counts and/or area totals. if you want different units than the ones available here, you should use r.report instead. no cap, that's just the boundary of what she does.

🦋 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

look at no-data doing the absolute most at the bottom. main character energy, honestly. 👑

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

descending order, biggest to smallest, she's ranking them like a tier list. 🔥

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%

four flags at once, -nacp, and she's out here serving columns. the range. 🌟

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 the 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

nsteps=10 and we get ten little elevation windows. so tidy. so demure. 🪟

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

note the # comments in there — those are comments, they're just chillin'. 🫶

👀 SEE ALSO 👀

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

the whole family. go say hi to them. 🌸

👑 AUTHORS 👑

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

thank you for your service, legends. 🫡

📦 SOURCE CODE 📦

available at: r.stats source code (history)

accessed: Saturday Jan 17 05:41:00 2026

main index | raster index | topics index | keywords index | graphical index | full index

and that's the whole manual bestie, we did it 💖 before you go: this whole thing lives in the GRASS GIS 8.4.2 Reference Manual, © 2003-2025 GRASS Development Team, and the version tagging along with it is GRASS 8.4.2 — the page is r.stats(1), and the footer date situation says accessed Saturday Jan 17 05:41:00 2026. slay, go run some stats, and remember: first column and row are 1. ✨🎀🦋

📦 where this page comes from