r.report
Reports statistics for raster maps.
r.report [-hfenaci] map=name [,name,...] [units=string [,string,...]] [output=name] [null_value=string] [page_length=integer] [page_width=integer] [nsteps=integer] [sort=string] format=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.report map=name format=plain
grass.script.parse_command("r.report", map, units="cells,percent", output=None, null_value="*", page_length=0, page_width=79, nsteps=255, sort=None, format="plain", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.parse_command("r.report", map="name", format="json")
Parameters
map=name [,name,...] [required]
Name of raster map(s) to report on
units=string [,string,...]
Units to report
Allowed values: miles, meters, kilometers, acres, hectares, cells, percent
Default: cells,percent
miles: area in square miles
meters: area in square meters
kilometers: area in square kilometers
acres: area in acres
hectares: area in hectares
cells: number of cells
percent: percent cover
output=name
Name for output file to hold the report
If no output file given report is printed to standard output
null_value=string
String representing NULL value
Default: *
page_length=integer
Page length
Default: 0
page_width=integer
Page width
Default: 79
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
Allowed values: asc, desc
asc: Sort by cell counts in ascending order
desc: Sort by cell counts in descending order
format=name [required]
Output format
Allowed values: plain, json
Default: plain
plain: Plain text output
json: JSON (JavaScript Object Notation)
-h
Suppress page headers
-f
Use formfeeds between pages
-e
Scientific format
-n
Do not report no data value
-a
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
--qq
Very quiet module output
--ui
Force launching GUI dialog
map : str | list[str], required
Name of raster map(s) to report on
Used as: input, raster, name
units : str | list[str], optional
Units to report
Allowed values: miles, meters, kilometers, acres, hectares, cells, percent
miles: area in square miles
meters: area in square meters
kilometers: area in square kilometers
acres: area in acres
hectares: area in hectares
cells: number of cells
percent: percent cover
Default: cells,percent
output : str, optional
Name for output file to hold the report
If no output file given report is printed to standard output
Used as: output, file, name
null_value : str, optional
String representing NULL value
Used as: string
Default: *
page_length : int, optional
Page length
Default: 0
page_width : int, optional
Page width
Default: 79
nsteps : int, optional
Number of floating-point subranges to collect stats from
Default: 255
sort : str, optional
Sort output statistics by cell counts
Default: sorted by categories or intervals
Allowed values: asc, desc
asc: Sort by cell counts in ascending order
desc: Sort by cell counts in descending order
format : str, required
Output format
Used as: name
Allowed values: plain, json
plain: Plain text output
json: JSON (JavaScript Object Notation)
Default: plain
flags : str, optional
Allowed values: h, f, e, n, a, c, i
h
Suppress page headers
f
Use formfeeds between pages
e
Scientific format
n
Do not report no data value
a
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: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
r.report allows the user to set up a series of report parameters to be applied to a raster map, and creates a report. The report will print out to the standard output if output parameter is not given. The report can be either formatted in a human-readable way (default) or in a JSON format using the format=json parameter.
The report itself consists of two parts, a header section and the main body of the report.
The header section of the report identifies the raster map(s) (by map name and title), project, mapset, report date, and the region of interest. The area of interest is described in two parts: the user's current geographic region is presented, and the mask is presented (if any is used).
The main body of the report consists of from one to three tables which present the statistics for each category and the totals for each unit column. Note that the statistics is always computed in the current computational region.
When multiple (typically two) raster maps are specified, cross-tabulation table for each combination of categories in the raster maps will be computed and formatted in a human-readable way (see example).
NOTES
Note that, unlike r.stats, r.report allows the user to select the specific units of measure in which statistics will be reported. To output computer-friendly data suitable for importing into a spreadsheet use the r.stats module. In fact r.report is running r.stats in the background and reformatting the results to be more human-friendly.
EXAMPLE
Report sorted areas in square miles and acres for each category. No-data are not reported (see -n flag).
g.region raster=geology_30m
r.report -n map=geology_30m units=mi,a sort=desc
+-----------------------------------------------------------------------------+
| RASTER MAP CATEGORY REPORT |
|PROJECT: nc_spm_08_grass7 Tue Jun 24 13:44:59 2025|
|-----------------------------------------------------------------------------|
| north: 228500 east: 645000 |
|REGION south: 215000 west: 630000 |
| res: 30 res: 30 |
|-----------------------------------------------------------------------------|
|MASK: none |
|-----------------------------------------------------------------------------|
|MAP: South-West Wake county: geology derived from vector map (geology_30m in |
|-----------------------------------------------------------------------------|
| Category Information | square| |
| #|description | miles| acres|
|-----------------------------------------------------------------------------|
|217|CZfg . . . . . . . . . . . . . . . . . . . . . . . | 28.014105|17,929.027|
|270|CZig . . . . . . . . . . . . . . . . . . . . . . . | 26.616840|17,034.778|
|405|CZbg . . . . . . . . . . . . . . . . . . . . . . . | 9.795798| 6269.311|
|262|CZlg . . . . . . . . . . . . . . . . . . . . . . . | 7.671232| 4909.589|
|862|CZam . . . . . . . . . . . . . . . . . . . . . . . | 2.383100| 1525.184|
|910|CZbg . . . . . . . . . . . . . . . . . . . . . . . | 1.736070| 1111.085|
|583|CZve . . . . . . . . . . . . . . . . . . . . . . . | 0.834328| 533.970|
|921|Km . . . . . . . . . . . . . . . . . . . . . . . . | 0.483709| 309.574|
|766|CZg. . . . . . . . . . . . . . . . . . . . . . . . | 0.273129| 174.802|
|720|CZam . . . . . . . . . . . . . . . . . . . . . . . | 0.186256| 119.204|
|946|CZam . . . . . . . . . . . . . . . . . . . . . . . | 0.157066| 100.522|
|948|CZam . . . . . . . . . . . . . . . . . . . . . . . | 0.033707| 21.572|
|945|CZbg . . . . . . . . . . . . . . . . . . . . . . . | 0.000347| 0.222|
|-----------------------------------------------------------------------------|
|TOTAL | 78.185687|50,038.840|
+-----------------------------------------------------------------------------+
import grass.script as gs
gs.run_command("g.region", raster="geology_30m")
report = gs.parse_command(
"r.report", flags="n", map="geology_30m", units="mi,a", sort="desc", format="json"
)
print(report["categories"][0])
{'category': 217, 'label': 'CZfg', 'units': [{'unit': 'square miles', 'value': 28.01410543563742}, {'unit': 'acres', 'value': 17929.02747880792}]}
The corresponding (shortened) JSON output is:
{
"project": "nc_spm_08_grass7",
"created": "2025-06-24T13:33:05-0400",
"region": {
"north": 228500,
"south": 215000,
"east": 645000,
"west": 630000,
"ewres": 30,
"nsres": 30
},
"mask": null,
"maps": [
{
"name": "geology_30m",
"title": "South-West Wake county: geology derived from vector map",
"type": "raster"
}
],
"categories": [
{
"category": 217,
"label": "CZfg",
"units": [
{
"unit": "square miles",
"value": 28.014105435637418
},
{
"unit": "acres",
"value": 17929.027478807919
}
]
},
{
"category": 270,
"label": "CZig",
"units": [
{
"unit": "square miles",
"value": 26.61684033408816
},
{
"unit": "acres",
"value": 17034.777813816392
}
]
},
...
],
"totals": [
{
"unit": "square miles",
"value": 78.185687104845314
},
{
"unit": "acres",
"value": 50038.839747100916
}
]
}
Report areas for each category of land use for each zipcode (included only part of the table):
g.region raster=zipcodes@PERMANENT
r.report map=zipcodes@PERMANENT,landclass96@PERMANENT units=h,p
+-----------------------------------------------------------------------------+
| RASTER MAP CATEGORY REPORT |
|PROJECT: nc_spm_08_grass7 Tue Jun 24 13:47:15 2025|
|-----------------------------------------------------------------------------|
| north: 228500 east: 645000 |
|REGION south: 215000 west: 630000 |
| res: 10 res: 10 |
|-----------------------------------------------------------------------------|
|MASK: none |
|-----------------------------------------------------------------------------|
|MAPS: South West Wake: Zipcode areas derived from vector map (zipcodes@PERMAN|
| South-West Wake county: Simplified landuse classes (landclass96@PERMA|
|-----------------------------------------------------------------------------|
| Category Information | | % |
| #|description | hectares| cover|
|-----------------------------------------------------------------------------|
|27511|CARY | 1058.000| 5.22|
| |-----------------------------------------------------|----------|------|
| |1|developed. . . . . . . . . . . . . . . . . . . . . | 197.940| 18.71|
| |3|herbaceous . . . . . . . . . . . . . . . . . . . . | 24.440| 2.31|
| |4|shrubland. . . . . . . . . . . . . . . . . . . . . | 58.080| 5.49|
| |5|forest . . . . . . . . . . . . . . . . . . . . . . | 775.910| 73.34|
| |6|water. . . . . . . . . . . . . . . . . . . . . . . | 1.540| 0.15|
| |*|no data. . . . . . . . . . . . . . . . . . . . . . | 0.090| 0.01|
|-----------------------------------------------------------|----------|------|
|27513|CARY | 205.300| 1.01|
| |-----------------------------------------------------|----------|------|
| |1|developed. . . . . . . . . . . . . . . . . . . . . | 32.580| 15.87|
| |3|herbaceous . . . . . . . . . . . . . . . . . . . . | 5.930| 2.89|
| |4|shrubland. . . . . . . . . . . . . . . . . . . . . | 52.030| 25.34|
| |5|forest . . . . . . . . . . . . . . . . . . . . . . | 114.760| 55.90|
|-----------------------------------------------------------|----------|------|
...
|-----------------------------------------------------------------------------|
|TOTAL |20,250.000|100.00|
+-----------------------------------------------------------------------------+
import grass.script as gs
gs.run_command("g.region", raster="zipcodes@PERMANENT")
report = gs.parse_command(
"r.report",
map=["zipcodes@PERMANENT", "landclass96@PERMANENT"],
units="h,p",
format="json",
)
print(report["categories"][0]["categories"][0])
{'category': 1, 'label': 'developed', 'units': [{'unit': 'hectares', 'value': 197.94}, {'unit': 'percent', 'value': 18.708884688090738}]}
The corresponding (shortened) JSON output is:
{
"project": "nc_spm_08_grass7",
"created": "2025-06-24T13:58:07-0400",
"region": {
"north": 228500,
"south": 215000,
"east": 645000,
"west": 630000,
"ewres": 10,
"nsres": 10
},
"mask": null,
"maps": [
{
"name": "zipcodes@PERMANENT",
"title": "South West Wake: Zipcode areas derived from vector map",
"type": "raster"
},
{
"name": "landclass96@PERMANENT",
"title": "South-West Wake county: Simplified landuse classes",
"type": "raster"
}
],
"categories": [
{
"category": 27511,
"label": "CARY",
"units": [
{
"unit": "hectares",
"value": 1058
},
{
"unit": "percent",
"value": 5.2246913580246916
}
],
"categories": [
{
"category": 1,
"label": "developed",
"units": [
{
"unit": "hectares",
"value": 197.94
},
{
"unit": "percent",
"value": 18.708884688090738
}
]
},
...
"totals": [
{
"unit": "hectares",
"value": 20250
},
{
"unit": "percent",
"value": 100
}
]
}
SEE ALSO
r.stats, g.region, r.coin, r.describe, r.info, 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.report source code
(history)
Latest change: Tuesday Jun 24 17:42:23 2025 in commit 058553a